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

package/dist/cli.js

@@ -5,7 +5,8 @@ import { parseCommandLine, printHelp } from "./utils/cli.js";
 import { scaffoldProject, printInitNextSteps, KNOWN_TARGETS } from "./create/index.js";
 import { runInitWizard } from "./create/index.js";
 import { generateLibraryDefinitions, transpileFile } from "./transpile.js";
-import { generateDecl, generateDeclsForDirectory } from "./libdef/cpp-to-decl.js";
+import { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
+import { discoverIdfRootForGenDecls } from "./libdef/idf-discovery.js";
 import { mapCppLocationToTs, readSourceMap, resolveMapPath } from "./mapping/source-map.js";
 import { compileSource, uploadFirmware, monitorDevice } from "./platform/toolchain.js";
 import { resolveStrategy } from "./platform/registry.js";
@@ -49,8 +50,14 @@ async function handleCreate(options) {
                 ? '@typecad/framework-avr'
                 : framework === 'arduino'
                     ? '@typecad/framework-arduino'
-                    : `@typecad/framework-${framework}`;
+                    : framework === 'esp32'
+                        ? '@typecad/framework-esp32'
+                        : `@typecad/framework-${framework}`;
         const projectName = options.projectName || 'my-project';
+        const isEspIdf = frameworkPackage === '@typecad/framework-esp32' || framework === 'esp32';
+        const idfTarget = target.frameworkData?.target
+            ?? target.architecture
+            ?? 'esp32';
         const result = scaffoldProject({
             projectName,
             targetId: target.id,
@@ -60,10 +67,18 @@ async function handleCreate(options) {
             boardPackage: target.boardPackage,
             frameworkPackage,
             framework,
-            buildTarget: target.buildTarget,
+            buildTarget: isEspIdf ? idfTarget : target.buildTarget,
             mcu: target.mcu,
             baudRate: target.isNative ? undefined : (options.baud ?? 9600),
             includeSketch: !options.noSketch,
+            ...(isEspIdf
+                ? {
+                    toolchainType: 'idf',
+                    frameworkData: target.frameworkData ?? { target: idfTarget, buildTarget: idfTarget },
+                }
+                : target.frameworkData
+                    ? { frameworkData: target.frameworkData }
+                    : {}),
         }, options.outDir);
         console.log(`\n${chalk.green("✓")} Created project files:`);
         for (const file of result.createdFiles) {
@@ -250,6 +265,47 @@ async function main() {
         // it intentionally has no inputFile (it scans scanDir instead), so the
         // generic "Missing input file path" check would otherwise block it.
         if (options.command === "gen-decls") {
+            // Check for --components flag (ESP-IDF components: managed + local).
+            // Runs before scanDir/single-file branches; components mode has no
+            // inputFile by design (it scans managed_components/ + components/).
+            const componentsDir = options.componentsDir;
+            if (componentsDir) {
+                ui.printHeader();
+                ui.printStep(`Generating component declarations for ${componentsDir}...`);
+                const config = loadCuttlefishConfig(componentsDir);
+                const frameworkConfig = (config?.frameworkConfig ?? {});
+                const componentsNode = frameworkConfig?.components ?? {};
+                const managedSpecs = Object.keys(componentsNode.managed ?? {});
+                // idf.py stores managed deps as <namespace>__<name> (slashes → __).
+                const managedNames = managedSpecs.map((spec) => spec.replace("/", "__"));
+                const localPaths = (componentsNode.local ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(componentsDir, p));
+                const builtinNames = componentsNode.builtin ?? [];
+                // Built-in components resolve against an ESP-IDF install. The CLI
+                // uses minimal discovery (env var + well-known paths). If no install
+                // is found, builtins are skipped with a notice — the framework-esp32
+                // compile path performs richer discovery and is the primary entry
+                // point for builtin gen-decls.
+                const idfRoot = discoverIdfRootForGenDecls();
+                if (builtinNames.length > 0 && !idfRoot) {
+                    ui.printInfo('components.builtin declared but no ESP-IDF install was found; skipping builtin headers. ' +
+                        'Run via `cuttlefish build --compile` (which performs full IDF discovery) or set $IDF_PATH.');
+                }
+                const created = generateComponentDeclsForProject(componentsDir, {
+                    managed: managedNames,
+                    local: localPaths,
+                    builtin: idfRoot ? builtinNames : [],
+                    idfRoot,
+                });
+                if (created.length === 0) {
+                    ui.printInfo("No component declaration files created.");
+                }
+                else {
+                    ui.printSuccess(`Created ${created.length} declaration file(s):`);
+                    for (const f of created)
+                        ui.printFileCreated(f);
+                }
+                return;
+            }
             // Check for --all flag (scan directory)
             const scanDir = options.scanDir;
             if (scanDir) {
@@ -321,6 +377,47 @@ async function main() {
         // ── Load cuttlefish.config.ts (config wins over CLI flags) ──────────
         const inputDir = path.dirname(path.resolve(options.inputFile));
         const config = loadCuttlefishConfig(inputDir);
+        // ── Pre-transpile: generate component .d.ts stubs ───────────────────
+        // The transpile type-check needs the .d.ts imports in main.ts to resolve.
+        // For ESP-IDF builtin/managed/local components, those .d.ts files are
+        // generated by gen-decls — so we must run it BEFORE type-checking, not
+        // only as part of --compile. The cache is written under the transpile
+        // output dir (the same path --compile uses), so user imports resolve
+        // identically in both flows.
+        if (config?.frameworkConfig) {
+            const fc = config.frameworkConfig;
+            const componentsNode = fc?.components ?? {};
+            const managedSpecs = Object.keys(componentsNode.managed ?? {});
+            const localPaths = (componentsNode.local ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(inputDir, p));
+            const builtinNames = componentsNode.builtin ?? [];
+            if (managedSpecs.length > 0 || localPaths.length > 0 || builtinNames.length > 0) {
+                // Resolve the transpile output dir — the cache lives under it so the
+                // framework's compile path and this pre-transpile pass agree on location.
+                // output.outDir in config is relative to the project root (inputDir);
+                // if absent, the transpile output goes alongside the entry file.
+                const outBase = config.outputOutDir
+                    ? path.resolve(inputDir, config.outputOutDir)
+                    : inputDir;
+                // For builtins we need IDF_PATH. Use cuttlefish's minimal discovery
+                // (env var + well-known paths) — full discovery is done by
+                // framework-esp32 at --compile time. If no install is found,
+                // builtins are skipped; --compile will regenerate them.
+                const idfRoot = discoverIdfRootForGenDecls();
+                try {
+                    generateComponentDeclsForProject(outBase, {
+                        managed: managedSpecs.map((s) => s.replace('/', '__')),
+                        local: localPaths,
+                        builtin: idfRoot ? builtinNames : [],
+                        idfRoot,
+                    });
+                }
+                catch {
+                    // Non-fatal: if gen-decls fails (e.g. component not yet fetched),
+                    // the type-checker will surface the missing-import errors with
+                    // clearer context than crashing here.
+                }
+            }
+        }
         // Load the UI engine (if @typecad/ui is installed) before any UI work.
         await loadUIEngine();
         let effectivePlatformContext = options.platformContext;
@@ -343,9 +440,17 @@ async function main() {
             }
             let configBuildTarget = config.buildTarget;
             if (configBuildTarget) {
+                // Reconstruct frameworkData from buildTarget, preserving other fields
+                // (psram, components, etc.) from the resolved frameworkConfig so the
+                // transpile-time diagnostics (e.g. scroll-canvas-memory PSRAM budget)
+                // and the toolchain both see the full frameworkData, not just buildTarget.
+                const fcPsram = config.frameworkConfig?.psram;
                 effectivePlatformContext = {
                     architecture: configBuildTarget.split(":")?.[1]?.toLowerCase(),
-                    frameworkData: { buildTarget: configBuildTarget },
+                    frameworkData: {
+                        buildTarget: configBuildTarget,
+                        ...(fcPsram ? { psram: fcPsram } : {}),
+                    },
                 };
             }
             if (config.outputOutDir && !options.outDir) {

package/dist/config-loader.js

@@ -9,6 +9,12 @@
 import path from "node:path";
 import fs from "node:fs";
 import ts from "typescript";
+/** True for the framework-esp32 package or any path that resolves to it.
+ *  Used to decide whether to route frameworkData → frameworkConfig so the
+ *  ESP-IDF toolchain can read components, target, etc. */
+function isEspIdfFramework(framework) {
+    return framework === "@typecad/framework-esp32" || framework.endsWith("framework-esp32");
+}
 import { safeValidateConfig } from "./config-schema.js";
 /** The filename we search for when walking up directories. */
 const CONFIG_FILENAME = "cuttlefish.config.ts";
@@ -323,8 +329,21 @@ export function parseConfigFile(configPath) {
     if (outputDefines)
         resolved.outputDefines = outputDefines;
     const nativeSection = extractFrameworkSection(configObject, "native");
-    if (nativeSection)
+    if (nativeSection) {
         resolved.frameworkConfig = nativeSection;
+    }
+    else if (resolved.framework && isEspIdfFramework(resolved.framework)) {
+        // ESP-IDF: route frameworkData through frameworkConfig so the toolchain
+        // can read components, target, and other framework-specific fields.
+        // extractFrameworkSection walks the AST and preserves nested shapes
+        // (components.managed, components.local, etc.).
+        const frameworkData = configObject
+            ? extractFrameworkSection(configObject, "frameworkData")
+            : undefined;
+        if (frameworkData) {
+            resolved.frameworkConfig = frameworkData;
+        }
+    }
     // Parse display profile config (nested object with profile name, wiring, touch)
     const displaySection = extractFrameworkSection(configObject, "display");
     if (displaySection)

package/dist/config-schema.d.ts

@@ -41,16 +41,16 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         buildTarget: z.ZodOptional<z.ZodString>;
         board: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
     }, {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
@@ -83,6 +83,12 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     frameworkData?: Record<string, unknown> | undefined;
     target?: string | undefined;
+    board?: string | undefined;
+    exclude?: string[] | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
     framework?: string | undefined;
     native?: Record<string, unknown> | undefined;
     output?: {
@@ -92,20 +98,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
     mcu?: string | undefined;
     include?: string[] | undefined;
     entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
     contract?: string | undefined;
-    exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
@@ -117,6 +117,12 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     frameworkData?: Record<string, unknown> | undefined;
     target?: string | undefined;
+    board?: string | undefined;
+    exclude?: string[] | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
     framework?: string | undefined;
     native?: Record<string, unknown> | undefined;
     output?: {
@@ -126,20 +132,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
     mcu?: string | undefined;
     include?: string[] | undefined;
     entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
     contract?: string | undefined;
-    exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
@@ -151,6 +151,12 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     frameworkData?: Record<string, unknown> | undefined;
     target?: string | undefined;
+    board?: string | undefined;
+    exclude?: string[] | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
     framework?: string | undefined;
     native?: Record<string, unknown> | undefined;
     output?: {
@@ -160,20 +166,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
     mcu?: string | undefined;
     include?: string[] | undefined;
     entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
     contract?: string | undefined;
-    exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;
@@ -185,6 +185,12 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
     frameworkData?: Record<string, unknown> | undefined;
     target?: string | undefined;
+    board?: string | undefined;
+    exclude?: string[] | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
+    } | undefined;
     framework?: string | undefined;
     native?: Record<string, unknown> | undefined;
     output?: {
@@ -194,20 +200,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
     mcu?: string | undefined;
     include?: string[] | undefined;
     entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
     contract?: string | undefined;
-    exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
+        port?: string | undefined;
+        buildTarget?: string | undefined;
         baudRate?: number | undefined;
         include?: string[] | undefined;
         timeout?: number | undefined;

package/dist/create/board-spec.d.ts

@@ -40,6 +40,7 @@ export declare const BoardSpecSchema: z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         gpio: number;
         capabilities: "FULL_GPIO" | "FULL_GPIO_ANALOG" | "FULL_GPIO_TOUCH" | "FULL_GPIO_ANALOG_TOUCH" | "FULL_GPIO_DAC" | "INPUT_ONLY";
+        notes?: string | undefined;
         functions?: {
             type: "i2c" | "spi" | "uart" | "adc" | "dac" | "pwm" | "touch" | "usb";
             instance: number;
@@ -48,11 +49,11 @@ export declare const BoardSpecSchema: z.ZodObject<{
         alt?: string[] | undefined;
         warnings?: string[] | undefined;
         unsafe?: boolean | undefined;
-        notes?: string | undefined;
         onboardLed?: boolean | undefined;
     }, {
         gpio: number;
         capabilities: "FULL_GPIO" | "FULL_GPIO_ANALOG" | "FULL_GPIO_TOUCH" | "FULL_GPIO_ANALOG_TOUCH" | "FULL_GPIO_DAC" | "INPUT_ONLY";
+        notes?: string | undefined;
         functions?: {
             type: "i2c" | "spi" | "uart" | "adc" | "dac" | "pwm" | "touch" | "usb";
             instance: number;
@@ -61,7 +62,6 @@ export declare const BoardSpecSchema: z.ZodObject<{
         alt?: string[] | undefined;
         warnings?: string[] | undefined;
         unsafe?: boolean | undefined;
-        notes?: string | undefined;
         onboardLed?: boolean | undefined;
     }>, "many">;
     unsafe: z.ZodArray<z.ZodString, "many">;
@@ -436,6 +436,7 @@ export declare const BoardSpecSchema: z.ZodObject<{
     pins: {
         gpio: number;
         capabilities: "FULL_GPIO" | "FULL_GPIO_ANALOG" | "FULL_GPIO_TOUCH" | "FULL_GPIO_ANALOG_TOUCH" | "FULL_GPIO_DAC" | "INPUT_ONLY";
+        notes?: string | undefined;
         functions?: {
             type: "i2c" | "spi" | "uart" | "adc" | "dac" | "pwm" | "touch" | "usb";
             instance: number;
@@ -444,7 +445,6 @@ export declare const BoardSpecSchema: z.ZodObject<{
         alt?: string[] | undefined;
         warnings?: string[] | undefined;
         unsafe?: boolean | undefined;
-        notes?: string | undefined;
         onboardLed?: boolean | undefined;
     }[];
     analog: string[];
@@ -568,6 +568,7 @@ export declare const BoardSpecSchema: z.ZodObject<{
     pins: {
         gpio: number;
         capabilities: "FULL_GPIO" | "FULL_GPIO_ANALOG" | "FULL_GPIO_TOUCH" | "FULL_GPIO_ANALOG_TOUCH" | "FULL_GPIO_DAC" | "INPUT_ONLY";
+        notes?: string | undefined;
         functions?: {
             type: "i2c" | "spi" | "uart" | "adc" | "dac" | "pwm" | "touch" | "usb";
             instance: number;
@@ -576,7 +577,6 @@ export declare const BoardSpecSchema: z.ZodObject<{
         alt?: string[] | undefined;
         warnings?: string[] | undefined;
         unsafe?: boolean | undefined;
-        notes?: string | undefined;
         onboardLed?: boolean | undefined;
     }[];
     analog: string[];

package/dist/create/init-scaffold.d.ts

@@ -10,6 +10,9 @@ export interface KnownTarget {
     framework: string;
     buildTarget?: string;
     mcu?: string;
+    /** Framework-specific config (becomes frameworkData in cuttlefish.config.ts).
+     *  Used by framework-esp32 to carry `target: 'esp32'|'esp32s3'|'esp32c3'|'esp32c6'`. */
+    frameworkData?: Record<string, unknown>;
 }
 export declare function registerKnownTarget(target: KnownTarget): void;
 export declare const KNOWN_TARGETS: ReadonlyArray<KnownTarget>;

package/dist/create/init-scaffold.js

@@ -33,6 +33,18 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32',
         mcu: 'esp32',
     },
+    {
+        id: 'esp32-devkit-idf',
+        displayName: 'ESP32 DevKit (native ESP-IDF)',
+        isNative: false,
+        architecture: 'esp32',
+        boardPackage: '@typecad/board-esp32-devkit',
+        frameworkPackage: '@typecad/framework-esp32',
+        framework: 'esp32',
+        buildTarget: 'esp32:esp32:esp32',
+        mcu: 'esp32',
+        frameworkData: { target: 'esp32' },
+    },
     {
         id: 'esp32s3',
         displayName: 'ESP32-S3',
@@ -44,6 +56,18 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32s3',
         mcu: 'esp32s3',
     },
+    {
+        id: 'esp32s3-idf',
+        displayName: 'ESP32-S3 (native ESP-IDF)',
+        isNative: false,
+        architecture: 'esp32s3',
+        boardPackage: '@typecad/board-esp32s3',
+        frameworkPackage: '@typecad/framework-esp32',
+        framework: 'esp32',
+        buildTarget: 'esp32:esp32:esp32s3',
+        mcu: 'esp32s3',
+        frameworkData: { target: 'esp32s3' },
+    },
     {
         id: 'esp32c3',
         displayName: 'ESP32-C3',
@@ -55,6 +79,18 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32c3',
         mcu: 'esp32c3',
     },
+    {
+        id: 'esp32c3-idf',
+        displayName: 'ESP32-C3 (native ESP-IDF)',
+        isNative: false,
+        architecture: 'esp32c3',
+        boardPackage: '@typecad/board-esp32c3',
+        frameworkPackage: '@typecad/framework-esp32',
+        framework: 'esp32',
+        buildTarget: 'esp32:esp32:esp32c3',
+        mcu: 'esp32c3',
+        frameworkData: { target: 'esp32c3' },
+    },
     {
         id: 'esp32c6',
         displayName: 'ESP32-C6',
@@ -66,6 +102,18 @@ const _knownTargets = [
         buildTarget: 'esp32:esp32:esp32c6',
         mcu: 'esp32c6',
     },
+    {
+        id: 'esp32c6-idf',
+        displayName: 'ESP32-C6 (native ESP-IDF)',
+        isNative: false,
+        architecture: 'esp32c6',
+        boardPackage: '@typecad/board-esp32c6',
+        frameworkPackage: '@typecad/framework-esp32',
+        framework: 'esp32',
+        buildTarget: 'esp32:esp32:esp32c6',
+        mcu: 'esp32c6',
+        frameworkData: { target: 'esp32c6' },
+    },
     {
         id: 'rp2040',
         displayName: 'RP2040 (Pico)',

package/dist/create/init-templates.d.ts

@@ -13,6 +13,8 @@ export interface InitProjectOptions {
     baudRate?: number;
     includeSketch: boolean;
     toolchainType?: string;
+    /** Extra frameworkData fields (e.g. `{ target: 'esp32s3' }` for framework-esp32). */
+    frameworkData?: Record<string, unknown>;
 }
 export declare function generateProjectPackageJson(options: InitProjectOptions): string;
 export declare function generateProjectTsconfig(options: InitProjectOptions): string;

package/dist/create/init-templates.js

@@ -150,8 +150,26 @@ export default config;
 `;
     }
     const buildTarget = options.buildTarget;
-    const resolvedToolchain = options.toolchainType ?? 'arduino-cli';
-    const buildTargetLine = buildTarget ? `\n  // Framework data\n  frameworkData: {\n    buildTarget: '${buildTarget}',\n  },` : '';
+    const isEspIdf = options.frameworkPackage === '@typecad/framework-esp32'
+        || options.framework === 'esp32'
+        || options.toolchainType === 'idf';
+    const resolvedToolchain = options.toolchainType
+        ?? (isEspIdf ? 'idf' : 'arduino-cli');
+    // framework-esp32 wants IDF chip ids in frameworkData (target + buildTarget),
+    // not Arduino FQBNs. Known IDF targets already set frameworkData.target;
+    // wizard/CLI may still pass an FQBN in buildTarget — normalize to the last segment.
+    let frameworkDataBlock = '';
+    if (isEspIdf) {
+        const idfTarget = options.frameworkData?.target
+            ?? options.frameworkData?.buildTarget
+            ?? (buildTarget?.includes(':') ? buildTarget.split(':').filter(Boolean).pop() : buildTarget)
+            ?? options.architecture
+            ?? 'esp32';
+        frameworkDataBlock = `\n  // Framework data (IDF chip target)\n  frameworkData: {\n    target: '${idfTarget}',\n    buildTarget: '${idfTarget}',\n  },`;
+    }
+    else if (buildTarget) {
+        frameworkDataBlock = `\n  // Framework data\n  frameworkData: {\n    buildTarget: '${buildTarget}',\n  },`;
+    }
     const mcuLine = options.mcu
         ? `\n  // MCU package — provides silicon-level pin definitions\n  mcu: '${options.mcu.startsWith('@') ? options.mcu : `@typecad/mcu-${options.mcu}`}',\n`
         : '';
@@ -181,7 +199,7 @@ const config: CuttlefishConfig = {
   target: '${options.architecture}',${mcuLine}${boardLine}
 
   // Framework package — controls code generation strategy
-  framework: '${options.frameworkPackage}',${buildTargetLine}
+  framework: '${options.frameworkPackage}',${frameworkDataBlock}
 
   // Output / build options
   output: {
@@ -508,11 +526,13 @@ export default [
     files: ["src/**/*.ts"],
     languageOptions: {
       parser: tsparser,
-      parserOptions: {
-        // Type-aware parsing so @typescript-eslint/no-explicit-any resolves
-        // imported bindings to their real types instead of defaulting to any.
-        project: "./tsconfig.json",
-      },
+      // NOTE: do NOT set parserOptions.project here. None of the rules below
+      // (no-restricted-syntax, the cuttlefish/* AST rules, no-explicit-any,
+      // no-eval, ...) consume type information, so enabling type-aware linting
+      // only forces ESLint to build a full TS type-program per file — ~3.4s of
+      // pure overhead on small projects with zero change to what is detected.
+      // If a future rule needs types, scope project to that rule only via
+      // parserOptions on a dedicated config block, not globally.
     },
     plugins: {
       "@typescript-eslint": tseslint,

package/dist/create/init-wizard.js

@@ -94,6 +94,11 @@ export async function runInitWizard(partialOptions) {
             if (target.architecture === 'avr') {
                 frameworkOptions.push({ label: "Bare-metal AVR (PORTB, etc.)", value: 'avr', pkg: '@typecad/framework-avr' });
             }
+            // ESP32 family: offer the native ESP-IDF flavor alongside Arduino.
+            if (target.architecture === 'esp32' || target.architecture === 'esp32s3'
+                || target.architecture === 'esp32c3' || target.architecture === 'esp32c6') {
+                frameworkOptions.push({ label: "ESP32 (native ESP-IDF)", value: 'esp32', pkg: '@typecad/framework-esp32' });
+            }
             if (partialOptions?.framework) {
                 const match = frameworkOptions.find(f => f.value === partialOptions.framework);
                 framework = match?.value ?? partialOptions.framework;
@@ -141,6 +146,10 @@ export async function runInitWizard(partialOptions) {
         else {
             includeSketch = await promptConfirm(rl, "Create starter sketch?", true);
         }
+        const isEspIdf = frameworkPackage === '@typecad/framework-esp32' || framework === 'esp32';
+        const idfTarget = target.frameworkData?.target
+            ?? target.architecture
+            ?? 'esp32';
         return {
             projectName,
             targetId: target.id,
@@ -150,10 +159,20 @@ export async function runInitWizard(partialOptions) {
             boardPackage: target.boardPackage,
             frameworkPackage,
             framework,
-            buildTarget: target.buildTarget,
+            buildTarget: isEspIdf ? idfTarget : target.buildTarget,
             mcu: target.mcu,
             baudRate,
             includeSketch,
+            ...(isEspIdf
+                ? {
+                    toolchainType: 'idf',
+                    frameworkData: target.frameworkData?.target
+                        ? { ...target.frameworkData }
+                        : { target: idfTarget, buildTarget: idfTarget },
+                }
+                : target.frameworkData
+                    ? { frameworkData: target.frameworkData }
+                    : {}),
         };
     }
     catch (err) {

package/dist/emit/cpp-emitter.js

@@ -1,5 +1,5 @@
 import { buildEmitterContext } from "./emitters/setup.js";
-import { emitPreamble } from "./emitters/output-finalizer.js";
+import { emitPreamble, emitAsyncTaskClasses, finalizeOutput } from "./emitters/output-finalizer.js";
 import { runTopLevelPreprocessing } from "./emitters/top-level-prep.js";
 import { synthesizeEntrypoints } from "./emitters/entrypoint-synthesizer.js";
 import { emitTypeDeclarations } from "./emitters/type-decl-emitter.js";
@@ -7,7 +7,6 @@ import { emitNamespaces } from "./emitters/namespace-emitter.js";
 import { emitClasses } from "./emitters/class-emitter.js";
 import { emitPostClassDeclarations, emitCallbackFunctions, emitFunctions, emitFunctionForwardDeclarations } from "./emitters/function-emitter-impl.js";
 import { emitUIRuntime } from "./emitters/ui-emitter.js";
-import { finalizeOutput } from "./emitters/output-finalizer.js";
 const globalEnumNames = new Set();
 const globalLargeEnumNames = new Set();
 export function registerAllEnumNames(enums) {
@@ -21,7 +20,7 @@ export function registerAllEnumNames(enums) {
 export function emitCpp(program, options) {
     // 1. Build shared emitter context (strategy, renderers, analysis, etc.)
     const ctx = buildEmitterContext(program, options);
-    // 2. Emit preamble (includes, polyfills, async task classes, shims)
+    // 2. Emit preamble (includes, polyfills, shims) — async task classes deferred
     emitPreamble(ctx);
     // 2.5. Emit UI runtime (header structs + static tables) — entry file only,
     //      when a UI is mounted. File-scope, must precede any function using it.
@@ -32,6 +31,8 @@ export function emitCpp(program, options) {
     synthesizeEntrypoints(ctx);
     // 5. Emit type declarations (enums, type aliases, interfaces, top-level constants)
     emitTypeDeclarations(ctx);
+    // 5.5. Async state machines — after globals so WIFI_SSID etc. are in scope
+    emitAsyncTaskClasses(ctx);
     // 6. Emit namespaces
     emitNamespaces(ctx);
     // 6.5. Emit function forward declarations (split mode — must precede class definitions)

package/dist/emit/emitters/emitter-context.d.ts

@@ -56,6 +56,11 @@ export interface CallbackFunction {
     params: string[];
     statements: StatementIR[];
     debounceMs?: number;
+    /**
+     * True for GPIO / hardware ISR callbacks only. WiFi event handlers, timers,
+     * and setInterval use the same hoist path but must NOT get IRAM_ATTR.
+     */
+    isInterruptHandler?: boolean;
     /**
      * Return type of the synthesized free function. Defaults to "void" (the
      * historical ISR/HAL-callback case). Populated from a hoisted lambda's