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

package/dist/create/wizard.js

@@ -0,0 +1,314 @@
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { execSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import chalk from "chalk";
+import { KNOWN_TARGETS } from "./scaffold.js";
+import { findPackBoard, packBoardAsTarget } from "./pack-targets.js";
+import { pickTarget } from "./board-search.js";
+import { activeBoardCatalog } from "../board-catalog/index.js";
+import { frameworksForTarget, frameworkCatalogEntry, frameworkCompatibleWithTarget, FRAMEWORK_CATALOG, frameworkTargetProfile, probeMethodsForBoard } from './framework-catalog.js';
+/**
+ * Attached serial ports for the wizard's port question — dependency-free
+ * (the wizard runs before any project deps exist, and cuttlefish itself
+ * carries no native serialport binding). Windows asks the .NET SerialPort
+ * class via PowerShell; macOS/Linux scan /dev for USB CDC/bridge nodes.
+ * Returns [] when enumeration fails — the question then falls back to a
+ * free-text prompt with the platform hint as default.
+ */
+export function detectSerialPorts() {
+    try {
+        if (process.platform === "win32") {
+            const out = execSync("[System.IO.Ports.SerialPort]::GetPortNames() -join ','", { shell: "powershell.exe", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).toString();
+            return out.split(",").map((s) => s.trim()).filter((s) => /^[Cc][Oo][Mm]\d+$/.test(s));
+        }
+        const dev = readdirSync("/dev");
+        return dev
+            .filter((n) => /^tty(ACM|USB)/.test(n) || /^cu\.(usb|USB|modem)/.test(n))
+            .map((n) => (process.platform === "darwin" ? `/dev/${n}` : `/dev/${n}`))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function validateProjectName(name) {
+    if (!name || name.trim().length === 0) {
+        return "Project name cannot be empty.";
+    }
+    const normalized = name.trim().toLowerCase();
+    if (!/^[a-z][a-z0-9-]*$/.test(normalized)) {
+        return "Project name must start with a letter and contain only lowercase letters, digits, and hyphens.";
+    }
+    if (normalized.length > 64) {
+        return "Project name must be 64 characters or fewer.";
+    }
+    return null;
+}
+async function promptText(rl, prompt, defaultValue, validate) {
+    while (true) {
+        const suffix = defaultValue ? ` (${defaultValue})` : "";
+        const answer = await rl.question(`${chalk.cyan("?")} ${prompt}${suffix}: `);
+        const value = (answer.trim() || (defaultValue ?? "")).trim();
+        if (validate) {
+            const error = validate(value);
+            if (error) {
+                console.log(`  ${chalk.red("✗")} ${error}`);
+                continue;
+            }
+        }
+        return value;
+    }
+}
+async function promptSelect(rl, prompt, options) {
+    console.log(`${chalk.cyan("?")} ${prompt}:`);
+    for (let i = 0; i < options.length; i++) {
+        console.log(`  ${chalk.dim(`${i + 1})`)} ${options[i].label}`);
+    }
+    while (true) {
+        const answer = await rl.question(`  Enter number (1-${options.length}): `);
+        const idx = parseInt(answer.trim(), 10) - 1;
+        if (idx >= 0 && idx < options.length) {
+            return options[idx].value;
+        }
+        console.log(`  ${chalk.red("✗")} Please enter a number between 1 and ${options.length}.`);
+    }
+}
+async function promptConfirm(rl, prompt, defaultValue) {
+    const suffix = defaultValue ? " (Y/n)" : " (y/N)";
+    const answer = await rl.question(`${chalk.cyan("?")} ${prompt}${suffix}: `);
+    const trimmed = answer.trim().toLowerCase();
+    if (trimmed === "")
+        return defaultValue;
+    return trimmed === "y" || trimmed === "yes";
+}
+export async function runCreateWizard(partialOptions) {
+    let rl = readline.createInterface({ input, output });
+    try {
+        console.log();
+        console.log(chalk.cyan("⤳ Cuttlefish") + chalk.dim(" — Project Setup"));
+        console.log();
+        // 1. Project name
+        const projectName = partialOptions?.projectName
+            ?? await promptText(rl, "Project name", "my-project", validateProjectName);
+        // 2. Target selection — the filterable board picker covers everything:
+        //    native, bare silicon (soc entries), and every Zephyr board from the
+        //    catalog. One search box, no two-stage list. A preseeded --board that
+        //    resolves skips the picker entirely.
+        let packBoard;
+        let foundTarget;
+        if (partialOptions?.board) {
+            const found = KNOWN_TARGETS.find((t) => t.id === partialOptions.board);
+            const packFound = found ? undefined : findPackBoard(partialOptions.board);
+            if (found) {
+                foundTarget = found;
+                console.log(`${chalk.cyan("?")} Target: ${chalk.white(found.displayName)} (${chalk.dim(partialOptions.board)})`);
+            }
+            else if (packFound) {
+                packBoard = packFound;
+                console.log(`${chalk.cyan("?")} Target: ${chalk.white(packFound.name)} (${chalk.dim(packFound.identifier)})`);
+            }
+        }
+        if (Object.keys(activeBoardCatalog()).length === 0) {
+            console.log(`  ${chalk.yellow("!")} No board catalog on this machine — the catalog is generated`);
+            console.log(`    from your Zephyr tree. Run the installer or 'cuttlefish board sync' to`);
+            console.log(`    list boards; a preseeded --board <target> still works and validates at`);
+            console.log(`    the first build.`);
+        }
+        if (!foundTarget && !packBoard) {
+            // Close the readline interface for the filterable select (it owns
+            // stdin in raw mode), then recreate it for the remaining prompts.
+            // Closing a readline pauses stdin; resume it so the select's internal
+            // readline receives character bytes (arrow keys arrive via keypress
+            // events either way, but typed characters need flowing mode).
+            rl.close();
+            input.resume();
+            const pick = await pickTarget();
+            rl = readline.createInterface({ input, output });
+            if (!pick) {
+                console.log(`  ${chalk.yellow("!")} Target selection cancelled.`);
+                return null;
+            }
+            if (pick.kind === 'native') {
+                foundTarget = KNOWN_TARGETS.find((t) => t.isNative);
+            }
+            else if (pick.kind === 'mcu') {
+                // Bare-silicon targets were removed with the curated soc layer.
+                console.log(`  ${chalk.yellow("!")} Bare-silicon targets no longer exist — pick a board from the catalog.`);
+            }
+            else {
+                packBoard = pick.entry;
+                console.log(`${chalk.cyan("?")} Target: ${chalk.white(pick.entry.name)} (${chalk.dim(pick.entry.identifier)})`);
+            }
+        }
+        const target = packBoard
+            ? packBoardAsTarget(packBoard)
+            : foundTarget;
+        // 3. Framework. Narrow to the frameworks compatible with the selected board
+        // (see framework-catalog), then let the user pick. The chosen package is
+        // installed into the new project by `cuttlefish create`, so we offer every
+        // compatible framework regardless of what is currently installed — no
+        // require.resolve discovery (which also avoided an ESM `require` pitfall
+        // where the lookup always failed and made the wizard dead-end).
+        let framework = target.framework;
+        let frameworkPackage = target.frameworkPackage;
+        const compatible = frameworksForTarget(target)
+            .filter((f) => f.installable);
+        if (compatible.length === 0) {
+            // Defensive: every known target maps to at least one framework in the catalog.
+            throw new Error(`No installable frameworks are compatible with target '${target.id}'.`);
+        }
+        if (partialOptions?.framework) {
+            const requested = frameworkCatalogEntry(partialOptions.framework);
+            if (!requested) {
+                const available = FRAMEWORK_CATALOG.filter(f => f.installable).map(f => f.id).join(", ");
+                throw new Error(`Unknown framework '${partialOptions.framework}'. Available: ${available}`);
+            }
+            // Same compatibility guard as the non-interactive CLI path: a preseeded
+            // --framework bypasses the narrowing below, so validate it explicitly.
+            if (!frameworkCompatibleWithTarget(target, requested.id)) {
+                const list = compatible.map(f => f.id).join(", ");
+                throw new Error(`Framework '${requested.id}' is not compatible with target '${target.id}' (${target.displayName}). ` +
+                    `Compatible frameworks: ${list}`);
+            }
+            framework = requested.id;
+            frameworkPackage = requested.packageName;
+            console.log(`${chalk.cyan("?")} Framework: ${chalk.white(requested.label)}`);
+        }
+        else if (compatible.length === 1) {
+            framework = compatible[0].id;
+            frameworkPackage = compatible[0].packageName;
+            console.log(`${chalk.cyan("?")} Framework: ${chalk.white(compatible[0].label)}`);
+        }
+        else {
+            const selected = await promptSelect(rl, "Framework", compatible.map((f) => ({ label: f.label, value: f.id })));
+            const match = compatible.find((f) => f.id === selected);
+            framework = match.id;
+            frameworkPackage = match.packageName;
+        }
+        // Resolve the framework-specific build target + toolchain (the Zephyr
+        // board id + 'west'). See framework-catalog.
+        const profile = frameworkTargetProfile(target, framework);
+        let buildTarget = profile.buildTarget ?? target.buildTarget;
+        let zephyrCustomBoard = false;
+        // 3.5 Probe method (Zephyr boards that ship a table). The probe in the
+        // user's hand becomes the scaffolded zephyr.probe entry — it serves both
+        // flashing and debugging; "board default" omits the section.
+        let probeMethod;
+        const probeMethods = framework === 'zephyr' ? probeMethodsForBoard(target.id) : [];
+        if (probeMethods.length > 0) {
+            if (partialOptions?.probe) {
+                probeMethod = partialOptions.probe;
+                console.log(`${chalk.cyan("?")} Probe method: ${chalk.white(probeMethod)}`);
+            }
+            else {
+                const chosen = await promptSelect(rl, "Which probe will you attach to this board?", [
+                    ...probeMethods.map((m) => ({ label: `${m.id} — ${m.description}`, value: m.id })),
+                    { label: "board default (no zephyr.probe entry)", value: "" },
+                ]);
+                probeMethod = chosen === "" ? undefined : chosen;
+            }
+        }
+        // 4. Serial port (only for embedded) — the port the board rides on.
+        // Detected ports are offered as a choice; the answer seeds test.port in
+        // the scaffolded config (no more guessing COM4). "skip" leaves the
+        // platform-hint placeholder.
+        let serialPort;
+        if (!target.isNative) {
+            if (partialOptions?.port) {
+                serialPort = partialOptions.port;
+                console.log(`${chalk.cyan("?")} Serial port: ${chalk.white(serialPort)}`);
+            }
+            else {
+                const detected = detectSerialPorts();
+                if (detected.length > 0) {
+                    const chosenPort = await promptSelect(rl, "Which serial port is the board attached to?", [
+                        ...detected.map((p) => ({ label: p, value: p })),
+                        { label: "not listed / set later (type a path)", value: "__other__" },
+                        { label: "skip — use the placeholder, configure later", value: "" },
+                    ]);
+                    serialPort = chosenPort === "" ? undefined
+                        : chosenPort === "__other__" ? await promptText(rl, "Serial port path", detected[0])
+                            : chosenPort;
+                }
+                else {
+                    const hint = process.platform === "win32" ? "COM4" : "/dev/ttyACM0";
+                    const typed = await promptText(rl, "Serial port (none detected — plug the board in, or type a path)", hint);
+                    serialPort = typed === hint ? undefined : typed;
+                }
+            }
+        }
+        // 5. Baud rate (only for embedded)
+        let baudRate;
+        if (!target.isNative) {
+            // Zephyr consoles default to 115200; 9600 is the Arduino-class default.
+            const defaultBaud = framework === 'zephyr' ? 115200 : 9600;
+            if (partialOptions?.baud) {
+                baudRate = partialOptions.baud;
+                console.log(`${chalk.cyan("?")} Serial baud rate: ${chalk.white(baudRate)}`);
+            }
+            else {
+                const baudAnswer = await promptText(rl, "Serial baud rate", String(defaultBaud));
+                baudRate = parseInt(baudAnswer, 10);
+                if (Number.isNaN(baudRate) || baudRate <= 0) {
+                    baudRate = defaultBaud;
+                    console.log(`  ${chalk.dim(`Using default: ${defaultBaud}`)}`);
+                }
+            }
+        }
+        // 5. Starter program
+        let includeStarter;
+        if (partialOptions?.noStarter) {
+            includeStarter = false;
+            console.log(`${chalk.cyan("?")} Create starter program: ${chalk.dim("no")}`);
+        }
+        else if (partialOptions?.noStarter === false) {
+            includeStarter = true;
+            console.log(`${chalk.cyan("?")} Create starter program: ${chalk.green("yes")}`);
+        }
+        else {
+            includeStarter = await promptConfirm(rl, "Create starter program?", true);
+        }
+        return {
+            probeMethod,
+            probeMethods,
+            projectName,
+            targetId: target.id,
+            targetDisplayName: target.displayName,
+            isNative: target.isNative,
+            architecture: target.architecture,
+            board: target.board,
+            // Pack fact: does the board's devicetree declare an LED? Drives the
+            // starter between LED-blink and an I/O skeleton.
+            ...(target.board ? { hasLed: Boolean(activeBoardCatalog()[target.board]?.led) } : {}),
+            ...(serialPort ? { port: serialPort } : {}),
+            frameworkPackage: frameworkPackage ?? '',
+            framework: framework ?? '',
+            buildTarget,
+            ...(profile.toolchainType ? { toolchainType: profile.toolchainType } : {}),
+            // soc rides the config only for native projects — a board target's
+            // soc derives from the identifier at boardgen time.
+            ...(target.board ? {} : { soc: target.soc }),
+            ...(zephyrCustomBoard ? { zephyrCustomBoard: true } : {}),
+            baudRate,
+            includeStarter,
+            ...(target.frameworkData
+                ? { frameworkData: target.frameworkData }
+                : {}),
+        };
+    }
+    catch (err) {
+        if (err && typeof err === 'object' && err.code === 'ERR_USE_AFTER_CLOSE') {
+            return null;
+        }
+        throw err;
+    }
+    finally {
+        // The board picker closes rl itself (it hands stdin to the filterable
+        // select); a second close is harmless but explicit is cleaner.
+        try {
+            rl.close();
+        }
+        catch { /* already closed */ }
+    }
+}

package/dist/debug/preprocessor.d.ts

@@ -1,4 +1,5 @@
 import type { BreakpointMap } from './types.js';
+import type { PlatformStrategy } from '../api/shared/platform-strategy.js';
 export declare function preprocess(options: {
     /** The source file path (for line number calculation) */
     fileName: string;
@@ -6,4 +7,8 @@ export declare function preprocess(options: {
     breakpoints: BreakpointMap;
     /** The source text to transform */
     source: string;
+    /** The platform strategy that will emit this file — its debug dialect
+     *  (generateDebug*Code) is used. Omit when unknown; the global loaded
+     *  framework is consulted, then the generic printf codegen. */
+    strategy?: PlatformStrategy;
 }): string;

package/dist/debug/preprocessor.js

@@ -10,20 +10,32 @@ import path from 'node:path';
 import { getBreakpointsForFile } from './breakpoint-loader.js';
 import { getLoadedFramework, hasLoadedFramework } from '../framework-registry.js';
 import { GenericStrategy } from '../platform/generic-strategy.js';
-function getDebugStrategy() {
+function getDebugStrategy(explicit) {
+    // The strategy that will EMIT this file decides the debug dialect — its
+    // codegen must match the runtime the emitted code links against. The
+    // global loaded-framework registry is only a fallback for callers that
+    // don't know their strategy (picking it blind once emitted Zephyr printk
+    // code into a native build).
+    if (explicit) {
+        if (explicit.generateDebugInitCode)
+            return explicit;
+        // The emitting strategy has no debug dialect (e.g. NativeStrategy) —
+        // its embedded fallback is the generic printf codegen.
+        return new GenericStrategy();
+    }
     if (hasLoadedFramework()) {
         const { strategy } = getLoadedFramework();
         if (strategy.generateDebugInitCode)
             return strategy;
     }
-    // Fall back to the generic strategy's std::cout-based debug output
+    // Fall back to the generic strategy's printf-based debug output
     return new GenericStrategy();
 }
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 export function preprocess(options) {
-    const { fileName, breakpoints, source } = options;
+    const { fileName, breakpoints, source, strategy: emittingStrategy } = options;
     const breakpointLines = getBreakpointsForFile(breakpoints, fileName);
     if (breakpointLines.length === 0) {
         return source; // No breakpoints, return unchanged
@@ -39,7 +51,7 @@ export function preprocess(options) {
     }
     // Collect variables in scope at each breakpoint
     const scopeAnalyzer = new ScopeAnalyzer(sf);
-    const debugStrategy = getDebugStrategy();
+    const debugStrategy = getDebugStrategy(emittingStrategy);
     // Per-file breakpoint ID counter. Each HALTING breakpoint gets a stable
     // integer ID so the codegen can emit a per-breakpoint disable flag (skipped
     // via the 's' key at runtime). IDs are scoped to this file and reset per
@@ -198,7 +210,11 @@ class ScopeAnalyzer {
         // so a local declared on line N is not yet in scope at line N. Params and
         // enclosing-scope vars are in scope from the function's first line.
         const recordFunction = (node, currentVars) => {
-            const startLine = this.sf.getLineAndCharacterOfPosition(node.getStart()).line;
+            // Scope starts at the BODY, not the signature: a breakpoint on the
+            // signature line is injected BEFORE the function exists (top-level
+            // position), so params are not in scope there — treating it as
+            // in-function dumped undeclared identifiers into main().
+            const startLine = this.sf.getLineAndCharacterOfPosition((node.body ?? node).getStart()).line;
             const endLine = node.body
                 ? this.sf.getLineAndCharacterOfPosition(node.body.getEnd()).line
                 : startLine;
@@ -227,9 +243,17 @@ class ScopeAnalyzer {
                 this.functionVars.set(line, [...alwaysInScope, ...localsInScope]);
             }
         };
-        // Find top-level functions, then recurse into their bodies for nested ones.
+        // Find top-level functions, then recurse into their bodies for nested
+        // ones. Top-level functions start from an EMPTY enclosing scope: the
+        // module-scope variables live in the enclosing scope chain only for
+        // NESTED functions. Top-level statements lower into main() locals, so a
+        // module-scope name is not visible inside a top-level function — dumping
+        // one there emitted references to undeclared identifiers (a breakpoint in
+        // any function flagged every top-level const). A breakpoint placed on a
+        // top-level statement still sees them via getVariablesInScope's top-level
+        // path, filtered by declaration order.
         for (const stmt of this.sf.statements) {
-            this.findAndRecordFunctions(stmt, topLevelVars, recordFunction);
+            this.findAndRecordFunctions(stmt, [], recordFunction);
         }
     }
     /** Collect variables declared directly by a single statement (top-level use). */

package/dist/diagnostics/diagnostics-report.d.ts

@@ -15,7 +15,7 @@ export interface DiagnosticsReportInput {
     /** Target architecture (e.g. "avr", "esp32") */
     target: string;
     /** Board package name */
-    boardPackage?: string;
+    boardTarget?: string;
     /** Framework package name */
     frameworkPackage?: string;
     /** Build target identifier */

package/dist/diagnostics/diagnostics-report.js

@@ -102,7 +102,7 @@ function buildPinUsage(program, boardPinsData) {
     const usage = program.peripheralUsage;
     // Map board pins to GPIO entries
     for (const pin of boardPinsData) {
-        // Only include pins that are explicitly used in the sketch to keep the table clean
+        // Only include pins that are explicitly used in the program to keep the table clean
         const isExplicitlyUsed = usage.pinsUsed.has(pin.name) ||
             pin.aliases.some(a => usage.pinsUsed.has(a)) ||
             (pin.number !== undefined && (usage.outputPins.has(pin.number) ||
@@ -161,14 +161,6 @@ function buildPinUsage(program, boardPinsData) {
             pins: [...usage.pwmPinsUsed].map((n) => `D${n}`),
         });
     }
-    if (usage.timer0) {
-        peripherals.push({
-            type: "timer",
-            instance: 0,
-            displayName: "Timer0 (millis/micros)",
-            pins: [],
-        });
-    }
     if (usage.externalInterrupts) {
         peripherals.push({
             type: "interrupt",
@@ -261,10 +253,10 @@ export function buildDiagnosticsReport(input) {
             timestamp: new Date().toISOString(),
             sourceFile: path.basename(input.entryFile),
             target: input.target,
-            board: input.boardPackage,
+            board: input.boardTarget,
             framework: input.frameworkPackage,
             buildTarget: input.buildTarget,
-            outputFile: input.outputFile ?? path.basename(input.entryFile, path.extname(input.entryFile)) + ".ino",
+            outputFile: input.outputFile ?? path.basename(input.entryFile, path.extname(input.entryFile)) + ".cpp",
             boardDetails: program?.boardConstants ? {
                 mcu: program.boardConstants.get("mcu"),
                 architecture: program.boardConstants.get("architecture"),

package/dist/diagnostics/json-schema.d.ts

@@ -8,7 +8,7 @@ export interface GpioPinEntry {
     peripheralRole?: string;
 }
 export interface PeripheralAllocation {
-    type: "i2c" | "spi" | "uart" | "adc" | "pwm" | "timer" | "interrupt";
+    type: "i2c" | "spi" | "uart" | "adc" | "pwm" | "interrupt";
     instance: number;
     displayName: string;
     pins: string[];

package/dist/diagnostics/md-writer.js

@@ -55,7 +55,7 @@ function buildExecutionFlowSection(flow, callGraph) {
     const lines = [];
     lines.push("## Execution Flow");
     lines.push("");
-    lines.push("> This graph shows the relationships between entry points, HAL objects, and Arduino APIs.");
+    lines.push("> This graph shows the relationships between entry points, HAL objects, and framework APIs.");
     lines.push("");
     lines.push(buildExecutionFlowDiagram(flow, callGraph));
     lines.push("");
@@ -174,7 +174,7 @@ function buildAsyncTasksSection(tasks) {
     lines.push("## Cooperative Multitasking");
     lines.push("");
     if (tasks.length === 0) {
-        lines.push("> _No async tasks registered in this sketch._");
+        lines.push("> _No async tasks registered in this program._");
         lines.push("");
         return lines.join("\n");
     }

package/dist/diagnostics/mermaid-builder.d.ts

@@ -1,7 +1,7 @@
 import type { CallGraph } from "../ir/call-graph.js";
 import type { GpioPinEntry, PeripheralAllocation, AsyncTaskEntry, ExecutionFlow, HeapEstimate, PeripheralConflictEntry, ModuleGraph, TreeShakingReport, BuildTiming } from "./json-schema.js";
 /**
- * Build a categorized architecture diagram showing how the sketch
+ * Build a categorized architecture diagram showing how the program
  * is organized: entry points, HAL objects, HAL APIs (grouped by
  * subsystem), state variables, and custom functions.
  *

package/dist/diagnostics/mermaid-builder.js

@@ -73,7 +73,7 @@ function isHalApi(name) {
 }
 // ── Execution Flow Diagram ──────────────────────────────────────────────────
 /**
- * Build a categorized architecture diagram showing how the sketch
+ * Build a categorized architecture diagram showing how the program
  * is organized: entry points, HAL objects, HAL APIs (grouped by
  * subsystem), state variables, and custom functions.
  *

package/dist/emit/cpp-emitter.js

@@ -1,5 +1,5 @@
 import { buildEmitterContext } from "./emitters/setup.js";
-import { emitPreamble, emitAsyncTaskClasses, finalizeOutput } from "./emitters/output-finalizer.js";
+import { emitPreamble, emitAsyncTaskClasses, emitAsyncMethodTasks, 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";
@@ -39,6 +39,9 @@ export function emitCpp(program, options) {
     emitFunctionForwardDeclarations(ctx);
     // 7. Emit classes
     emitClasses(ctx);
+    // 7.5. Async-method tasks — after the owning classes (segments dereference
+    // _owner->field on a complete type), before functions (loop pump + starters).
+    emitAsyncMethodTasks(ctx);
     // 8. Emit post-class declarations (runtime vars, promoted vars, object literal structs)
     emitPostClassDeclarations(ctx);
     // 9. Emit callbacks + forward declarations + function definitions

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

@@ -142,7 +142,7 @@ export function emitClasses(ctx) {
     // Build variable → accessor map. NOTE: the variable/parameter registration
     // now lives in setup.ts so it runs before any emit pass. The classAccessorNames
     // map built here is still used below for the per-method "this" registration.
-    // See SUPPORT_MATRIX §4.3 (demo #4 fix).
+    // (demo #4 fix.)
     // Build virtual/override maps for inherited methods
     const classMethodNames = new Map();
     for (const cls of program.classes) {
@@ -331,7 +331,19 @@ export function emitClasses(ctx) {
                 if (method.typeParameters && method.typeParameters.length > 0) {
                     appendSourceLine(ctx, `  template<typename ${method.typeParameters.join(", typename ")}>`);
                 }
-                appendSourceLine(ctx, `  ${virtualPrefix}${staticPrefix}${returnType} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams})${overrideSuffix} {`);
+                // Async methods: the body becomes an owner-bound cooperative task
+                // (setup.ts generates it); the in-class body just binds the receiver
+                // via the forward-declared starter. Return type is void — the task
+                // is fire-and-forget.
+                const asyncKick = method.isAsync && ctx.hasAsyncRuntime;
+                const emittedReturnType = asyncKick ? "void" : returnType;
+                appendSourceLine(ctx, `  ${virtualPrefix}${staticPrefix}${emittedReturnType} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams})${overrideSuffix} {`);
+                if (asyncKick) {
+                    appendSourceLine(ctx, `    __tc_async_start_${classDef.name}_${method.name}(this);`);
+                    appendSourceLine(ctx, "  }");
+                    appendSourceLine(ctx, "");
+                    continue;
+                }
                 const methodScope = createChildEmissionScope(topLevelScope, method.parameters);
                 addClassFieldsToScope(classDef, methodScope);
                 const classAccessors = classAccessorNames.get(classDef.name);
@@ -403,7 +415,15 @@ export function emitClasses(ctx) {
                 if (method.typeParameters && method.typeParameters.length > 0) {
                     appendSourceLine(ctx, `  template<typename ${method.typeParameters.join(", typename ")}>`);
                 }
-                appendSourceLine(ctx, `  ${virtualPrefix}${staticPrefix}${normalizeCppTypeForTarget(method.returnType)} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams})${overrideSuffix} {`);
+                const asyncKick = method.isAsync && ctx.hasAsyncRuntime;
+                const emittedReturnType = asyncKick ? "void" : normalizeCppTypeForTarget(method.returnType);
+                appendSourceLine(ctx, `  ${virtualPrefix}${staticPrefix}${emittedReturnType} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams})${overrideSuffix} {`);
+                if (asyncKick) {
+                    appendSourceLine(ctx, `    __tc_async_start_${classDef.name}_${method.name}(this);`);
+                    appendSourceLine(ctx, "  }");
+                    appendSourceLine(ctx, "");
+                    continue;
+                }
                 const methodScope = createChildEmissionScope(topLevelScope, method.parameters);
                 addClassFieldsToScope(classDef, methodScope);
                 withThisAccessors(classDef, method.isStatic, () => {
@@ -469,7 +489,15 @@ export function emitClasses(ctx) {
                 if (method.typeParameters && method.typeParameters.length > 0) {
                     appendSourceLine(ctx, `  template<typename ${method.typeParameters.join(", typename ")}>`);
                 }
-                appendSourceLine(ctx, `  ${virtualPrefix}${staticPrefix}${normalizeCppTypeForTarget(method.returnType)} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams})${overrideSuffix} {`);
+                const asyncKick = method.isAsync && ctx.hasAsyncRuntime;
+                const emittedReturnType = asyncKick ? "void" : normalizeCppTypeForTarget(method.returnType);
+                appendSourceLine(ctx, `  ${virtualPrefix}${staticPrefix}${emittedReturnType} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams})${overrideSuffix} {`);
+                if (asyncKick) {
+                    appendSourceLine(ctx, `    __tc_async_start_${classDef.name}_${method.name}(this);`);
+                    appendSourceLine(ctx, "  }");
+                    appendSourceLine(ctx, "");
+                    continue;
+                }
                 const methodScope = createChildEmissionScope(topLevelScope, method.parameters);
                 addClassFieldsToScope(classDef, methodScope);
                 withThisAccessors(classDef, method.isStatic, () => {

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

@@ -90,6 +90,16 @@ export interface AsyncTaskClass {
     classDef: string;
     instanceDecl: string;
     taskVarName: string;
+    /** Async methods: the starter-function DEFINITION (binds the owner and
+     *  arms the task). Emitted after the task class; the matching prototype
+     *  (asyncMethodStarters) precedes the owning class. */
+    starterDef?: string;
+}
+/** Forward prototypes for async-method starters — emitted before the class
+ *  definitions whose method bodies call them. */
+export interface AsyncMethodStarter {
+    /** The `void __tc_async_start_<Class>_<method>(<Class>*);` prototype. */
+    proto: string;
 }
 export interface FixPointerFieldAccessFn {
     (callee: string): string;
@@ -139,6 +149,7 @@ export interface EmitterContext {
     boardConstants?: BoardConstants;
     restParamFunctions?: Map<string, string>;
     asyncTaskClasses: AsyncTaskClass[];
+    asyncMethodStarters: AsyncMethodStarter[];
     asyncFunctionOriginalNames: Set<string>;
     asyncFunctionMappedNames: Set<string>;
     hasAsyncRuntime: boolean;

package/dist/emit/emitters/entrypoint-synthesizer.js

@@ -53,7 +53,7 @@ export function synthesizeEntrypoints(ctx) {
                 ctx.emitDiagnostics.push({
                     severity: "error",
                     code: "gpio-unsupported-on-target",
-                    message: `${which} require GPIO hardware, which this target (${ctx.options.target}) does not model. Use the browser preview to exercise pin-driven UI, or target @typecad/framework-arduino.`,
+                    message: `${which} require GPIO hardware, which this target (${ctx.options.target}) does not model. Use the browser preview to exercise pin-driven UI, or target a framework that models GPIO pins.`,
                     source: program.fileName,
                 });
             }