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

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

@@ -26,7 +26,7 @@ function polyfillDefinitionGuard(definition) {
     return null;
 }
 export function emitPreamble(ctx) {
-    const { strategy, effectiveEmitMode, program, shimLines, emittedPolyfills, asyncTaskClasses, includes, programAnalysis } = ctx;
+    const { strategy, effectiveEmitMode, program, shimLines, emittedPolyfills, includes, programAnalysis } = ctx;
     for (const include of dedupe(includes)) {
         appendSourceLineLocal(ctx, `#include ${include}`);
     }
@@ -73,16 +73,8 @@ export function emitPreamble(ctx) {
         }
         appendSourceLineLocal(ctx, "");
     }
-    if (asyncTaskClasses.length > 0) {
-        for (const { classDef, instanceDecl } of asyncTaskClasses) {
-            for (const line of classDef.split("\n")) {
-                appendSourceLineLocal(ctx, line);
-            }
-            appendSourceLineLocal(ctx, "");
-            appendSourceLineLocal(ctx, instanceDecl);
-            appendSourceLineLocal(ctx, "");
-        }
-    }
+    // Async task classes are emitted later (emitAsyncTaskClasses) AFTER top-level
+    // globals so references like WIFI_SSID inside the state machine compile.
     if (strategy.needsVectorOverload() && hasConsoleCalls(program, strategy) && (programAnalysis.usesVectorTypes || programAnalysis.hasArrayInObjectLiteral)) {
         appendSourceLineLocal(ctx, "template <typename T>");
         appendSourceLineLocal(ctx, "std::ostream& operator<<(std::ostream& os, const std::vector<T>& values)");
@@ -136,6 +128,24 @@ export function emitPreamble(ctx) {
         appendSourceLineLocal(ctx, "");
     }
 }
+/**
+ * Emit cooperative async state-machine classes. Must run AFTER top-level
+ * globals (emitTypeDeclarations) so identifiers like WIFI_SSID referenced
+ * from task bodies are already declared.
+ */
+export function emitAsyncTaskClasses(ctx) {
+    const { asyncTaskClasses } = ctx;
+    if (asyncTaskClasses.length === 0)
+        return;
+    for (const { classDef, instanceDecl } of asyncTaskClasses) {
+        for (const line of classDef.split("\n")) {
+            appendSourceLineLocal(ctx, line);
+        }
+        appendSourceLineLocal(ctx, "");
+        appendSourceLineLocal(ctx, instanceDecl);
+        appendSourceLineLocal(ctx, "");
+    }
+}
 export function finalizeOutput(ctx) {
     const { program, strategy, options, effectiveEmitMode, isNpmPackage, baseName, includes, shimLines, emittedPolyfills } = ctx;
     const outDir = options.outDir;

package/dist/emit/emitters/setup.js

@@ -31,6 +31,80 @@ function filterShimBlock(lines, startMarker, endMarker) {
     }
     return filtered;
 }
+/**
+ * Detect whether a program uses the watchdog timer. The HAL resolver lowers
+ * `WDT.enable/reset/disable` calls to structured `wdt.*` hal-ops, which the
+ * setup emitter then renders as bare `wdt_enable/wdt_reset/wdt_disable` calls
+ * (or constant-folded `wdt_enable(WDTO_*)` macros). All of those require
+ * `<avr/wdt.h>`, so the include is gated on this check instead of being forced
+ * into every AVR program.
+ *
+ * `programAnalysis.usesWDT` is NOT used here: it scans `WDT.`-prefixed
+ * callees and raw-code hal-ops, but the structured `wdt.*` ops carry a typed
+ * operation name with no raw code, so the analysis misses them.
+ *
+ * The recursion mirrors `collectStatementIdentifiers` (identifier-collector.ts)
+ * — the canonical IR walker — so every compound statement shape is covered.
+ */
+function programUsesWdt(program) {
+    const visitStatement = (stmt) => {
+        if (stmt.kind === "hal-op") {
+            const opName = stmt.operation?.operation;
+            if (typeof opName === "string" && opName.startsWith("wdt."))
+                return true;
+        }
+        switch (stmt.kind) {
+            case "block":
+            case "labeled":
+                return visit(stmt.body);
+            case "if":
+                return visit(stmt.thenBranch) || visit(stmt.elseBranch ?? []);
+            case "for":
+                return visit(stmt.body)
+                    || (stmt.initializer ? visitStatement(stmt.initializer) : false);
+            case "while":
+            case "do_while":
+            case "for_of":
+            case "for_in":
+                return visit(stmt.body);
+            case "switch":
+                return stmt.cases.some((c) => visit(c.body ?? []));
+            case "try":
+                return visit(stmt.tryBlock) || visit(stmt.catchBlock ?? []) || visit(stmt.finallyBlock ?? []);
+            default:
+                return false;
+        }
+    };
+    const visit = (statements) => {
+        if (!statements)
+            return false;
+        for (const stmt of statements) {
+            if (visitStatement(stmt))
+                return true;
+        }
+        return false;
+    };
+    if (visit(program.topLevelStatements))
+        return true;
+    for (const fn of program.functions) {
+        if (visit(fn.statements))
+            return true;
+    }
+    for (const cls of program.classes) {
+        for (const m of cls.methods)
+            if (visit(m.statements))
+                return true;
+        for (const g of cls.getters)
+            if (visit(g.statements))
+                return true;
+        for (const s of cls.setters)
+            if (visit(s.statements))
+                return true;
+        if (cls.constructor && visit(cls.constructor.statements))
+            return true;
+    }
+    return false;
+}
 /**
  * Extract a `#ifndef MACRO ... #endif` include-guard block from a shim line
  * list. Used to emit just the macro definition (e.g. CUTTLEFISH_UNDEFINED) in
@@ -118,6 +192,14 @@ export function buildEmitterContext(program, options) {
     })();
     const programAnalysis = analyzeProgram(program, strategy);
     if (options.platformContext) {
+        // The UI runtime's per-frame tick calls millis() (injected by the emitter,
+        // not present in user source), so a mounted UI needs the native millis ISR
+        // even when usesNativeTiming is false. OR entryHasUI() into the flag the
+        // AVR strategy reads when gating native_millis, so framework-avr doesn't
+        // drop the Timer0 ISR from a UI program.
+        if (!programAnalysis.usesNativeTiming && entryHasUI()) {
+            programAnalysis.usesNativeTiming = true;
+        }
         options.platformContext.analysis = programAnalysis;
         if (!options.platformContext.architecture && program.boardConstants) {
             options.platformContext.architecture = program.boardConstants.get("architecture");
@@ -223,6 +305,68 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesStrPtr) {
             shimLines = filterShimBlock(shimLines, '#ifndef CUTTLEFISH_STR_BUF_SIZE', 'inline size_t (strlen)(const __tc_str_ptr& s) { return ::strlen(s.buf); }');
         }
+        // framework-avr native peripheral driver shims. Each block carries a
+        // CUTTLEFISH_*_BEGIN/END marker pair; strip the ones the program doesn't
+        // use. framework-arduino's shimLines contain none of these markers, so
+        // these filters are no-ops there. The strategies also self-gate on the
+        // same flags; this is the defensive backstop (mirrors how usesWDT/etc.
+        // backstop the strategy-side gating above).
+        if (!programAnalysis.usesUart) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_BEGIN', '// CUTTLEFISH_UART_END');
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_EXT_BEGIN', '// CUTTLEFISH_UART_EXT_END');
+        }
+        if (!programAnalysis.usesSPI) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_SPI_BEGIN', '// CUTTLEFISH_SPI_END');
+        }
+        if (!programAnalysis.usesI2C) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TWI_BEGIN', '// CUTTLEFISH_TWI_END');
+        }
+        if (!programAnalysis.usesEEPROM) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_EEPROM_BEGIN', '// CUTTLEFISH_EEPROM_END');
+        }
+        if (!programAnalysis.usesTone) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TONE_BEGIN', '// CUTTLEFISH_TONE_END');
+        }
+        // framework-esp32 native peripheral driver shims. Same defensive-backstop
+        // pattern as the UART/SPI/TWI/EEPROM/tone blocks above. framework-arduino's
+        // and framework-avr's shimLines contain none of these markers, so these
+        // filters are no-ops there.
+        if (!programAnalysis.usesGPIO) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_GPIO_BEGIN', '// CUTTLEFISH_GPIO_END');
+        }
+        if (!programAnalysis.usesPWM) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_PWM_BEGIN', '// CUTTLEFISH_PWM_END');
+        }
+        if (!programAnalysis.usesADC) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_ADC_BEGIN', '// CUTTLEFISH_ADC_END');
+        }
+        if (!programAnalysis.usesDAC) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_DAC_BEGIN', '// CUTTLEFISH_DAC_END');
+        }
+        if (!programAnalysis.usesPower) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_POWER_BEGIN', '// CUTTLEFISH_POWER_END');
+        }
+        if (!programAnalysis.usesWdt) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WDT_BEGIN', '// CUTTLEFISH_WDT_END');
+        }
+        if (!programAnalysis.usesInterrupts) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_INTR_BEGIN', '// CUTTLEFISH_INTR_END');
+        }
+        if (!programAnalysis.usesPulse) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_PULSE_BEGIN', '// CUTTLEFISH_PULSE_END');
+        }
+        if (!programAnalysis.usesShift) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_SHIFT_BEGIN', '// CUTTLEFISH_SHIFT_END');
+        }
+        if (!programAnalysis.usesWifi) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WIFI_BEGIN', '// CUTTLEFISH_WIFI_END');
+        }
+        if (!programAnalysis.usesHttp) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_HTTP_BEGIN', '// CUTTLEFISH_HTTP_END');
+        }
+        if (!programAnalysis.usesPreferences) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_PREFERENCES_BEGIN', '// CUTTLEFISH_PREFERENCES_END');
+        }
         profileDiagnostics = [...strategy.profileDiagnostics(program, options.platformContext)];
     }
     for (const imported of program.imports) {
@@ -745,6 +889,17 @@ export function buildEmitterContext(program, options) {
     if (stringEnumNames.size > 0) {
         includes.push(strategy.cstringHeader());
     }
+    // `<avr/wdt.h>` is only needed when the program actually uses the watchdog.
+    // The HAL resolver lowers WDT.enable/reset/disable to bare wdt_*() calls
+    // (or constant-folded wdt_enable(WDTO_*) macros), all of which require the
+    // header. Detect the structured `wdt.*` hal-ops directly here rather than
+    // relying on programAnalysis.usesWDT (which misses these ops — they carry
+    // a typed operation name, not raw code the analysis scans) or on a forced
+    // include in the AVR profile (which leaked the header into every AVR
+    // program, even ones that never touch the watchdog like `led.toggle()`).
+    if (programUsesWdt(program)) {
+        includes.push("<avr/wdt.h>");
+    }
     // Placeholder defaults for fields that are computed later by other phases
     const noopFixPointer = (c) => c;
     // Demo #18 Finding B: collect the names of non-exported free functions that

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

@@ -597,6 +597,8 @@ export function runTopLevelPreprocessing(ctx) {
             statements: callbackIR.statements ?? callbackIR.body ?? [],
             debounceMs: callbackIR.debounceMs,
             isInterruptHandler: callbackIR.isInterruptHandler,
+            ...(callbackIR.returnType ? { returnType: callbackIR.returnType } : {}),
+            ...(callbackIR.typedParams ? { typedParams: callbackIR.typedParams } : {}),
         });
         replacePlaceholderInAllStatements(filteredTopLevelExecutables, rc.placeholderName, callbackName);
         for (const fn of mappedFunctions) {

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

@@ -34,7 +34,7 @@ import { getRadioGroups } from "../../ir/ui-element-auto-wire.js";
 // minPressure gate is skipped for them. Resistive controllers (XPT2046,
 // STMPE610, Adafruit_TouchScreen) keep the gate.
 // ---------------------------------------------------------------------------
-const CAPACITIVE_TOUCH_LIBS = new Set(["FT6336U", "sdl"]);
+const CAPACITIVE_TOUCH_LIBS = new Set(["FT6336U", "GT911", "CST816S", "sdl"]);
 /** Generate the ui_poll_touch() body, or null for the no-touch path. */
 export function generateTouchPollBody(input) {
     const { library, minPressure, calibration, profile } = input;
@@ -141,9 +141,14 @@ export function emitUIRuntime(ctx) {
     // display-adapter registry. Must precede the runtime header so the
     // adapter functions (__tc_display, display_init, etc.) are available.
     const profile = getDisplayProfile();
-    // 0. SPI-bus display drivers (ILI9341, ST7796, …) need the SPI library.
-    // Host render targets (sdl, native-preview) have no SPI bus, so skip it.
-    const spiDriver = profile?.driver !== "sdl" && profile?.driver !== "native-preview";
+    // 0. SPI-bus display drivers (ILI9341, ST7796, …) need the Arduino SPI
+    // library — but ONLY on the Adafruit path. Native adapters (AVR, ESP32)
+    // emit their own bus setup and would break on <SPI.h>. Host render targets
+    // (sdl, native-preview) have no SPI bus at all.
+    const nativeAdapter = ctx.strategy?.providesDisplayAdapter?.() ?? false;
+    const spiDriver = profile?.driver !== "sdl"
+        && profile?.driver !== "native-preview"
+        && !nativeAdapter;
     if (spiDriver && !ctx.includes.includes("<SPI.h>")) {
         ctx.includes.push("<SPI.h>");
     }
@@ -151,7 +156,7 @@ export function emitUIRuntime(ctx) {
     // buildEmitterContext (setup.ts), NOT here — emitPreamble runs before this
     // function, so a push here would be too late to land in the output.
     if (profile) {
-        const adapter = generateDisplayAdapter(profile);
+        const adapter = generateDisplayAdapter(profile, ctx.strategy);
         // Prepend includes to the very front — Arduino's auto-prototyper scans
         // the whole .ino and generates prototypes that reference GFXcanvas16
         // etc. before any #include, so the GFX header must come first.
@@ -164,6 +169,14 @@ export function emitUIRuntime(ctx) {
         ctx.sourceLines.push(is888
             ? "#define UI_COLOR_DEPTH 888\n#define UI_COLOR_T uint32_t\n#define UI_DIM_MASK 0x7F7F7Fu"
             : "#define UI_COLOR_DEPTH 565\n#define UI_COLOR_T uint16_t\n#define UI_DIM_MASK 0x7BEFu");
+        // Native display adapters (AVR, ESP32) instantiate CuttlefishGFX by value
+        // in their declaration block. The class MUST be defined before that —
+        // emit the cuttlefish-gfx slice here, between the color preamble and the
+        // adapter declaration. Arduino path (Adafruit) returns "" from the slice.
+        const nativeDisplayActive = ctx.strategy?.providesDisplayAdapter?.() ?? false;
+        if (nativeDisplayActive) {
+            ctx.sourceLines.push(ui.emitCuttlefishGfx(true));
+        }
         ctx.sourceLines.push(adapter.declaration);
         ctx.sourceLines.push(adapter.functions);
     }
@@ -173,7 +186,7 @@ export function emitUIRuntime(ctx) {
     if (profile.touch) {
         const t = profile.touch;
         if (t.library) {
-            touchAdapter = generateTouchAdapter(t);
+            touchAdapter = generateTouchAdapter(t, ctx.strategy);
             // Prepend includes to the front (Arduino auto-prototyper safety).
             ctx.sourceLines.unshift(touchAdapter.includes[0]);
             for (let i = 1; i < touchAdapter.includes.length; i++) {
@@ -252,13 +265,15 @@ export function emitUIRuntime(ctx) {
     //     header so its #ifndef guards adopt them. Source of truth:
     //     resolveScrollConfig(profile.scroll). Defaults derive from the declared
     //     touch hardware, so the demo (XPT2046) gets resistive+full with no config.
-    const scroll = resolveScrollConfig(profile, { buildTarget: profile._buildTarget });
+    const scroll = resolveScrollConfig(profile, { buildTarget: profile._buildTarget, psram: profile._psram });
     ctx.sourceLines.push(`#define UI_SCROLL_MAX_OVERSCROLL ${scroll.maxOverscroll}`, `#define UI_SCROLL_STIFFNESS_X10 ${Math.round(scroll.stiffness * 10)}`, `#define UI_SCROLL_EDGE_SNAP_PX ${scroll.edgeSnapPx}`, `#define UI_SCROLL_DRAG_SCALE_X10 ${Math.round(scroll.dragScale * 10)}`, `#define UI_SCROLL_INPUT_TIER_CAPACITIVE ${scroll.inputTier === "capacitive" ? 1 : 0}`, `#define UI_SCROLL_INPUT_TIER_RESISTIVE ${scroll.inputTier === "resistive" ? 1 : 0}`, `#define UI_SCROLL_INPUT_TIER_NONE ${scroll.inputTier === "none" ? 1 : 0}`, `#define UI_SCROLL_RENDER_TIER_FULL ${scroll.renderTier === "full" ? 1 : 0}`, `#define UI_SCROLL_RENDER_TIER_CONSTRAINED ${scroll.renderTier === "constrained" ? 1 : 0}`, `#define UI_SCROLL_CANVAS_BUDGET_BYTES ${scroll.scrollCanvasBudgetBytes}`, ...(scroll.debug ? [`#define UI_SCROLL_DEBUG 1`] : []));
     // Forward-declare __ui_kb_set_onchange before the runtime header: the
     // header's keyboard-open function calls it, but the definition is emitted
     // later (section 8b). On native (single TU) this must precede the header.
     ctx.sourceLines.push(`void __ui_kb_set_onchange();`);
-    ctx.sourceLines.push(emitRuntimeHeader());
+    ctx.sourceLines.push(emitRuntimeHeader({
+        nativeDisplayActive: ctx.strategy?.providesDisplayAdapter?.() ?? false,
+    }));
     // 1.5. Touch poll function (uses the adapter pattern). Body is generated by
     // generateTouchPollBody — extracted for unit-testability of the capacitive
     // vs resistive branch (FT6336U/SDL skip the minPressure gate).

package/dist/emit/expression-renderer.js

@@ -10,6 +10,7 @@ import { accessorGetterName } from "./utils/cpp-helpers.js";
 import { INTEGRAL_CPP_TYPE_RE } from "./utils/cpp-helpers.js";
 import { renderPeripheralProperty } from "../mapping/peripheral-names.js";
 import { parseCppType, renderCppType, bareType, parsedIsPointer, parsedIsVector, needsCStrForStringLike } from "../api/shared/cpp-type-ir.js";
+import { cppTypeForHalOp } from "./utils/hal-op-cpp-type.js";
 /**
  * Renders ExpressionIR nodes to C++ code strings.
  */
@@ -403,6 +404,8 @@ export class ExpressionRenderer {
             }
             case "unary":
                 return expr.operator === "!" ? "bool" : this.inferExpressionCppType(expr.operand, knownVariableTypes);
+            case "hal-expr":
+                return cppTypeForHalOp(expr.operation.operation);
             default:
                 return undefined;
         }
@@ -714,10 +717,16 @@ export class ExpressionRenderer {
             }
             case "hal-expr": {
                 const rendered = this.render(expr, exprTransformer);
-                // HAL expressions that resolve to string-like outputs use %s
                 if (rendered.startsWith('"') || this.stringVarNames?.has(rendered)) {
                     return { format: "%s", arg: rendered, estimatedLength: 32 };
                 }
+                const cppType = cppTypeForHalOp(expr.operation.operation);
+                if (cppType && this.isStringLikeCppType(cppType)) {
+                    return { format: "%s", arg: rendered, estimatedLength: 32 };
+                }
+                if (cppType === "bool") {
+                    return { format: "%s", arg: `(${rendered} ? "true" : "false")`, estimatedLength: 5 };
+                }
                 return { format: "%d", arg: rendered, estimatedLength: 12 };
             }
             case "method-call":

package/dist/emit/snprintf-helpers.js

@@ -8,6 +8,7 @@
 // Types are imported from @typecad/cuttlefish/api/shared.
 // ---------------------------------------------------------------------------
 import { escapeCppStringLiteral, escapeSnprintfFormatFragment } from "../utils/strings.js";
+import { cppTypeForHalOp } from "./utils/hal-op-cpp-type.js";
 import { parsedElementString, parsedIsStringLike } from "../api/shared/cpp-type-ir.js";
 // ---------------------------------------------------------------------------
 // Scope state management
@@ -369,6 +370,13 @@ export function inferSnprintfArg(expr, strategy, scopeState, renderExpression, p
             if (rendered.startsWith('"') || stringVarNames?.has(rendered)) {
                 return { format: "%s", arg: rendered, estimatedLength: 32, preludeLines: [] };
             }
+            const cppType = cppTypeForHalOp(expr.operation.operation);
+            if (cppType && strategy.isStringLikeType(cppType)) {
+                return { format: "%s", arg: rendered, estimatedLength: 32, preludeLines: [] };
+            }
+            if (cppType === "bool") {
+                return { format: "%s", arg: `(${rendered} ? "true" : "false")`, estimatedLength: 5, preludeLines: [] };
+            }
             return { format: "%d", arg: rendered, estimatedLength: 12, preludeLines: [] };
         }
         default:

package/dist/emit/statement-renderer.js

@@ -485,6 +485,19 @@ export class StatementRenderer {
             const rawStmt = statement.callee.slice('__RAW_STMT__'.length);
             return forHeader ? rawStmt : `${rawStmt.endsWith(';') ? rawStmt : rawStmt + ';'}`;
         }
+        // Awaited network markers (__WIFI_WAIT__/__HTTP_WAIT__) reaching the
+        // plain renderer means the await sits outside an async state machine
+        // (top-level await, or a position the state-machine splitter doesn't
+        // support). Fall back to the blocking form of the op they carry.
+        if ((statement.callee === "__WIFI_WAIT__" || statement.callee === "__HTTP_WAIT__" || statement.callee === "__BLE_WAIT__" || statement.callee === "__HAL_WAIT__")
+            && statement.args[0]?.kind === "hal-expr") {
+            const resolved = routeHALOp(statement.args[0].operation, this.strategy);
+            const code = resolved?.code ?? (resolved?.expression ? `${resolved.expression};` : undefined);
+            if (code) {
+                return forHeader ? code.replace(/;$/, "") : code;
+            }
+            return `/* unhandled awaited hal-op: ${statement.args[0].operation.operation} */`;
+        }
         // Handle emit() — compile-time C++ injection
         if (statement.callee === "__EMIT__") {
             const rawText = statement.args.map(arg => this.renderEmitArg(arg)).join("");