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

package/dist/api/config.d.ts

@@ -19,6 +19,26 @@ interface CuttlefishOutputConfig {
     /** Extra compiler flags forwarded verbatim. */
     extraFlags?: string[];
 }
+/**
+ * Zephyr-specific configuration.
+ *
+ * When `framework` is `'@typecad/framework-zephyr'`, this section controls
+ * Kconfig symbols merged into prj.conf, extra CMake arguments forwarded to
+ * `west build`, and the flash runner override.
+ */
+export interface CuttlefishZephyrConfig {
+    /**
+     * Additional Kconfig symbols merged into the generated prj.conf.
+     *
+     * Example:
+     *   kconfig: { CONFIG_ESP32_USE_UNSUPPORTED_REVISION: 'y' }
+     */
+    kconfig?: Record<string, string>;
+    /** Extra arguments forwarded to `west build`. */
+    cmakeArgs?: string[];
+    /** Override the west flash runner (e.g. 'nrfjprog', 'jlink'). */
+    runner?: string;
+}
 /**
  * Root configuration object exported from `cuttlefish.config.ts`.
  */
@@ -45,6 +65,13 @@ export interface CuttlefishConfig {
      * Framework package for code generation strategy.
      */
     framework?: string;
+    /**
+     * ESP32 PSRAM type. When set, the framework emits the PSRAM-enabling
+     * Kconfig (Zephyr) / define + FQBN option (Arduino) so large canvas
+     * allocations (scroll viewports, lists) prefer external RAM. No effect
+     * on boards without PSRAM.
+     */
+    psram?: 'opi' | 'quad';
     /** Output / build options. */
     output?: CuttlefishOutputConfig;
     /**
@@ -78,6 +105,11 @@ export interface CuttlefishConfig {
      * display: { profile: 'ili9341-spi', cs: 5, dc: 21, rst: 22 }
      */
     display?: DisplayConfig;
+    /**
+     * Zephyr-specific configuration. Only used when the framework is
+     * '@typecad/framework-zephyr'.
+     */
+    zephyr?: CuttlefishZephyrConfig;
 }
 /**
  * Toolchain configuration for compile and upload operations.

package/dist/api/index.d.ts

@@ -1,5 +1,5 @@
 export * from './shared/index.js';
 export type { ArchitectureIdentifier } from './board-types.js';
 export type { PinCapabilityFlags } from './capabilities.js';
-export type { CuttlefishConfig } from './config.js';
+export type { CuttlefishConfig, CuttlefishZephyrConfig } from './config.js';
 export * from './schema/index.js';

package/dist/api/schema/types.d.ts

@@ -252,6 +252,21 @@ export interface BoardDefinition {
     peripherals: PeripheralDefinitions;
     /** Build configuration (overrides/extends MCU build). */
     build: BuildConfig;
+    /**
+     * Optional @typecad/framework-zephyr chip data for this board.
+     *
+     * Opaque (`Record<string, unknown>`) here so the core schema does not import
+     * framework-zephyr's typed descriptor. framework-zephyr reads the flattened
+     * board constants under `zephyr.*` to reconstruct its `ZephyrChipDescriptor`
+     * — e.g. `zephyr.gpio.dtSpecs` maps GPIO pins to devicetree aliases (`led0`,
+     * `sw0`), so the GPIO lowering emits `gpio_pin_*_dt()` (polarity-correct via
+     * the DT's `GPIO_ACTIVE_LOW` flag) instead of the raw-controller fallback.
+     *
+     * Only literal object/array data is honored (the board-constants flattener
+     * walks it recursively); `as const` on nested values defeats the walker, so
+     * nested objects/arrays must be plain literals.
+     */
+    zephyr?: Record<string, unknown>;
     /** Related board variants. */
     variants?: string[];
 }

package/dist/api/shared/async-runtime-static.d.ts

@@ -4,5 +4,16 @@
  * @param capacity Fixed number of timer/task slots. Keep small on constrained
  *   targets (e.g. 8 on AVR). Caps the number of simultaneously pending
  *   Async.sleep / sleepUntil / yield operations.
+ * @param waitForPinEdge How `__cuttlefish_wait_pin_edge` (the HAL gpio
+ *   waitForRising/waitForFalling lowering target) is implemented:
+ *   - "polling" (default): a busy-wait loop using digitalRead/delay/millis +
+ *     the RISING/FALLING/HIGH/LOW symbols. For Arduino-style targets where
+ *     those are part of the core API.
+ *   - "stub": resolve immediately, emitting NO Arduino symbols in the body.
+ *     Also defines RISING/FALLING (guarded) so the call site
+ *     `__cuttlefish_wait_pin_edge(pin, RISING, t)` compiles on targets that
+ *     don't define them (e.g. Zephyr). For testing/debug or targets where edge
+ *     waits are not yet wired.
+ *   - "interrupt": omit entirely — the strategy/ISR layer provides the symbol.
  */
-export declare function generateStaticAsyncRuntime(capacity: number): string;
+export declare function generateStaticAsyncRuntime(capacity: number, waitForPinEdge?: "interrupt" | "polling" | "stub", strategy?: import("./platform-strategy.js").PlatformStrategy): string;

package/dist/api/shared/async-runtime-static.js

@@ -29,8 +29,23 @@
  * @param capacity Fixed number of timer/task slots. Keep small on constrained
  *   targets (e.g. 8 on AVR). Caps the number of simultaneously pending
  *   Async.sleep / sleepUntil / yield operations.
+ * @param waitForPinEdge How `__cuttlefish_wait_pin_edge` (the HAL gpio
+ *   waitForRising/waitForFalling lowering target) is implemented:
+ *   - "polling" (default): a busy-wait loop using digitalRead/delay/millis +
+ *     the RISING/FALLING/HIGH/LOW symbols. For Arduino-style targets where
+ *     those are part of the core API.
+ *   - "stub": resolve immediately, emitting NO Arduino symbols in the body.
+ *     Also defines RISING/FALLING (guarded) so the call site
+ *     `__cuttlefish_wait_pin_edge(pin, RISING, t)` compiles on targets that
+ *     don't define them (e.g. Zephyr). For testing/debug or targets where edge
+ *     waits are not yet wired.
+ *   - "interrupt": omit entirely — the strategy/ISR layer provides the symbol.
  */
-export function generateStaticAsyncRuntime(capacity) {
+export function generateStaticAsyncRuntime(capacity, waitForPinEdge = "polling", strategy) {
+    // The current-time expression (millis() on Wiring-derived frameworks,
+    // std::chrono on generic). Falling back to millis() preserves the historical
+    // behavior when no strategy is supplied.
+    const now = strategy?.currentTimeMillis?.() ?? "millis()";
     return `
 // TypeCAD static (heap-free) async runtime — for targets without <vector>.
 namespace typecad_async_static {
@@ -67,7 +82,7 @@ public:
       if (!_timers[i].active) {
         _timers[i].active = true;
         _timers[i].repeat = false;
-        _timers[i].deadline = millis() + ms;
+        _timers[i].deadline = ${now} + ms;
         _timers[i].periodMs = 0;
         return true;
       }
@@ -83,7 +98,7 @@ public:
       if (!_timers[i].active) {
         _timers[i].active = true;
         _timers[i].repeat = true;
-        _timers[i].deadline = millis() + ms;
+        _timers[i].deadline = ${now} + ms;
         _timers[i].periodMs = ms;
         return true;
       }
@@ -109,12 +124,12 @@ public:
   // Advance the runtime: expire due timers and run ready tasks. Called from
   // cuttlefish_pump_microtasks(), which the transpiler injects into loop().
   void pump() {
-    const unsigned long now = millis();
+    const unsigned long now = ${now};
     // Timers: one-shot slots deactivate on expiry; periodic slots re-arm.
     for (int i = 0; i < CAP; ++i) {
       if (_timers[i].active) {
         // (now - deadline) handles the millis() 32-bit wrap correctly
-        if ((long)(now - _timers[i].deadline) >= 0) {
+        if (static_cast<long>(now - _timers[i].deadline) >= 0) {
           if (_timers[i].repeat) {
             _timers[i].deadline = now + _timers[i].periodMs;
           } else {
@@ -178,24 +193,54 @@ inline void cuttlefish_pump_microtasks() {
   typecad_async_static::StaticAsyncRuntime::instance().pump();
 }
 
-// HAL-level wait for pin edge — polling-based implementation for static
-// (heap-free) targets. Blocks the current task until the pin edge is detected
-// or the timeout elapses. An edge is a transition: for RISING, the pin must
-// first be LOW then go HIGH; for FALLING, first HIGH then go LOW.
-inline void __cuttlefish_wait_pin_edge(int pin, int mode, long timeout) {
-  int targetState = (mode == RISING) ? HIGH : LOW;
-  int idleState = (mode == RISING) ? LOW : HIGH;
-  unsigned long start = millis();
-  // Phase 1: wait for the pin to be in the idle state (the "before" level)
-  while (digitalRead(pin) != idleState) {
-    if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) return;
-    delay(1);
-  }
-  // Phase 2: wait for the transition to the target state (the actual edge)
-  while (digitalRead(pin) != targetState) {
-    if (timeout >= 0 && (millis() - start >= (unsigned long)timeout)) return;
-    delay(1);
-  }
-}
+// HAL-level wait for pin edge. The body depends on the strategy's
+// waitForPinEdge mode — see generateStaticAsyncRuntime()'s doc comment.
+${waitPinEdgeForMode(waitForPinEdge, strategy, now)}
 `;
 }
+/** Emit `__cuttlefish_wait_pin_edge` per the strategy's waitForPinEdge mode. */
+function waitPinEdgeForMode(mode, strategy, now = "millis()") {
+    if (mode === "interrupt") {
+        // The strategy/ISR layer provides the symbol; emit nothing here.
+        return "// __cuttlefish_wait_pin_edge is provided by the strategy (interrupt mode).";
+    }
+    if (mode === "stub") {
+        // Resolve immediately. Define RISING/FALLING (guarded) so the call site
+        // `__cuttlefish_wait_pin_edge(pin, RISING, t)` compiles on targets that
+        // don't define them (Zephyr). No digitalRead/delay/millis in the body.
+        return [
+            "#ifndef RISING",
+            "#define RISING 1",
+            "#endif",
+            "#ifndef FALLING",
+            "#define FALLING 2",
+            "#endif",
+            "// Stub: edge waits resolve immediately (waitForPinEdge=\"stub\").",
+            "inline void __cuttlefish_wait_pin_edge(int /*pin*/, int /*mode*/, long /*timeout*/) {",
+            "}",
+        ].join("\n");
+    }
+    // polling: busy-wait using Arduino-style digitalRead/delay/millis + RISING/
+    // FALLING/HIGH/LOW. For targets whose core API defines those (Arduino).
+    return [
+        "// HAL-level wait for pin edge — polling-based implementation for static",
+        "// (heap-free) targets. Blocks the current task until the pin edge is detected",
+        "// or the timeout elapses. An edge is a transition: for RISING, the pin must",
+        "// first be LOW then go HIGH; for FALLING, first HIGH then go LOW.",
+        "inline void __cuttlefish_wait_pin_edge(int pin, int mode, long timeout) {",
+        "  int targetState = (mode == RISING) ? HIGH : LOW;",
+        "  int idleState = (mode == RISING) ? LOW : HIGH;",
+        `  unsigned long start = ${now};`,
+        "  // Phase 1: wait for the pin to be in the idle state (the \"before\" level)",
+        `  while (${strategy?.readDigitalPin?.("pin") ?? "digitalRead(pin)"} != idleState) {`,
+        `    if (timeout >= 0 && (${now} - start >= static_cast<unsigned long>(timeout))) return;`,
+        `    ${strategy?.delayMs?.("1") ?? "delay(1)"};`,
+        "  }",
+        "  // Phase 2: wait for the transition to the target state (the actual edge)",
+        `  while (${strategy?.readDigitalPin?.("pin") ?? "digitalRead(pin)"} != targetState) {`,
+        `    if (timeout >= 0 && (${now} - start >= static_cast<unsigned long>(timeout))) return;`,
+        `    ${strategy?.delayMs?.("1") ?? "delay(1)"};`,
+        "  }",
+        "}",
+    ].join("\n");
+}

package/dist/api/shared/async-symbol-detector.d.ts

@@ -0,0 +1,11 @@
+import type { ProgramIR } from "../index.js";
+/**
+ * Walk a program's IR and return true if ANY statement or expression references
+ * a cooperative-runtime symbol. Short-circuits on the first hit.
+ *
+ * Inspects the same node shapes the duplicated framework-strategy walkers did:
+ * `raw` expressions, `hal-expr`/`hal-op` nodes whose operation carries raw
+ * `code`, and any `raw`-kind subtree. Covers both the statement and expression
+ * IR trees.
+ */
+export declare function programUsesAsyncRuntimeSymbols(program: ProgramIR): boolean;

package/dist/api/shared/async-symbol-detector.js

@@ -0,0 +1,140 @@
+// ---------------------------------------------------------------------------
+// Shared async-runtime symbol detector
+//
+// Returns true when a program actually references a symbol provided by the
+// cooperative Promise/microtask runtime (MicrotaskQueue, Promise<T>,
+// enqueueMicrotask, cuttlefish_pump_microtasks, the __cuttlefish_async_*
+// HAL helpers, __cuttlefish_wait_pin_edge). This is the precise gate for
+// emitting the `async_runtime` polyfill.
+//
+// It is intentionally NARROWER than "does the program have an async function?"
+// An `async function` whose body only does `await delay(ms)` lowers to a
+// pure millis()-polling state machine (see emit/utils/async-state-machine.ts)
+// that touches NONE of these symbols — so it needs the AsyncTaskClass (gated
+// separately on fn.isAsync) but NOT the Promise runtime. Conflating the two
+// pulls ~250 lines of dead Promise/microtask code into every such sketch.
+//
+// Both framework strategies (Arduino, Zephyr) previously carried a private
+// copy of this walk; this shared version de-duplicates them and is also used
+// centrally by emit/emitters/setup.ts to filter the polyfill id.
+// ---------------------------------------------------------------------------
+/** Tokens that only exist in the cooperative Promise/microtask runtime. */
+const ASYNC_RUNTIME_TOKENS = [
+    "__cuttlefish_async_", // Async.sleep / Async.yield / Async.sleepUntil / Async.currentTask
+    "__cuttlefish_wait_pin_edge", // HAL edge-wait helper (polling-based Promise impl)
+    "enqueueMicrotask", // MicrotaskQueue::enqueue alias
+    "cuttlefish_pump_microtasks", // loop() injection target
+    "typecad_async::", // direct namespace qualification
+    "Promise<", // Promise<T> / Promise<void> instantiation
+];
+/** True if `text` references any async-runtime symbol. */
+function referencesAsyncSymbol(text) {
+    for (const tok of ASYNC_RUNTIME_TOKENS) {
+        if (text.includes(tok))
+            return true;
+    }
+    return false;
+}
+/**
+ * Walk a program's IR and return true if ANY statement or expression references
+ * a cooperative-runtime symbol. Short-circuits on the first hit.
+ *
+ * Inspects the same node shapes the duplicated framework-strategy walkers did:
+ * `raw` expressions, `hal-expr`/`hal-op` nodes whose operation carries raw
+ * `code`, and any `raw`-kind subtree. Covers both the statement and expression
+ * IR trees.
+ */
+export function programUsesAsyncRuntimeSymbols(program) {
+    const FOUND = {};
+    const seen = new Set();
+    const walkExpr = (expr) => {
+        if (!expr || typeof expr !== "object")
+            return;
+        if (seen.has(expr))
+            return;
+        seen.add(expr);
+        const e = expr;
+        if (e.kind === "raw" && typeof e.value === "string" && referencesAsyncSymbol(e.value)) {
+            throw FOUND;
+        }
+        // HAL method calls that lower via rawCpp() become `hal-expr` nodes whose
+        // `operation` is { operation: "raw", code: "..." }. The Async singleton's
+        // methods (sleep/yield/sleepUntil/currentTask) land here.
+        if (e.kind === "hal-expr" && e.operation && typeof e.operation === "object") {
+            const op = e.operation;
+            if (op.operation === "raw" && typeof op.code === "string" && referencesAsyncSymbol(op.code)) {
+                throw FOUND;
+            }
+        }
+        for (const v of Object.values(e)) {
+            if (Array.isArray(v)) {
+                for (const item of v) {
+                    if (item && typeof item === "object") {
+                        if ("kind" in item && typeof item.kind === "string") {
+                            walkExpr(item);
+                        }
+                        else {
+                            walkStmt(item);
+                        }
+                    }
+                }
+            }
+            else if (v && typeof v === "object" && "kind" in v && typeof v.kind === "string") {
+                walkExpr(v);
+            }
+        }
+    };
+    const walkStmt = (stmt) => {
+        if (!stmt || typeof stmt !== "object")
+            return;
+        if (seen.has(stmt))
+            return;
+        seen.add(stmt);
+        const s = stmt;
+        // HAL method calls that lower via rawCpp() become `hal-op` statements whose
+        // `operation` is { operation: "raw", code: "..." }. The Async singleton's
+        // methods land here at statement level.
+        if (s.kind === "hal-op" && s.operation && typeof s.operation === "object") {
+            const op = s.operation;
+            if (op.operation === "raw" && typeof op.code === "string" && referencesAsyncSymbol(op.code)) {
+                throw FOUND;
+            }
+        }
+        for (const v of Object.values(s)) {
+            if (Array.isArray(v)) {
+                for (const item of v) {
+                    if (item && typeof item === "object") {
+                        if ("body" in item || "statements" in item || "thenBranch" in item || "cases" in item) {
+                            walkStmt(item);
+                        }
+                        else if ("kind" in item && typeof item.kind === "string") {
+                            walkExpr(item);
+                        }
+                    }
+                }
+            }
+            else if (v && typeof v === "object" && "kind" in v && typeof v.kind === "string") {
+                walkExpr(v);
+            }
+            else if (v && typeof v === "object") {
+                walkStmt(v);
+            }
+        }
+    };
+    try {
+        for (const fn of program.functions) {
+            for (const stmt of fn.statements)
+                walkStmt(stmt);
+        }
+        // Top-level statements (outside any function) — e.g. a bare Async.sleep()
+        // called from setup-level code.
+        for (const stmt of program.topLevelStatements)
+            walkStmt(stmt);
+    }
+    catch (e) {
+        if (e === FOUND)
+            return true;
+        throw e;
+    }
+    return false;
+}

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

@@ -39,4 +39,28 @@ export interface AsyncRuntimeConfig {
      * e.g. ["<functional>", "<vector>", "<utility>", "<string>"]
      */
     requiredIncludes: string[];
+    /**
+     * Enable priority-ordered dispatch of per-frame work units.
+     * Default false → legacy flat pump sequence. When true, higher-priority
+     * units drain before lower-priority ones each frame.
+     */
+    enablePriority?: boolean;
+    /**
+     * Enable mid-batch yielding when the per-frame time budget is exceeded.
+     * Default false. When true, CoopSched::run() breaks out of its dispatch
+     * loop once `timeBudgetMs` has elapsed, leaving remaining units for the
+     * next frame. This bounds worst-case latency for background RTOS work and
+     * prevents a single greedy unit from starving others.
+     */
+    enableTimeBudget?: boolean;
+    /**
+     * Per-frame wall-clock budget in milliseconds. Only consulted when
+     * `enableTimeBudget` is true. Default 5.
+     */
+    timeBudgetMs?: number;
+    /**
+     * Number of distinct priority levels CoopSched should model. Default 2
+     * (high/low). Only consulted when `enablePriority` is true.
+     */
+    schedulerPriorities?: number;
 }

package/dist/api/shared/coop-scheduler.d.ts

@@ -0,0 +1,60 @@
+/** A per-frame work unit to be driven by CoopSched. */
+export interface CoopWorkUnit {
+    /**
+     * Stable identifier for the trampoline (used to form the C++ trampoline and
+     * registration function names). Must be a valid C++ identifier suffix.
+     */
+    name: string;
+    /** C++ statement to execute when this unit runs, e.g. `fooTask.run();`. */
+    body: string;
+    /** Dispatch priority (higher runs first). Default 0. */
+    priority?: number;
+}
+export interface CoopSchedOptions {
+    /** Maximum number of registered work units. Default 8. */
+    capacity?: number;
+    /** Number of distinct priority levels. Default 2. */
+    priorities?: number;
+    /** Whether to break mid-batch once timeBudgetMs elapses. Default false. */
+    enableTimeBudget?: boolean;
+    /** Per-frame wall-clock budget in ms. Only consulted when budgeting. Default 5. */
+    timeBudgetMs?: number;
+    /**
+     * C++ expression yielding the current monotonic time in ms, used for the
+     * budget check (e.g. `millis()`, `k_uptime_get_32()`). Required only when
+     * enableTimeBudget is true.
+     */
+    currentTimeExpr?: string;
+}
+/**
+ * Generate the CoopSched C++ runtime (a self-contained namespace + global
+ * `CoopSched::run()` alias). The scheduler is independent of which work units
+ * are registered; units are registered per-program via buildCoopSchedInjection().
+ *
+ * AUTOSAR C++14 notes:
+ *  - Uses int32_t/uint32_t/int8_t (no bare int).
+ *  - No STL: function-pointer + void* trampolines, static fixed-size arrays.
+ *  - `final` on the scheduler class (nothing inherits it).
+ *  - static_cast for all primitive conversions; reinterpret_cast for the
+ *    void* <-> trampoline boundary is unnecessary (we pass ctx through verbatim).
+ */
+export declare function generateCoopScheduler(options?: CoopSchedOptions): string;
+/**
+ * Build the loop()/main() injection lines that register the given work units
+ * into CoopSched (once, guarded) and dispatch one frame. The returned lines
+ * are meant to be emitted verbatim by a strategy's asyncLoopInjection().
+ *
+ * Each work unit gets a static trampoline `__tc_coop_<name>(void*)` that runs
+ * its body; registration is idempotent (guarded by CoopSched::isRegistered())
+ * so the same loop() body can safely contain it every frame at zero cost
+ * after the first.
+ *
+ * Trampoline definitions are returned as the first element of the tuple so the
+ * caller can place them in the file's shim/declarations region (they must
+ * appear before the loop body). The per-frame injection lines are the second
+ * element.
+ */
+export declare function buildCoopSchedInjection(units: CoopWorkUnit[]): {
+    trampolines: string[];
+    injection: string[];
+};

package/dist/api/shared/coop-scheduler.js

@@ -0,0 +1,149 @@
+// ---------------------------------------------------------------------------
+// Shared cooperative scheduler C++ code generator (no-STL)
+//
+// Generates a priority-ordered, time-budget-bounded cooperative scheduler that
+// drives the per-frame async pumps (async task .run(), microtask pump, timer
+// pump) in loop()/main(). It is deliberately STL-free: function-pointer +
+// void* trampolines over a statically-allocated fixed slot table. This lets it
+// compile on targets whose minimal libc lacks std::function/std::vector (e.g.
+// Zephyr), giving those targets full cooperative-scheduling parity with the
+// std::function-based MicrotaskQueue used on Arduino/ESP32/native.
+//
+// The scheduler is emitted as a polyfill (id: 'coop_scheduler') only when a
+// strategy opts in via AsyncRuntimeConfig.enablePriority/enableTimeBudget.
+// Per-framework asyncLoopInjection() builds the work-unit registrations and
+// the single CoopSched::run() call (see buildCoopSchedInjection()).
+// ---------------------------------------------------------------------------
+/**
+ * Generate the CoopSched C++ runtime (a self-contained namespace + global
+ * `CoopSched::run()` alias). The scheduler is independent of which work units
+ * are registered; units are registered per-program via buildCoopSchedInjection().
+ *
+ * AUTOSAR C++14 notes:
+ *  - Uses int32_t/uint32_t/int8_t (no bare int).
+ *  - No STL: function-pointer + void* trampolines, static fixed-size arrays.
+ *  - `final` on the scheduler class (nothing inherits it).
+ *  - static_cast for all primitive conversions; reinterpret_cast for the
+ *    void* <-> trampoline boundary is unnecessary (we pass ctx through verbatim).
+ */
+export function generateCoopScheduler(options = {}) {
+    const capacity = options.capacity ?? 8;
+    const priorities = options.priorities ?? 2;
+    const enableTimeBudget = options.enableTimeBudget ?? false;
+    const timeBudgetMs = options.timeBudgetMs ?? 5;
+    const currentTimeExpr = options.currentTimeExpr ?? "millis()";
+    // Budget check snippet, only included when time-budgeting is enabled.
+    const budgetCheck = enableTimeBudget
+        ? `      if ((${currentTimeExpr} - _start) >= static_cast<uint32_t>(${timeBudgetMs})) { break; }`
+        : `      (void)_start;`;
+    return `// ── Cooperative scheduler (no-STL: priority-ordered, budget-bounded) ──────
+// Drives the per-frame async pumps. Emitted only when a strategy opts in via
+// AsyncRuntimeConfig.enablePriority / enableTimeBudget. STL-free so it links
+// on minimal-libc targets (Zephyr). See coop-scheduler.ts.
+namespace typecad_coop {
+  using WorkFn = void (*)(void*);
+
+  struct WorkUnit final {
+    int8_t priority;   // higher runs first
+    WorkFn fn;
+    void* ctx;
+  };
+
+  class CoopSched final {
+   public:
+    static CoopSched& instance() {
+      static CoopSched s;
+      return s;
+    }
+
+    // Register a work unit. Called once per unit (idempotent registration is
+    // driven by begin()/runFirst() below). Returns false if the slot table is
+    // full.
+    bool registerUnit(int8_t priority, WorkFn fn, void* ctx) {
+      if (_count >= static_cast<int32_t>(${capacity})) { return false; }
+      _slots[_count].priority = priority;
+      _slots[_count].fn = fn;
+      _slots[_count].ctx = ctx;
+      ++_count;
+      return true;
+    }
+
+    bool isRegistered() const { return _registered; }
+    void markRegistered() { _registered = true; }
+
+    // Dispatch one frame. Runs registered units in descending-priority order.
+    // Newly-registered units during dispatch are NOT run this frame (the count
+    // is snapshotted at entry) — mirroring the microtask pump's anti-recursion
+    // semantics. When time-budgeting is enabled, dispatch breaks early once
+    // the per-frame budget elapses; remaining units run next frame.
+    void run() {
+      const int32_t total = _count;
+      const uint32_t _start = ${currentTimeExpr};
+      for (int8_t level = static_cast<int8_t>(${priorities - 1}); level >= 0; --level) {
+        for (int32_t i = 0; i < total; ++i) {
+          if (_slots[i].priority == level && _slots[i].fn != nullptr) {
+            _slots[i].fn(_slots[i].ctx);
+${budgetCheck}
+          }
+        }
+      }
+    }
+
+   private:
+    CoopSched() : _count(0), _registered(false) {
+      for (int32_t i = 0; i < static_cast<int32_t>(${capacity}); ++i) {
+        _slots[i].priority = 0;
+        _slots[i].fn = nullptr;
+        _slots[i].ctx = nullptr;
+      }
+    }
+
+    WorkUnit _slots[${capacity}];
+    int32_t _count;
+    bool _registered;
+  };
+
+  inline void run() { CoopSched::instance().run(); }
+}  // namespace typecad_coop
+
+// Global-scope alias so HAL/loop() emit resolves.
+inline void CoopSched_run() { typecad_coop::run(); }
+`;
+}
+/**
+ * Build the loop()/main() injection lines that register the given work units
+ * into CoopSched (once, guarded) and dispatch one frame. The returned lines
+ * are meant to be emitted verbatim by a strategy's asyncLoopInjection().
+ *
+ * Each work unit gets a static trampoline `__tc_coop_<name>(void*)` that runs
+ * its body; registration is idempotent (guarded by CoopSched::isRegistered())
+ * so the same loop() body can safely contain it every frame at zero cost
+ * after the first.
+ *
+ * Trampoline definitions are returned as the first element of the tuple so the
+ * caller can place them in the file's shim/declarations region (they must
+ * appear before the loop body). The per-frame injection lines are the second
+ * element.
+ */
+export function buildCoopSchedInjection(units) {
+    const trampolines = [];
+    const injection = [];
+    for (const unit of units) {
+        const prio = unit.priority ?? 0;
+        const trampName = `__tc_coop_${unit.name}`;
+        // Trampoline definition (file scope, before loop()).
+        trampolines.push(`static void ${trampName}(void* /*ctx*/) { ${unit.body} }`);
+    }
+    // Idempotent registration guarded by isRegistered(); then one dispatch.
+    // Emitted into the loop body.
+    injection.push(`  if (!typecad_coop::CoopSched::instance().isRegistered()) {`);
+    for (const unit of units) {
+        const prio = unit.priority ?? 0;
+        const trampName = `__tc_coop_${unit.name}`;
+        injection.push(`    typecad_coop::CoopSched::instance().registerUnit(static_cast<int8_t>(${prio}), ${trampName}, nullptr);`);
+    }
+    injection.push(`    typecad_coop::CoopSched::instance().markRegistered();`);
+    injection.push(`  }`);
+    injection.push(`  CoopSched_run();`);
+    return { trampolines, injection };
+}

package/dist/api/shared/display-adapter.d.ts

@@ -1,9 +1,9 @@
 import type { ResolvedDisplay } from "./display-profile.js";
 import type { PlatformStrategy } from "./platform-strategy.js";
 export interface DisplayAdapterCode {
-    /** C++ #include lines (e.g. "#include <Adafruit_ILI9341.h>"). */
+    /** C++ #include lines (e.g. "#include <SDL2/SDL.h>"). */
     includes: string;
-    /** C++ display object declaration (e.g. "Adafruit_ILI9341 __tc_display = ..."). */
+    /** C++ display object declaration (e.g. the framework-specific display object). */
     declaration: string;
     /** C++ static inline adapter functions (display_init, display_fillScreen, etc.). */
     functions: string;