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

package/dist/libdef/c-to-decl.js

@@ -0,0 +1,397 @@
+/**
+ * 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
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { stripPreprocessorBlocks } from './header-parser.js';
+const BUILTIN_TS_TYPES = new Set(['number', 'string', 'boolean', 'void', 'any']);
+/**
+ * Map a C type string to a TS type string. Pointer types become `number`
+ * (handles/opaque addresses) since the transpiler treats C pointers as
+ * numbers anyway. Unknown named types are returned as-is so they resolve
+ * to a typedef alias emitted by this same header (or fall back to `number`
+ * via the alias-emission pass in generateCDecl).
+ */
+function mapCTypeToTs(cType) {
+    let t = cType.trim();
+    // Strip leading `const`/`volatile` qualifiers — they don't affect the TS shape.
+    t = t.replace(/^(?:const|volatile)\s+/, '');
+    const typeMap = {
+        int: 'number',
+        'unsigned int': 'number',
+        'unsigned': 'number',
+        'short': 'number',
+        'unsigned short': 'number',
+        'long': 'number',
+        'unsigned long': 'number',
+        'long long': 'number',
+        'unsigned long long': 'number',
+        uint8_t: 'number',
+        uint16_t: 'number',
+        uint32_t: 'number',
+        uint64_t: 'number',
+        int8_t: 'number',
+        int16_t: 'number',
+        int32_t: 'number',
+        int64_t: 'number',
+        size_t: 'number',
+        ssize_t: 'number',
+        intptr_t: 'number',
+        uintptr_t: 'number',
+        float: 'number',
+        double: 'number',
+        bool: 'boolean',
+        _Bool: 'boolean',
+        void: 'void',
+        char: 'number',
+    };
+    if (typeMap[t])
+        return typeMap[t];
+    // Strip a trailing pointer; pointers are number-typed handles/addresses.
+    if (t.endsWith('*'))
+        return 'number';
+    return t;
+}
+/** Parse function signatures like `esp_err_t foo(int x, const char *y);`. */
+function parseFunctions(stripped) {
+    const fns = [];
+    const fnRegex = /^([\w\s\*]+?)\s+(\w+)\s*\(([^;]*)\)\s*;/gm;
+    let m;
+    while ((m = fnRegex.exec(stripped)) !== null) {
+        const returnType = m[1].trim();
+        const name = m[2];
+        const paramsRaw = m[3].trim();
+        // Skip non-function declarations these regexes might catch.
+        if (returnType === 'typedef' || returnType === 'struct' || returnType === 'enum')
+            continue;
+        if (returnType === 'static' || returnType === 'extern' || returnType === 'inline')
+            continue;
+        if (name === 'if' || name === 'for' || name === 'while' || name === 'return' || name === 'switch')
+            continue;
+        fns.push({ returnType, name, params: parseParams(paramsRaw) });
+    }
+    return fns;
+}
+function parseParams(raw) {
+    if (!raw || raw === 'void')
+        return [];
+    return raw.split(',').map((part, idx) => {
+        let trimmed = part.trim();
+        trimmed = trimmed.split('=')[0].trim();
+        if (!trimmed)
+            return { type: '', name: `_arg${idx}` };
+        // C array declarator on a parameter: `<type> <name>[<size>]` or `<type> <name>[]`.
+        // Normalize: the array decays to a pointer in C anyway, so we record the
+        // base type and the original name. e.g. `uint8_t mac[6]` → type="uint8_t",
+        // name="mac"; `uint8_t mac[]` → same.
+        const arrParam = trimmed.match(/^(.*?)\b(\w+)\s*\[[^\]]*\]\s*$/);
+        if (arrParam) {
+            const type = arrParam[1].trim();
+            // If the type is empty (e.g. bare `mac[6]` with no preceding type),
+            // fall through to the default parser rather than emitting a bogus type.
+            if (type)
+                return { type, name: arrParam[2] };
+        }
+        // A parameter is `<type> <name>` where name is the trailing identifier
+        // and type is everything before. For function-pointer params (rare in
+        // user-facing IDF APIs) we fall back to treating the whole thing as a
+        // type with a synthesized name.
+        if (trimmed.includes('(*)')) {
+            return { type: trimmed, name: `_arg${idx}` };
+        }
+        const m = trimmed.match(/^(.*?)(\b\w+)$/);
+        if (!m)
+            return { type: trimmed, name: `_arg${idx}` };
+        let type = m[1].trim();
+        const name = m[2];
+        // If the regex left the * glued to the name, pull it back to the type.
+        if (!type && trimmed.includes('*')) {
+            type = '*';
+        }
+        return { type: type || trimmed, name };
+    });
+}
+/** Parse typedef'd enums: `typedef enum { A, B=2, C } foo_t;`. */
+function parseEnumTypedefs(stripped) {
+    const tds = [];
+    const re = /typedef\s+enum\s*(?:\w+\s*)?\{([^}]*)\}\s*(\w+)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const body = m[1];
+        const name = m[2];
+        const members = body.split(',').map((s) => s.trim()).filter(Boolean);
+        let next = 0;
+        const values = members.map((mem) => {
+            const eq = mem.indexOf('=');
+            if (eq >= 0) {
+                const val = parseInt(mem.slice(eq + 1).trim(), 10);
+                if (!Number.isNaN(val))
+                    next = val + 1;
+                return { name: mem.slice(0, eq).trim(), value: Number.isNaN(val) ? undefined : val };
+            }
+            const v = next++;
+            return { name: mem, value: v };
+        });
+        tds.push({ kind: 'enum', name, values });
+    }
+    return tds;
+}
+/** Parse typedef'd structs: `typedef struct { int x; } foo_t;` or
+ *  `typedef struct foo { int x; } foo_t;`. Handles array fields
+ *  (`int arr[6]`) by recording the array-ness on the field. */
+function parseStructTypedefs(stripped) {
+    const tds = [];
+    const re = /typedef\s+struct\s*(?:\w+\s*)?\{([^}]*)\}\s*(\w+)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const body = m[1];
+        const name = m[2];
+        const fields = body
+            .split(';')
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .map((field, idx) => {
+            // Array field: `<type> <name>[<size>]` → name + isArray.
+            const arr = field.match(/^(.*?)\b(\w+)\s*\[[^\]]*\]\s*$/);
+            if (arr) {
+                return { type: arr[1].trim() || field, name: arr[2], isArray: true };
+            }
+            const pm = field.match(/^(.*?)(\b\w+)$/);
+            if (!pm)
+                return { type: field, name: `_f${idx}`, isArray: false };
+            return { type: pm[1].trim() || field, name: pm[2], isArray: false };
+        });
+        tds.push({ kind: 'struct', name, fields });
+    }
+    return tds;
+}
+/** Parse opaque handle typedefs: `typedef struct foo *foo_handle_t;`. */
+function parseOpaqueTypedefs(stripped) {
+    const tds = [];
+    const re = /typedef\s+struct\s+\w+\s*\*\s*(\w+)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        tds.push({ kind: 'opaque', name: m[1] });
+    }
+    return tds;
+}
+/** Parse function-pointer typedefs: `typedef void (*handler_t)(void *arg);`.
+ *  Emits as `any` — TS has no faithful representation of a C function pointer,
+ *  and IDF user code that registers one needs `rawCpp()` anyway. */
+function parseFuncPtrTypedefs(stripped) {
+    const tds = [];
+    const re = /typedef\s+[\w\s\*]+?\(\s*\*\s*(\w+)\s*\)\s*\([^;]*\)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        tds.push({ kind: 'funcptr', name: m[1] });
+    }
+    return tds;
+}
+/** Parse plain alias typedefs: `typedef int esp_err_t;`, `typedef uint32_t foo_t;`.
+ *  These are extremely common in ESP-IDF (esp_err_t, TickType_t, etc.). */
+function parseAliasTypedefs(stripped) {
+    const tds = [];
+    // `typedef <type> <name>;` where <type> is a single token (possibly with
+    // qualifiers) and <name> is the alias. Struct/enum/funcptr typedefs are
+    // handled by their own parsers, so exclude those keywords here.
+    const re = /typedef\s+(?!struct\b)(?!enum\b)(?!union\b)([\w\s\*]+?)\s+(\w+)\s*;/g;
+    let m;
+    while ((m = re.exec(stripped)) !== null) {
+        const aliasedType = m[1].trim();
+        const name = m[2];
+        // Skip if this is actually the tail of a struct/enum/funcptr typedef that
+        // a sibling parser already consumed (defensive — the negative lookahead
+        // should already exclude those, but the regex can still match fragments
+        // inside a `typedef struct { ... } foo_t;` body in edge cases).
+        if (aliasedType === '' || aliasedType.includes('{'))
+            continue;
+        // Skip array typedefs: `typedef uint8_t mac[6];` is NOT a plain alias.
+        // It would parse as aliasedType="uint8_t" name="mac" with the regex, but
+        // the trailing `[6]` between name and `;` makes it an array typedef — the
+        // regex's `\s*;` lookahead fails to match `[6];`, so this branch only
+        // fires for true plain aliases. Defensive: bail if the captured aliasedType
+        // somehow contains a `[` (would indicate a parse fragment).
+        if (aliasedType.includes('['))
+            continue;
+        tds.push({ kind: 'alias', name, aliasedType });
+    }
+    return tds;
+}
+/** Parse `#define FOO 42` and `#define BAR "str"` (integers and strings only). */
+function parseSimpleDefines(content) {
+    const out = [];
+    const re = /^\s*#define\s+(\w+)\s+(.+?)\s*$/gm;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        const name = m[1];
+        const value = m[2].trim();
+        if (/^-?\d+$/.test(value) || /^"[^"]*"$/.test(value)) {
+            out.push({ name, value });
+        }
+    }
+    return out;
+}
+// Strip C-style comments so they don't interfere with parsing.
+// Block comments and line comments are both removed; preprocessor
+// directives are preserved (stripPreprocessorBlocks handles those next).
+function stripComments(content) {
+    return content.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+}
+function parseHeader(content) {
+    const noComments = stripComments(content);
+    const stripped = stripPreprocessorBlocks(noComments);
+    return {
+        functions: parseFunctions(stripped),
+        typedefs: [
+            ...parseEnumTypedefs(stripped),
+            ...parseStructTypedefs(stripped),
+            ...parseOpaqueTypedefs(stripped),
+            ...parseFuncPtrTypedefs(stripped),
+            ...parseAliasTypedefs(stripped),
+        ],
+        defines: parseSimpleDefines(noComments),
+    };
+}
+function emitEnumTypedef(td) {
+    const literalUnion = td.values.every((v) => typeof v.value === 'number')
+        ? td.values.map((v) => v.value).join(' | ')
+        : 'number';
+    const lines = [`export type ${td.name} = ${literalUnion};`];
+    // Export named constants so user code can reference WIFI_MODE_STA directly,
+    // exactly as ESP-IDF examples do.
+    for (const v of td.values) {
+        lines.push(`export const ${v.name}: ${td.name} = ${v.value ?? 0};`);
+    }
+    return lines;
+}
+function emitStructTypedef(td) {
+    const fields = td.fields.map((f) => {
+        const tsType = mapCTypeToTs(f.type);
+        return `  ${f.name}: ${f.isArray ? `${tsType}[]` : tsType};`;
+    });
+    return [`export interface ${td.name} {`, ...fields, `}`];
+}
+function emitTypedef(td) {
+    switch (td.kind) {
+        case 'enum':
+            return emitEnumTypedef(td);
+        case 'struct':
+            return emitStructTypedef(td);
+        case 'opaque':
+            return [`export type ${td.name} = number;`];
+        case 'alias':
+            return [`export type ${td.name} = ${mapCTypeToTs(td.aliasedType)};`];
+        case 'funcptr':
+            // Function-pointer typedefs have no faithful TS representation. Emit
+            // `any` with a comment so users know to use `rawCpp()` for callbacks.
+            return [
+                `// ${td.name} is a C function-pointer typedef; TS has no faithful representation.`,
+                `export type ${td.name} = any;`,
+            ];
+    }
+}
+/** Emit a free function declaration, name matching the C header 1-to-1. */
+function emitFunction(fn) {
+    const params = fn.params.map((p, idx) => {
+        const name = p.name || `_arg${idx}`;
+        const tsType = p.type === '' ? 'any' : mapCTypeToTs(p.type);
+        return `${name}: ${tsType}`;
+    });
+    const returnType = mapCTypeToTs(fn.returnType);
+    return `export declare function ${fn.name}(${params.join(', ')}): ${returnType};`;
+}
+/**
+ * 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 function generateCDecl(filePath, outputPath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    const content = fs.readFileSync(filePath, 'utf8');
+    const header = parseHeader(content);
+    // Collect every type name the header defines so the alias-emission pass
+    // below doesn't emit spurious `export type X = number;` for types that
+    // are already declared.
+    const knownTypes = new Set([
+        ...header.typedefs.map((t) => t.name),
+        ...BUILTIN_TS_TYPES,
+    ]);
+    // Find referenced types that aren't declared anywhere in this header and
+    // aren't builtins — emit them as `export type X = number;` so the .d.ts
+    // compiles standalone. (Common case: a header references `esp_err_t` from
+    // another header without re-typedef'ing it.)
+    const referencedTypes = new Set();
+    for (const f of header.functions) {
+        referencedTypes.add(mapCTypeToTs(f.returnType));
+        for (const p of f.params)
+            referencedTypes.add(mapCTypeToTs(p.type));
+    }
+    for (const td of header.typedefs) {
+        if (td.kind === 'struct') {
+            for (const f of td.fields)
+                referencedTypes.add(mapCTypeToTs(f.type));
+        }
+        else if (td.kind === 'alias') {
+            referencedTypes.add(mapCTypeToTs(td.aliasedType));
+        }
+    }
+    const aliasesToEmit = [...referencedTypes].filter((t) => !knownTypes.has(t) && !t.includes('|') && !BUILTIN_TS_TYPES.has(t));
+    // Nothing to emit → tell the caller.
+    if (header.functions.length === 0 &&
+        header.typedefs.length === 0 &&
+        header.defines.length === 0 &&
+        aliasesToEmit.length === 0) {
+        return null;
+    }
+    const lines = [
+        '// Auto-generated by cuttlefish gen-decls. Do not edit.',
+        '// Source: ' + path.basename(filePath),
+        '// C names are preserved verbatim; calls lower 1-to-1 to the C header.',
+        '',
+    ];
+    // Standalone type aliases for cross-header references (e.g. esp_err_t).
+    for (const a of aliasesToEmit) {
+        lines.push(`export type ${a} = number;`);
+    }
+    if (aliasesToEmit.length > 0)
+        lines.push('');
+    // Typedefs (enums, structs, opaque handles, aliases, function pointers).
+    for (const td of header.typedefs) {
+        lines.push(...emitTypedef(td), '');
+    }
+    // #define constants (integer/string literals only).
+    for (const d of header.defines) {
+        lines.push(`export const ${d.name}: ${/^"/.test(d.value) ? 'string' : 'number'} = ${d.value};`);
+    }
+    if (header.defines.length > 0)
+        lines.push('');
+    // Free functions, named 1-to-1 with the C header.
+    for (const fn of header.functions) {
+        lines.push(emitFunction(fn));
+    }
+    const outPath = outputPath ?? filePath.replace(/\.h$/i, '.d.ts');
+    const outContent = lines.join('\n') + '\n';
+    if (!fs.existsSync(outPath) || fs.readFileSync(outPath, 'utf8') !== outContent) {
+        fs.writeFileSync(outPath, outContent, 'utf8');
+    }
+    return outPath;
+}

package/dist/libdef/component-decls.d.ts

@@ -0,0 +1,2 @@
+export { generateComponentDeclsForProject } from "./cpp-to-decl.js";
+export type { ComponentScanRoots } from "./component-discovery.js";

package/dist/libdef/component-decls.js

@@ -0,0 +1,6 @@
+// Public barrel for component declaration generation.
+//
+// framework-esp32 imports `generateComponentDeclsForProject` from here so its
+// dependency on cuttlefish is declared through the package exports map rather
+// than a deep relative path. Spec: 2026-07-19-framework-esp32-components-design.md
+export { generateComponentDeclsForProject } from "./cpp-to-decl.js";

package/dist/libdef/component-discovery.d.ts

@@ -0,0 +1,43 @@
+export interface ComponentScanRoots {
+    /** Subdirectory names under managed_components/ (e.g. espressif__esp_wifi). */
+    managed: string[];
+    /** Absolute paths to local component directories. */
+    local: string[];
+    /**
+     * ESP-IDF built-in component names (e.g. esp_wifi). Resolved against
+     * `idfRoot/components/<name>/include/` when idfRoot is provided; ignored
+     * otherwise (the caller is responsible for passing idfRoot when builtins
+     * are present).
+     */
+    builtin: string[];
+    /** Optional ESP-IDF install root for resolving `builtin` names. */
+    idfRoot?: string;
+}
+/**
+ * A discovered header plus the directory its generated .d.ts should land in.
+ *
+ * `outputDir` is alongside the header for managed/local components (so the
+ * .d.ts lives in the same gitignored component dir, regenerated on each run).
+ * For built-in components it's a project-local cache — NEVER write into the
+ * IDF install itself.
+ */
+export interface DiscoveredHeader {
+    /** Absolute path to the source .h file. */
+    path: string;
+    /** Absolute directory where the generated .d.ts should be written. */
+    outputDir: string;
+}
+/**
+ * Find all .h files for the declared components.
+ *
+ * - managed: scan `managed_components/<name>/include/` (falling back to the
+ *   component dir if no include/ exists). Populated by `idf.py reconfigure`.
+ * - local: scan `<path>/include/` (or `<path>/`).
+ * - builtin: scan `<idfRoot>/components/<name>/include/` (IDF ships with these).
+ *
+ * For builtins the output .d.ts goes to `<projectDir>/.cuttlefish/component-decls/<component>/`
+ * — never into `$IDF_PATH/components/`, which would pollute the IDF install.
+ *
+ * Returned entries are unsorted — the caller decides ordering.
+ */
+export declare function discoverComponentHeaders(projectDir: string, roots: ComponentScanRoots): DiscoveredHeader[];

package/dist/libdef/component-discovery.js

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** Walk a directory recursively, returning all .h files. */
+function walkHeaders(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(cur);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const full = join(cur, name);
+            try {
+                const st = statSync(full);
+                if (st.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (name.toLowerCase().endsWith('.h')) {
+                    out.push(full);
+                }
+            }
+            catch {
+                // Stat failed (race); skip.
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Find all .h files for the declared components.
+ *
+ * - managed: scan `managed_components/<name>/include/` (falling back to the
+ *   component dir if no include/ exists). Populated by `idf.py reconfigure`.
+ * - local: scan `<path>/include/` (or `<path>/`).
+ * - builtin: scan `<idfRoot>/components/<name>/include/` (IDF ships with these).
+ *
+ * For builtins the output .d.ts goes to `<projectDir>/.cuttlefish/component-decls/<component>/`
+ * — never into `$IDF_PATH/components/`, which would pollute the IDF install.
+ *
+ * Returned entries are unsorted — the caller decides ordering.
+ */
+export function discoverComponentHeaders(projectDir, roots) {
+    const headers = [];
+    for (const name of roots.managed) {
+        const base = join(projectDir, 'managed_components', name);
+        const includeDir = join(base, 'include');
+        const dir = existsSync(includeDir) ? includeDir : base;
+        for (const h of walkHeaders(dir)) {
+            headers.push({ path: h, outputDir: dir });
+        }
+    }
+    for (const localPath of roots.local) {
+        const includeDir = join(localPath, 'include');
+        const dir = existsSync(includeDir) ? includeDir : localPath;
+        for (const h of walkHeaders(dir)) {
+            headers.push({ path: h, outputDir: dir });
+        }
+    }
+    if (roots.idfRoot) {
+        for (const name of roots.builtin) {
+            const base = join(roots.idfRoot, 'components', name);
+            const includeDir = join(base, 'include');
+            const dir = existsSync(includeDir) ? includeDir : base;
+            // Project-local cache for builtins. Mirrors the include/ layout so
+            // imports can substitute `managed_components/<name>/include/X.d.ts`
+            // patterns. Each header's .d.ts is named after the header basename.
+            const outDir = join(projectDir, '.cuttlefish', 'component-decls', name);
+            if (!existsSync(outDir))
+                mkdirSync(outDir, { recursive: true });
+            for (const h of walkHeaders(dir)) {
+                headers.push({ path: h, outputDir: outDir });
+            }
+        }
+    }
+    return headers;
+}

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

@@ -32,3 +32,12 @@ export declare function generateDeclsForDirectory(dir: string, recursive?: boole
  * a later step for the directory-scan path.
  */
 export declare function generateDecl(filePath: string, outputPath?: string): string | null;
+import { type ComponentScanRoots } from "./component-discovery.js";
+/**
+ * Generate .d.ts declarations for every declared component's headers,
+ * picking the C or C++ emitter per header based on whether it declares classes.
+ *
+ * Returns the list of created/updated .d.ts paths (headers that produced no
+ * declarations are skipped).
+ */
+export declare function generateComponentDeclsForProject(projectDir: string, roots: ComponentScanRoots): string[];

package/dist/libdef/cpp-to-decl.js

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseHeader } from "./header-parser.js";
 import { buildClassIndex, BaseClassResolver } from "./base-class-resolver.js";
+import { writeText } from "../utils/fs.js";
 /**
  * Maps C++ types to TypeScript types
  */
@@ -582,3 +583,74 @@ function generateDeclWithResolver(filePath, resolver) {
     }
     return outPath;
 }
+// ─── ESP-IDF component dispatch ───────────────────────────────────────────
+//
+// Picks the C or C++ emitter per header based on whether it declares classes.
+// ESP-IDF components are mostly C (free functions + typedefs); Arduino-style
+// libraries are C++ classes. Spec:
+// docs/superpowers/specs/2026-07-19-framework-esp32-components-design.md
+import { generateCDecl } from "./c-to-decl.js";
+import { discoverComponentHeaders } from "./component-discovery.js";
+/** Heuristic: does this header declare any C++ classes? */
+function hasClasses(headerPath) {
+    try {
+        const content = fs.readFileSync(headerPath, "utf8");
+        return parseHeader(content).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate .d.ts declarations for every declared component's headers,
+ * picking the C or C++ emitter per header based on whether it declares classes.
+ *
+ * Returns the list of created/updated .d.ts paths (headers that produced no
+ * declarations are skipped).
+ */
+export function generateComponentDeclsForProject(projectDir, roots) {
+    const headers = discoverComponentHeaders(projectDir, roots);
+    const created = [];
+    for (const discovered of headers) {
+        // Output path: <outputDir>/<basename>.d.ts. For managed/local this is
+        // alongside the header; for builtins it's the project-local cache dir.
+        const baseName = path.basename(discovered.path).replace(/\.h$/i, '');
+        const outputPath = path.join(discovered.outputDir, baseName + '.d.ts');
+        const out = hasClasses(discovered.path)
+            ? generateDecl(discovered.path, outputPath)
+            : generateCDecl(discovered.path, outputPath);
+        if (out) {
+            created.push(out);
+            // Write a sibling .libdef.json so the import → #include resolver picks
+            // up the real (case-preserving) header name. Without this, the resolver
+            // falls back to toPascalCase(moduleKey) + ".h" — fine for Arduino libs
+            // (Adafruit_GFX → Adafruit_GFX.h, resolved separately) but wrong for
+            // ESP-IDF component headers (esp_wifi → <EspWifi.h>, not <esp_wifi.h>).
+            // The libdef declares the actual header basename ("esp_wifi.h"), which
+            // is the ground truth — the generator just read the file.
+            writeComponentLibdef(discovered.path, outputPath);
+        }
+    }
+    return created;
+}
+/**
+ * Write `<d.ts-basename>.libdef.json` next to a generated component `.d.ts`,
+ * pointing the import → #include resolver at the actual source header.
+ *
+ * The libdef `module` field is the lowercased basename (matches what
+ * `toModuleKey()` produces from an import specifier), and `include` is the
+ * case-preserving `<basename>.h` — quote-wrapped because component headers
+ * are project-local (resolved via the include path), not system angle-bracket
+ * includes. Matches the local-header convention in `resolveLocalModuleHeader`.
+ */
+function writeComponentLibdef(sourceHeaderPath, dtsOutputPath) {
+    const headerBaseName = path.basename(sourceHeaderPath); // e.g. "esp_wifi.h"
+    const dtsBaseName = path.basename(dtsOutputPath, '.d.ts'); // e.g. "esp_wifi"
+    const libdefPath = path.join(path.dirname(dtsOutputPath), `${dtsBaseName}.libdef.json`);
+    const libdef = {
+        module: dtsBaseName.toLowerCase(),
+        include: `"${headerBaseName}"`,
+        source: sourceHeaderPath,
+    };
+    writeText(libdefPath, JSON.stringify(libdef, null, 2) + '\n');
+}

package/dist/libdef/registry.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { listFiles, readText } from "../utils/fs.js";
+import { listFilesRecursive, readText } from "../utils/fs.js";
 import { toModuleKey, toPascalCase } from "../utils/strings.js";
 import { getLoadedFramework, hasLoadedFramework } from "../framework-registry.js";
 function toArchitectureFromFqbn(fqbn) {
@@ -21,7 +21,10 @@ function getLibraryResolver() {
 }
 export function loadLibraryDefinitions(definitionsDir) {
     const registry = new Map();
-    const files = listFiles(definitionsDir, ".libdef.json");
+    // Recursive scan: libdefs may live at the entry dir (single-level convention)
+    // or nested under cache trees like `.cuttlefish/component-decls/<component>/`
+    // (per-component overrides generated alongside .d.ts stubs).
+    const files = listFilesRecursive(definitionsDir, ".libdef.json");
     for (const filePath of files) {
         let def;
         try {