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

package/dist/create/debug-artifacts.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// debug-artifacts.ts — create-time framework debug profile generation
+//
+// `cuttlefish create` scaffolds a project that has never been built, so the
+// framework toolchain's post-build debug-artifact writer (e.g. Zephyr's
+// writeDebugConfig, which runs after a successful `west build --debug`) has
+// never had a chance to run. Without a .vscode/launch.json, pressing F5 in VS
+// Code just opens the "select a debugger" menu.
+//
+// Frameworks that support native debugging may export
+// `writeProjectDebugArtifacts({ workspaceRoot, buildTarget })` from their
+// package root (see @typecad/framework-zephyr). This helper loads the freshly
+// installed framework package and invokes that export — the framework decides
+// whether the target is debug-capable and what to write. Frameworks without
+// the export (or targets without native debug support) are a silent no-op.
+//
+// Everything here is best-effort: a failed or skipped generation never fails
+// `cuttlefish create`, because the first `--debug` build still writes the
+// artifacts the hard way.
+// ---------------------------------------------------------------------------
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadFrameworkPackage } from "../framework-package.js";
+const cliModuleDir = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Generate the framework's starter debug artifacts for a new project.
+ * Returns the workspace-relative paths written (e.g. ['.vscode/launch.json']),
+ * or [] when the framework has no debug support, isn't resolvable yet, or the
+ * generator failed (warns, never throws).
+ */
+export function generateFrameworkDebugArtifacts(o, loadModule) {
+    if (!o.frameworkPackage || !o.workspaceRoot)
+        return [];
+    // Default loader: prefer the new project's node_modules (populated by the
+    // create install step), then the CLI's own module location (monorepo /
+    // --no-install flows where the framework is a workspace sibling of the
+    // running cuttlefish).
+    const loader = loadModule ?? ((packageName) => {
+        for (const dir of [o.workspaceRoot, cliModuleDir]) {
+            try {
+                return loadFrameworkPackage(packageName, dir);
+            }
+            catch {
+                // not resolvable from this location — try the next
+            }
+        }
+        return undefined;
+    });
+    let mod;
+    try {
+        mod = loader(o.frameworkPackage);
+    }
+    catch {
+        return [];
+    }
+    if (!mod || typeof mod.writeProjectDebugArtifacts !== "function")
+        return [];
+    try {
+        const written = mod.writeProjectDebugArtifacts({
+            workspaceRoot: o.workspaceRoot,
+            buildTarget: o.buildTarget,
+        });
+        return Array.isArray(written) ? written.map(String) : [];
+    }
+    catch (e) {
+        console.warn(`! Debug profile generation failed: ${e.message}`);
+        return [];
+    }
+}

package/dist/create/index.d.ts

@@ -7,6 +7,8 @@ export type { ProjectInstallResult } from './install-deps.js';
 export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
 export type { InitProjectOptions } from './init-templates.js';
 export { runInitWizard } from './init-wizard.js';
+export { generateFrameworkDebugArtifacts } from './debug-artifacts.js';
+export type { FrameworkDebugArtifactsOptions, FrameworkModuleLoader } from './debug-artifacts.js';
 export { scaffoldBoardPackages } from './board-codegen.js';
 export type { ScaffoldBoardResult } from './board-codegen.js';
 export { generateFrameworkChecklist } from './board-checklist.js';

package/dist/create/index.js

@@ -3,6 +3,7 @@ export { FRAMEWORK_CATALOG, frameworksForTarget, frameworkCatalogEntry, detectPa
 export { installProjectDependencies, __setProjectInstallRunnerForTest } from './install-deps.js';
 export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
 export { runInitWizard } from './init-wizard.js';
+export { generateFrameworkDebugArtifacts } from './debug-artifacts.js';
 // Board codegen tool (`cuttlefish board add`)
 export { scaffoldBoardPackages } from './board-codegen.js';
 export { generateFrameworkChecklist } from './board-checklist.js';

package/dist/create/init-scaffold.d.ts

@@ -33,4 +33,5 @@ export interface ScaffoldProjectResult {
 export declare function scaffoldProject(options: InitProjectOptions, outDir?: string): ScaffoldProjectResult;
 export declare function printInitNextSteps(options: InitProjectOptions, outDir: string, opts?: {
     installed?: boolean;
+    debugProfile?: boolean;
 }): void;

package/dist/create/init-scaffold.js

@@ -168,6 +168,11 @@ export function printInitNextSteps(options, outDir, opts = {}) {
         console.log(chalk.dim(`  npm install`));
     }
     console.log(`  ${chalk.cyan("npm run compile")}`);
+    if (opts.debugProfile) {
+        console.log();
+        console.log(chalk.bold.white("To debug (VS Code):"));
+        console.log(`  ${chalk.cyan("open the folder and press F5")} ${chalk.dim("(builds + flashes, then attaches GDB)")}`);
+    }
     if (!options.isNative) {
         const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
         console.log();

package/dist/create/init-templates.js

@@ -149,7 +149,6 @@ const config = {
 
   // Output options
   output: {
-    optimize: 'speed',
     outDir: './out',
   },
 };
@@ -198,7 +197,6 @@ const config: CuttlefishConfig = {
   // Output / build options
   output: {
     framework: '${options.framework}',
-    optimize: 'size',
     outDir: './out',
   },
 

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/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

@@ -9,6 +9,7 @@ import { resolveBoardConstants, tryResolveBoardDefFile } from "./board-resolver.
 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 { 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
@@ -786,7 +788,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 +810,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({