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

package/dist/emit/emitters/setup.js

@@ -1,13 +1,16 @@
 import path from "node:path";
 import { filterPolyfillHelpers, isStringEnum } from "../../api/shared/index.js";
+import { hasSafetyHook, requireSafetyHook } from "../../safety-hook.js";
 import { analyzeProgram } from "../../ir/program-analysis.js";
 import { collectStatementIdentifiers } from "../../ir/identifier-collector.js";
 import { ensureDir } from "../../utils/fs.js";
 import { resolveImport } from "../../libdef/registry.js";
 import { emitPolyfillBoilerplate } from "../native-helpers-emitter.js";
 import { resolveStrategy } from "../../platform/registry.js";
+import { buildCoopSchedulerPolyfill } from "../../platform/coop-scheduler-runtime.js";
 import { getLoadedFramework } from "../../framework-registry.js";
 import { entryHasUI } from "../../ui-hook.js";
+import { ComplianceContext } from "../compliance/compliance-context.js";
 import { createEmissionScopeState, statementNeedsSnprintf, } from "../snprintf-helpers.js";
 import { ExpressionRenderer } from "../expression-renderer.js";
 import { StatementRenderer } from "../statement-renderer.js";
@@ -86,18 +89,18 @@ function programUsesWdt(program) {
     };
     if (visit(program.topLevelStatements))
         return true;
-    for (const fn of program.functions) {
+    for (const fn of program.functions ?? []) {
         if (visit(fn.statements))
             return true;
     }
-    for (const cls of program.classes) {
-        for (const m of cls.methods)
+    for (const cls of program.classes ?? []) {
+        for (const m of cls.methods ?? [])
             if (visit(m.statements))
                 return true;
-        for (const g of cls.getters)
+        for (const g of cls.getters ?? [])
             if (visit(g.statements))
                 return true;
-        for (const s of cls.setters)
+        for (const s of cls.setters ?? [])
             if (visit(s.statements))
                 return true;
         if (cls.constructor && visit(cls.constructor.statements))
@@ -106,12 +109,109 @@ function programUsesWdt(program) {
     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
- * non-entry files of a split compilation, where the full helper shim belongs
- * to the entry file but the macro token is still referenced here.
- * Returns an empty array if no matching guard is found.
+ * Detect whether a program uses @typecad/safety. The safety transform pass
+ * injects safety.* ops when in use; strategies consult this to decide
+ * whether to emit the __tc_gpio_read shim that the safety voter calls.
+ * Mirrors programUsesWdt() above (same inline walker pattern).
+ *
+ * `hal-expr` (the expression-position safety.read_safe lowering produced
+ * by `const r = safe.read(pin)`) lives in expression trees, not at statement
+ * level — but it's carried inside a var_decl statement whose initializer is
+ * the hal-expr, and the var_decl gets visited as a top-level statement. We
+ * detect both: statement-level `hal-op` operations, and any statement whose
+ * rendered initializer text mentions safety.* (a defensive catch for the
+ * hal-expr-in-initializer case). The latter is rarely needed because the
+ * voter's read_safe op is also captured at the call site, but kept for
+ * robustness.
  */
+export function programUsesSafety(program) {
+    // Defensive: some test fixtures and partial-program callers pass a minimal
+    // object (e.g. `{} as any`). Treat a missing iterable field as "no safety
+    // ops" rather than crashing — matches how the existing ArduinoStrategy path
+    // behaves when given a partial program.
+    if (!program)
+        return false;
+    const visitStatement = (stmt) => {
+        if (stmt.kind === "hal-op") {
+            const opName = stmt.operation?.operation;
+            if (typeof opName === "string" && opName.startsWith("safety."))
+                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;
+    }
+    // SafeInt<T> / SafeVariable<T> usage does not produce safety.* hal-ops
+    // (they are plain C++ template types), so the op-walk above misses them.
+    // Detect via the var_decl cppType: any declaration whose type starts with
+    // "SafeInt" or "SafeVariable" needs the corresponding polyfill to ship.
+    const usesSafeWrapperType = (statements) => {
+        if (!statements)
+            return false;
+        for (const stmt of statements) {
+            if (stmt.kind === "var_decl") {
+                const cppType = stmt.cppType;
+                if (typeof cppType === "string" && (cppType.startsWith("SafeInt") || cppType.startsWith("SafeVariable"))) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    };
+    if (usesSafeWrapperType(program.topLevelStatements))
+        return true;
+    for (const fn of program.functions ?? []) {
+        if (usesSafeWrapperType(fn.statements))
+            return true;
+    }
+    return false;
+}
 function extractShimMacro(lines, macroName) {
     const ifndefIdx = lines.findIndex(l => {
         const trimmed = l.trim();
@@ -174,9 +274,29 @@ export function buildEmitterContext(program, options) {
             stringEnumNames.add(name);
         }
     }
+    // When @typecad/safety is active, register its enum names so the expression
+    // renderer uses :: (C++ enum-class scope resolution) instead of . (TS dot
+    // access) for member access like SafetyFaultCategory.Configuration. The
+    // graph-builder skips @typecad/safety (its source isn't parsed), so these
+    // enum names never enter program.enums — we register them manually here.
+    if (hasSafetyHook()) {
+        enumNames.add("SafetyFaultCategory");
+        enumNames.add("SafetyFaultCode");
+        enumNames.add("SafetyStatus");
+    }
     const strategy = options.strategy ?? resolveStrategy(options.target ?? "generic");
     strategy.setLargeEnumNames?.(largeEnumNames);
-    const reservedNames = strategy.reservedNames();
+    // When @typecad/safety is active, `safe` is a compile-time-only construct
+    // (its methods are intercepted at IR-build time). Its top-level var_decl
+    // (from the parsed safety module source) must NOT be emitted as a C++
+    // _safe_t struct — add it to reservedNames so the top-level-prep filter
+    // strips it. Mirrors how platform reserved names (HIGH, LOW, etc.) are
+    // kept out of user-code emission.
+    let reservedNames = new Set(strategy.reservedNames());
+    if (hasSafetyHook()) {
+        reservedNames = new Set(reservedNames);
+        reservedNames.add("safe");
+    }
     ensureDir(options.outDir);
     const classNameMap = (() => {
         try {
@@ -226,14 +346,50 @@ export function buildEmitterContext(program, options) {
         ? (strategy.generateNativePolyfills?.(program, options.platformContext) ?? [])
         : (strategy.generateNativePolyfills?.(program, options.platformContext) ?? []);
     let filteredNativePolyfills = filterPolyfillHelpers(nativePolyfills, programAnalysis.usedPolyfillHelpers);
-    if (!programAnalysis.hasThrowStatements) {
+    // cuttlefish_halt: keep when the program throws (throw lowers to cuttlefish_halt)
+    // OR explicitly calls cuttlefish_halt in lowered raw text.
+    if (!programAnalysis.hasThrowStatements && !programAnalysis.usesHalt) {
         filteredNativePolyfills = filteredNativePolyfills.filter(p => p.id !== "cuttlefish_halt");
     }
+    // static_array: the __tc_StaticArray struct has no __tc_*() call pattern, so
+    // filterPolyfillHelpers' per-function tree-shaker can't drop it (it sees no
+    // extractable name). Gate at the polyfill-id level instead: keep only when
+    // __tc_StaticArray genuinely appears in used code.
+    if (!programAnalysis.usedPolyfillHelpers.has('__tc_StaticArray')) {
+        filteredNativePolyfills = filteredNativePolyfills.filter(p => p.id !== "static_array");
+    }
     const usesTimers = programAnalysis.usedPolyfillHelpers.has('__tc_setInterval') ||
         programAnalysis.usedPolyfillHelpers.has('__tc_setTimeout');
     if (!usesTimers) {
         filteredNativePolyfills = filteredNativePolyfills.filter(p => p.id !== "timer_methods");
     }
+    // Safety polyfills (mode table + voter + SafeVariable + SafeInt). Gated on
+    // programUsesSafety(program) so they ONLY appear when the sketch actually
+    // references a safety construct — emitting them unconditionally (just because
+    // @typecad/safety is installed and registered its hook) leaks ~200 lines of
+    // polyfill into every sketch, and SafeInt's `return *this` chaining methods
+    // tripped byte-identity / lowering assertions that expect no `this` token.
+    // programUsesSafety walks the IR for any safety.* hal-op.
+    if (isEntryFile && hasSafetyHook() && programUsesSafety(program)) {
+        const safetyPolyfills = filterPolyfillHelpers(requireSafetyHook().buildPolyfills?.() ?? [], programAnalysis.usedPolyfillHelpers);
+        filteredNativePolyfills = [...filteredNativePolyfills, ...safetyPolyfills];
+    }
+    // Cooperative scheduler polyfill (Phase 0). Injected centrally when the
+    // strategy opts into priority/time-budget scheduling AND there is per-frame
+    // work to schedule (async tasks, the std::function microtask pump, or the
+    // cooperative timer pump). The polyfill carries only the no-STL CoopSched
+    // namespace; per-program trampoline registration is emitted by the function
+    // emitter around the driver's loop injection. STL-free so it links on
+    // minimal-libc targets (Zephyr) where the Promise runtime does not.
+    const coopConfig = strategy.getAsyncRuntimeConfig?.();
+    const hasCoopWork = program.functions.some(fn => fn.isAsync) ||
+        programAnalysis.usedPolyfillHelpers.has('__tc_setInterval') ||
+        programAnalysis.usedPolyfillHelpers.has('__tc_setTimeout');
+    if (isEntryFile && coopConfig && hasCoopWork) {
+        const coop = buildCoopSchedulerPolyfill(program, coopConfig, strategy.currentTimeMillis());
+        if (coop)
+            filteredNativePolyfills = [...filteredNativePolyfills, coop];
+    }
     const allPolyfills = filteredNativePolyfills;
     const emittedPolyfills = allPolyfills.length > 0
         ? emitPolyfillBoilerplate(allPolyfills)
@@ -243,23 +399,15 @@ export function buildEmitterContext(program, options) {
     if (!isNpmPackage) {
         includes.push(...strategy.forcedIncludes(program, options.platformContext));
         Object.assign(symbolMap, strategy.symbolAliases(program, options.platformContext));
-        if (isEntryFile) {
-            shimLines = [...strategy.shimLines(program, options.platformContext)];
-        }
-        else {
-            // Non-entry files in split compilation: always emit the full shim
-            // block. A class method body that uses `??` lowers to a
-            // cuttlefish_nullish(...) call, but the helper lives in the entry
-            // file's shim — which isn't visible from this header. We used to gate
-            // this on programAnalysis.usesNullish, but that flag is unreliable:
-            // the analysis runs before the expression renderer, which can
-            // introduce cuttlefish_nullish calls (e.g. for default-param
-            // destructuring, or `??` inside class methods on abstract bases)
-            // that the analysis pass didn't see, leaving the header referencing
-            // an undeclared helper. The shim is fully idempotent (#ifndef
-            // guards), so emitting it unconditionally is safe and cheap.
-            shimLines = [...strategy.shimLines(program, options.platformContext)];
-        }
+        // Both entry and non-entry files get the strategy's shim lines, then the
+        // Layer B filters below strip unused blocks based on programAnalysis. For
+        // non-entry (split-file) headers, the per-file pre-render analysis can miss
+        // renderer-introduced calls (e.g. cuttlefish_nullish from `??` lowering);
+        // output-finalizer.ts handles that case with a post-render text scan that
+        // re-injects the nullish helper shim into a header whose emitted lines
+        // actually contain a cuttlefish_nullish( call. So gating here is safe — the
+        // post-render injection covers the one unreliable pre-render signal.
+        shimLines = [...strategy.shimLines(program, options.platformContext)];
         if (!programAnalysis.usesStringConversion) {
             shimLines = shimLines.filter(l => !l.includes('std::string String('));
         }
@@ -311,7 +459,9 @@ export function buildEmitterContext(program, options) {
         // 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) {
+        // Keep the UART block when console calls are present (console_log etc.
+        // call _uart_* functions) even if no direct uart.* HAL ops are used.
+        if (!programAnalysis.usesUart && !programAnalysis.hasConsoleCalls) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_BEGIN', '// CUTTLEFISH_UART_END');
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_EXT_BEGIN', '// CUTTLEFISH_UART_EXT_END');
         }
@@ -321,7 +471,7 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesI2C) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TWI_BEGIN', '// CUTTLEFISH_TWI_END');
         }
-        if (!programAnalysis.usesEEPROM) {
+        if (!programAnalysis.usesEEPROM && !programAnalysis.usesPreferences) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_EEPROM_BEGIN', '// CUTTLEFISH_EEPROM_END');
         }
         if (!programAnalysis.usesTone) {
@@ -361,6 +511,23 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesWifi) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WIFI_BEGIN', '// CUTTLEFISH_WIFI_END');
         }
+        else {
+            if (!programAnalysis.usesWifiConnect) {
+                shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WIFI_CONNECT_BEGIN', '// CUTTLEFISH_WIFI_CONNECT_END');
+            }
+            if (!programAnalysis.usesWifiConnectBlocking) {
+                shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WIFI_CONNECT_BLOCKING_BEGIN', '// CUTTLEFISH_WIFI_CONNECT_BLOCKING_END');
+            }
+            if (!programAnalysis.usesWifiQuery) {
+                shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WIFI_QUERY_BEGIN', '// CUTTLEFISH_WIFI_QUERY_END');
+            }
+            if (!programAnalysis.usesWifiScan) {
+                shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WIFI_SCAN_BEGIN', '// CUTTLEFISH_WIFI_SCAN_END');
+            }
+            if (!programAnalysis.usesWifiConfig) {
+                shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_WIFI_CONFIG_BEGIN', '// CUTTLEFISH_WIFI_CONFIG_END');
+            }
+        }
         if (!programAnalysis.usesHttp) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_HTTP_BEGIN', '// CUTTLEFISH_HTTP_END');
         }
@@ -402,11 +569,11 @@ export function buildEmitterContext(program, options) {
                 symbolMap[defaultName] = defaultName;
             continue;
         }
-        // Compile-time-only packages (@typecad/ui, @typecad/ui): their calls are
-        // intercepted at IR-build time; the package emits NO C++ module/header.
-        // Register the imported symbols so references resolve, but skip the
-        // #include generation (there is no Ui.h to include).
-        if (imported.moduleSpecifier === "@typecad/ui" || imported.moduleSpecifier === "@typecad/ui") {
+        // Compile-time-only packages: their calls are intercepted at IR-build
+        // time; the package emits NO C++ module/header. Register the imported
+        // symbols so references resolve, but skip the #include generation.
+        if (imported.moduleSpecifier === "@typecad/ui" ||
+            imported.moduleSpecifier === "@typecad/safety") {
             for (const symbol of imported.namedImports) {
                 symbolMap[symbol] = symbol;
             }
@@ -759,6 +926,10 @@ export function buildEmitterContext(program, options) {
         knownTopLevelObjectTypes,
         diagnostics: emitDiagnostics,
     });
+    // Construct the compliance context early so it can be threaded into the
+    // renderers (StatementRenderer needs it for A3-9-1 fixed-width integer
+    // default). It's also returned in the EmitterContext at the end.
+    const compliance = new ComplianceContext(options.autosar ?? "off");
     const statementRenderer = new StatementRenderer({
         strategy,
         boardConstants: program.boardConstants,
@@ -777,6 +948,7 @@ export function buildEmitterContext(program, options) {
         interfaceFieldTypes,
         crossModuleClassNames: classNames,
         diagnostics: emitDiagnostics,
+        compliance,
     });
     const asyncFunctionOriginalNames = new Set(program.functions.filter((fn) => fn.isAsync).map((fn) => fn.originalName));
     const mapFunctionNameLocal = (originalName) => statementRenderer.mapFunctionName(originalName);
@@ -991,6 +1163,14 @@ export function buildEmitterContext(program, options) {
         headerLines: ["#pragma once", ""],
         sourceMapEntries: [],
         headerMapEntries: [],
+        // GDB debug mode: emit #line markers at appendSourceLine when 'gdb'.
+        // Resolved once from strategy.debugMode(buildTarget); defaults to 'printf'
+        // so all existing paths keep their pre-marker behavior.
+        debugMode: (() => {
+            const buildTarget = options.platformContext?.frameworkData?.buildTarget;
+            return strategy.debugMode?.(buildTarget) ?? 'printf';
+        })(),
+        lastEmittedSource: null,
         cArrayVarNames: new Set(),
         fnCArrayVarNames: new Map(),
         globalPointerVarTypes,
@@ -1008,5 +1188,6 @@ export function buildEmitterContext(program, options) {
         templateInterfaceNames,
         interfaceNamespaceMap,
         interfaceFieldTypes,
+        compliance,
     };
 }

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

@@ -187,6 +187,12 @@ function collectCallbackFromExpression(expr, callbackFunctions, isrPrefix, count
 function collectCallbacks(statements, callbackFunctions, isrPrefix, counter) {
     for (const stmt of statements) {
         if (stmt.kind === "call") {
+            // __EXPR_STMT__ statements carry an expression IR (args[0]) that the
+            // statement renderer renders at EMIT time via the expression renderer
+            // (which handles lambdas inline via renderLambda). Do NOT hoist lambdas
+            // from these — they must stay inline to preserve closure captures.
+            if (stmt.callee === "__EXPR_STMT__")
+                continue;
             for (const arg of stmt.args) {
                 collectCallbackFromExpression(arg, callbackFunctions, isrPrefix, counter);
             }

package/dist/emit/emitters/type-decl-emitter.js

@@ -5,7 +5,27 @@ import { isStringEnum } from "../../api/shared/index.js";
 import { resolveEnumValues, narrowestEnumUnderlying } from "../utils/cpp-helpers.js";
 export function emitTypeDeclarations(ctx) {
     const { program, strategy, effectiveEmitMode, reservedNames, emittedTopLevelStatements, topLevelScope } = ctx;
-    const normalizeCppTypeForTarget = (cppType) => strategy.normalizeCppType(cppType);
+    const normalizeCppTypeForTarget = (cppType) => {
+        // A3-9-1: resolve "auto" and substitute "int" with the fixed-width
+        // default — but ONLY when autosar is active. When off, fall through to
+        // the strategy's normalizeCppType (Arduino returns "auto" for "auto").
+        const autosarOn = ctx.compliance.isEnabled() && ctx.compliance.isBanned("A3-9-1");
+        if (autosarOn && (cppType === "auto" || cppType === "int")) {
+            return strategy.defaultNumericType(ctx.compliance);
+        }
+        // Also apply the int->int32_t substitution to the inner template argument
+        // of safety wrappers (SafeInt<int> -> SafeInt<int32_t>, SafeVariable<int>
+        // -> SafeVariable<int32_t>). The whole-type check above misses these
+        // because the full string is "Name<int>", not "int".
+        if (autosarOn) {
+            const wrapperMatch = cppType.match(/^(Safe(?:Int|Variable))<int>$/);
+            if (wrapperMatch) {
+                const fixedWidth = strategy.defaultNumericType(ctx.compliance);
+                return `${wrapperMatch[1]}<${fixedWidth}>`;
+            }
+        }
+        return strategy.normalizeCppType(cppType);
+    };
     // Split-mode header include + forward declarations
     if (effectiveEmitMode === "split") {
         appendSourceLine(ctx, `#include \"${ctx.baseName}.h\"`);
@@ -222,7 +242,12 @@ export function emitTypeDeclarations(ctx) {
                     cppType = strategy.normalizeCppType(resolved);
             }
             const isConst = statement.storage === "const";
-            const constPrefix = isConst ? "const " : "";
+            // A const-qualified top-level variable whose cppType already begins with
+            // `const` (e.g. a string-literal global lowered as `const char*`) would
+            // otherwise emit `extern const const char* X;` — a duplicate-const error.
+            // Don't prepend the storage qualifier when the type already carries it.
+            const typeAlreadyConst = cppType.trimStart().startsWith("const");
+            const constPrefix = isConst && !typeAlreadyConst ? "const " : "";
             const varName = escapeCppKeyword(statement.name, platformReservedNames);
             // Array-typed top-level consts (e.g. `export const ARR: T[] = [...]`)
             // lower with cppType "auto" and a `{ kind: "array", elementType }`
@@ -234,7 +259,7 @@ export function emitTypeDeclarations(ctx) {
             if (cppType === "auto" && statement.initializer && statement.initializer.kind === "array") {
                 const elemType = statement.initializer.elementType && statement.initializer.elementType !== "auto"
                     ? strategy.normalizeCppType(statement.initializer.elementType)
-                    : strategy.defaultNumericType();
+                    : strategy.defaultNumericType(ctx.compliance.isEnabled() ? ctx.compliance : undefined);
                 appendHeaderLine(ctx, `extern ${constPrefix}${elemType} ${varName}[];`);
                 emitted = true;
                 continue;

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

@@ -169,12 +169,21 @@ 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) {
+        // The native CuttlefishGFX/CuttlefishCanvas16 class slice is emitted ONLY
+        // for adapters that instantiate CuttlefishGFX by value (the planned
+        // framework-avr/framework-esp32 native panel drivers). Adapters that alias
+        // the token via macro — the Adafruit path (`#define CuttlefishCanvas16
+        // GFXcanvas16`) and the SDL path (`#define CuttlefishCanvas16 SdlGfxCanvas`)
+        // — own the canvas type; emitting the class slice alongside the macro makes
+        // `class CuttlefishCanvas16` macro-expand into a redefinition of Adafruit's
+        // GFXcanvas16. Detect the macro-alias path from the adapter's own includes
+        // and suppress the slice there. The previous gate reused
+        // providesDisplayAdapter(), which merely means "the strategy owns its
+        // adapters" (true for Arduino/Adafruit) and is unrelated to whether the
+        // native GFX class is wanted — it wrongly emitted the slice on every
+        // Arduino build, breaking compilation.
+        const macroAliasesCanvas16 = /^\s*#\s*define\s+CuttlefishCanvas16\b/m.test(adapter.includes);
+        if (!macroAliasesCanvas16) {
             ctx.sourceLines.push(ui.emitCuttlefishGfx(true));
         }
         ctx.sourceLines.push(adapter.declaration);
@@ -265,8 +274,8 @@ 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, 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`] : []));
+    const scroll = resolveScrollConfig(profile);
+    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}`, ...(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.

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

@@ -88,7 +88,7 @@ export declare class ExpressionRenderer {
     private readonly stringEnumNames;
     private readonly largeEnumNames;
     private readonly knownFunctionReturnTypes?;
-    private readonly knownVariableTypes?;
+    private knownVariableTypes?;
     private readonly pointerVarTypes?;
     private readonly globalPointerVarTypes?;
     private readonly stringVarNames?;

package/dist/emit/expression-renderer.js

@@ -80,6 +80,18 @@ export class ExpressionRenderer {
         if (!expr || typeof expr !== 'object' || !expr.kind) {
             return "/* invalid expression */";
         }
+        // When a per-scope knownVariableTypes is passed (e.g. a function's child
+        // emission scope carrying its parameters), install it on the instance for
+        // the duration of this render so every recursive render() call and
+        // renderIdentifier() reads the merged scope (globals + params). Without
+        // this, recursive paths that don't forward knownVariableTypes (ternary
+        // branches, call args, array elements, …) would resolve identifiers
+        // against only the top-level scope, missing function parameters — which
+        // breaks reserved-name escaping for params like `min`/`max` on Arduino.
+        const prevKnownVariableTypes = this.knownVariableTypes;
+        if (knownVariableTypes) {
+            this.knownVariableTypes = knownVariableTypes;
+        }
         let rendered;
         switch (expr.kind) {
             case "number": {
@@ -100,7 +112,7 @@ export class ExpressionRenderer {
                 rendered = expr.value ? "true" : "false";
                 break;
             case "identifier":
-                rendered = this.renderIdentifier(expr.value);
+                rendered = this.renderIdentifier(expr.value, knownVariableTypes);
                 break;
             case "raw":
                 rendered = this.renderRaw(expr.value, exprTransformer);
@@ -150,6 +162,18 @@ export class ExpressionRenderer {
             case "method-call":
                 rendered = this.renderMethodCall(expr, exprTransformer);
                 break;
+            case "call": {
+                // Bare call expression: `Name(args)` with no receiver (e.g. a
+                // constructor call `SafeInt(x)` written inline, or a free function).
+                // Method-on-receiver calls lower as "method-call"; this arm is for the
+                // receiverless form. The callee is escaped against C++ reserved names;
+                // when a target type is in scope, renderValueForTarget (the caller)
+                // wraps this with template args (SafeInt(x) -> SafeInt<int32_t>(x)).
+                const callArgs = expr.args.map(a => this.render(a, exprTransformer)).join(", ");
+                const callCallee = escapeCppKeyword(exprTransformer ? exprTransformer(expr.callee) : expr.callee, this.strategy.reservedNames());
+                rendered = `${callCallee}(${callArgs})`;
+                break;
+            }
             case "element-access":
                 rendered = this.renderElementAccess(expr, exprTransformer, knownVariableTypes);
                 break;
@@ -192,9 +216,10 @@ export class ExpressionRenderer {
                     `This is a transpiler bug; the renderer is missing a case for this kind.`);
             }
         }
+        this.knownVariableTypes = prevKnownVariableTypes;
         return normalizeRawExpression(rendered, this.strategy, this.classNameMap);
     }
-    renderIdentifier(value) {
+    renderIdentifier(value, scopeKnownVariableTypes) {
         const nullVal = this.strategy.nullValue();
         // expression-to-ir lowers the TS `null` literal to the identifier sentinel
         // "nullptr" and `undefined` to "CUTTLEFISH_UNDEFINED". Both must route
@@ -210,7 +235,27 @@ export class ExpressionRenderer {
         if (this.strategy.passthroughMacroNames().has(value)) {
             return value;
         }
-        return escapeCppKeyword(value, this.strategy.reservedNames());
+        // Platform-reserved names (e.g. Arduino `Serial`, or the `min`/`max` math
+        // macros) are globals/macros provided by the framework headers. Escaping
+        // them would break references to those globals — UNLESS the name is a
+        // user-declared variable/parameter that shadows and would collide. Check
+        // both the instance field (globals/locals seen so far) AND the per-scope
+        // map passed by the caller (function parameters, which live in the child
+        // emission scope and aren't on the instance field). Declaration sites
+        // already escape user vars (renderParameters → renderTypedName), so the
+        // body references must escape to match.
+        const reservedNames = this.strategy.reservedNames();
+        if (reservedNames.has(value)) {
+            const isUserVar = (this.knownVariableTypes !== undefined && this.knownVariableTypes.has(value)) ||
+                (scopeKnownVariableTypes !== undefined && scopeKnownVariableTypes.has(value)) ||
+                (this.pointerVarTypes !== undefined && this.pointerVarTypes.has(value)) ||
+                (this.globalPointerVarTypes !== undefined && this.globalPointerVarTypes.has(value)) ||
+                (this.stringVarNames !== undefined && this.stringVarNames.has(value));
+            if (!isUserVar) {
+                return value;
+            }
+        }
+        return escapeCppKeyword(value, reservedNames);
     }
     renderRaw(value, exprTransformer) {
         const effectiveClassNameMap = this.classNameMap;
@@ -887,10 +932,27 @@ export class ExpressionRenderer {
      * (safer than a wrong cast).
      */
     renderValueForTarget(expr, targetType, knownVariableTypes, exprTransformer) {
-        const rendered = this.render(expr, exprTransformer, knownVariableTypes);
         if (!targetType)
-            return rendered;
+            return this.render(expr, exprTransformer, knownVariableTypes);
         const normalizedTarget = targetType.trim();
+        // Inject template args for constructor calls on pre-C++17 toolchains
+        // (e.g. AVR without CTAD). SafeVariable(0) → SafeVariable<int32_t>(0).
+        // Handles both `method-call` (when the constructor appears as a standalone
+        // initializer) and `call` (when it appears on the RHS of an assignment,
+        // which lowers as `T x = {}; x = T(args);`). The callee must match the
+        // template name and the target must be a `Name<...>` instantiation, so a
+        // regular function call assigned to a non-templated type never matches.
+        const tmplMatch = normalizedTarget.match(/^([A-Za-z_]\w*)<(.+)>/);
+        const exprAny = expr;
+        const isCtorCall = tmplMatch != null
+            && (exprAny.kind === "method-call" || exprAny.kind === "call")
+            && exprAny.callee === tmplMatch[1]
+            && exprAny.callee != null && !exprAny.callee.includes("<");
+        if (isCtorCall && exprAny.args) {
+            const argsText = exprAny.args.map(a => this.render(a, exprTransformer, knownVariableTypes)).join(", ");
+            return `${tmplMatch[1]}<${tmplMatch[2]}>(${argsText})`;
+        }
+        const rendered = this.render(expr, exprTransformer, knownVariableTypes);
         // Never cast into string-like storage — enums that lower to const char*
         // (string enums) already match, and a string target is never an enum boundary.
         if (this.isStringLikeCppType(normalizedTarget))
@@ -1359,6 +1421,8 @@ export class ExpressionRenderer {
     renderMethodCall(expr, exprTransformer) {
         const argsText = expr.args.map(a => this.render(a, exprTransformer)).join(", ");
         let callee = exprTransformer ? exprTransformer(expr.callee) : expr.callee;
+        const rExpr = expr.receiverExpr;
+        const mName = expr.methodName;
         // Convert . to :: for static or namespace method calls if the IR flagged them.
         if (expr.isStatic || expr.isNamespace) {
             callee = callee.replace(/\./g, "::");
@@ -1389,6 +1453,18 @@ export class ExpressionRenderer {
             return callee;
         }
         callee = this.escapeFinalMemberName(callee);
+        // Structured-receiver path: when the method-call IR carries a receiverExpr
+        // (the safe.read().ok().fail() chain builder sets this), render the receiver
+        // via the full renderer so nested lambda args survive (the flat callee string
+        // would have destroyed them as /* __lambda__ */ placeholders). The methodName
+        // is escaped against reserved names (e.g. div -> div_).
+        const receiverExpr = expr.receiverExpr;
+        const methodName = expr.methodName;
+        if (receiverExpr !== undefined && methodName !== undefined) {
+            const receiverText = this.render(receiverExpr, exprTransformer);
+            const escapedMethod = escapeCppKeyword(methodName, this.strategy.reservedNames());
+            return `${receiverText}.${escapedMethod}(${argsText})`;
+        }
         return `${callee}(${argsText})`;
     }
     escapeFinalMemberName(callee) {