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

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

@@ -13,12 +13,16 @@ 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;
 export declare function generateProjectConfig(options: InitProjectOptions): string;
 export declare function generateProjectEnvDts(options: InitProjectOptions): string;
 export declare function generateStarterSketch(options: InitProjectOptions): string;
+export declare function generateStarterTest(_options: InitProjectOptions): string;
+export declare function generateStarterSim(options: InitProjectOptions): string;
 export declare function generateBoardForwardingFile(boardPackage: string): string;
 export declare function generateGitignore(_options: InitProjectOptions): string;
 export declare function generateEslintConfig(_options: InitProjectOptions): string;

package/dist/create/init-templates.js

@@ -2,11 +2,11 @@ import { LINT_RULES } from '../ir/feature-registry.js';
 export function generateProjectPackageJson(options) {
     const { projectName, frameworkPackage, boardPackage } = options;
     const deps = {
-        "@typecad/cuttlefish": "^0.1.0-alpha.1",
-        [frameworkPackage]: "^0.1.0-alpha.1",
+        "@typecad/cuttlefish": "^1.0.0-alpha.3",
+        [frameworkPackage]: "^1.0.0-alpha.3",
     };
     if (boardPackage) {
-        deps[boardPackage] = "^0.1.0-alpha.1";
+        deps[boardPackage] = "^1.0.0-alpha.3";
     }
     const depsJson = Object.entries(deps)
         .map(([k, v]) => `    "${k}": "${v}"`)
@@ -15,12 +15,27 @@ export function generateProjectPackageJson(options) {
     // eslint-transpiler-rules plugin (which is plain JS, no dep). Without these
     // devDependencies `npm run lint` fails to resolve the parser/plugin in a
     // freshly created project. Versions mirror the repo demo's package.json.
-    const devDepsJson = [
+    const baseDevDeps = [
         '    "eslint": "^10.4.1"',
         '    "@typescript-eslint/parser": "^8.61.0"',
         '    "@typescript-eslint/eslint-plugin": "^8.61.0"',
-    ].join(',\n');
+    ];
+    // Developer-utility scripts shared by every target (native + embedded).
+    // None require hardware or extra dependencies:
+    //   dev        — auto-retranspile on save (transpile-only; append --compile
+    //                to also compile on each change). The fast "does it
+    //                typecheck" feedback loop.
+    //   gen-decls  — generate TypeScript .d.ts from C++ headers. File-argument:
+    //                `npm run gen-decls -- lib/foo.h` or `-- --all lib/`.
+    //   gen-libdefs — generate library-definition stubs from a TS file's imports.
+    //                File-argument: `npm run gen-libdefs -- src/main.ts`.
+    const devScripts = [
+        '"dev": "cuttlefish build --watch"',
+        '"gen-decls": "cuttlefish gen-decls"',
+        '"gen-libdefs": "cuttlefish gen-libdefs"',
+    ];
     if (options.isNative) {
+        const devDepsJson = baseDevDeps.join(',\n');
         return `{
   "name": "${projectName}",
   "version": "1.0.0",
@@ -28,7 +43,8 @@ export function generateProjectPackageJson(options) {
   "scripts": {
     "build": "cuttlefish build",
     "compile": "cuttlefish build --compile",
-    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/",
+    ${devScripts.join(',\n    ')}
   },
   "dependencies": {
 ${depsJson}
@@ -39,6 +55,19 @@ ${devDepsJson}
 }
 `;
     }
+    // Embedded projects get two host-side testing tiers:
+    //  - @typecad/expect: hardware tests run on the board via cuttlefish-test
+    //    (`npm run test:hw`), scoped to tests/**/*.test.ts.
+    //  - @typecad/simulator + vitest: simulate the board in Node (`npm run
+    //    simulate`), scoped to sim/**/*.test.ts so vitest never collides with the
+    //    @typecad/expect no-op stubs under tests/.
+    // Versions mirror the workspace's published releases / root devDeps.
+    const devDepsJson = [
+        ...baseDevDeps,
+        '    "@typecad/expect": "^1.0.0-alpha.3"',
+        '    "@typecad/simulator": "^1.0.0-alpha.3"',
+        '    "vitest": "^4.0.18"',
+    ].join(',\n');
     return `{
   "name": "${projectName}",
   "version": "1.0.0",
@@ -48,7 +77,10 @@ ${devDepsJson}
     "compile": "cuttlefish build --compile",
     "upload": "cuttlefish build --compile --upload",
     "monitor": "cuttlefish build --compile --upload --monitor",
-    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+    "test:hw": "npm exec -- cuttlefish-test",
+    "simulate": "vitest run sim/",
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/",
+    ${devScripts.join(',\n    ')}
   },
   "dependencies": {
 ${depsJson}
@@ -85,9 +117,10 @@ export function generateProjectTsconfig(options) {
     "noEmit": true,
     "resolveJsonModule": true,
     "allowArbitraryExtensions": true,
+    "allowImportingTsExtensions": true,
     "rootDirs": ["src", "types"]${paths}
   },
-  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts"${options.boardPackage ? ', ".cuttlefish/cuttlefish-env.d.ts"' : ''}]
+  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts"${options.boardPackage ? ', ".cuttlefish/cuttlefish-env.d.ts"' : ''}${options.isNative ? '' : ', "sim/**/*.ts"'}]
 }
 `;
 }
@@ -117,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`
         : '';
@@ -127,6 +178,11 @@ export default config;
         : '';
     const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
     const baudLine = options.baudRate ? `\n\n  // Console polyfill configuration\n  console: {\n    baudRate: ${options.baudRate},\n    // Serial port for upload/monitor. Override with --port on the CLI.\n    port: '${portHint}',\n  },` : '';
+    // Hardware test runner configuration — used by \`npm run test:hw\` (cuttlefish-test,
+    // provided by @typecad/expect). It transpiles each tests/**/*.test.ts file,
+    // flashes it to the board, and evaluates the assertions over serial.
+    const resolvedBaud = options.baudRate ?? 115200;
+    const testLine = `\n\n  // Hardware test runner (@typecad/expect / \`npm run test:hw\`)\n  test: {\n    // Serial port for the test board. Override with --port on the CLI or the\n    // CUTTLEFISH_PORT env var (e.g. CUTTLEFISH_PORT=/dev/ttyUSB0 npm run test:hw).\n    port: '${portHint}',\n    baudRate: ${resolvedBaud},\n    timeout: 30000,\n    include: ['tests/**/*.test.ts'],\n  },`;
     return `// ---------------------------------------------------------------------------
 // cuttlefish.config.ts — Project configuration
 //
@@ -143,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: {
@@ -155,7 +211,7 @@ const config: CuttlefishConfig = {
   // Toolchain configuration
   toolchain: {
     type: '${resolvedToolchain}',
-  },${baudLine}
+  },${baudLine}${testLine}
 };
 
 export default config;
@@ -286,6 +342,148 @@ while (true) {
 }
 `;
 }
+export function generateStarterTest(_options) {
+    return `// ---------------------------------------------------------------------------
+// Hardware test — Basics
+//
+// Runs on the board via \`npm run test:hw\` (cuttlefish-test). Each test file is
+// transpiled, flashed to the board, and its assertions are evaluated on the host
+// over serial. Change the serial port in cuttlefish.config.ts (the \`test.port\`
+// field) or override it with the CUTTLEFISH_PORT env var.
+//
+// API: describe(...).it(...).expect(value).<matcher>() chains. Import pin
+// objects from '@typecad/board' to assert on real hardware I/O. Every file ends
+// with done().
+// ---------------------------------------------------------------------------
+
+import { describe, done } from '@typecad/expect';
+
+describe("Basics")
+  .it("adds two numbers")
+  .expect(
+    (() => {
+      const a = 1;
+      let b = 2;
+      return a + b;
+    })
+  ).toBe(3)
+  .it("multiplies two numbers")
+  .expect(
+    (() => {
+      let a = 3;
+      let b = 4;
+      return a * b;
+    })
+  ).toBe(12)
+  .it("reads an array element")
+  .expect(
+    (() => {
+      const data = new Uint8Array([0xAA, 0x10, 0x20]);
+      return data[1];
+    })
+  ).toBe(0x10)
+  .it("clamps a value to a range")
+  .expect(
+    (() => {
+      const value = 2000;
+      return Math.max(0, Math.min(1023, value));
+    })
+  ).toBe(1023);
+
+done();
+`;
+}
+export function generateStarterSim(options) {
+    const boardType = options.targetId;
+    return `// ---------------------------------------------------------------------------
+// Hardware simulation — Button + LED
+//
+// Runs entirely on your computer with \`npm run simulate\` (vitest + the
+// @typecad/simulator package). No board, serial port, or arduino-cli required.
+// The simulator mirrors the pins/peripherals of your ${options.targetDisplayName}
+// (${boardType}); you inject fake inputs and assert on the outputs in Node.
+//
+// This is the fast tier — iterate on logic here, then confirm on real hardware
+// with \`npm run test:hw\` (which flashes tests/ to the board).
+// ---------------------------------------------------------------------------
+
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  createSimBoard,
+  type SimBoard,
+  type SimDigitalPin,
+} from "@typecad/simulator";
+
+// ===========================================================================
+// FIRMWARE LOGIC
+// ---------------------------------------------------------------------------
+// Factor your firmware into a function that takes the simulated pins as
+// arguments. In a real project this same logic runs on the board against real
+// pins — here it runs against the sim board so you can test it without hardware.
+// ===========================================================================
+
+/**
+ * Reads a button and reflects its state on an LED.
+ *
+ * To use your own logic: replace the body of this function with whatever your
+ * firmware does (read a sensor, drive a motor, print to serial, ...). As long
+ * as it only touches pins you pass in, the simulator can exercise it.
+ */
+function reflectButtonOnLed(button: SimDigitalPin, led: SimDigitalPin): void {
+  // The button pin is pulled HIGH (1) at rest and reads LOW (0) when pressed.
+  if (button.isLow()) {
+    led.high();
+  } else {
+    led.low();
+  }
+}
+
+// ===========================================================================
+// TEST BENCH
+// ---------------------------------------------------------------------------
+// \`createSimBoard\` builds an in-memory version of your board. The pin numbers
+// below match the physical pinout. Add the pins/peripherals your firmware uses:
+// board.digital(n), board.analog(n), board.pwm(n), board.serial(n),
+// board.i2c(n), board.spi(n), board.interrupt(n).
+// ===========================================================================
+
+function setupSim(): { board: SimBoard; button: SimDigitalPin; led: SimDigitalPin } {
+  // boardType mirrors the target chosen with \`cuttlefish create\`.
+  const board = createSimBoard({ boardType: "${boardType}" });
+
+  const button = board.digital(2).asInputPullUp();  // button on pin 2 (INPUT_PULLUP)
+  const led = board.digital(13).asOutput(false);    // LED on pin 13
+
+  return { board, button, led };
+}
+
+describe("Button + LED (simulator)", () => {
+  beforeEach(() => {
+    // A fresh board per test keeps state isolated. For a long-running sim you
+    // can call board.reset() between cycles instead.
+  });
+
+  it("keeps the LED off while the button is released", () => {
+    const { button, led } = setupSim();
+
+    // Button at rest: INPUT_PULLUP reads HIGH.
+    reflectButtonOnLed(button, led);
+
+    expect(led.getBitValue()).toBe(0);
+  });
+
+  it("turns the LED on while the button is pressed", () => {
+    const { button, led } = setupSim();
+
+    // Simulate a press: drive the button pin LOW.
+    button.injectValue(0);
+    reflectButtonOnLed(button, led);
+
+    expect(led.getBitValue()).toBe(1);
+  });
+});
+`;
+}
 export function generateBoardForwardingFile(boardPackage) {
     return `// ---------------------------------------------------------------------------
 // .cuttlefish/board.ts — Dynamically generated forwarding board package
@@ -328,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

package/dist/emit/emitters/function-emitter-impl.js

@@ -128,7 +128,12 @@ export function emitCallbackFunctions(ctx) {
             appendSourceLine(ctx, `const unsigned long ${callback.name}_debounce = ${callback.debounceMs};`);
             appendSourceLine(ctx, "");
         }
-        appendSourceLine(ctx, `${strategy.isrFunctionAttribute?.() ?? ""}${renderCallbackSignature(callback)} {`);
+        // IRAM_ATTR only on true ISR definitions. ESP-IDF's IRAM_ATTR uses
+        // __COUNTER__, so putting it on both forward decl and definition assigns
+        // conflicting .iram1.N sections (-Werror=attributes). Non-ISR callbacks
+        // (WiFi events, timers) must not be IRAM-placed either — they call printf.
+        const isrAttr = callback.isInterruptHandler ? (strategy.isrFunctionAttribute?.() ?? "") : "";
+        appendSourceLine(ctx, `${isrAttr}${renderCallbackSignature(callback)} {`);
         if (callback.debounceMs !== undefined && callback.debounceMs > 0) {
             appendSourceLine(ctx, `  volatile unsigned long now = ${strategy.currentTimeMillis()};`);
             appendSourceLine(ctx, `  if (now - ${callback.name}_lastTime < ${callback.name}_debounce) return;`);
@@ -141,10 +146,11 @@ export function emitCallbackFunctions(ctx) {
         appendSourceLine(ctx, "}");
         appendSourceLine(ctx, "");
     }
-    // Split-mode ISR callback forward declarations in header
+    // Split-mode ISR callback forward declarations in header (no IRAM_ATTR —
+    // attribute belongs on the definition only; see comment above).
     if (effectiveEmitMode === "split") {
         for (const callback of ctx.callbackFunctions) {
-            appendHeaderLine(ctx, `${strategy.isrFunctionAttribute?.() ?? ""}${renderCallbackSignature(callback)};`);
+            appendHeaderLine(ctx, `${renderCallbackSignature(callback)};`);
         }
     }
 }
@@ -172,6 +178,10 @@ export function emitFunctions(ctx) {
     // exported functions (which ride along with their definition below).
     for (let fi = 0; fi < mappedFunctions.length; fi++) {
         const fn = mappedFunctions[fi];
+        // Async functions become cooperative *Task state machines (emitAsyncTaskClasses).
+        // Emitting an empty stub here triggers -Wunused-function with no value.
+        if (fn.isAsync && ctx.hasAsyncRuntime)
+            continue;
         const declarationParameterList = ctx.statementRenderer.renderParameters(fn.parameters, true);
         const definitionParameterList = ctx.statementRenderer.renderParameters(fn.parameters, false);
         const readonlyPrefix = fn.isReadonlyReturnType ? "const " : "";
@@ -246,65 +256,60 @@ export function emitFunctions(ctx) {
         if (hasPromiseRuntime && fn.name === asyncDriverFn) {
             appendSourceLine(ctx, "  cuttlefish_pump_microtasks();");
         }
-        if (fn.isAsync && ctx.hasAsyncRuntime) {
-            appendSourceLine(ctx, `  // driven as cooperative task in ${asyncDriverFn}()`);
-        }
-        else {
-            if (fn.typeParameterConstraints) {
-                for (const [param, expr] of fn.typeParameterConstraints) {
-                    appendSourceLine(ctx, `  static_assert(${expr}, "${param} constraint violated");`);
-                }
+        if (fn.typeParameterConstraints) {
+            for (const [param, expr] of fn.typeParameterConstraints) {
+                appendSourceLine(ctx, `  static_assert(${expr}, "${param} constraint violated");`);
             }
-            const functionScope = createChildEmissionScope(topLevelScope, fn.parameters);
-            ctx.cArrayVarNames = ctx.fnCArrayVarNames.get(String(fi)) ?? new Set();
-            const isLoopDriver = fn.name === asyncDriverFn;
-            const lastStmt = fn.statements.length > 0 ? fn.statements[fn.statements.length - 1] : null;
-            const lastIsReturn = lastStmt?.kind === "return";
-            const stmtsToEmit = (isLoopDriver && lastIsReturn)
-                ? fn.statements.slice(0, -1)
-                : fn.statements;
-            for (const statement of stmtsToEmit) {
-                appendRenderedStatement(ctx, statement, "  ", functionScope);
-            }
-            // Drive the UI runtime each frame. Fires only in the driver function when
-            // a UI is mounted (entryHasUI). Uses a separate gate from the async pump
-            // so a pure-UI program (no async/timers) still animates. When the strategy
-            // provides hostEventLoop, the per-frame work runs inside a while loop so a
-            // host target (SDL) can pump events and present between ticks. Emitted
-            // AFTER the function's init statements (ui_init/display_init/touch_init)
-            // so initialization precedes the loop.
-            if (entryHasUI() && fn.name === asyncDriverFn) {
-                const loop = strategy.hostEventLoop?.();
-                if (loop) {
-                    appendSourceLine(ctx, `  bool ${loop.flagName} = true;`);
-                    appendSourceLine(ctx, `  while (${loop.continueCondition}) {`);
-                    appendSourceLine(ctx, `    ${loop.preIteration}`);
-                }
-                appendSourceLine(ctx, `  uint32_t __tc_ui_now = (uint32_t)${strategy.currentTimeMillis()};`);
-                appendSourceLine(ctx, "  static uint32_t __tc_ui_last_tick = __tc_ui_now;");
-                appendSourceLine(ctx, "  uint32_t __tc_ui_delta = __tc_ui_now - __tc_ui_last_tick;");
-                appendSourceLine(ctx, "  __tc_ui_last_tick = __tc_ui_now;");
-                appendSourceLine(ctx, "  if (__tc_ui_delta > 250) __tc_ui_delta = 250;");
-                appendSourceLine(ctx, "  ui_tick((uint16_t)__tc_ui_delta);");
-                if (loop) {
-                    appendSourceLine(ctx, `    ${loop.postIteration}`);
-                    appendSourceLine(ctx, `  }`);
-                }
+        }
+        const functionScope = createChildEmissionScope(topLevelScope, fn.parameters);
+        ctx.cArrayVarNames = ctx.fnCArrayVarNames.get(String(fi)) ?? new Set();
+        const isLoopDriver = fn.name === asyncDriverFn;
+        const lastStmt = fn.statements.length > 0 ? fn.statements[fn.statements.length - 1] : null;
+        const lastIsReturn = lastStmt?.kind === "return";
+        const stmtsToEmit = (isLoopDriver && lastIsReturn)
+            ? fn.statements.slice(0, -1)
+            : fn.statements;
+        for (const statement of stmtsToEmit) {
+            appendRenderedStatement(ctx, statement, "  ", functionScope);
+        }
+        // Drive the UI runtime each frame. Fires only in the driver function when
+        // a UI is mounted (entryHasUI). Uses a separate gate from the async pump
+        // so a pure-UI program (no async/timers) still animates. When the strategy
+        // provides hostEventLoop, the per-frame work runs inside a while loop so a
+        // host target (SDL) can pump events and present between ticks. Emitted
+        // AFTER the function's init statements (ui_init/display_init/touch_init)
+        // so initialization precedes the loop.
+        if (entryHasUI() && fn.name === asyncDriverFn) {
+            const loop = strategy.hostEventLoop?.();
+            if (loop) {
+                appendSourceLine(ctx, `  bool ${loop.flagName} = true;`);
+                appendSourceLine(ctx, `  while (${loop.continueCondition}) {`);
+                appendSourceLine(ctx, `    ${loop.preIteration}`);
             }
-            if (isLoopDriver && (hasPromiseRuntime || asyncTaskClasses.length > 0 || usesTimers)) {
-                const taskNames = asyncTaskClasses.map(t => t.taskVarName);
-                const asyncConfig = strategy.getAsyncRuntimeConfig();
-                asyncConfig.hasPromiseRuntime = hasPromiseRuntime;
-                asyncConfig.hasTimers = usesTimers;
-                const injectionLines = strategy.asyncLoopInjection(taskNames, asyncConfig);
-                for (const line of injectionLines) {
-                    appendSourceLine(ctx, `  ${line}`);
-                }
+            appendSourceLine(ctx, `  uint32_t __tc_ui_now = (uint32_t)${strategy.currentTimeMillis()};`);
+            appendSourceLine(ctx, "  static uint32_t __tc_ui_last_tick = __tc_ui_now;");
+            appendSourceLine(ctx, "  uint32_t __tc_ui_delta = __tc_ui_now - __tc_ui_last_tick;");
+            appendSourceLine(ctx, "  __tc_ui_last_tick = __tc_ui_now;");
+            appendSourceLine(ctx, "  if (__tc_ui_delta > 250) __tc_ui_delta = 250;");
+            appendSourceLine(ctx, "  ui_tick((uint16_t)__tc_ui_delta);");
+            if (loop) {
+                appendSourceLine(ctx, `    ${loop.postIteration}`);
+                appendSourceLine(ctx, `  }`);
             }
-            if (isLoopDriver && lastIsReturn) {
-                appendRenderedStatement(ctx, lastStmt, "  ", functionScope);
+        }
+        if (isLoopDriver && (hasPromiseRuntime || asyncTaskClasses.length > 0 || usesTimers)) {
+            const taskNames = asyncTaskClasses.map(t => t.taskVarName);
+            const asyncConfig = strategy.getAsyncRuntimeConfig();
+            asyncConfig.hasPromiseRuntime = hasPromiseRuntime;
+            asyncConfig.hasTimers = usesTimers;
+            const injectionLines = strategy.asyncLoopInjection(taskNames, asyncConfig);
+            for (const line of injectionLines) {
+                appendSourceLine(ctx, `  ${line}`);
             }
         }
+        if (isLoopDriver && lastIsReturn) {
+            appendRenderedStatement(ctx, lastStmt, "  ", functionScope);
+        }
         appendSourceLine(ctx, "}");
         emitCommentLines(fn.trailingComments, "", (line) => appendSourceLine(ctx, line));
         appendSourceLine(ctx, "");
@@ -338,16 +343,21 @@ export function emitFunctions(ctx) {
 export function emitFunctionForwardDeclarations(ctx) {
     const { strategy, effectiveEmitMode } = ctx;
     const excludedNames = new Set(strategy.forwardDeclarationExclusions?.() ?? []);
-    // ISR callback forward declarations.
+    // Callback forward declarations (no IRAM_ATTR — ESP-IDF's attribute uses
+    // __COUNTER__, so decl+def would get conflicting .iram1.N sections).
     if (effectiveEmitMode !== "split") {
         for (const callback of ctx.callbackFunctions) {
-            appendSourceLine(ctx, `${strategy.isrFunctionAttribute?.() ?? ""}${renderCallbackSignature(callback)};`);
+            appendSourceLine(ctx, `${renderCallbackSignature(callback)};`);
         }
     }
     let emittedAnyFn = false;
     for (const fn of ctx.mappedFunctions) {
         if (excludedNames.has(fn.name))
             continue;
+        // Async functions become *Task classes; calls lower to `fooTask.run()`.
+        // Forward-declaring empty stubs triggers -Wunused-function.
+        if (fn.isAsync && ctx.hasAsyncRuntime)
+            continue;
         const isExported = fn.isExported === true;
         // A function is an entrypoint if it is the strategy's primary entrypoint
         // (e.g. `setup` on Arduino, `main` on native) OR one of the platform's

package/dist/emit/emitters/output-finalizer.d.ts

@@ -1,4 +1,10 @@
 import type { GeneratedOutputs } from "../../types.js";
 import type { EmitterContext } from "./emitter-context.js";
 export declare function emitPreamble(ctx: EmitterContext): void;
+/**
+ * Emit cooperative async state-machine classes. Must run AFTER top-level
+ * globals (emitTypeDeclarations) so identifiers like WIFI_SSID referenced
+ * from task bodies are already declared.
+ */
+export declare function emitAsyncTaskClasses(ctx: EmitterContext): void;
 export declare function finalizeOutput(ctx: EmitterContext): GeneratedOutputs;