@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/platform-strategy.d.ts

@@ -0,0 +1,402 @@
+import type { ExpressionIR, ProgramIR } from './ir.js';
+import type { HALOpIR } from './hal-op-ir.js';
+import type { Diagnostic, PlatformContext } from './types.js';
+import type { BoardConstants } from './board-resolver.js';
+import type { AsyncRuntimeConfig } from './async-types.js';
+import type { RuntimePolyfillIR, StdLibSupport } from './polyfill-types.js';
+import type { PlatformGraphicsStrategy } from './graphics-strategy.js';
+export interface PlatformProfileStrategy {
+    /** System #include headers forced at the top of every emitted file. */
+    forcedIncludes(program: ProgramIR, ctx?: PlatformContext): string[];
+    /** Symbol aliases (TypeScript name → C++ name). */
+    symbolAliases(program: ProgramIR, ctx?: PlatformContext): Record<string, string>;
+    /** Extra shim lines emitted after includes (e.g. #define fallbacks). */
+    shimLines(program: ProgramIR, ctx?: PlatformContext): string[];
+    /** Diagnostics produced during profile resolution. */
+    profileDiagnostics(program: ProgramIR, ctx?: PlatformContext): Diagnostic[];
+    /** Extension for the output source file ("ino", "cpp", "c"). */
+    sourceExtension(isEntryFile: boolean, isNpmPackage: boolean): string;
+    /**
+     * Returns code to insert at the beginning of setup()/main().
+     * Used for platform-specific initialization (e.g., UART init for native console).
+     */
+    setupInitCode?(program: ProgramIR, ctx?: PlatformContext): string[];
+    /** Name of the entrypoint function ("setup" for embedded, "main" for hosted). */
+    entrypointFunctionName(): string;
+    /** Whether a no-arg loop function must be auto-generated (embedded targets need loop()). */
+    requiresLoopFunction(): boolean;
+    /** Base name override for the output file (some targets use the output dir name). */
+    overrideBaseName(originalBaseName: string, outDirBaseName: string, isEntryFile: boolean, isNpmPackage: boolean): string;
+    /** Effective emit mode – some targets force "cpp" regardless of user choice. */
+    effectiveEmitMode(requestedMode: string, isNpmPackage: boolean): string;
+    /** Whether <iostream> should be included (for std::cout). */
+    needsIostream(): boolean;
+    /** Whether <string> should be included. */
+    needsStdString(): boolean;
+    /** Whether <vector> should be included. */
+    needsStdVector(): boolean;
+    /** Whether <stdexcept> should be included. */
+    needsStdExcept(): boolean;
+    /** Whether <functional> should be included. */
+    needsStdFunction(): boolean;
+    /** Math header name ("<cmath>" or "<math.h>"). */
+    mathHeader(): string;
+    /** cstring header name ("<cstring>" on hosted, "<string.h>" on embedded/AVR). */
+    cstringHeader(): string;
+    /** Whether the vector operator<< overload should be emitted. */
+    needsVectorOverload(): boolean;
+    /** Whether a large enum needs an explicit underlying type. */
+    needsLargeEnumUnderlying(): boolean;
+    /** Whether to skip a type alias for this platform (e.g. std::string where unsupported). */
+    shouldSkipTypeAlias(cppType: string): boolean;
+    /** Extra diagnostics to add during emit. */
+    emitDiagnostics(emitMode: string): Diagnostic[];
+    /**
+     * Names of functions that must be excluded from forward declarations
+     * (e.g., entry points like setup/loop/main that the platform defines).
+     */
+    forwardDeclarationExclusions?(): string[];
+    /**
+     * Platform-specific ambient TypeScript type declarations appended to
+     * the generated cuttlefish-env.d.ts file.
+     * Return an empty array if no platform-specific declarations are needed.
+     */
+    ambientTypeDeclarations?(): string[];
+}
+export interface PlatformPolyfillStrategy {
+    /**
+     * Returns a set of polyfill IDs that this strategy handles natively.
+     * The emitter will skip emitting these polyfills from the global system.
+     */
+    nativePolyfills?(): Set<string>;
+    /**
+     * Returns polyfill IR for polyfills that this strategy provides natively.
+     */
+    generateNativePolyfills?(program: ProgramIR, ctx?: PlatformContext): RuntimePolyfillIR[];
+}
+export interface PlatformTypeStrategy {
+    /** Map a C++ type string to the platform-safe equivalent. */
+    normalizeCppType(typeName: string): string;
+    /** Return type to use for a named function (e.g. setup/loop → void). */
+    mapReturnType(functionName: string, returnType: string): string;
+    /** Whether a C++ type behaves like a string (needs .c_str() or is const char*). */
+    isStringLikeType(cppType: string): boolean;
+    /** Whether a C++ type is a pointer (needs -> instead of .). */
+    isPointerType(cppType: string): boolean;
+    /** Map a function name to the platform entrypoint (e.g. void/__cuttlefish_entrypoint__ → setup). */
+    mapFunctionName(originalName: string): string;
+    /**
+     * Prefix an enum member name if it conflicts with a platform macro.
+     * Return the original name if no rename is needed.
+     */
+    renameEnumMember(enumName: string, memberName: string): string;
+    /**
+     * Whether enum member access should be wrapped in static_cast<int/long>.
+     * Returns the cast type ("int", "long") or undefined for no cast.
+     */
+    enumCastType(enumName: string): string | undefined;
+    /**
+     * Enum names whose member access should render as bare C identifiers
+     * (no scoped prefix).  For example, if "AnalogReference" is a passthrough
+     * enum, `AnalogReference.INTERNAL` renders as just `INTERNAL` — useful
+     * when the enum members map directly to platform preprocessor macros.
+     */
+    passthroughEnumNames?(): ReadonlySet<string>;
+    /** Default numeric type for the platform (e.g. "int" on hosted, "int32_t" on embedded). */
+    defaultNumericType(): string;
+    /**
+     * Inform the strategy which enums have values exceeding the signed 16-bit range.
+     * The strategy can use this to choose an appropriate underlying type.
+     */
+    setLargeEnumNames?(names: ReadonlySet<string>): void;
+    /** Rename a struct field if it conflicts with platform-reserved names. */
+    renameStructField(fieldName: string): string;
+    /**
+     * Override how a struct initializer field renders its value.
+     * Return undefined to use default rendering.
+     */
+    structFieldInitializer(fieldValue: ExpressionIR, compiletimeVarNames: Set<string>, renderExpr: (e: ExpressionIR) => string): string | undefined;
+}
+export interface PlatformExpressionStrategy {
+    /**
+     * Platform-specific normalisation of raw expression strings.
+     * Applied after the common === → == and !== → != transforms.
+     */
+    normalizeRawExpression(value: string): string;
+    /** How to render a null/undefined identifier value. */
+    nullValue(): string;
+    /** Whether string-literal + concatenation needs wrapping (e.g. String(...) on Arduino). */
+    wrapStringConcat(leftRendered: string, rightRendered: string, leftIsString: boolean): string | undefined;
+    /** Wrap an expression in the platform's string object type (e.g. String(...) on Arduino). */
+    wrapStringObject(expr: string): string;
+    /** Platform-specific expression for current time in milliseconds (e.g. "millis()" on Arduino, "std::chrono" on hosted). */
+    currentTimeMillis(): string;
+    /**
+     * Whether string concat / template interpolation should use snprintf()
+     * instead of platform string objects.
+     */
+    useSnprintfForStrings(): boolean;
+    /**
+     * Whether integer division should be promoted to double to match JavaScript
+     * semantics where 7 / 2 === 3.5.
+     */
+    promoteDivisionToDouble?(): boolean;
+    /**
+     * Convert a float expression to an snprintf-compatible argument.
+     * Return undefined to let the emitter use generic %g / %.Nf formatting.
+     */
+    floatToSnprintfArg?(renderedExpr: string, precision: number | undefined, tempId: number): {
+        format: string;
+        arg: string;
+        estimatedLength: number;
+        preludeLines: string[];
+    } | undefined;
+    /**
+     * Try to render a Board.definition.* property access.
+     * Return `undefined` to fall back to default rendering.
+     */
+    renderBoardDefinitionAccess(chain: string[], boardConstants?: BoardConstants): string | undefined;
+    /**
+     * Maps a generic peripheral name (e.g., I2C0, UART0) to a platform-specific C++ name (e.g., Wire, Serial).
+     * Returns undefined if the strategy does not recognize the name.
+     */
+    mapPeripheralIdentifier?(name: string): string | undefined;
+    /**
+     * Resolve the C++ type for a pin field on a board object (e.g., Pins.D2).
+     * Return `undefined` to use default type inference.
+     */
+    resolvePinType?(objectName: string, fieldName: string): string | undefined;
+}
+export interface PlatformStatementStrategy {
+    /**
+     * How to render a `throw` statement on this platform.
+     * Embedded targets without exception support may emit an infinite loop or halt.
+     */
+    renderThrow(valueExpr: string): string;
+    /**
+     * Transform console.log/error/warn calls to platform output.
+     */
+    isConsoleCall(callee: string): boolean;
+    /** Transform console.log/error/warn calls based on target platform. */
+    transformConsoleCall(method: string, renderedArgs: string, forHeader: boolean): string;
+    /**
+     * Transform console expressions that return values (e.g., console.readLine, console.readCharacter).
+     * Returns the C++ expression that evaluates to the result.
+     * Return undefined to fall back to default rendering.
+     */
+    transformConsoleExpression?(method: string, renderedArgs: string): string | undefined;
+    /**
+     * Fallback value for an object initializer field on this platform.
+     * Some targets use "0" for nested objects; hosted targets pass through.
+     */
+    objectFieldInitializer(fieldValue: ExpressionIR, renderExpr: (e: ExpressionIR) => string): string | undefined;
+    /**
+     * Override a class field type when platform-specific types differ.
+     * E.g. interrupt handlers may need function-pointer types on embedded targets.
+     */
+    overrideClassFieldType(fieldName: string, normalizedType: string): string;
+    /**
+     * Render a serial print/println call that uses a pre-formatted snprintf buffer.
+     * Called when a cuttlefish-call for a serial peripheral has a snprintf-formatted argument.
+     * Return `undefined` to use default method-call rendering.
+     */
+    renderSerialPrintWithSnprintf?(params: {
+        receiver: string;
+        method: string;
+        bufferName: string;
+    }): {
+        finalLine: string;
+    } | undefined;
+    /**
+     * Optional attribute prefix placed before ISR function declarations and
+     * definitions.  Required on ESP32/Xtensa to place ISR code in IRAM so it
+     * can execute while flash is being accessed.
+     *
+     * Returns an empty string on platforms that do not need an attribute
+     * (e.g. AVR).  Includes a trailing space when non-empty.
+     *
+     * Example: `"IRAM_ATTR "` (note the trailing space).
+     */
+    isrFunctionAttribute?(): string;
+}
+export interface PlatformSafetyStrategy {
+    /**
+     * Names that must not be re-declared because the platform already defines them
+     * (e.g. platform macros like HIGH, LOW, Serial, A0 on Arduino).
+     */
+    reservedNames(): ReadonlySet<string>;
+    /**
+     * Identifier names that are platform *value/function-like macros* (e.g.
+     * INPUT, OUTPUT, HIGH, LOW on Arduino) and therefore must pass through
+     * verbatim when referenced in an expression — they must NOT be escaped
+     * (suffixed with `_`) the way a conflicting declaration would be.
+     *
+     * These names typically also appear in `reservedNames()` (so user
+     * declarations with these names are still escaped), but a *reference* to
+     * such a macro should be emitted as-is.
+     */
+    passthroughMacroNames(): ReadonlySet<string>;
+    /**
+     * Enum class names already declared as typedefs by the platform framework.
+     * These get a `#if !defined(...)` guard in the emitted code.
+     */
+    apiReservedEnumNames(): ReadonlySet<string>;
+    /**
+     * The preprocessor guard expression for API-reserved enums
+     * (e.g. "ARDUINO_API_VERSION" on Arduino).
+     */
+    apiReservedEnumGuard(): string;
+    /**
+     * Operations that are unsafe to use inside interrupt handlers.
+     * Returns a map of operation name/prefix → { reason, severity }.
+     */
+    isrUnsafeOperations?(): Map<string, {
+        reason: string;
+        severity: 'warning' | 'info';
+    }>;
+    /**
+     * Whether heap allocation via `operator new` is unsafe on the given architecture.
+     * Frameworks return true for memory-constrained targets (e.g. AVR with 2 KB SRAM).
+     */
+    isHeapAllocationUnsafe?(architecture: string): boolean;
+    /**
+     * Whether C++ exceptions are disabled on the given architecture.
+     * Frameworks return true for targets compiled with -fno-exceptions (e.g. AVR-GCC).
+     */
+    isExceptionSupportDisabled?(architecture: string): boolean;
+    /**
+     * Whether an array literal (`const a: T[] = [...]`) lowers to a fixed-capacity
+     * `__tc_StaticArray<T, N>` (true) or a `std::vector<T>` (false). Embedded and
+     * generic targets return true (StaticArray avoids heap); the native/hosted
+     * target returns false (std::vector). Defaults to true. Used by the structural
+     * array-method lowering to decide whether `.push`/`.pop`/`.indexOf` emit the
+     * StaticArray wrapper's methods or the std::vector/__tc_* helper form.
+     */
+    promotesArrayLiteralsToStaticArray?(): boolean;
+}
+export interface PlatformBuildStrategy {
+    /** Queue capacity for the async microtask ring buffer. */
+    asyncQueueCapacity(): number;
+    /** Output subdirectory relative to base dir. */
+    outputSubdirectory(baseName: string): string;
+    /** Whether to generate a separate header file. */
+    generateHeaderFile(): boolean;
+    /**
+     * Preprocessor guard for API-reserved enums.
+     * Return undefined for no guard.
+     */
+    enumApiGuard(enumName: string): {
+        open: string;
+        close: string;
+    } | undefined;
+    /** Standard library support for the given architecture. */
+    getStdLibSupport(architecture?: string): StdLibSupport;
+}
+/**
+ * Debug code generation sub-interface.
+ * Frameworks implement these to provide platform-specific debug output
+ * (e.g., Serial.println on embedded, std::cout on hosted targets).
+ */
+export interface PlatformDebugStrategy {
+    /** Generate initialization code for the debug subsystem. */
+    generateDebugInitCode?(): string[];
+    /** Generate code for a breakpoint with optional condition and variable dump. */
+    generateDebugBreakpointCode?(params: {
+        fileName: string;
+        lineNum: number;
+        originalLine: string;
+        variables: Array<{
+            name: string;
+            isFunction?: boolean;
+        }>;
+        normalizedCondition?: string;
+    }): string[];
+    /** Generate code for a logpoint with interpolated message parts. */
+    generateDebugLogpointCode?(params: {
+        fileName: string;
+        lineNum: number;
+        parts: Array<{
+            type: 'text' | 'variable';
+            value: string;
+        }>;
+        variables: Array<{
+            name: string;
+            isFunction?: boolean;
+        }>;
+    }): string[];
+}
+export interface PlatformAsyncStrategy {
+    /**
+     * Returns the async runtime configuration for this platform.
+     * The emitter uses this to decide:
+     *   - Whether to include the MicrotaskQueue + Promise<T> runtime
+     *   - How to implement waitForRising/waitForFalling
+     *   - What headers to include
+     *   - What queue capacity to use
+     */
+    getAsyncRuntimeConfig(): AsyncRuntimeConfig;
+    /**
+     * Lines to inject into the loop/run function body to drive async tasks.
+     */
+    asyncLoopInjection(taskVarNames: string[], config: AsyncRuntimeConfig): string[];
+    /**
+     * The function name where microtask pumping and async task driving happens.
+     * Embedded targets: "loop"; Hosted: "main".
+     */
+    asyncDriverFunctionName(): string;
+    /** Optional host event-loop scaffolding wrapping ui_tick in the driver
+     *  function. Return null/undefined for single-shot (today's native behavior)
+     *  or the Arduino repeatedly-called loop(). When provided, the emitter
+     *  declares `flagName` as a bool, then wraps the per-frame work in
+     *  `while (continueCondition) { preIteration; <tick>; postIteration; }`.
+     *  Used by the SDL native target to pump SDL events and present each frame. */
+    hostEventLoop?(): {
+        flagName: string;
+        continueCondition: string;
+        preIteration: string;
+        postIteration: string;
+    } | null;
+}
+/**
+ * Strategy for resolving semantic HAL operations to framework-specific C++.
+ *
+ * When the transpiler encounters a HAL method call that has been resolved to
+ * a {@link HALOpIR} node, it calls {@link resolveHALOperation} so the
+ * framework can produce the correct C++ for the target platform.
+ *
+ * Returning `undefined` signals that the strategy does not handle the
+ * operation; the emitter will fall back to a default or raw emission.
+ */
+export interface PlatformHALStrategy {
+    /**
+     * Resolve a HAL operation to C++ code.
+     *
+     * @param op  The semantic hardware operation to translate.
+     * @returns An object with either `code` (for statements) or `expression`
+     *          (for value-returning operations), or `undefined` to fall back.
+     */
+    resolveHALOperation?(op: HALOpIR): {
+        code?: string;
+        expression?: string;
+    } | undefined;
+    /**
+     * Whether this target models GPIO pins. Hardware targets (Arduino, AVR,
+     * ESP32) return true; host/desktop targets (SDL native) return false. Used to
+     * gate GPIO-dependent APIs (ui.watchPin, ui.press) — when false, those APIs
+     * produce a transpile-time diagnostic instead of emitting pinMode/
+     * attachInterrupt calls that would be undefined symbols or silent no-ops.
+     * Default true (preserves existing behavior for hardware strategies).
+     */
+    modelsGpio?(): boolean;
+}
+/**
+ * Full platform strategy composed from focused sub-interfaces.
+ *
+ * Existing implementations that implement PlatformStrategy automatically
+ * satisfy every sub-interface.  New code that only needs a subset can accept
+ * e.g. `PlatformExpressionStrategy` instead of the full interface.
+ */
+export interface PlatformStrategy extends PlatformProfileStrategy, PlatformPolyfillStrategy, PlatformTypeStrategy, PlatformExpressionStrategy, PlatformStatementStrategy, PlatformSafetyStrategy, PlatformBuildStrategy, PlatformDebugStrategy, PlatformAsyncStrategy, PlatformHALStrategy, PlatformGraphicsStrategy {
+    /** Unique identifier for this strategy (e.g. "arduino", "generic"). */
+    readonly id: string;
+}

package/dist/api/shared/platform-strategy.js

@@ -0,0 +1,14 @@
+// ---------------------------------------------------------------------------
+// PlatformStrategy — abstract interface for target-specific C++ emit decisions
+//
+// Framework packages provide concrete implementations (e.g. ArduinoStrategy,
+// NativeStrategy) so the emitter stays target-agnostic.  Each framework
+// registers its strategy via the platform registry; the emitter calls methods
+// on the interface without knowing which framework is active.
+//
+// The full interface is composed from focused sub-interfaces so that
+// call-sites can accept a narrower type when they only need a subset of the
+// strategy.  All existing implementations automatically satisfy every sub-interface
+// since they already implement the full PlatformStrategy.
+// ---------------------------------------------------------------------------
+export {};

package/dist/api/shared/polyfill-helper-registry.d.ts

@@ -0,0 +1,11 @@
+import type { RuntimePolyfillIR } from './polyfill-types.js';
+/**
+ * Maps a JS method call pattern (substring) to the __tc_* C++ helper
+ * function names that normalizeRawExpression will emit for it.
+ */
+export declare const POLYFILL_HELPER_MAP: Record<string, string[]>;
+/**
+ * Filter helper functions in RuntimePolyfillIR objects to only those
+ * whose names appear in the usedHelpers set. Non-__tc_ helpers are always kept.
+ */
+export declare function filterPolyfillHelpers(polyfills: RuntimePolyfillIR[], usedHelpers: Set<string>): RuntimePolyfillIR[];

package/dist/api/shared/polyfill-helper-registry.js

@@ -0,0 +1,86 @@
+// ---------------------------------------------------------------------------
+// Polyfill helper registry
+//
+// Maps JS method call patterns to the __tc_* C++ helper function names
+// that normalizeRawExpression produces. Used by program analysis to detect
+// which polyfill helpers are actually needed by a program.
+// ---------------------------------------------------------------------------
+/**
+ * Maps a JS method call pattern (substring) to the __tc_* C++ helper
+ * function names that normalizeRawExpression will emit for it.
+ */
+export const POLYFILL_HELPER_MAP = {
+    // String methods
+    '.toUpperCase(': ['__tc_toUpperCase'],
+    '.toLowerCase(': ['__tc_toLowerCase'],
+    '.trim(': ['__tc_trim'],
+    '.endsWith(': ['__tc_endsWith'],
+    '.lastIndexOf(': ['__tc_lastIndexOf'],
+    '.padStart(': ['__tc_padStart', '__tc_padStart_default'],
+    '.padEnd(': ['__tc_padEnd', '__tc_padEnd_default'],
+    '.repeat(': ['__tc_repeat'],
+    '.charAt(': ['__tc_charAt'],
+    '.charCodeAt(': ['__tc_charCodeAt'],
+    '.replace(': ['__tc_replace'],
+    '.split(': ['__tc_split'],
+    '.substring(': ['__tc_substring2', '__tc_substring1'],
+    '.includes(': ['__tc_includes'],
+    '.indexOf(': ['__tc_indexOf'],
+    '.slice(': ['__tc_slice2', '__tc_slice1'],
+    // Timer methods
+    'setTimeout(': ['__tc_setTimeout'],
+    'setInterval(': ['__tc_setInterval'],
+    'clearTimeout(': ['__tc_clearTimeout'],
+    'clearInterval(': ['__tc_clearInterval'],
+    // Math methods
+    'Math.random(': ['__tc_random'],
+    // Array methods
+    '.join(': ['__tc_join'],
+    '.reverse(': ['__tc_reverse'],
+    '.shift(': ['__tc_shift'],
+    '.pop(': ['__tc_pop'],
+    '.unshift(': ['__tc_unshift'],
+    '.sort(': ['__tc_sort', '__tc_sort_fn'],
+    '.fill(': ['__tc_fill', '__tc_fill3'],
+    '.concat(': ['__tc_concat'],
+    '.splice(': ['__tc_splice1', '__tc_splice2'],
+    '.filter(': ['__tc_filter'],
+    '.map(': ['__tc_map'],
+    '.reduce(': ['__tc_reduce', '__tc_reduce_no_init'],
+    '.find(': ['__tc_find'],
+    '.findIndex(': ['__tc_findIndex'],
+    '.every(': ['__tc_every'],
+    '.some(': ['__tc_some'],
+    // Map helper methods (Object.keys/values/entries AND Map.values/keys/entries)
+    '__tc_mapKeys(': ['__tc_mapKeys'],
+    '__tc_mapValues(': ['__tc_mapValues'],
+    '__tc_mapEntries(': ['__tc_mapEntries'],
+    '__tc_fromEntries(': ['__tc_fromEntries'],
+    // Set helper methods (Set.values()/keys()/entries()) — demo #15 fix A
+    '__tc_setValues(': ['__tc_setValues'],
+    '__tc_setEntries(': ['__tc_setEntries'],
+    // JSON helpers
+    '__tc_jsonStringify(': ['__tc_jsonStringify'],
+    '__tc_jsonParse(': ['__tc_jsonParse'],
+};
+function extractHelperFunctionNames(funcDef) {
+    const matches = funcDef.matchAll(/\b(__tc_[A-Za-z0-9_]+)\s*\(/g);
+    return [...new Set([...matches].map(m => m[1]))];
+}
+/**
+ * Filter helper functions in RuntimePolyfillIR objects to only those
+ * whose names appear in the usedHelpers set. Non-__tc_ helpers are always kept.
+ */
+export function filterPolyfillHelpers(polyfills, usedHelpers) {
+    return polyfills.map(polyfill => ({
+        ...polyfill,
+        helperFunctions: polyfill.helperFunctions.filter(func => {
+            const names = extractHelperFunctionNames(func);
+            if (names.length === 0)
+                return true;
+            return names.some(name => usedHelpers.has(name));
+        }),
+    })).filter(polyfill => polyfill.helperFunctions.length > 0 ||
+        polyfill.forwardDeclarations.length > 0 ||
+        polyfill.helperStructs.length > 0);
+}

package/dist/api/shared/polyfill-types.d.ts

@@ -0,0 +1,33 @@
+export interface RuntimePolyfillIR {
+    kind: "polyfill";
+    id: string;
+    domain: "standard" | "embedded" | (string & {});
+    requiredIncludes: string[];
+    forwardDeclarations: string[];
+    helperStructs: string[];
+    helperFunctions: string[];
+    shimMacros: string[];
+    dependencies: string[];
+    /**
+     * Variable names of async task instances generated by the async polyfill.
+     * The emitter uses these to call `taskVar.run()` inside `loop()`.
+     */
+    asyncTaskVars?: string[];
+    /**
+     * True when the Promise/MicrotaskQueue runtime was emitted (requires <functional>/<vector>).
+     * False for architectures that lack the C++ standard library.
+     * When false, the emitter must NOT emit cuttlefish_pump_microtasks() calls.
+     */
+    hasPromiseRuntime?: boolean;
+}
+export interface StdLibSupport {
+    hasVector: boolean;
+    hasString: boolean;
+    hasIostream: boolean;
+    hasExceptions: boolean;
+    hasRTTI: boolean;
+    recommendedArrayImpl: "std_vector" | "static_array";
+    recommendedStringImpl: "std_string" | "static_string";
+}
+export declare const DEFAULT_STDLIB_SUPPORT: StdLibSupport;
+export declare function getStdLibSupport(architecture?: string): StdLibSupport;

package/dist/api/shared/polyfill-types.js

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// Polyfill types
+//
+// Types for runtime polyfill generation via platform strategies.
+// ---------------------------------------------------------------------------
+export const DEFAULT_STDLIB_SUPPORT = {
+    hasVector: true,
+    hasString: true,
+    hasIostream: true,
+    hasExceptions: true,
+    hasRTTI: true,
+    recommendedArrayImpl: "std_vector",
+    recommendedStringImpl: "std_string",
+};
+const STDLIB_SUPPORT = {
+    avr: {
+        hasVector: false,
+        hasString: false,
+        hasIostream: false,
+        hasExceptions: false,
+        hasRTTI: false,
+        recommendedArrayImpl: "static_array",
+        recommendedStringImpl: "static_string",
+    },
+    esp32: {
+        hasVector: true,
+        hasString: true,
+        hasIostream: true,
+        hasExceptions: true,
+        hasRTTI: true,
+        recommendedArrayImpl: "std_vector",
+        recommendedStringImpl: "std_string",
+    },
+    esp8266: {
+        hasVector: true,
+        hasString: true,
+        hasIostream: true,
+        hasExceptions: true,
+        hasRTTI: true,
+        recommendedArrayImpl: "std_vector",
+        recommendedStringImpl: "std_string",
+    },
+    rp2040: {
+        hasVector: true,
+        hasString: true,
+        hasIostream: true,
+        hasExceptions: true,
+        hasRTTI: true,
+        recommendedArrayImpl: "std_vector",
+        recommendedStringImpl: "std_string",
+    },
+    samd: {
+        hasVector: true,
+        hasString: true,
+        hasIostream: true,
+        hasExceptions: true,
+        hasRTTI: true,
+        recommendedArrayImpl: "std_vector",
+        recommendedStringImpl: "std_string",
+    },
+    megaavr: {
+        hasVector: false,
+        hasString: false,
+        hasIostream: false,
+        hasExceptions: false,
+        hasRTTI: false,
+        recommendedArrayImpl: "static_array",
+        recommendedStringImpl: "static_string",
+    },
+    default: DEFAULT_STDLIB_SUPPORT,
+};
+export function getStdLibSupport(architecture) {
+    if (!architecture)
+        return DEFAULT_STDLIB_SUPPORT;
+    return STDLIB_SUPPORT[architecture.toLowerCase()] ?? DEFAULT_STDLIB_SUPPORT;
+}

package/dist/api/shared/promise-runtime.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generate the cooperative microtask queue + minimal Promise runtime for C++.
+ *
+ * @param queueCapacity Maximum number of pending microtasks in the queue.
+ *   Use a smaller value (e.g. 32) for memory-constrained targets like AVR,
+ *   and a larger value (e.g. 256) for targets with more RAM.
+ * @param includeWaitForPinEdge Whether to include the `waitForPinEdge` stub
+ *   (used by Arduino targets).
+ */
+export declare function generatePromiseRuntime(queueCapacity: number, includeWaitForPinEdge?: boolean): string;