@typecad/cuttlefish 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/create/{init-wizard.js → wizard.js}

@@ -1,8 +1,8 @@
 import * as readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import chalk from "chalk";
-import { KNOWN_TARGETS } from "./init-scaffold.js";
-import { frameworksForTarget, frameworkCatalogEntry, FRAMEWORK_CATALOG, frameworkTargetProfile } from "./framework-catalog.js";
+import { KNOWN_TARGETS } from "./scaffold.js";
+import { frameworksForTarget, frameworkCatalogEntry, frameworkCompatibleWithTarget, FRAMEWORK_CATALOG, frameworkTargetProfile } from "./framework-catalog.js";
 function validateProjectName(name) {
     if (!name || name.trim().length === 0) {
         return "Project name cannot be empty.";
@@ -53,7 +53,7 @@ async function promptConfirm(rl, prompt, defaultValue) {
         return defaultValue;
     return trimmed === "y" || trimmed === "yes";
 }
-export async function runInitWizard(partialOptions) {
+export async function runCreateWizard(partialOptions) {
     const rl = readline.createInterface({ input, output });
     try {
         console.log();
@@ -101,9 +101,16 @@ export async function runInitWizard(partialOptions) {
         if (partialOptions?.framework) {
             const requested = frameworkCatalogEntry(partialOptions.framework);
             if (!requested) {
-                const available = FRAMEWORK_CATALOG.filter((f) => f.installable).map((f) => f.id).join(", ");
+                const available = FRAMEWORK_CATALOG.filter(f => f.installable).map(f => f.id).join(", ");
                 throw new Error(`Unknown framework '${partialOptions.framework}'. Available: ${available}`);
             }
+            // Same compatibility guard as the non-interactive CLI path: a preseeded
+            // --framework bypasses the narrowing below, so validate it explicitly.
+            if (!frameworkCompatibleWithTarget(target, requested.id)) {
+                const list = compatible.map(f => f.id).join(", ");
+                throw new Error(`Framework '${requested.id}' is not compatible with target '${target.id}' (${target.displayName}). ` +
+                    `Compatible frameworks: ${list}`);
+            }
             framework = requested.id;
             frameworkPackage = requested.packageName;
             console.log(`${chalk.cyan("?")} Framework: ${chalk.white(requested.label)}`);

package/dist/emit/compliance/rules.js

@@ -146,8 +146,8 @@ export const RULES = [
             },
         ],
     },
-    { id: "A18-5-10", title: "No malloc/calloc/realloc", severity: "required", category: "C",
-        detect: /\b(malloc|calloc|realloc)\s*\(/, enabled: true,
+    { id: "A18-5-10", title: "No malloc/calloc/realloc/free (C dynamic memory family)", severity: "required", category: "C",
+        detect: /\b(?:ps_)?(?:malloc|calloc|realloc|free)\s*\(/, enabled: true,
         knownPatterns: [
             {
                 // Offscreen canvas allocation (CuttlefishCanvas16/CuttlefishCanvasMono
@@ -163,10 +163,24 @@ export const RULES = [
                 // the alternative (operator new) is the very thing that crashes. The
                 // object is placement-constructed on the malloc'd memory and freed via
                 // an explicit dtor + free, so the vtable/lifetime are correct.
-                detect: /malloc\s*\(/,
-                justification: "Canvas object/buffer allocation on full-libcpp-without-exceptions targets; malloc avoids the operator-new std::bad_alloc → std::terminate → abort path. OOM returns NULL and the runtime degrades gracefully.",
+                // ps_malloc is the ESP32 PSRAM variant of the same constraint.
+                detect: /(?:ps_)?malloc\s*\(/,
+                justification: "Canvas object/buffer allocation on full-libcpp-without-exceptions targets; malloc (or ESP32 ps_malloc) avoids the operator-new std::bad_alloc → std::terminate → abort path. OOM returns NULL and the runtime degrades gracefully.",
                 kind: "ts-literal",
             },
+            {
+                // Offscreen canvas teardown, the release side of the allocations
+                // above (canvas objects and their malloc'd/ps_malloc'd pixel
+                // buffers). On Arduino cores operator new is malloc-backed and
+                // free() releases both SRAM and PSRAM objects via the ESP32 unified
+                // heap, so dtor + free() is the correct teardown for every canvas
+                // allocation path — `delete` would be UB on the placement-new PSRAM
+                // object. Only these named canvas/buffer releases are deviations;
+                // any other free() stays an unrecorded violation.
+                detect: /\bfree\s*\(\s*(?:canvas|buffer_|psramBuf)\s*\)/,
+                justification: "Canvas teardown on targets whose operator new is malloc-backed (Arduino cores, ESP32 unified heap): the object was placement-constructed or allocation-path-compatible, so dtor + free() is the only well-defined release; delete would be UB on placement-new PSRAM objects.",
+                kind: "raw-array",
+            },
         ],
     },
     { id: "A27-0-4", title: "No function returning std::move of local", severity: "required", category: "C",

package/dist/emit/emitters/function-emitter-impl.js

@@ -31,7 +31,13 @@ export function emitPostClassDeclarations(ctx) {
     // and failed at g++ time. Demo #28 Finding B.
     if (ctx.promotedVarDecls.size > 0) {
         for (const [varName, info] of ctx.promotedVarDecls) {
-            appendSourceLine(ctx, `${info.cppType} ${escapeCppKeyword(varName, platformReservedNames)} = {};`);
+            // A3-9-1: promoted file-scope declarations bypass renderVarDecl, so the
+            // int -> fixed-width substitution has to be applied here as well.
+            const autosarOn = ctx.compliance.isEnabled() && ctx.compliance.isBanned("A3-9-1");
+            const fwdType = autosarOn && info.cppType === "int"
+                ? strategy.defaultNumericType(ctx.compliance)
+                : normalizeCppTypeForTarget(info.cppType);
+            appendSourceLine(ctx, `${fwdType} ${escapeCppKeyword(varName, platformReservedNames)} = {};`);
             // Seed the top-level scope's type map so subsequent assign rendering
             // (e.g. the deferred `c = SafeInt(0)` initializer) can resolve the
             // variable's type and inject template args / casts via

package/dist/emit/emitters/line-appender.js

@@ -298,6 +298,12 @@ export function appendRenderedStatement(ctx, statement, indent, scopeState) {
         return;
     }
     if (statement.kind === "block") {
+        if (statement.body.length === 0) {
+            // An empty block is a no-op statement — skip it entirely so lowered
+            // top-level statements don't litter setup() with bare { } pairs.
+            emitCommentLines(statement.trailingComments, indent, (line) => appendSourceLine(ctx, line));
+            return;
+        }
         appendSourceLine(ctx, `${indent}{`, { tsSpan: statement.sourceSpan, nodeKind: statement.kind });
         const nestedScope = cloneEmissionScopeState(scopeState);
         for (const nested of statement.body)

package/dist/emit/emitters/setup.js

@@ -5,6 +5,7 @@ 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 { isRegisteredCuttlefishLibrary } from "../../library-packages.js";
 import { emitPolyfillBoilerplate } from "../native-helpers-emitter.js";
 import { resolveStrategy } from "../../platform/registry.js";
 import { buildCoopSchedulerPolyfill } from "../../platform/coop-scheduler-runtime.js";
@@ -547,6 +548,14 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesPreferences) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_PREFERENCES_BEGIN', '// CUTTLEFISH_PREFERENCES_END');
         }
+        // Entry-TU marker for framework shims: the UI runtime header (ui_tick) is
+        // emitted ONLY into the entry file (emitUIRuntime gates on isEntryFile), so
+        // shim helpers that keep the UI alive during bounded blocking waits (e.g.
+        // Zephyr's wifi connect) must compile those calls down everywhere else.
+        // Defined before the shim lines land in the preamble, after all filters.
+        if (isEntryFile && entryHasUI() && shimLines.length > 0) {
+            shimLines.unshift("#define CUTTLEFISH_ENTRY_UI_TU 1");
+        }
         profileDiagnostics = [...strategy.profileDiagnostics(program, options.platformContext)];
     }
     for (const imported of program.imports) {
@@ -554,6 +563,19 @@ export function buildEmitterContext(program, options) {
         // named imports — add it to the symbolMap so cross-module references
         // resolve. Demo #12 Finding C — was skipped, so `encode` wasn't declared.
         const defaultName = imported.defaultImportName;
+        // Cuttlefish library packages: the import emits the shim-header include
+        // (resolved through the libdef registry from the library manifest) and
+        // contributes native shims + build fragments. This must run BEFORE the
+        // SDK skip below — @typecad-scoped libraries would otherwise be treated
+        // as type-level-only like the rest of the SDK.
+        if (isRegisteredCuttlefishLibrary(imported.moduleSpecifier)) {
+            const resolved = resolveImport(imported, options.libdefs, options.target, options.platformContext, program.fileName);
+            includes.push(normalizeInclude(resolved.include));
+            Object.assign(symbolMap, resolved.symbolMap);
+            if (defaultName)
+                symbolMap[defaultName] = defaultName;
+            continue;
+        }
         if (isCuttlefishSDKImport(imported.moduleSpecifier, program.fileName)) {
             for (const symbol of imported.namedImports) {
                 symbolMap[symbol] = symbol;

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

@@ -46,8 +46,13 @@ export function generateTouchPollBody(input) {
     const hasNativeSize = profile.nativeWidth !== undefined && profile.nativeHeight !== undefined;
     const nativeWidth = profile.nativeWidth ?? profile.width;
     const nativeHeight = profile.nativeHeight ?? profile.height;
-    const rawMapX = `map(__rawX, ${xMin}, ${xMax}, 0, ${nativeWidth})`;
-    const rawMapY = `map(__rawY, ${yMin}, ${yMax}, 0, ${nativeHeight})`;
+    // Inlined Arduino map() arithmetic, NOT a map() call: the emitted body must
+    // be self-contained. The map/constrain helpers are capability-gated
+    // (usesMap is set by SCRIPT-level map() calls only), so a bare map() here
+    // failed to link on frameworks without a core map() (Zephyr).
+    const mapCall = (raw, inMin, inMax, outMin, outMax) => `((${raw} - ${inMin}) * (${outMax} - ${outMin}) / (${inMax} - ${inMin}) + ${outMin})`;
+    const rawMapX = mapCall("__rawX", xMin, xMax, 0, nativeWidth);
+    const rawMapY = mapCall("__rawY", yMin, yMax, 0, nativeHeight);
     let mapX, mapY;
     let sdlClamp = false;
     if (library === "sdl") {
@@ -69,15 +74,15 @@ export function generateTouchPollBody(input) {
         const invertY = rotation === 1 || rotation === 2;
         if (isLandscape) {
             mapX = invertX
-                ? `map(__rawX, ${xMin}, ${xMax}, ${profile.width}, 0)`
-                : `map(__rawX, ${xMin}, ${xMax}, 0, ${profile.width})`;
+                ? mapCall("__rawX", xMin, xMax, profile.width, 0)
+                : mapCall("__rawX", xMin, xMax, 0, profile.width);
             mapY = invertY
-                ? `map(__rawY, ${yMin}, ${yMax}, ${profile.height}, 0)`
-                : `map(__rawY, ${yMin}, ${yMax}, 0, ${profile.height})`;
+                ? mapCall("__rawY", yMin, yMax, profile.height, 0)
+                : mapCall("__rawY", yMin, yMax, 0, profile.height);
         }
         else {
-            mapX = `map(__rawY, ${yMin}, ${yMax}, ${profile.width}, 0)`;
-            mapY = `map(__rawX, ${xMin}, ${xMax}, 0, ${profile.height})`;
+            mapX = mapCall("__rawY", yMin, yMax, profile.width, 0);
+            mapY = mapCall("__rawX", xMin, xMax, 0, profile.height);
         }
     }
     else {
@@ -323,8 +328,12 @@ export function emitUIRuntime(ctx) {
             ctx.sourceLines.push(lowered.keyboardDispatch);
     }
     // 3. Signal variables (one per ui.signal / const X = ui.signal).
+    // A3-9-1: signal decls bypass the statement renderer, so apply the
+    // int -> fixed-width substitution here under --autosar.
+    const signalAutosarOn = ctx.compliance.isEnabled() && ctx.compliance.isBanned("A3-9-1");
+    const fixedWidth = signalAutosarOn && ctx.strategy ? ctx.strategy.defaultNumericType(ctx.compliance) : "";
     for (const decl of uiSignalDecls()) {
-        ctx.sourceLines.push(decl);
+        ctx.sourceLines.push(fixedWidth && decl.startsWith("int ") ? `${fixedWidth}${decl.slice(3)}` : decl);
     }
     // 4. Binding table (accumulated from ui.bind calls).
     // Forward-declare the binding compute functions first: the table references
@@ -462,17 +471,33 @@ export function emitUIRuntime(ctx) {
         }
         return entries.join(", ");
     };
+    // Per-table counts: the runtime indexes each table by node, so the safe
+    // bound for dispatch is each table's own highest populated index + 1 — not
+    // the shared click-table size (holds/releases can span fewer nodes).
+    const tableCount = (kind) => {
+        const max = touchHandlers
+            .filter(h => h.kind === kind)
+            .reduce((m, h) => Math.max(m, h.nodeIndex), -1);
+        return Math.max(max + 1, 1);
+    };
+    // The handler tables are link-time constants (function pointers only) and
+    // are never written at runtime — emit them const so they land in flash
+    // rodata instead of stealing DRAM (~4.5KB on a 380-node demo).
     if (profile.touch) {
-        ctx.sourceLines.push(`void (*__ui_click_handlers[])() = { ${buildTable("click")} };`);
-        ctx.sourceLines.push(`void (*__ui_hold_handlers[])() = { ${buildTable("hold")} };`);
-        ctx.sourceLines.push(`void (*__ui_release_handlers[])() = { ${buildTable("release")} };`);
+        ctx.sourceLines.push(`void (*const __ui_click_handlers[])() = { ${buildTable("click")} };`);
+        ctx.sourceLines.push(`void (*const __ui_hold_handlers[])() = { ${buildTable("hold")} };`);
+        ctx.sourceLines.push(`void (*const __ui_release_handlers[])() = { ${buildTable("release")} };`);
         ctx.sourceLines.push(`const uint16_t __ui_click_handler_count = ${tableSize};`);
+        ctx.sourceLines.push(`const uint16_t __ui_hold_handler_count = ${tableCount("hold")};`);
+        ctx.sourceLines.push(`const uint16_t __ui_release_handler_count = ${tableCount("release")};`);
     }
     else {
-        ctx.sourceLines.push(`void (*__ui_click_handlers[])() = {};`);
-        ctx.sourceLines.push(`void (*__ui_hold_handlers[])() = {};`);
-        ctx.sourceLines.push(`void (*__ui_release_handlers[])() = {};`);
+        ctx.sourceLines.push(`void (*const __ui_click_handlers[])() = {};`);
+        ctx.sourceLines.push(`void (*const __ui_hold_handlers[])() = {};`);
+        ctx.sourceLines.push(`void (*const __ui_release_handlers[])() = {};`);
         ctx.sourceLines.push(`const uint16_t __ui_click_handler_count = 0;`);
+        ctx.sourceLines.push(`const uint16_t __ui_hold_handler_count = 0;`);
+        ctx.sourceLines.push(`const uint16_t __ui_release_handler_count = 0;`);
     }
     // 8b. Input onChange dispatch — assigns __ui_kb_onchange based on __ui_kb_target.
     // Forward-declare __ui_kb_set_onchange unconditionally: the runtime header's

package/dist/emit/route-hal-op.js

@@ -8,8 +8,20 @@
 // everything else goes to resolveHALOperation (the existing generic seam).
 // Keeps the consumer sites (expression-renderer, statement-renderer,
 // render-expr) DRY.
+//
+// Output-pin state tracking is also handled here, centrally, so every
+// strategy benefits without per-strategy changes:
+// - gpio.read with `trackedValue` never reaches the strategy (a hardware
+//   read of a direction-only output is not portable, e.g. Zephyr); it folds
+//   to a constant or the tracked shadow variable.
+// - gpio.write / gpio.toggle flagged `updatesShadow` get the shadow variable
+//   update appended to whatever the strategy produced. The flag is baked
+//   into the op at IR-build time (markShadowUpdatingOps) — emit must not
+//   consult live tracker state, because all files build (each resetting the
+//   tracker) before any file emits.
 // ---------------------------------------------------------------------------
 import { getSafetyHook } from "../safety-hook.js";
+import { pinShadowVarName } from "../ir/pin-state-tracking.js";
 export function routeHALOp(op, strategy) {
     if (typeof op.operation === "string") {
         if (op.operation.startsWith("display.")) {
@@ -22,5 +34,47 @@ export function routeHALOp(op, strategy) {
             return getSafetyHook()?.resolveSafetyOp?.(op);
         }
     }
-    return strategy.resolveHALOperation?.(op);
+    if (op.operation === "gpio.read" && op.trackedValue) {
+        // Tracked OUTPUT-pin read: software truth, never a hardware read.
+        if (op.trackedValue === "high")
+            return { expression: "true" };
+        if (op.trackedValue === "low")
+            return { expression: "false" };
+        return { expression: pinShadowVarName(op.pin) };
+    }
+    const resolved = strategy.resolveHALOperation?.(op);
+    // Toggle on a shadow-tracked pin must not use the strategy's default
+    // read-modify-write form (e.g. digitalWrite(p, digitalRead(p) ...) on
+    // Arduino) — reading the pin back is exactly what tracking avoids. Lower
+    // it as a write of the shadow's current value, then flip the shadow.
+    if (op.operation === "gpio.toggle" && op.updatesShadow) {
+        const varName = pinShadowVarName(op.pin);
+        const writeOp = {
+            operation: "gpio.write",
+            pin: op.pin,
+            value: varName,
+            ...(op.port !== undefined ? { port: op.port } : {}),
+        };
+        const writeResolved = strategy.resolveHALOperation?.(writeOp);
+        const flip = `${varName} = (!${varName});`;
+        if (writeResolved?.code) {
+            return { ...writeResolved, code: `${writeResolved.code}\n${flip}` };
+        }
+        if (writeResolved?.expression) {
+            return { ...writeResolved, expression: `${writeResolved.expression}, ${flip}` };
+        }
+        return { code: flip };
+    }
+    if (op.operation === "gpio.write" && op.updatesShadow) {
+        const varName = pinShadowVarName(op.pin);
+        const update = `${varName} = ((${op.value}) != 0);`;
+        if (resolved?.code) {
+            return { ...resolved, code: `${resolved.code}\n${update}` };
+        }
+        if (resolved?.expression) {
+            return { ...resolved, expression: `${resolved.expression}, ${update}` };
+        }
+        return { code: update };
+    }
+    return resolved;
 }

package/dist/emit/statement-renderer.js

@@ -551,8 +551,11 @@ export class StatementRenderer {
         }
         const declaredType = this.normalizeCppType(statement.cppType);
         const volatilePrefix = statement.isVolatile ? "volatile " : "";
-        // Transform type name for Arduino library classes (add namespace prefix)
-        const transformedType = transformTypeName(statement.cppType, this.classNameMap);
+        // Transform type name for Arduino library classes (add namespace prefix).
+        // A3-9-1: substitute the fixed-width default for the IR's hardcoded "int"
+        // BEFORE the class-name transform so var declarations match the other
+        // declaration paths under --autosar.
+        const transformedType = transformTypeName(declaredType, this.classNameMap);
         const ownershipKind = statement.ownershipKind;
         // Emit const for Shared<T> ownership annotations (ownershipKind === 'shared')
         const isConst = statement.storage === "const" || ownershipKind === 'shared';

package/dist/ir/build-ir.js

@@ -8,7 +8,8 @@ import { buildFunctionReturnTypeMap } from "./type-resolution.js";
 import { resolveBoardConstants, tryResolveBoardDefFile } from "./board-resolver.js";
 import { analyzePeripheralUsage, createEmptyPeripheralUsage } from "./peripheral-usage.js";
 import { runProgramValidations } from "./validation-orchestrator.js";
-import { registerFieldMap, hoistedNestedFunctions, hoistedNestedClasses, hoistedNestedEnums, hoistedNestedInterfaces, hoistedNestedTypeAliases, activeNamespaceNames, activeEnumNames, activeStringEnumNames, peripheralAliasMap, pinAliasMap, mcuPinReverseMap, topLevelClassNames, topLevelInterfaceNames, classTypeNames, topLevelClasses, requiredIncludes, resetBuildState, getCurrentBoardConstants, setCurrentBoardConstants, contextStorage, CompilationContext, registeredCallbacks, getContext, discriminatedUnionVariantNames, restParamFunctions, topLevelAliasReceivers } from "./build-ir-state.js";
+import { registerFieldMap, hoistedNestedFunctions, hoistedNestedClasses, hoistedNestedEnums, hoistedNestedInterfaces, hoistedNestedTypeAliases, activeNamespaceNames, activeEnumNames, activeStringEnumNames, peripheralAliasMap, pinAliasMap, mcuPinForwardMap, mcuPinReverseMap, topLevelClassNames, topLevelInterfaceNames, classTypeNames, topLevelClasses, requiredIncludes, resetBuildState, getCurrentBoardConstants, setCurrentBoardConstants, contextStorage, CompilationContext, registeredCallbacks, getContext, discriminatedUnionVariantNames, restParamFunctions, topLevelAliasReceivers } from "./build-ir-state.js";
+import { pinShadowVarName, takeShadowDeclarations, resetPinStateTracking, markShadowUpdatingOps } from "./pin-state-tracking.js";
 import { collectPointerVars, expressionStatementToIR, lowerStatement, variableStatementToIR, prescanArrayUsage, lowerStatementList } from "./statement-to-ir.js";
 import { registerUIModuleImport, registerElementValue } from "./transformers/ui-call-resolver.js";
 import { requireUIHook } from "../ui-hook.js";
@@ -181,6 +182,7 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
         // Reset module-level state for this file
         resetBuildState();
         resetHALResolver();
+        resetPinStateTracking();
         registerFieldMap.clear();
         // Phase 0: Pre-scan for top-level classes and register them so type inference can resolve them.
         // Also register classes from other files in the transpile graph so that property accesses
@@ -495,10 +497,31 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
                             halInstances.set(name, { className: "Pin", fieldValues: fields });
                             continue;
                         }
-                        // A-pins: A0-A19 → Pin instance with board-specific offset and MCU port name (fallback)
+                        // A-pins: A0, A1, … → resolve through the board manifest's analog
+                        // pin list first (A-ordered on every board package: A<n> →
+                        // pins.analog[n] → the MCU port name → pin number). Only when the
+                        // list is absent (bare Arduino-style boards) fall back to the
+                        // analogOffset convention (A0 = 14) — on port-named boards that
+                        // fallback resolves A1 to a random GPIO (Black Pill PA15, a
+                        // non-analog pin, was the first to surface it via a capability
+                        // error).
                         const aMatch = name.match(/^A(\d+)$/);
                         if (aMatch) {
-                            const pinNum = String(analogOffset + parseInt(aMatch[1]));
+                            let pinNum;
+                            // The flattener stores the manifest's analog pin list as a
+                            // comma-joined string under `pins.analog`.
+                            const analogList = boardConstants.get("pins.analog");
+                            if (typeof analogList === "string") {
+                                const analogName = analogList.split(",")[parseInt(aMatch[1], 10)];
+                                if (analogName) {
+                                    const byName = mcuPinForwardMap.get(analogName);
+                                    if (byName !== undefined)
+                                        pinNum = String(byName);
+                                }
+                            }
+                            if (pinNum === undefined) {
+                                pinNum = String(analogOffset + parseInt(aMatch[1]));
+                            }
                             const fields = new Map([["_pin", pinNum]]);
                             const portName = mcuPinReverseMap.get(pinNum);
                             if (portName)
@@ -786,7 +809,7 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
             // If peripheral analysis fails, use empty usage
             peripheralUsage = createEmptyPeripheralUsage();
         }
-        return {
+        const program = {
             fileName,
             imports,
             reExports,
@@ -808,5 +831,24 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
             restParamFunctions: new Map(restParamFunctions),
             ...(defaultExportName ? { defaultExportName } : {}),
         };
+        // Output-pin state tracking. First bake the shadow-update flags into the
+        // write/toggle ops, while this file's tracker state is still live (the
+        // next file's build resets it, and emit runs after every file is built —
+        // multi-file programs would lose the updates otherwise). Then consume the
+        // shadow declarations — pins whose reads lowered to the shadow variable
+        // form need a file-scope declaration.
+        markShadowUpdatingOps(program);
+        const shadowDecls = takeShadowDeclarations();
+        for (const { pin, initial } of shadowDecls) {
+            program.topLevelStatements.unshift({
+                kind: "var_decl",
+                sourceSpan: { filePath: fileName, startOffset: 0, endOffset: 0, startLine: 0, startColumn: 0, endLine: 0, endColumn: 0 },
+                name: pinShadowVarName(pin),
+                storage: "var",
+                cppType: "bool",
+                initializer: { kind: "boolean", value: initial },
+            });
+        }
+        return program;
     });
 }

package/dist/ir/expression-to-ir.js

@@ -1,6 +1,7 @@
 import ts from "typescript";
 import { makeDiagnostic, makeSourceSpan } from "./ast-node-utils.js";
 import { PIN_FACTORY_FUNCTIONS, CONSTANT_FOLD_FUNCTIONS, TYPED_ARRAY_ELEMENT_MAP, activeCArrayVars, activeArrayLiteralVars, activeStringVars, nestedFunctionAliases, nestedClassAliases, hoistedNestedClasses, mutableArrayVars, arrayLiteralSizes, filteredArrayLengthVars, activeNamespaceNames, activeEnumNames, activeStringEnumNames, topLevelClassNames, topLevelInterfaceNames, classTypeNames, topLevelClasses, getActiveExtendsClass, restParamFunctions, getContext, getCurrentBoardConstants } from "./build-ir-state.js";
+import { isPinFoldingEnabled, setPinFoldingEnabled } from "./pin-state-tracking.js";
 import { getCurrentIrTypeScope } from "./symbol-types.js";
 import { renderExprAsText } from "./render-expr.js";
 import { lowerStatement, tryResolveHALExpression } from "./statement-to-ir.js";
@@ -340,6 +341,17 @@ export function expressionToIR(expr, sourceText, diagnostics, pointerVars = new
      * variable name prefixed with "__FILTERED_LEN__" so the caller can detect it.
      */
     function resolveLengthProperty(receiverNode, objectText) {
+        // UI element text: screen.<id>.text is a raw char buffer on the node —
+        // `.length` must be strlen, not `.size()` (char[33] has no size member).
+        if (ts.isPropertyAccessExpression(receiverNode) &&
+            receiverNode.name.text === "text" &&
+            ts.isPropertyAccessExpression(receiverNode.expression) &&
+            ts.isIdentifier(receiverNode.expression.expression)) {
+            const nodeIdx = resolveElementValue(receiverNode.expression.expression.text, receiverNode.expression.name.text);
+            if (nodeIdx !== undefined) {
+                return `static_cast<long long>(strlen(__ui_nodes[${nodeIdx}].textBuffer))`;
+            }
+        }
         if (ts.isStringLiteral(receiverNode) || ts.isNoSubstitutionTemplateLiteral(receiverNode)) {
             return `${receiverNode.text.length}`;
         }
@@ -2185,6 +2197,10 @@ export function expressionToIR(expr, sourceText, diagnostics, pointerVars = new
             }
         }
         const isBlock = ts.isBlock(body);
+        // Lambda bodies run at an unmodeled time (callbacks), so pin-state
+        // constant folding must be off inside them.
+        const prevPinFolding = isPinFoldingEnabled();
+        setPinFoldingEnabled(false);
         const bodyStmts = isBlock
             ? body.statements.map(stmt => {
                 const lowered = lowerStatement(stmt, "", sourceText, diagnostics, new Map(), new Map(), "<lambda>", new Map(), pointerVars);
@@ -2196,6 +2212,7 @@ export function expressionToIR(expr, sourceText, diagnostics, pointerVars = new
                     sourceSpan: makeSourceSpan(body, "", sourceText),
                     value: expressionToIR(body, sourceText, diagnostics, pointerVars),
                 }];
+        setPinFoldingEnabled(prevPinFolding);
         // Infer return type: use explicit annotation, or infer from body. Thread
         // the lambda's own param types into the inference so a body like
         // `(n) => n.capacity` can resolve `n` and deduce the return type.

package/dist/ir/hal/hal-emitter.js

@@ -5,6 +5,7 @@ import { renderExprAsText } from "../render-expr.js";
 import { escapeCppKeyword } from "../../utils/strings.js";
 import { halClassRegistry, halGlobalFunctions } from "./hal-parser.js";
 import { tryResolveSemanticCall, tryResolveBoardResolveArg, tryResolveCompoundSemanticReturn, resolveConcatPath } from "./hal-plugins.js";
+import { resolveTrackedRead, pinShadowVarName } from "../pin-state-tracking.js";
 import { cppTypeForHalOp } from "../../emit/utils/hal-op-cpp-type.js";
 /** Escape C++ keywords in resolved text, but only when the text looks like a
  *  variable reference (not a literal like "false", "true", "42", or a string). */
@@ -58,13 +59,30 @@ function prefixOperatorText(operator) {
 function inlineThisGetterCall(methodName, pin, strategy) {
     switch (methodName) {
         case "read":
-            return strategy?.readDigitalPin?.(pin) ?? `digitalRead(${pin})`;
-        case "readAnalog":
-            return strategy?.readAnalogPin?.(pin) ?? `analogRead(${pin})`;
         case "isHigh":
-            return strategy?.readDigitalPin?.(pin) ?? `digitalRead(${pin})`;
-        case "isLow":
+        case "isLow": {
+            // Output-pin state tracking: when the receiver is a tracked OUTPUT pin,
+            // lower to the tracked level (constant when statically known, shadow
+            // variable otherwise) instead of a hardware read. Reading back a
+            // direction-only output is not portable (e.g. Zephyr).
+            const pinNum = Number.parseInt(pin, 10);
+            if (Number.isFinite(pinNum)) {
+                const tracked = resolveTrackedRead(pinNum);
+                if (tracked !== null) {
+                    const levelText = tracked === "shadow"
+                        ? pinShadowVarName(pinNum)
+                        : (tracked === "high" ? "true" : "false");
+                    return methodName === "isLow" ? `(!${levelText})` : levelText;
+                }
+            }
+            if (methodName === "read")
+                return strategy?.readDigitalPin?.(pin) ?? `digitalRead(${pin})`;
+            if (methodName === "isHigh")
+                return strategy?.readDigitalPin?.(pin) ?? `digitalRead(${pin})`;
             return strategy?.readDigitalPin ? `(!${strategy.readDigitalPin(pin)})` : `(!digitalRead(${pin}))`;
+        }
+        case "readAnalog":
+            return strategy?.readAnalogPin?.(pin) ?? `analogRead(${pin})`;
         default:
             return null;
     }

package/dist/ir/hal/hal-plugins.js

@@ -3,6 +3,7 @@ import { getCurrentBoardConstants, halInstances, getContext } from "../build-ir-
 import { resolveExpressionText } from "./hal-emitter.js";
 import { renderExprAsText } from "../render-expr.js";
 import { hasSafetyHook, requireSafetyHook } from "../../safety-hook.js";
+import { notePinSetMode, notePinToggle, notePinWrite, notePinAnalogOutput, resolveTrackedRead } from "../pin-state-tracking.js";
 /**
  * Split a comma-joined argument list back into individual arguments, respecting
  * nesting (parens/brackets/braces) and string literals so a comma inside one of
@@ -326,11 +327,13 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
             // Try literal resolution first (compile-time 0/1/true/false)
             const numValue = resolveNumericArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
             if (numValue !== null) {
+                notePinWrite(pin, numValue);
                 return { operation: "gpio.write", port, pin, value: (numValue ? 1 : 0) };
             }
             // Fall back to runtime expression (e.g. a variable, negated expression)
             const exprValue = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
             if (exprValue !== null) {
+                notePinWrite(pin, null);
                 return { operation: "gpio.write", port, pin, value: exprValue };
             }
             return null;
@@ -339,12 +342,17 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
             const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
             if (pin === null)
                 return null;
+            const tracked = resolveTrackedRead(pin);
+            if (tracked !== null) {
+                return { operation: "gpio.read", port, pin, trackedValue: tracked };
+            }
             return { operation: "gpio.read", port, pin };
         }
         case "gpioToggle": {
             const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
             if (pin === null)
                 return null;
+            notePinToggle(pin);
             return { operation: "gpio.toggle", port, pin };
         }
         case "gpioSetMode": {
@@ -352,6 +360,7 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
             const mode = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
             if (pin === null || mode === null)
                 return null;
+            notePinSetMode(pin, mode);
             return { operation: "gpio.set_mode", port, pin, mode };
         }
         // ── PWM ──
@@ -360,6 +369,7 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
             const duty = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
             if (pin === null || duty === null)
                 return null;
+            notePinAnalogOutput(pin);
             return { operation: "pwm.write", port, pin, duty };
         }
         // ── RMT ──
@@ -1127,6 +1137,7 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
             const duration = resolveNumericOrExpression(args, 2, instance, paramNames, callArgTexts, paramDefaults);
             if (pin === null || frequency === null)
                 return null;
+            notePinAnalogOutput(pin);
             return { operation: "tone.play", port, pin, frequency, ...(duration !== null ? { duration } : {}) };
         }
         case "toneStop": {

package/dist/ir/pin-mode-validation.js

@@ -34,6 +34,9 @@ export function validatePinModeConfig(program) {
     const diagnostics = [];
     // Track which receivers have had their mode explicitly set
     const pinModeSet = new Set();
+    // Pins currently driven by PWM/tone (since their last digital write or
+    // mode change). Reading such a pin has no defined digital level.
+    const analogDrivenPins = new Set();
     const checkCuttlefishCall = (receiver, receiverKind, method) => {
         if (!receiverKind || !PIN_RECEIVER_KINDS.has(receiverKind))
             return;
@@ -98,16 +101,36 @@ export function validatePinModeConfig(program) {
         const pinKey = `pin${op.pin}`;
         if (op.operation === 'gpio.set_mode') {
             pinModeSet.add(pinKey);
+            analogDrivenPins.delete(pinKey);
         }
-        else if (op.operation === 'gpio.read' && !pinModeSet.has(pinKey)) {
-            diagnostics.push({
-                severity: 'warning',
-                message: `Pin ${op.pin} read without prior mode configuration. ` +
-                    `Call asInput() or inputPullUp() first — reading a floating pin is undefined behavior.`,
-                filePath: program.fileName,
-                code: 'pin-mode-not-set',
-                source: 'pin-mode-validation',
-            });
+        else if (op.operation === 'pwm.write' || op.operation === 'tone.play') {
+            analogDrivenPins.add(pinKey);
+        }
+        else if (op.operation === 'gpio.write' || op.operation === 'gpio.toggle') {
+            analogDrivenPins.delete(pinKey);
+        }
+        else if (op.operation === 'gpio.read') {
+            if (analogDrivenPins.has(pinKey)) {
+                diagnostics.push({
+                    severity: 'warning',
+                    message: `Pin ${op.pin} read while driven by PWM/tone. ` +
+                        `The pin has no defined digital level while an analog output is active; ` +
+                        `tracked reads return the last digital write, not the waveform.`,
+                    filePath: program.fileName,
+                    code: 'pin-read-while-pwm',
+                    source: 'pin-mode-validation',
+                });
+            }
+            else if (!pinModeSet.has(pinKey)) {
+                diagnostics.push({
+                    severity: 'warning',
+                    message: `Pin ${op.pin} read without prior mode configuration. ` +
+                        `Call asInput() or inputPullUp() first — reading a floating pin is undefined behavior.`,
+                    filePath: program.fileName,
+                    code: 'pin-mode-not-set',
+                    source: 'pin-mode-validation',
+                });
+            }
         }
         else if ((op.operation === 'gpio.write' || op.operation === 'gpio.toggle') && !pinModeSet.has(pinKey)) {
             diagnostics.push({