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

package/dist/emit/expression-renderer.js

@@ -179,8 +179,17 @@ export class ExpressionRenderer {
                 break;
             case "hal-expr": {
                 const resolved = routeHALOp(expr.operation, this.strategy);
+                // A method body's preceding side-effect ops (bus transactions, pin
+                // configures) must run even in expression position — wrap them with
+                // the value in a GCC statement-expression.
+                const prefix = (expr.prefixOps ?? [])
+                    .map((op) => routeHALOp(op, this.strategy))
+                    .map((r) => r?.code ?? `/* unhandled hal-op prefix: dropped */`)
+                    .join(' ');
                 if (resolved?.expression) {
-                    rendered = resolved.expression;
+                    rendered = prefix
+                        ? `({ ${prefix} ${resolved.expression}; })`
+                        : resolved.expression;
                 }
                 else if (resolved?.code) {
                     // Strip trailing semicolon and a leading `return ` for expression
@@ -189,7 +198,8 @@ export class ExpressionRenderer {
                     // `return` keyword is invalid (avr-g++: "expected primary-expression
                     // before 'return'") and would leak as
                     // `strcmp(return Preferences.getString(...), ...)`. Demo #33 Finding C.
-                    rendered = resolved.code.replace(/;\s*$/, "").replace(/^\s*return\s+/, "");
+                    const asExpr = resolved.code.replace(/;\s*$/, "").replace(/^\s*return\s+/, "");
+                    rendered = prefix ? `({ ${prefix} ${asExpr}; })` : asExpr;
                 }
                 else {
                     // Unregistered HAL op: surface as a warning so the user sees it, but
@@ -862,7 +872,7 @@ export class ExpressionRenderer {
         // must be cast to an integral type — a C++ `enum class` does not
         // implicitly convert to `size_t`, so `vector[enumValue]` fails to compile.
         // `renderEnumSafeValue` already wraps numeric-enum operands in
-        // `static_cast<int>(...)` (SUPPORT_MATRIX §1.7); route the index through it
+        // `static_cast<int>(...)`; route the index through it
         // (with the in-scope variable types so a bare enum-typed identifier
         // resolves) so enum indices lower correctly. Non-enum indices are passed
         // through unchanged. Demo #28 Finding E.
@@ -886,8 +896,8 @@ export class ExpressionRenderer {
      * String-enum operands are passed through unchanged (they're `const char*`).
      *
      * This is the assignment/argument-site counterpart to the operator-level
-     * enum wrapping in renderBinary. SUPPORT_MATRIX §1.7: enum values used as
-     * integers need an explicit cast in C++.
+     * enum wrapping in renderBinary. Enum values used as integers need an
+     * explicit cast in C++.
      */
     renderEnumSafeValue(expr, knownVariableTypes) {
         const rendered = this.render(expr, undefined, knownVariableTypes);
@@ -919,7 +929,7 @@ export class ExpressionRenderer {
      *     operand → `static_cast<EnumType>(value)` (int → enum). C++ `enum
      *     class` does not implicitly convert FROM an integral storage type
      *     either, so reading an `int`/`uint8_t` cell back into an enum-typed
-     *     local needs the reverse cast. SUPPORT_MATRIX §1.7.
+     *     local needs the reverse cast.
      *
      * This closes the "enum↔integral storage boundary" family — the previous
      * point-specific casts handled enum-as-array-index (demo #28 E) and
@@ -1155,7 +1165,7 @@ export class ExpressionRenderer {
         // Wrap enum-class operands in static_cast<int>() for arithmetic operators
         // (+, -, *, /) and bitwise operators (&, |, ^, <<, >>). C++ enum class
         // values don't interoperate with int implicitly — `trophic - 1`, `a | b`,
-        // `x & MASK` all fail without the cast. SUPPORT_MATRIX §1.7/§5.1. The
+        // `x & MASK` all fail without the cast. The
         // shared castEnumOperandsForOperator helper handles detection + defensive
         // symmetry in one place.
         const numericOps = new Set(["+", "-", "*", "/", "&", "|", "^", "<<", ">>"]);

package/dist/emit/route-hal-op.js

@@ -11,70 +11,39 @@
 //
 // Output-pin state tracking is also handled here, centrally, so every
 // strategy benefits without per-strategy changes:
-// - gpio.read with `trackedValue` never reaches the strategy (a hardware
-//   read of a direction-only output is not portable, e.g. Zephyr); it folds
-//   to a constant or the tracked shadow variable.
-// - gpio.write / gpio.toggle flagged `updatesShadow` get the shadow variable
+// - (pin-state-tracking removed: every gpio.* op lowers through the strategy)
 //   update appended to whatever the strategy produced. The flag is baked
 //   into the op at IR-build time (markShadowUpdatingOps) — emit must not
 //   consult live tracker state, because all files build (each resetting the
 //   tracker) before any file emits.
 // ---------------------------------------------------------------------------
 import { getSafetyHook } from "../safety-hook.js";
-import { pinShadowVarName } from "../ir/pin-state-tracking.js";
+import { markHalOpResolved } from "../ir/build-ir-state.js";
 export function routeHALOp(op, strategy) {
+    // An op resolved here during IR-build-time method inlining may never exist
+    // as an IR node (its text is baked into the calling method's emit lines),
+    // so record it for program-analysis's peripheral usage flags — every
+    // branch, matching the IR-node paths (display.* sets usesGPIO/usesDisplay,
+    // safety.* maps the __tc_safety_* helpers).
     if (typeof op.operation === "string") {
         if (op.operation.startsWith("display.")) {
-            return strategy.resolveDisplayOp?.(op);
+            const r = strategy.resolveDisplayOp?.(op);
+            if (r)
+                markHalOpResolved(op.operation);
+            return r;
         }
         if (op.operation.startsWith("safety.")) {
             // Safety ops are resolved by the @typecad/safety package via hook.
             // Returns undefined if the package is not loaded (caller emits an
             // unhandled-op warning).
-            return getSafetyHook()?.resolveSafetyOp?.(op);
+            const r = getSafetyHook()?.resolveSafetyOp?.(op);
+            if (r)
+                markHalOpResolved(op.operation);
+            return r;
         }
     }
-    if (op.operation === "gpio.read" && op.trackedValue) {
-        // Tracked OUTPUT-pin read: software truth, never a hardware read.
-        if (op.trackedValue === "high")
-            return { expression: "true" };
-        if (op.trackedValue === "low")
-            return { expression: "false" };
-        return { expression: pinShadowVarName(op.pin) };
-    }
     const resolved = strategy.resolveHALOperation?.(op);
-    // Toggle on a shadow-tracked pin must not use the strategy's default
-    // read-modify-write form (e.g. digitalWrite(p, digitalRead(p) ...) on
-    // Arduino) — reading the pin back is exactly what tracking avoids. Lower
-    // it as a write of the shadow's current value, then flip the shadow.
-    if (op.operation === "gpio.toggle" && op.updatesShadow) {
-        const varName = pinShadowVarName(op.pin);
-        const writeOp = {
-            operation: "gpio.write",
-            pin: op.pin,
-            value: varName,
-            ...(op.port !== undefined ? { port: op.port } : {}),
-        };
-        const writeResolved = strategy.resolveHALOperation?.(writeOp);
-        const flip = `${varName} = (!${varName});`;
-        if (writeResolved?.code) {
-            return { ...writeResolved, code: `${writeResolved.code}\n${flip}` };
-        }
-        if (writeResolved?.expression) {
-            return { ...writeResolved, expression: `${writeResolved.expression}, ${flip}` };
-        }
-        return { code: flip };
-    }
-    if (op.operation === "gpio.write" && op.updatesShadow) {
-        const varName = pinShadowVarName(op.pin);
-        const update = `${varName} = ((${op.value}) != 0);`;
-        if (resolved?.code) {
-            return { ...resolved, code: `${resolved.code}\n${update}` };
-        }
-        if (resolved?.expression) {
-            return { ...resolved, expression: `${resolved.expression}, ${update}` };
-        }
-        return { code: update };
-    }
+    if (resolved)
+        markHalOpResolved(op.operation);
     return resolved;
 }

package/dist/emit/snprintf-helpers.d.ts

@@ -1,4 +1,4 @@
-import type { AssignmentIR, ExpressionIR, StatementIR, VariableDeclarationIR } from "../api/shared/index.js";
+import type { ExpressionIR, StatementIR, VariableDeclarationIR } from "../api/shared/index.js";
 import type { PlatformStrategy } from "../api/shared/index.js";
 import type { KnownVariableInfo, SnprintfArgRenderResult, SnprintfRenderResult, EmissionScopeState, SnprintfExpressionRenderer } from "../api/shared/index.js";
 import { escapeCppStringLiteral } from "../utils/strings.js";
@@ -12,6 +12,4 @@ export declare function createChildEmissionScope(baseScope: EmissionScopeState,
 export declare function recordVariableType(statement: VariableDeclarationIR, scopeState: EmissionScopeState): void;
 export { escapeCppStringLiteral };
 export declare function inferSnprintfArg(expr: ExpressionIR, strategy: PlatformStrategy, scopeState: EmissionScopeState, renderExpression: SnprintfExpressionRenderer, pointerVarTypes?: Map<string, string>, knownFunctionReturnTypes?: Map<string, string>, stringVarNames?: Set<string>): SnprintfArgRenderResult | undefined;
-export declare function buildSnprintfRenderResult(expr: ExpressionIR, strategy: PlatformStrategy, scopeState: EmissionScopeState, renderExpression: SnprintfExpressionRenderer, pointerVarTypes?: Map<string, string>, knownFunctionReturnTypes?: Map<string, string>, stringVarNames?: Set<string>): SnprintfRenderResult | undefined;
-export declare function shouldUseSnprintfForString(statement: VariableDeclarationIR | AssignmentIR, strategy: PlatformStrategy): boolean;
 export declare function statementNeedsSnprintf(statement: StatementIR, strategy: PlatformStrategy): boolean;

package/dist/emit/snprintf-helpers.js

@@ -7,7 +7,7 @@
 // All logic lives in the CLI; no framework package dependency.
 // Types are imported from @typecad/cuttlefish/api/shared.
 // ---------------------------------------------------------------------------
-import { escapeCppStringLiteral, escapeSnprintfFormatFragment } from "../utils/strings.js";
+import { escapeCppStringLiteral } from "../utils/strings.js";
 import { cppTypeForHalOp } from "./utils/hal-op-cpp-type.js";
 import { parsedElementString, parsedIsStringLike } from "../api/shared/cpp-type-ir.js";
 // ---------------------------------------------------------------------------
@@ -387,46 +387,8 @@ export function inferSnprintfArg(expr, strategy, scopeState, renderExpression, p
     }
 }
 // ---------------------------------------------------------------------------
-// Snprintf render result builder
-// ---------------------------------------------------------------------------
-export function buildSnprintfRenderResult(expr, strategy, scopeState, renderExpression, pointerVarTypes, knownFunctionReturnTypes, stringVarNames) {
-    if (expr.kind !== "string_concat") {
-        return undefined;
-    }
-    let formatString = "";
-    const args = [];
-    let estimatedLength = 1;
-    const preludeLines = [];
-    for (const part of expr.parts) {
-        if (part.kind === "string") {
-            // These literal parts are concatenated into the snprintf *format* string,
-            // so any embedded `%` must be doubled or snprintf misreads it on hardware.
-            formatString += escapeSnprintfFormatFragment(part.value);
-            estimatedLength += part.value.length;
-            continue;
-        }
-        const innerExpr = part.kind === "template_string" ? part.expression : part;
-        const arg = inferSnprintfArg(innerExpr, strategy, scopeState, renderExpression, pointerVarTypes, knownFunctionReturnTypes, stringVarNames);
-        if (!arg) {
-            return undefined;
-        }
-        formatString += arg.format;
-        args.push(arg.arg);
-        estimatedLength += arg.estimatedLength;
-        preludeLines.push(...arg.preludeLines);
-    }
-    return { formatString, args, estimatedLength: Math.max(estimatedLength, 16), preludeLines };
-}
-// ---------------------------------------------------------------------------
 // Snprintf usage detection
 // ---------------------------------------------------------------------------
-export function shouldUseSnprintfForString(statement, strategy) {
-    if (!strategy.useSnprintfForStrings()) {
-        return false;
-    }
-    const value = statement.kind === "var_decl" ? statement.initializer : statement.value;
-    return value?.kind === "string_concat";
-}
 export function statementNeedsSnprintf(statement, strategy) {
     if (!strategy.useSnprintfForStrings()) {
         return false;

package/dist/emit/statement-renderer.d.ts

@@ -171,10 +171,6 @@ export declare class StatementRenderer {
     mapReturnTypeForEmit(fnName: string, returnType: string): string;
     private normalizeCppType;
     private inferFieldType;
-    /**
-     * Transform console.log/error/warn calls based on target platform.
-     */
-    private transformConsoleCall;
     private renderEmitArg;
     /**
      * Map a function name to its platform-specific name.

package/dist/emit/statement-renderer.js

@@ -6,7 +6,7 @@
 import { routeHALOp } from "./route-hal-op.js";
 import { activeNamespaceNames } from "../ir/build-ir-state.js";
 import { ExpressionRenderer, transformTypeName, normalizeRawExpression } from "./expression-renderer.js";
-import { isConsoleCall, getConsoleMethod, inferObjectFieldType, collectNestedStructDefs } from "./utils/index.js";
+import { inferObjectFieldType, collectNestedStructDefs } from "./utils/index.js";
 import { escapeCppKeyword, escapeTrailingMember } from "../utils/strings.js";
 import { accessorGetterName, accessorSetterName } from "./utils/cpp-helpers.js";
 import { parseCppType, bareType, parsedIsPointer, parsedIsVector, parsedElementString, parsedIsPlainStructType } from "../api/shared/cpp-type-ir.js";
@@ -270,7 +270,7 @@ export class StatementRenderer {
                 // `return nullptr;` / `return CUTTLEFISH_UNDEFINED;` — those are
                 // integer/pointer literals that won't convert to the struct type.
                 // Lower to a value-initialized `return {};` instead. The `T | null`
-                // union already strips to `T` (SUPPORT_MATRIX §1.8), so the function
+                // union already strips to `T`, so the function
                 // signature really does return the struct. Demo #14 Finding A.
                 const retType = statement.functionReturnType;
                 if (retType && isStructReturnType(retType, this.strategy) && isNullishReturnValue(statement.value)) {
@@ -383,29 +383,46 @@ export class StatementRenderer {
                 return "co_yield;";
             }
             if (statement.kind === "block") {
-                return `{`;
+                // Blocks reach the single-line renderer as async state-machine segment
+                // pre-statements (chained HAL calls lower to a block of hal-ops). The
+                // former bare `{` dropped the block body AND emitted an unbalanced
+                // brace. Mirrors the line-appender's block emission: empty body →
+                // no-op, otherwise brace + rendered statements.
+                const bodyLines = statement.body
+                    .map((nested) => this.render(nested, forHeader, calleeTransformer, knownVariableTypes))
+                    .filter((line) => line.length > 0);
+                if (bodyLines.length === 0) {
+                    return "";
+                }
+                return ["{", ...bodyLines, "}"].join("\n");
             }
             if (statement.kind === "hal-op") {
                 const resolved = routeHALOp(statement.operation, this.strategy);
-                if (resolved?.code) {
-                    // Strip leading 'return ' from raw hal-op code when emitted as a
-                    // standalone statement.  The HAL definition includes `return` because
-                    // the TypeScript stub returns a value, but the C++ statement context
-                    // (e.g. inside void setup()) does not expect it.
-                    let code = resolved.code;
-                    if (code.startsWith('return '))
-                        code = code.slice('return '.length);
-                    // A raw hal-op statement (e.g. `Async.sleep(10)` →
-                    // `__cuttlefish_async_sleep(10)`) is a complete C++ statement and
-                    // needs a terminating semicolon, unless it already ends with one or
-                    // with `}` (a compound block).
-                    if (!forHeader && !code.endsWith(';') && !code.endsWith('}')) {
-                        code = code + ';';
+                if (resolved) {
+                    // `{ code: '' }` is a registered op's deliberate elision (sentinel
+                    // facts — an absent request body, insecure=false) — emit nothing and
+                    // do NOT fall through to the unregistered-op warning.
+                    if (resolved.code) {
+                        // Strip leading 'return ' from raw hal-op code when emitted as a
+                        // standalone statement.  The HAL definition includes `return` because
+                        // the TypeScript stub returns a value, but the C++ statement context
+                        // (e.g. inside void setup()) does not expect it.
+                        let code = resolved.code;
+                        if (code.startsWith('return '))
+                            code = code.slice('return '.length);
+                        // A raw hal-op statement (e.g. `Async.sleep(10)` →
+                        // `__cuttlefish_async_sleep(10)`) is a complete C++ statement and
+                        // needs a terminating semicolon, unless it already ends with one or
+                        // with `}` (a compound block).
+                        if (!forHeader && !code.endsWith(';') && !code.endsWith('}')) {
+                            code = code + ';';
+                        }
+                        return code;
                     }
-                    return code;
-                }
-                if (resolved?.expression) {
-                    return forHeader ? resolved.expression : `${resolved.expression};`;
+                    if (resolved.expression) {
+                        return forHeader ? resolved.expression : `${resolved.expression};`;
+                    }
+                    return "";
                 }
                 // Unregistered HAL op: surface as a warning so the user sees it, but
                 // keep HAL as an extensibility point. The bare comment is retained as
@@ -506,6 +523,11 @@ export class StatementRenderer {
             if (code) {
                 return forHeader ? code.replace(/;$/, "") : code;
             }
+            // A resolved op with no code/expression is a deliberate elision
+            // (sentinel facts) — emit nothing, no placeholder comment.
+            if (resolved) {
+                return "";
+            }
             return `/* unhandled awaited hal-op: ${statement.args[0].operation.operation} */`;
         }
         // Handle emit() — compile-time C++ injection
@@ -513,9 +535,16 @@ export class StatementRenderer {
             const rawText = statement.args.map(arg => this.renderEmitArg(arg)).join("");
             return forHeader ? rawText : `${rawText.endsWith(';') ? rawText : rawText + ';'}`;
         }
-        // Handle console.* calls specially
-        if (isConsoleCall(statement.callee)) {
-            return this.transformConsoleCall(statement.callee, statement.args, forHeader, knownVariableTypes);
+        // console.* is not a supported API — it was a TypeScript carry-over whose
+        // lowering (platform print + a config section routing it) cost more than
+        // it bought. Programs write to a serial console explicitly instead.
+        if (statement.callee.startsWith("console.")) {
+            this._diagnostics.push({
+                severity: "error",
+                code: "console-unsupported",
+                message: `console.${statement.callee.slice("console.".length)}() is not supported — write to a serial console instead: \`USB0.writeLine(...)\` (USB CDC) or \`UART0.writeLine(...)\` from the board module.`,
+            });
+            return "";
         }
         let callee = statement.callee;
         if (callee.startsWith("this.")) {
@@ -781,7 +810,7 @@ export class StatementRenderer {
                     ? `${arrayType} ${safeSpreadArrName}[] = { ${initializerText} }`
                     : `${arrayType} ${safeSpreadArrName}[] = { ${initializerText} };`;
             }
-            // Enum ↔ integral storage boundary (SUPPORT_MATRIX §1.7). TS lets an
+            // Enum ↔ integral storage boundary. TS lets an
             // enum and a number flow into each other freely (enums ARE numbers at
             // runtime), but the lowered C++ `enum class` has NO implicit conversion
             // in EITHER direction: `const n: int = Color.Red` AND
@@ -917,26 +946,6 @@ export class StatementRenderer {
         return inferObjectFieldType(value, this.pointerVarTypes, this.knownFunctionReturnTypes, undefined, undefined, undefined, // largeEnumNames - would need to pass through
         parentName, fieldName, this.strategy.defaultNumericType(this._compliance), (o, n) => this.strategy.resolvePinType?.(o, n));
     }
-    /**
-     * Transform console.log/error/warn calls based on target platform.
-     */
-    transformConsoleCall(callee, args, forHeader, knownVariableTypes) {
-        const method = getConsoleMethod(callee);
-        const renderedArgs = args.map((arg) => {
-            let rendered = this.expressionRenderer.render(arg, undefined, knownVariableTypes);
-            if (arg.kind === "identifier" && knownVariableTypes) {
-                const varInfo = knownVariableTypes.get(arg.value);
-                if (varInfo && this.enumNames.has(varInfo.cppType)) {
-                    rendered = `static_cast<int>(${rendered})`;
-                }
-            }
-            if (arg.kind === "property-access" && arg.isEnum) {
-                rendered = `static_cast<int>(${rendered})`;
-            }
-            return rendered;
-        }).join(" << ");
-        return this.strategy.transformConsoleCall(method, renderedArgs, forHeader);
-    }
     renderEmitArg(arg) {
         if (arg.kind === "string")
             return arg.value;

package/dist/emit/utils/async-state-machine.d.ts

@@ -5,14 +5,6 @@
  */
 import type { StatementIR } from "../../api/index.js";
 import type { PlatformStrategy } from "../../api/shared/index.js";
-/**
- * Converts a string to PascalCase.
- * Used for generating class names from function names.
- *
- * @param str The input string (e.g., "my_function" or "myFunction")
- * @returns PascalCase string (e.g., "MyFunction")
- */
-export declare function toPascalCaseLocal(str: string): string;
 /**
  * Result of generating an async task class.
  */
@@ -23,6 +15,21 @@ export interface AsyncTaskClassResult {
     instanceDecl: string;
     /** The task variable name for use in loop() */
     taskVarName: string;
+    /** For async METHODS: the definition of the starter function the in-class
+     *  body calls (binds the owner and arms STATE_0). Emitted after the task
+     *  class; the matching prototype must precede the owning class. */
+    starterDef?: string;
+}
+/** Options for generateAsyncTaskClass. */
+export interface AsyncTaskClassOptions {
+    /** Owning class name for async METHODS: the task binds `this` to an owner
+     *  pointer set by start(owner); segment code that renders `this->x` is
+     *  rewritten to `_owner->x` by the embedding renderStatement callback. */
+    ownerClassName?: string;
+    /** Invoked for every awaited call that has no cooperative lowering (the
+     *  call would be silently dropped). The emitter surfaces it as a
+     *  diagnostic instead of emitting wrong code. */
+    onUnsupportedAwait?: (callee: string, span: StatementIR["sourceSpan"] | undefined) => void;
 }
 /**
  * Generates a cooperative state-machine class for an async function.
@@ -39,4 +46,4 @@ export interface AsyncTaskClassResult {
  * @param knownFunctionReturnTypes Map of function names to their return types
  * @returns The class definition, instance declaration, and task variable name
  */
-export declare function generateAsyncTaskClass(fnName: string, fnStatements: StatementIR[], strategy: PlatformStrategy, knownFunctionReturnTypes: Map<string, string>, renderStatement: (stmt: StatementIR, forHeader: boolean, strategy: PlatformStrategy, pointerVarTypes?: Map<string, string>, calleeTransformer?: (callee: string) => string, knownFunctionReturnTypes?: Map<string, string>) => string): AsyncTaskClassResult;
+export declare function generateAsyncTaskClass(fnName: string, fnStatements: StatementIR[], strategy: PlatformStrategy, knownFunctionReturnTypes: Map<string, string>, renderStatement: (stmt: StatementIR, forHeader: boolean, strategy: PlatformStrategy, pointerVarTypes?: Map<string, string>, calleeTransformer?: (callee: string) => string, knownFunctionReturnTypes?: Map<string, string>) => string, options?: AsyncTaskClassOptions): AsyncTaskClassResult;

package/dist/emit/utils/async-state-machine.js

@@ -12,12 +12,23 @@ import { routeHALOp } from "../route-hal-op.js";
  * @param str The input string (e.g., "my_function" or "myFunction")
  * @returns PascalCase string (e.g., "MyFunction")
  */
-export function toPascalCaseLocal(str) {
+function toPascalCaseLocal(str) {
     return str
         .split(/[_\s]+/)
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
         .join("");
 }
+/** Awaited callees that legitimately lower to a plain timed wait (their
+ *  single numeric argument IS the deadline). Everything else reaching the
+ *  plain-wait arm would have its call silently dropped — the embedding
+ *  emitter turns that into a diagnostic via onUnsupportedAwait. */
+const PLAIN_AWAIT_CALLEES = new Set([
+    "Async.sleep",
+    "AsyncClass.sleep",
+    "__cuttlefish_async_sleep",
+    "delay",
+    "sleep",
+]);
 /**
  * Generates a cooperative state-machine class for an async function.
  *
@@ -33,9 +44,11 @@ export function toPascalCaseLocal(str) {
  * @param knownFunctionReturnTypes Map of function names to their return types
  * @returns The class definition, instance declaration, and task variable name
  */
-export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunctionReturnTypes, renderStatement) {
+export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunctionReturnTypes, renderStatement, options) {
     const className = toPascalCaseLocal(fnName) + "Task";
     const instanceName = `${fnName}Task`;
+    const owner = options?.ownerClassName;
+    const starterName = `__tc_async_start_${fnName}`;
     // Detect whether the body is a single while-loop (cyclic) or linear statements
     let bodyStatements;
     let isCyclic = false;
@@ -51,7 +64,7 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
     let currentPre = [];
     for (const stmt of bodyStatements) {
         if (stmt.kind === "call" && stmt.isAwaited) {
-            segments.push({ preStatements: currentPre, awaitedCallee: stmt.callee, awaitedArgs: stmt.args });
+            segments.push({ preStatements: currentPre, awaitedCallee: stmt.callee, awaitedArgs: stmt.args, awaitedSpan: stmt.sourceSpan });
             currentPre = [];
         }
         else if (
@@ -65,7 +78,7 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
             stmt.body[stmt.body.length - 1].isAwaited) {
             const last = stmt.body[stmt.body.length - 1];
             currentPre.push(...stmt.body.slice(0, -1));
-            segments.push({ preStatements: currentPre, awaitedCallee: last.callee, awaitedArgs: last.args });
+            segments.push({ preStatements: currentPre, awaitedCallee: last.callee, awaitedArgs: last.args, awaitedSpan: last.sourceSpan });
             currentPre = [];
         }
         else {
@@ -173,7 +186,13 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
             }
         }
         else {
-            // Plain timed wait (await delay(ms)) — arm its deadline.
+            // Plain timed wait (await delay(ms)) — arm its deadline. Anything whose
+            // callee is not a known timer shape has no cooperative lowering here:
+            // the call itself is NOT rendered (only marker/net awaits carry start
+            // code), so report it instead of silently dropping it.
+            if (!PLAIN_AWAIT_CALLEES.has(seg.awaitedCallee)) {
+                options?.onUnsupportedAwait?.(seg.awaitedCallee, seg.awaitedSpan);
+            }
             const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
             lines.push(`${pad}_waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
         }
@@ -265,19 +284,37 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
         inits.push(`${m}(LOW)`);
     for (const m of tapMemberArr)
         inits.push(`${m}(0)`);
+    // Owner pointer (async methods): initialized null, bound by start(owner).
+    // Declared last / initialized last so the initializer list order matches.
+    if (owner)
+        inits.push("_owner(nullptr)");
     const ctorInitList = inits.join(", ");
     const edgeResetList = edgeMemberArr.map(m => ` ${m} = LOW;`).join("");
     const tapResetList = tapMemberArr.map(m => ` ${m} = 0;`).join("");
     const edgeMemberDecls = edgeMemberArr.map(m => `  int ${m};`);
     // __ui_tap_seq is uint32_t; the snapshot must match to detect bumps correctly.
     const tapMemberDecls = tapMemberArr.map(m => `  uint32_t ${m};`);
+    const ownerMemberDecl = owner ? [`  ${owner}* _owner;`] : [];
+    const runGuard = owner ? [`    if (_owner == nullptr) { return; }`] : [];
+    // start(owner): (re)bind the receiver and rewind the machine. Calling the
+    // async method again restarts the task with the new receiver — the task
+    // is a singleton per method, mirroring the free-function tasks.
+    const startMethod = owner ? [
+        `  void start(${owner}* owner) {`,
+        `    _owner = owner;`,
+        `    _state = ${Q_0};`,
+        `    _waitUntil = 0;${edgeResetList}${tapResetList}`,
+        `  }`,
+    ] : [];
     const classDef = [
         `// Async state machine for ${fnName}`,
         `class ${className} {`,
         `public:`,
         `  enum class State { ${stateEnumList} };`,
         `  ${className}() : ${ctorInitList} {}`,
+        ...startMethod,
         `  void run() {`,
+        ...runGuard,
         `    switch (_state) {`,
         ...caseLines,
         `    }`,
@@ -289,9 +326,13 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
         `  unsigned long _waitUntil;`,
         ...edgeMemberDecls,
         ...tapMemberDecls,
+        ...ownerMemberDecl,
         `};`,
     ].join("\n");
-    return { classDef, instanceDecl: `${className} ${instanceName};`, taskVarName: instanceName };
+    const starterDef = owner
+        ? `void ${starterName}(${owner}* owner) { ${instanceName}.start(owner); }`
+        : undefined;
+    return { classDef, instanceDecl: `${className} ${instanceName};`, taskVarName: instanceName, starterDef };
 }
 /**
  * Renders an expression to a string (simplified version for async state machine).
@@ -346,10 +387,16 @@ function netWaitInfo(op, strategy) {
     const route = (routedOp) => routeHALOp(routedOp, strategy);
     const expr = (operation) => route({ operation })?.expression ?? null;
     switch (op.operation) {
-        case "timing.delay":
+        case "timing.sleep":
+            // Pure deadline wait: no start op, no poll — the machine arms
+            // _waitUntil and cooperatively yields until it passes. Bare
+            // (non-awaited) calls lower to the blocking form (k_msleep).
             return { startLines: [], pollCond: null, timeoutExpr: ms(o.ms) };
-        case "wifi.connect": {
-            const start = route({ operation: "wifi.connect_start", ssid: o.ssid, password: o.password });
+        case "wifi.join": {
+            // Awaited join splits into the staged association + the L4 poll.
+            // (Static-IPv4/power-save facts are join()-side blocking-path extras;
+            // the async form associates with defaults and polls connectivity.)
+            const start = route({ operation: "wifi.connect_start", ssid: o.ssid, password: o.psk });
             const poll = expr("wifi.is_connected");
             if (start?.code && poll) {
                 return {
@@ -360,24 +407,6 @@ function netWaitInfo(op, strategy) {
             }
             break;
         }
-        case "wifi.wait_connected": {
-            const poll = expr("wifi.is_connected");
-            if (poll) {
-                return {
-                    startLines: [],
-                    pollCond: poll,
-                    timeoutExpr: isZeroTimeout(o.timeoutMs) ? null : ms(o.timeoutMs),
-                };
-            }
-            break;
-        }
-        case "wifi.wait_disconnected": {
-            const poll = expr("wifi.is_connected");
-            if (poll) {
-                return { startLines: [], pollCond: `!${poll}`, timeoutExpr: null };
-            }
-            break;
-        }
         case "wifi.scan": {
             const start = route({ operation: "wifi.scan_start" });
             const poll = expr("wifi.scan_done");
@@ -394,33 +423,6 @@ function netWaitInfo(op, strategy) {
             }
             break;
         }
-        case "ble.until_connected": {
-            const start = route({ operation: "ble.until_connected_start" });
-            const poll = expr("ble.is_connected");
-            if (start?.code && poll) {
-                return {
-                    startLines: [start.code],
-                    pollCond: poll,
-                    timeoutExpr: isZeroTimeout(o.timeoutMs) ? null : ms(o.timeoutMs),
-                };
-            }
-            break;
-        }
-        case "worker.submit": {
-            // Worker offload (Phase 3). `await worker.submit(fn, arg)` rewrites to:
-            // submit the worker (start), then poll worker.done on the same handle.
-            // The submit op is emitted verbatim as the start line; the poll predicate
-            // is worker.done(handle) carrying the SAME handleId. This is a predicate-
-            // poll resume (same per-frame cost as net/timer awaits), NOT an ISR-driven
-            // resume — that defers with DMA-backed awaits.
-            const submit = routeHALOp(op, strategy);
-            // Carry the handle through to the poll so submit + done agree on the slot.
-            const poll = route({ operation: "worker.done", handleId: o.handleId })?.expression ?? null;
-            if (submit?.code && poll) {
-                return { startLines: [submit.code], pollCond: poll, timeoutExpr: null };
-            }
-            break;
-        }
     }
     // Fallback: run the blocking form immediately and complete on the next tick.
     const blocking = routeHALOp(op, strategy);

package/dist/emit/utils/comment-helpers.d.ts

@@ -2,14 +2,6 @@
  * Comment handling utilities for C++ code emission.
  * Extracted from cpp-emitter.ts
  */
-/**
- * Normalizes a comment string into an array of trimmed lines.
- * Removes empty lines and trailing whitespace.
- *
- * @param comment The comment string (may contain newlines)
- * @returns Array of normalized comment lines
- */
-export declare function normalizeComment(comment: string): string[];
 /**
  * Emits comment lines with proper indentation.
  *