@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

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

@@ -311,36 +311,40 @@ export function emitFunctions(ctx) {
         // 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}`);
+        // provides hostEventLoop, the per-frame work — ui_tick AND the async-task
+        // injections below — runs inside a while loop so a driver that is called
+        // once (a main() entrypoint: SDL native, Zephyr's scheduler loop) can pump
+        // events, tick the UI, and advance async tasks every frame. (A repeatedly-
+        // called driver like Arduino's loop() provides no hostEventLoop and the
+        // work stays flat.) Emitted AFTER the function's init statements
+        // (ui_init/display_init/touch_init) so initialization precedes the loop.
+        const hostLoop = entryHasUI() && fn.name === asyncDriverFn
+            ? strategy.hostEventLoop?.()
+            : undefined;
+        if (hostLoop) {
+            appendSourceLine(ctx, `  bool ${hostLoop.flagName} = true;`);
+            appendSourceLine(ctx, `  while (${hostLoop.continueCondition}) {`);
+            if (hostLoop.preIteration) {
+                appendSourceLine(ctx, `    ${hostLoop.preIteration}`);
             }
+        }
+        if (entryHasUI() && fn.name === asyncDriverFn) {
             appendSourceLine(ctx, `  uint32_t __tc_ui_now = static_cast<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(static_cast<uint16_t>(__tc_ui_delta));");
-            if (loop) {
-                appendSourceLine(ctx, `    ${loop.postIteration}`);
-                appendSourceLine(ctx, `  }`);
-            }
         }
         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 injectionIndent = hostLoop ? "    " : "  ";
             // Cooperative scheduler path (Phase 0): when opted in, replace the flat
             // per-frame pump sequence with a single CoopSched dispatch. The work
-            // units mirror exactly what the strategy's asyncLoopInjection() would
+            // units mirror exactly what a strategy's asyncLoopInjection() would
             // have emitted (so Zephyr, which omits the microtask pump, still omits
             // it), but they are dispatched in priority order and budget-bounded.
             if (asyncConfig.enablePriority || asyncConfig.enableTimeBudget) {
@@ -354,16 +358,22 @@ export function emitFunctions(ctx) {
                     // No work units: fall back to the strategy's own injection.
                     const injectionLines = strategy.asyncLoopInjection(taskNames, asyncConfig);
                     for (const line of injectionLines)
-                        appendSourceLine(ctx, `  ${line}`);
+                        appendSourceLine(ctx, `${injectionIndent}${line}`);
                 }
             }
             else {
                 const injectionLines = strategy.asyncLoopInjection(taskNames, asyncConfig);
                 for (const line of injectionLines) {
-                    appendSourceLine(ctx, `  ${line}`);
+                    appendSourceLine(ctx, `${injectionIndent}${line}`);
                 }
             }
         }
+        if (hostLoop) {
+            if (hostLoop.postIteration) {
+                appendSourceLine(ctx, `    ${hostLoop.postIteration}`);
+            }
+            appendSourceLine(ctx, "  }");
+        }
         if (isLoopDriver && lastIsReturn) {
             appendRenderedStatement(ctx, lastStmt, "  ", functionScope);
         }
@@ -400,6 +410,12 @@ export function emitFunctions(ctx) {
 export function emitFunctionForwardDeclarations(ctx) {
     const { strategy, effectiveEmitMode } = ctx;
     const excludedNames = new Set(strategy.forwardDeclarationExclusions?.() ?? []);
+    // Async-method starters: the owning class's method body calls these before
+    // the task class (and this definition) exists later in the TU. The class
+    // forward declarations emitted nearby make the <Class>* parameter valid.
+    for (const starter of ctx.asyncMethodStarters ?? []) {
+        appendSourceLine(ctx, starter.proto);
+    }
     // Callback forward declarations (no IRAM_ATTR — ESP-IDF's attribute uses
     // __COUNTER__, so decl+def would get conflicting .iram1.N sections).
     if (effectiveEmitMode !== "split") {

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

@@ -7,4 +7,11 @@ export declare function emitPreamble(ctx: EmitterContext): void;
  * from task bodies are already declared.
  */
 export declare function emitAsyncTaskClasses(ctx: EmitterContext): void;
+/**
+ * Emit async-METHOD task classes + instances + starter definitions. Must run
+ * AFTER emitClasses (segments dereference _owner->field on the now-complete
+ * owning class) and BEFORE emitFunctions (the loop pump references the
+ * instances; the starter definitions call .start on them).
+ */
+export declare function emitAsyncMethodTasks(ctx: EmitterContext): void;
 export declare function finalizeOutput(ctx: EmitterContext): GeneratedOutputs;

package/dist/emit/emitters/output-finalizer.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { writeText, readText } from "../../utils/fs.js";
 import { makeGeneratedMap, writeSourceMap } from "../../mapping/source-map.js";
-import { dedupe, hasConsoleCalls, resolveTranspiledModuleInclude } from "../utils/index.js";
+import { dedupe, resolveTranspiledModuleInclude } from "../utils/index.js";
 import { appendHeaderLine } from "./line-appender.js";
 import { runSelfCheck } from "../compliance/rule-engine.js";
 import { renderRegistryJson } from "../compliance/deviation-writer.js";
@@ -78,24 +78,6 @@ export function emitPreamble(ctx) {
     }
     // Async task classes are emitted later (emitAsyncTaskClasses) AFTER top-level
     // globals so references like WIFI_SSID inside the state machine compile.
-    if (strategy.needsVectorOverload() && hasConsoleCalls(program, strategy) && (programAnalysis.usesVectorTypes || programAnalysis.hasArrayInObjectLiteral)) {
-        appendSourceLineLocal(ctx, "template <typename T>");
-        appendSourceLineLocal(ctx, "std::ostream& operator<<(std::ostream& os, const std::vector<T>& values)");
-        appendSourceLineLocal(ctx, "{");
-        appendSourceLineLocal(ctx, '  os << "[";');
-        appendSourceLineLocal(ctx, "  for (size_t i = 0; i < values.size(); ++i)");
-        appendSourceLineLocal(ctx, "  {");
-        appendSourceLineLocal(ctx, "    if (i > 0)");
-        appendSourceLineLocal(ctx, "    {");
-        appendSourceLineLocal(ctx, '      os << ", ";');
-        appendSourceLineLocal(ctx, "    }");
-        appendSourceLineLocal(ctx, "    os << values[i];");
-        appendSourceLineLocal(ctx, "  }");
-        appendSourceLineLocal(ctx, '  os << "]";');
-        appendSourceLineLocal(ctx, "  return os;");
-        appendSourceLineLocal(ctx, "}");
-        appendSourceLineLocal(ctx, "");
-    }
     if (programAnalysis.hasGenerators) {
         appendSourceLineLocal(ctx, "#include <coroutine>");
         appendSourceLineLocal(ctx, "#include <optional>");
@@ -140,12 +122,38 @@ export function emitAsyncTaskClasses(ctx) {
     const { asyncTaskClasses } = ctx;
     if (asyncTaskClasses.length === 0)
         return;
-    for (const { classDef, instanceDecl } of asyncTaskClasses) {
-        for (const line of classDef.split("\n")) {
+    for (const t of asyncTaskClasses) {
+        // Async-METHOD tasks move to emitAsyncMethodTasks (after the user
+        // classes): their segment bodies dereference `_owner->field`, which
+        // needs the owning class COMPLETE — at this point only the forward
+        // declaration exists.
+        if (t.starterDef !== undefined)
+            continue;
+        for (const line of t.classDef.split("\n")) {
+            appendSourceLineLocal(ctx, line);
+        }
+        appendSourceLineLocal(ctx, "");
+        appendSourceLineLocal(ctx, t.instanceDecl);
+        appendSourceLineLocal(ctx, "");
+    }
+}
+/**
+ * Emit async-METHOD task classes + instances + starter definitions. Must run
+ * AFTER emitClasses (segments dereference _owner->field on the now-complete
+ * owning class) and BEFORE emitFunctions (the loop pump references the
+ * instances; the starter definitions call .start on them).
+ */
+export function emitAsyncMethodTasks(ctx) {
+    const { asyncTaskClasses } = ctx;
+    for (const t of asyncTaskClasses) {
+        if (t.starterDef === undefined)
+            continue;
+        for (const line of t.classDef.split("\n")) {
             appendSourceLineLocal(ctx, line);
         }
         appendSourceLineLocal(ctx, "");
-        appendSourceLineLocal(ctx, instanceDecl);
+        appendSourceLineLocal(ctx, t.instanceDecl);
+        appendSourceLineLocal(ctx, t.starterDef);
         appendSourceLineLocal(ctx, "");
     }
 }
@@ -330,7 +338,7 @@ export function finalizeOutput(ctx) {
         }
         // Sidecar deviation registry — written for both warn and strict modes
         // alongside the emitted artifact (mirrors how .thcppmap.json sits next
-        // to the .cpp/.ino today).
+        // to the .cpp today).
         const toolVersion = options.toolVersion ?? "unknown";
         const registryPath = path.join(outDir, `${baseName}.autosar-deviations.json`);
         writeText(registryPath, renderRegistryJson(ctx.compliance, path.basename(sourcePath), toolVersion));

package/dist/emit/emitters/setup.js

@@ -1,10 +1,12 @@
 import path from "node:path";
 import { filterPolyfillHelpers, isStringEnum } from "../../api/shared/index.js";
 import { hasSafetyHook, requireSafetyHook } from "../../safety-hook.js";
+import { isSafetyImportSpecifier } from "../../safety/specifiers.js";
 import { analyzeProgram } from "../../ir/program-analysis.js";
 import { collectStatementIdentifiers } from "../../ir/identifier-collector.js";
 import { ensureDir } from "../../utils/fs.js";
 import { resolveImport } from "../../libdef/registry.js";
+import { isRegisteredCuttlefishLibrary } from "../../library-packages.js";
 import { emitPolyfillBoilerplate } from "../native-helpers-emitter.js";
 import { resolveStrategy } from "../../platform/registry.js";
 import { buildCoopSchedulerPolyfill } from "../../platform/coop-scheduler-runtime.js";
@@ -239,6 +241,11 @@ function extractShimMacro(lines, macroName) {
     return lines.slice(ifndefIdx, endIdx + 1);
 }
 export function buildEmitterContext(program, options) {
+    // Framework strategies that resolve per-program chip data (Zephyr's chip
+    // view reconstructs from the generated manifest) must do it before any
+    // body rendering — hal-op lowering reads their cached descriptor.
+    options.strategy
+        ?.prepareChip?.(program, options.platformContext);
     const largeEnumNames = new Set();
     const enumNames = new Set();
     const stringEnumNames = new Set();
@@ -312,23 +319,6 @@ export function buildEmitterContext(program, options) {
     })();
     const programAnalysis = analyzeProgram(program, strategy);
     if (options.platformContext) {
-        // The UI runtime's per-frame tick calls millis() (injected by the emitter,
-        // not present in user source), so a mounted UI needs the native millis ISR
-        // even when usesNativeTiming is false. OR entryHasUI() into the flag the
-        // AVR strategy reads when gating native_millis, so framework-avr doesn't
-        // drop the Timer0 ISR from a UI program.
-        if (!programAnalysis.usesNativeTiming && entryHasUI()) {
-            programAnalysis.usesNativeTiming = true;
-        }
-        // The UI runtime header calls constrain() in the progress/range node draw
-        // and touch-slider paths (injected by the emitter, not present in user
-        // source), so a mounted UI needs the constrain polyfill even when
-        // usesConstrain is false. OR entryHasUI() into the flag the native
-        // strategy reads when gating the constrain helper, mirroring the
-        // usesNativeTiming handling above.
-        if (!programAnalysis.usesConstrain && entryHasUI()) {
-            programAnalysis.usesConstrain = true;
-        }
         options.platformContext.analysis = programAnalysis;
         if (!options.platformContext.architecture && program.boardConstants) {
             options.platformContext.architecture = program.boardConstants.get("architecture");
@@ -367,16 +357,11 @@ export function buildEmitterContext(program, options) {
     if (!programAnalysis.usedPolyfillHelpers.has('__tc_StaticArray')) {
         filteredNativePolyfills = filteredNativePolyfills.filter(p => p.id !== "static_array");
     }
-    const usesTimers = programAnalysis.usedPolyfillHelpers.has('__tc_setInterval') ||
-        programAnalysis.usedPolyfillHelpers.has('__tc_setTimeout');
-    if (!usesTimers) {
-        filteredNativePolyfills = filteredNativePolyfills.filter(p => p.id !== "timer_methods");
-    }
     // Safety polyfills (mode table + voter + SafeVariable + SafeInt). Gated on
-    // programUsesSafety(program) so they ONLY appear when the sketch actually
+    // programUsesSafety(program) so they ONLY appear when the program actually
     // references a safety construct — emitting them unconditionally (just because
     // @typecad/safety is installed and registered its hook) leaks ~200 lines of
-    // polyfill into every sketch, and SafeInt's `return *this` chaining methods
+    // polyfill into every program, and SafeInt's `return *this` chaining methods
     // tripped byte-identity / lowering assertions that expect no `this` token.
     // programUsesSafety walks the IR for any safety.* hal-op.
     if (isEntryFile && hasSafetyHook() && programUsesSafety(program)) {
@@ -392,8 +377,7 @@ export function buildEmitterContext(program, options) {
     // minimal-libc targets (Zephyr) where the Promise runtime does not.
     const coopConfig = strategy.getAsyncRuntimeConfig?.();
     const hasCoopWork = program.functions.some(fn => fn.isAsync) ||
-        programAnalysis.usedPolyfillHelpers.has('__tc_setInterval') ||
-        programAnalysis.usedPolyfillHelpers.has('__tc_setTimeout');
+        program.classes.some(c => c.methods.some(m => m.isAsync));
     if (isEntryFile && coopConfig && hasCoopWork) {
         const coop = buildCoopSchedulerPolyfill(program, coopConfig, strategy.currentTimeMillis());
         if (coop)
@@ -403,8 +387,13 @@ export function buildEmitterContext(program, options) {
     const emittedPolyfills = allPolyfills.length > 0
         ? emitPolyfillBoilerplate(allPolyfills)
         : undefined;
-    const hasAsyncRuntime = program.functions.some(fn => fn.isAsync);
+    const hasAsyncRuntime = program.functions.some(fn => fn.isAsync) || program.classes.some(c => c.methods.some(m => m.isAsync));
     const hasPromiseRuntime = nativePolyfills.some((p) => p.id === "async_runtime" && p.hasPromiseRuntime === true);
+    // Native timer capability comes from the strategy's async config, not from
+    // scanning the program: platforms either provide native timer callbacks for
+    // the async runtime (host/native) or they do not (Zephyr — periodic work is
+    // a Thread or a Counter there).
+    const usesTimers = strategy.getAsyncRuntimeConfig?.()?.hasTimers === true;
     if (!isNpmPackage) {
         includes.push(...strategy.forcedIncludes(program, options.platformContext));
         Object.assign(symbolMap, strategy.symbolAliases(program, options.platformContext));
@@ -423,16 +412,6 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesDateNow) {
             shimLines = shimLines.filter(l => !l.includes('namespace Date'));
         }
-        // The UI runtime's per-frame tick uses millis() (injected by the emitter,
-        // not authored in user source), so keep the millis() shim when a UI is
-        // mounted even if the source-level analysis didn't flag usesMillis. The
-        // async runtime and the setInterval/setTimeout scheduler also poll
-        // millis() without any user-source millis() call (Async.sleep lowers to a
-        // raw hal-op the timing scanners can't see) — mirror the usesNativeTiming
-        // derivation and keep the shim for those hidden consumers too.
-        if (!programAnalysis.usesMillis && !programAnalysis.hasAsync && programAnalysis.timerCallCount === 0 && !entryHasUI()) {
-            shimLines = shimLines.filter(l => !l.includes('millis()'));
-        }
         // Strip the nullish helper FUNCTIONS (not the CUTTLEFISH_UNDEFINED macro)
         // when the file doesn't actually emit cuttlefish_nullish(...) calls. A
         // file that only references `null`/`undefined` literals needs just the
@@ -444,6 +423,14 @@ export function buildEmitterContext(program, options) {
         // cuttlefish_nullish( call (a more reliable post-emit check than the
         // per-file pre-emit analysis flag). The logic here governs the .cpp
         // source shim only.
+        // The runtime clock (__tc_now_ms) is gated by the Zephyr strategy at
+        // emission; native emits its definition unconditionally. Strip it from
+        // programs that can never read the clock (no Time calls, async, timers,
+        // scheduler, or mounted UI) so the definition doesn't leak into the
+        // emitted header.
+        if (!programAnalysis.usesWallClock && !programAnalysis.hasAsync && !entryHasUI() && !hasPromiseRuntime) {
+            shimLines = shimLines.filter(l => !l.includes('__tc_now_ms'));
+        }
         if (!programAnalysis.usesNullishHelper) {
             const filtered = [];
             for (let i = 0; i < shimLines.length; i++) {
@@ -457,9 +444,6 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesNum) {
             shimLines = filterShimBlock(shimLines, 'struct __tc_Num {', '} Num;');
         }
-        if (!programAnalysis.usesTiming) {
-            shimLines = filterShimBlock(shimLines, 'struct __tc_Timing {', '} Timing;');
-        }
         if (!programAnalysis.usesWDT) {
             shimLines = filterShimBlock(shimLines, '#include <avr/wdt.h>', '} WDT;');
         }
@@ -472,9 +456,7 @@ export function buildEmitterContext(program, options) {
         // these filters are no-ops there. The strategies also self-gate on the
         // same flags; this is the defensive backstop (mirrors how usesWDT/etc.
         // backstop the strategy-side gating above).
-        // Keep the UART block when console calls are present (console_log etc.
-        // call _uart_* functions) even if no direct uart.* HAL ops are used.
-        if (!programAnalysis.usesUart && !programAnalysis.hasConsoleCalls) {
+        if (!programAnalysis.usesUart) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_BEGIN', '// CUTTLEFISH_UART_END');
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_EXT_BEGIN', '// CUTTLEFISH_UART_EXT_END');
         }
@@ -484,14 +466,8 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesI2C) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TWI_BEGIN', '// CUTTLEFISH_TWI_END');
         }
-        if (!programAnalysis.usesEEPROM && !programAnalysis.usesPreferences) {
-            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_EEPROM_BEGIN', '// CUTTLEFISH_EEPROM_END');
-        }
-        if (!programAnalysis.usesTone) {
-            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TONE_BEGIN', '// CUTTLEFISH_TONE_END');
-        }
         // framework-esp32 native peripheral driver shims. Same defensive-backstop
-        // pattern as the UART/SPI/TWI/EEPROM/tone blocks above. framework-arduino's
+        // pattern as the UART/SPI/TWI/EEPROM blocks above. framework-arduino's
         // and framework-avr's shimLines contain none of these markers, so these
         // filters are no-ops there.
         if (!programAnalysis.usesGPIO) {
@@ -506,9 +482,6 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesDAC) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_DAC_BEGIN', '// CUTTLEFISH_DAC_END');
         }
-        if (!programAnalysis.usesPower) {
-            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_POWER_BEGIN', '// CUTTLEFISH_POWER_END');
-        }
         if (!programAnalysis.usesWdt) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WDT_BEGIN', '// CUTTLEFISH_WDT_END');
         }
@@ -547,6 +520,14 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesPreferences) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_PREFERENCES_BEGIN', '// CUTTLEFISH_PREFERENCES_END');
         }
+        // Entry-TU marker for framework shims: the UI runtime header (ui_tick) is
+        // emitted ONLY into the entry file (emitUIRuntime gates on isEntryFile), so
+        // shim helpers that keep the UI alive during bounded blocking waits (e.g.
+        // Zephyr's wifi connect) must compile those calls down everywhere else.
+        // Defined before the shim lines land in the preamble, after all filters.
+        if (isEntryFile && entryHasUI() && shimLines.length > 0) {
+            shimLines.unshift("#define CUTTLEFISH_ENTRY_UI_TU 1");
+        }
         profileDiagnostics = [...strategy.profileDiagnostics(program, options.platformContext)];
     }
     for (const imported of program.imports) {
@@ -554,6 +535,19 @@ export function buildEmitterContext(program, options) {
         // named imports — add it to the symbolMap so cross-module references
         // resolve. Demo #12 Finding C — was skipped, so `encode` wasn't declared.
         const defaultName = imported.defaultImportName;
+        // Cuttlefish library packages: the import emits the shim-header include
+        // (resolved through the libdef registry from the library manifest) and
+        // contributes native shims + build fragments. This must run BEFORE the
+        // SDK skip below — @typecad-scoped libraries would otherwise be treated
+        // as type-level-only like the rest of the SDK.
+        if (isRegisteredCuttlefishLibrary(imported.moduleSpecifier)) {
+            const resolved = resolveImport(imported, options.libdefs, options.target, options.platformContext, program.fileName);
+            includes.push(normalizeInclude(resolved.include));
+            Object.assign(symbolMap, resolved.symbolMap);
+            if (defaultName)
+                symbolMap[defaultName] = defaultName;
+            continue;
+        }
         if (isCuttlefishSDKImport(imported.moduleSpecifier, program.fileName)) {
             for (const symbol of imported.namedImports) {
                 symbolMap[symbol] = symbol;
@@ -586,7 +580,7 @@ export function buildEmitterContext(program, options) {
         // time; the package emits NO C++ module/header. Register the imported
         // symbols so references resolve, but skip the #include generation.
         if (imported.moduleSpecifier === "@typecad/ui" ||
-            imported.moduleSpecifier === "@typecad/safety") {
+            isSafetyImportSpecifier(imported.moduleSpecifier)) {
             for (const symbol of imported.namedImports) {
                 symbolMap[symbol] = symbol;
             }
@@ -680,11 +674,11 @@ export function buildEmitterContext(program, options) {
     // Map a function's original TS name to its emitted C++ name, applying the
     // strategy's user-function renames. The entrypoint sentinel
     // `__cuttlefish_entrypoint__` maps to the strategy's entrypoint name
-    // (`main` on native, `setup` on Arduino); every other name is routed through
+    // (per-target entrypoint names); every other name is routed through
     // `strategy.mapFunctionName`, which is where a target renames a user
     // function that would otherwise collide with a C++/framework reserved name
-    // — e.g. Arduino renames a user `function main()` to `cuttlefish_main`,
-    // because Arduino has no `main()` (the entrypoints are the auto-generated
+    // — e.g. Targets without a user `main()` rename one to `cuttlefish_main`;
+    // because this target has no user `main()` (the entrypoints are the auto-generated
     // `setup()`/`loop()`), and a file-scope `static void main()` collides with
     // C++'s required `int main()` signature. Call-site renames are applied
     // uniformly in StatementRenderer.renderCall (the single call-rendering
@@ -857,7 +851,7 @@ export function buildEmitterContext(program, options) {
     // method/ctor parameter, or a top-level binding. Previously only local
     // var_decls were registered (in class-emitter), which ran too late for the
     // free-function pass — leaving `hero->alive` unrewritten and failing g++.
-    // See SUPPORT_MATRIX §4.3 (demo #4 fix).
+    // (demo #4 fix.)
     // `classAccessorNames` is built at the outer scope (not inside a nested
     // block) so it can also be passed to the expression renderer as
     // `typeAccessorNames` — the type-keyed fallback used when a getter access's
@@ -967,6 +961,7 @@ export function buildEmitterContext(program, options) {
     const mapFunctionNameLocal = (originalName) => statementRenderer.mapFunctionName(originalName);
     const asyncFunctionMappedNames = new Set(program.functions.filter((fn) => fn.isAsync).map((fn) => mapFunctionNameLocal(fn.originalName)));
     const asyncTaskClasses = [];
+    const asyncMethodStarters = [];
     if (hasAsyncRuntime) {
         for (const fn of program.functions) {
             if (fn.isAsync) {
@@ -992,21 +987,103 @@ export function buildEmitterContext(program, options) {
                     // Use renderWithPrelude so snprintf buffer declarations (e.g.
                     // char __cuttlefish_str_N[...]; snprintf(...)) are emitted before
                     // the statement that references them. Without this, template-literal
-                    // console.log inside async functions loses the buffer declaration.
+                    // string building inside async functions loses the buffer declaration.
                     const { prelude, statement } = contextRenderer.renderWithPrelude(stmt, forHeader, calleeTransformer);
                     if (prelude.length > 0) {
                         return prelude.join("\n") + "\n" + statement;
                     }
                     return statement;
+                }, {
+                    onUnsupportedAwait: (callee, span) => {
+                        emitDiagnostics.push({
+                            severity: "error",
+                            code: "await-unsupported-call",
+                            message: `await ${callee}(...) has no cooperative lowering here — the call would be dropped. Await is supported on Time.sleep, HAL ops (wifi.join / wifi.scan / http.send), ui.onTap(), and pin-edge waits.`,
+                            ...(span ? { source: `${callee}(...)` } : {}),
+                        });
+                    },
                 });
                 asyncTaskClasses.push({ ...task, taskVarName: `${fn.originalName}Task` });
             }
         }
+        // Async METHODS on user classes: the body becomes an owner-bound task
+        // (this->x renders as _owner->x inside segments); the in-class method
+        // body is replaced by a call to a forward-declared starter that binds
+        // the receiver and arms the machine (see class-emitter.ts).
+        for (const cls of program.classes) {
+            for (const method of cls.methods) {
+                if (!method.isAsync)
+                    continue;
+                const fnName = `${cls.name}_${method.name}`;
+                if (method.isStatic) {
+                    emitDiagnostics.push({
+                        severity: "error",
+                        code: "async-method-static",
+                        message: `static async method ${cls.name}.${method.name}() is not supported — hoist it to a free async function instead.`,
+                    });
+                    continue;
+                }
+                if (method.parameters.length > 0) {
+                    emitDiagnostics.push({
+                        severity: "error",
+                        code: "async-method-params",
+                        message: `async method ${cls.name}.${method.name}() takes parameters, which the cooperative state machine cannot capture — make it parameterless.`,
+                    });
+                    continue;
+                }
+                if (method.returnType !== "void" && !String(method.returnType).startsWith("Promise")) {
+                    emitDiagnostics.push({
+                        severity: "error",
+                        code: "async-method-return",
+                        message: `async method ${cls.name}.${method.name}() returns ${method.returnType}; async methods lower to fire-and-forget tasks and must return void (Promise<void>).`,
+                    });
+                    continue;
+                }
+                const task = generateAsyncTaskClass(fnName, method.statements, strategy, knownFunctionReturnTypes, (stmt, forHeader, strategy, pointerVarTypes, calleeTransformer, knownReturnTypes) => {
+                    const contextRenderer = new StatementRenderer({
+                        strategy,
+                        boardConstants: program.boardConstants,
+                        classNameMap,
+                        enumNames,
+                        stringEnumNames,
+                        largeEnumNames,
+                        knownFunctionReturnTypes: knownReturnTypes ?? knownFunctionReturnTypes,
+                        knownVariableTypes: topLevelScope.knownVariableTypes,
+                        globalPointerVarTypes,
+                        namespaceNames,
+                        snprintfCounter,
+                        stringVarNames,
+                        varAccessorNames,
+                        typeAccessorNames: classAccessorNames,
+                        pointerVarTypes,
+                        diagnostics: emitDiagnostics,
+                    });
+                    const { prelude, statement } = contextRenderer.renderWithPrelude(stmt, forHeader, calleeTransformer);
+                    const body = prelude.length > 0 ? prelude.join("\n") + "\n" + statement : statement;
+                    // The task class is not the receiver: rebind member accesses from
+                    // the owning instance to the task's _owner pointer. The renderer
+                    // emits every this-form as `this->`; a rendered string literal
+                    // containing that token would be rewritten too (accepted edge).
+                    return body.replace(/this->/g, "_owner->");
+                }, {
+                    ownerClassName: cls.name,
+                    onUnsupportedAwait: (callee, span) => {
+                        emitDiagnostics.push({
+                            severity: "error",
+                            code: "await-unsupported-call",
+                            message: `await ${callee}(...) has no cooperative lowering here — the call would be dropped. Await is supported on Time.sleep, HAL ops (wifi.join / wifi.scan / http.send), ui.onTap(), and pin-edge waits.`,
+                            ...(span ? { source: `${callee}(...)` } : {}),
+                        });
+                    },
+                });
+                asyncTaskClasses.push({ ...task, taskVarName: `${fnName}Task` });
+                asyncMethodStarters.push({
+                    proto: `void __tc_async_start_${fnName}(${cls.name}* owner);`,
+                });
+            }
+        }
     }
     // Additional includes computed from analysis
-    if (strategy.needsIostream() && programAnalysis.hasConsoleCalls) {
-        includes.push("<iostream>");
-    }
     const usesVectorTypes = programAnalysis.usesVectorTypes || programAnalysis.hasArrayInObjectLiteral;
     if (programAnalysis.usesStdString && strategy.needsStdString()) {
         includes.push("<string>");
@@ -1083,7 +1160,13 @@ export function buildEmitterContext(program, options) {
     // include in the AVR profile (which leaked the header into every AVR
     // program, even ones that never touch the watchdog like `led.toggle()`).
     if (programUsesWdt(program)) {
-        includes.push("<avr/wdt.h>");
+        // Strategy-vetoed: framework-zephyr lowers wdt.* to the Zephyr watchdog
+        // driver (<zephyr/drivers/watchdog.h>, forced under usesWDT) and must not
+        // carry the AVR-only header into a Zephyr build.
+        const wdtInc = strategy.filterRequiredIncludes
+            ? strategy.filterRequiredIncludes(["<avr/wdt.h>"])
+            : ["<avr/wdt.h>"];
+        includes.push(...wdtInc);
     }
     // Placeholder defaults for fields that are computed later by other phases
     const noopFixPointer = (c) => c;
@@ -1166,6 +1249,7 @@ export function buildEmitterContext(program, options) {
         boardConstants: program.boardConstants,
         restParamFunctions: program.restParamFunctions,
         asyncTaskClasses,
+        asyncMethodStarters,
         asyncFunctionOriginalNames,
         asyncFunctionMappedNames,
         hasAsyncRuntime,

package/dist/emit/emitters/top-level-prep.js

@@ -411,7 +411,7 @@ export function runTopLevelPreprocessing(ctx) {
     // sees runtime mutations — e.g. `const reached = descended` freezes `reached`
     // at `descended`'s initial value because both are emitted as file-scope globals
     // initialized before main(), while the `descended = depth` assignments run
-    // inside main(). See SUPPORT_MATRIX §6.1.
+    // inside main().
     {
         // Collect every variable name that is the target of an assignment anywhere
         // in the program (top-level statements + function/method bodies). Such

package/dist/emit/emitters/type-decl-emitter.js

@@ -2,6 +2,7 @@ import { emitCommentLines, isRuntimeExpression } from "../utils/index.js";
 import { appendSourceLine, appendHeaderLine, appendRenderedStatement } from "./line-appender.js";
 import { escapeCppKeyword } from "../../utils/strings.js";
 import { isStringEnum } from "../../api/shared/index.js";
+import { parsedIsVector } from "../../api/shared/cpp-type-ir.js";
 import { resolveEnumValues, narrowestEnumUnderlying } from "../utils/cpp-helpers.js";
 export function emitTypeDeclarations(ctx) {
     const { program, strategy, effectiveEmitMode, reservedNames, emittedTopLevelStatements, topLevelScope } = ctx;
@@ -249,14 +250,18 @@ export function emitTypeDeclarations(ctx) {
             const typeAlreadyConst = cppType.trimStart().startsWith("const");
             const constPrefix = isConst && !typeAlreadyConst ? "const " : "";
             const varName = escapeCppKeyword(statement.name, platformReservedNames);
-            // Array-typed top-level consts (e.g. `export const ARR: T[] = [...]`)
-            // lower with cppType "auto" and a `{ kind: "array", elementType }`
-            // initializer. They emit as C-style arrays (`T name[] = {...}`), so the
-            // matching extern is `extern const T name[];` — not a scalar extern and
-            // not a std::vector extern. Without this, cross-file consumers fail with
-            // "was not declared in this scope" (the definition lives in the .cpp
-            // only). Mirror renderVarDecl's element-type fallback for "auto".
-            if (cppType === "auto" && statement.initializer && statement.initializer.kind === "array") {
+            // Array-typed top-level consts (e.g. `export const ARR: T[] = [...]`
+            // and `new Uint8Array(N)` buffers) lower with an `{ kind: "array",
+            // elementType }` initializer — typed arrays carry a pointer cppType
+            // (`uint8_t*`) even though renderVarDecl emits the DEFINITION as a
+            // C-style array (`T name[] = {...}`). The matching extern must use the
+            // same array form regardless of cppType — a pointer extern conflicts
+            // with the array definition. Vector-typed arrays are the exception: the
+            // definition emits `std::vector<T> name = {...}`, so the extern stays a
+            // vector extern. Without this, cross-file consumers fail with "was not
+            // declared in this scope" (the definition lives in the .cpp only).
+            // Mirror renderVarDecl's element-type fallback for "auto".
+            if (statement.initializer && statement.initializer.kind === "array" && !parsedIsVector(cppType)) {
                 const elemType = statement.initializer.elementType && statement.initializer.elementType !== "auto"
                     ? strategy.normalizeCppType(statement.initializer.elementType)
                     : strategy.defaultNumericType(ctx.compliance.isEnabled() ? ctx.compliance : undefined);

package/dist/emit/emitters/ui-emitter.js

@@ -163,7 +163,7 @@ export function emitUIRuntime(ctx) {
     if (profile) {
         const adapter = generateDisplayAdapter(profile, ctx.strategy);
         // Prepend includes to the very front — Arduino's auto-prototyper scans
-        // the whole .ino and generates prototypes that reference GFXcanvas16
+        // the whole translation unit and generates prototypes that reference GFXcanvas16
         // etc. before any #include, so the GFX header must come first.
         ctx.sourceLines.unshift(adapter.includes);
         // Color-depth preamble: UI_COLOR_T is referenced by adapter draw