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

package/dist/ir/pin-state-tracking.d.ts

@@ -0,0 +1,58 @@
+import type { ProgramIR } from "../api/index.js";
+export type TrackedPinLevel = 'high' | 'low' | 'unknown';
+/** C++ identifier for a pin's shadow state variable. */
+export declare function pinShadowVarName(pin: number): string;
+export declare function resetPinStateTracking(): void;
+/** Record gpio.set_mode — OUTPUT* modes enable tracking, anything else ends it. */
+export declare function notePinSetMode(pin: number, mode: string | null): void;
+/** Record gpio.write — literal values set the level; expressions make it unknown. */
+export declare function notePinWrite(pin: number, literalValue: number | boolean | null): void;
+/** Record gpio.toggle — inverts a known level, keeps unknown as unknown. */
+export declare function notePinToggle(pin: number): void;
+/**
+ * Record PWM/tone output — the pin no longer has a digital level, so any
+ * tracked level goes unknown (reads must not fold to the pre-PWM literal).
+ * A later digital write/toggle restores digital tracking.
+ */
+export declare function notePinAnalogOutput(pin: number): void;
+/**
+ * Resolve a read on a pin at the current program point.
+ * Returns 'high'/'low' when the level folds to a constant, 'shadow' when a
+ * shadow variable must carry it, or null when the pin is not a tracked
+ * output pin (unconfigured or input mode → normal hardware read lowering).
+ */
+export declare function resolveTrackedRead(pin: number): 'high' | 'low' | 'shadow' | null;
+/** Whether write/toggle ops on this pin must also update its shadow variable. */
+export declare function isShadowPin(pin: number): boolean;
+/** Consume the shadow declarations owed by this build (pin + initializer).
+ *  Clears the shadow set: emit reads the updatesShadow flags baked into the
+ *  ops below, never this module's live state (each file's build resets the
+ *  tracker, and all files finish building before any emit runs). */
+export declare function takeShadowDeclarations(): {
+    pin: number;
+    initial: boolean;
+}[];
+/** Mark every gpio.write / gpio.toggle op in the program whose pin has a
+ *  tracked shadow read, so the emitter appends the shadow-variable update.
+ *  Runs once at the end of buildProgramIR, after the whole file is lowered —
+ *  at that point the shadow set is final, so writes that were lowered BEFORE
+ *  the first shadow read are marked too (their ops are already in the IR).
+ *  This is what makes emit independent of tracker state across files. */
+export declare function markShadowUpdatingOps(program: ProgramIR): void;
+export type PinLevelSnapshot = Map<number, TrackedPinLevel>;
+export declare function snapshotPinLevels(): PinLevelSnapshot;
+export declare function restorePinLevels(snapshot: PinLevelSnapshot): void;
+/**
+ * Merge two branch-end states into the live state: pins that agree keep
+ * their level; pins that differ (or exist in only one branch) become
+ * unknown. Pass the pre-branch state as one side when there is no else
+ * branch, so pins written in the taken branch invalidate.
+ */
+export declare function mergePinLevels(a: PinLevelSnapshot, b: PinLevelSnapshot): void;
+/** Invalidate all known levels (after loop/switch bodies, which may run any
+ *  number of times). Shadow tracking is unaffected — it is runtime truth. */
+export declare function invalidatePinLevels(): void;
+/** Disable/enable constant folding around function and callback bodies. */
+export declare function setPinFoldingEnabled(enabled: boolean): void;
+/** Whether pin-level constant folding is currently allowed. */
+export declare function isPinFoldingEnabled(): boolean;

package/dist/ir/pin-state-tracking.js

@@ -0,0 +1,182 @@
+// ---------------------------------------------------------------------------
+// Output Pin State Tracking
+//
+// Tracks the driven level of pins configured as OUTPUT so that
+// OutputPin.read()/isHigh()/isLow() can be answered without a hardware pin
+// read. Reading back an OUTPUT-only pin is not portable (Zephyr's
+// gpio_pin_get reads the input latch, which is undefined for direction-only
+// outputs), so the transpiler instead maintains the state itself:
+//
+// - When the level is statically known at the read site (asOutput(false)
+//   followed by literal high/low/write/toggle calls), the read folds to a
+//   compile-time constant.
+// - When it is not (runtime-valued writes, loops, branches, function
+//   bodies), the read lowers to a shadow variable (`__tc_pin_state_<n>`)
+//   that every generated write/toggle on that pin keeps updated.
+//
+// The tracker is updated in program order during IR lowering (the same pass
+// that resolves HAL method bodies), so the state seen at each read site is
+// the state at that point in the source. Control-flow joins and loop bodies
+// conservatively invalidate levels (see control-flow.ts hooks); function and
+// callback bodies disable folding entirely and force the shadow form.
+// ---------------------------------------------------------------------------
+import { walkProgramIR, walkExpressions } from "./utils/walk-ir.js";
+/** Pin numbers explicitly configured as OUTPUT via gpio.set_mode. */
+const outputPins = new Set();
+/** Last driven level per output pin, at the current program point. */
+const pinLevels = new Map();
+/** Output pins whose reads lowered to the shadow variable form. */
+const shadowPins = new Set();
+/** Initializer for each shadow variable: the statically-known level at the
+ *  time the first shadow read was resolved, or `false` when unknown. */
+const shadowInitial = new Map();
+/** Folding is disabled inside function/callback bodies, where the top-level
+ *  program-point state does not apply at runtime. */
+let foldingEnabled = true;
+/** C++ identifier for a pin's shadow state variable. */
+export function pinShadowVarName(pin) {
+    return `__tc_pin_state_${pin}`;
+}
+export function resetPinStateTracking() {
+    outputPins.clear();
+    pinLevels.clear();
+    shadowPins.clear();
+    shadowInitial.clear();
+    foldingEnabled = true;
+}
+/** Record gpio.set_mode — OUTPUT* modes enable tracking, anything else ends it. */
+export function notePinSetMode(pin, mode) {
+    const isOutput = mode !== null && /output/i.test(mode);
+    if (isOutput) {
+        outputPins.add(pin);
+        pinLevels.set(pin, 'unknown');
+    }
+    else {
+        outputPins.delete(pin);
+        pinLevels.delete(pin);
+    }
+}
+/** Record gpio.write — literal values set the level; expressions make it unknown. */
+export function notePinWrite(pin, literalValue) {
+    if (!outputPins.has(pin))
+        return;
+    pinLevels.set(pin, literalValue === null ? 'unknown' : (literalValue ? 'high' : 'low'));
+}
+/** Record gpio.toggle — inverts a known level, keeps unknown as unknown. */
+export function notePinToggle(pin) {
+    if (!outputPins.has(pin))
+        return;
+    const level = pinLevels.get(pin);
+    if (level === 'high')
+        pinLevels.set(pin, 'low');
+    else if (level === 'low')
+        pinLevels.set(pin, 'high');
+    else
+        pinLevels.set(pin, 'unknown');
+}
+/**
+ * Record PWM/tone output — the pin no longer has a digital level, so any
+ * tracked level goes unknown (reads must not fold to the pre-PWM literal).
+ * A later digital write/toggle restores digital tracking.
+ */
+export function notePinAnalogOutput(pin) {
+    if (!outputPins.has(pin))
+        return;
+    pinLevels.set(pin, 'unknown');
+}
+/**
+ * Resolve a read on a pin at the current program point.
+ * Returns 'high'/'low' when the level folds to a constant, 'shadow' when a
+ * shadow variable must carry it, or null when the pin is not a tracked
+ * output pin (unconfigured or input mode → normal hardware read lowering).
+ */
+export function resolveTrackedRead(pin) {
+    if (!outputPins.has(pin))
+        return null;
+    const level = pinLevels.get(pin);
+    if (foldingEnabled && (level === 'high' || level === 'low'))
+        return level;
+    shadowPins.add(pin);
+    if (!shadowInitial.has(pin))
+        shadowInitial.set(pin, level === 'high');
+    return 'shadow';
+}
+/** Whether write/toggle ops on this pin must also update its shadow variable. */
+export function isShadowPin(pin) {
+    return shadowPins.has(pin);
+}
+/** Consume the shadow declarations owed by this build (pin + initializer).
+ *  Clears the shadow set: emit reads the updatesShadow flags baked into the
+ *  ops below, never this module's live state (each file's build resets the
+ *  tracker, and all files finish building before any emit runs). */
+export function takeShadowDeclarations() {
+    const decls = [...shadowPins].sort((a, b) => a - b).map(pin => ({
+        pin,
+        initial: shadowInitial.get(pin) ?? false,
+    }));
+    shadowPins.clear();
+    shadowInitial.clear();
+    return decls;
+}
+/** Mark every gpio.write / gpio.toggle op in the program whose pin has a
+ *  tracked shadow read, so the emitter appends the shadow-variable update.
+ *  Runs once at the end of buildProgramIR, after the whole file is lowered —
+ *  at that point the shadow set is final, so writes that were lowered BEFORE
+ *  the first shadow read are marked too (their ops are already in the IR).
+ *  This is what makes emit independent of tracker state across files. */
+export function markShadowUpdatingOps(program) {
+    if (shadowPins.size === 0)
+        return;
+    const markOp = (op) => {
+        const halOp = op;
+        if (!halOp)
+            return;
+        if ((halOp.operation === "gpio.write" || halOp.operation === "gpio.toggle") && isShadowPin(halOp.pin)) {
+            halOp.updatesShadow = true;
+        }
+    };
+    walkProgramIR(program, (stmt) => {
+        if (stmt.kind === "hal-op")
+            markOp(stmt.operation);
+        walkExpressions([stmt], (expr) => {
+            if (expr.kind === "hal-expr")
+                markOp(expr.operation);
+        });
+    });
+}
+export function snapshotPinLevels() {
+    return new Map(pinLevels);
+}
+export function restorePinLevels(snapshot) {
+    pinLevels.clear();
+    for (const [pin, level] of snapshot)
+        pinLevels.set(pin, level);
+}
+/**
+ * Merge two branch-end states into the live state: pins that agree keep
+ * their level; pins that differ (or exist in only one branch) become
+ * unknown. Pass the pre-branch state as one side when there is no else
+ * branch, so pins written in the taken branch invalidate.
+ */
+export function mergePinLevels(a, b) {
+    const pins = new Set([...a.keys(), ...b.keys()]);
+    for (const pin of pins) {
+        const la = a.get(pin) ?? 'unknown';
+        const lb = b.get(pin) ?? 'unknown';
+        pinLevels.set(pin, la === lb ? la : 'unknown');
+    }
+}
+/** Invalidate all known levels (after loop/switch bodies, which may run any
+ *  number of times). Shadow tracking is unaffected — it is runtime truth. */
+export function invalidatePinLevels() {
+    for (const pin of outputPins)
+        pinLevels.set(pin, 'unknown');
+}
+/** Disable/enable constant folding around function and callback bodies. */
+export function setPinFoldingEnabled(enabled) {
+    foldingEnabled = enabled;
+}
+/** Whether pin-level constant folding is currently allowed. */
+export function isPinFoldingEnabled() {
+    return foldingEnabled;
+}

package/dist/ir/program-analysis.d.ts

@@ -19,6 +19,12 @@ export interface ProgramAnalysisResult {
     usesStringConversion: boolean;
     usesDateNow: boolean;
     usesMillis: boolean;
+    /** True when the program references millis()/micros() directly — WITHOUT the
+     *  delay() conflation usesMillis carries (framework-avr needs delay to keep
+     *  the native timing ISR alive, but frameworks whose delay() lowers straight
+     *  to a native sleep — e.g. Zephyr's k_msleep — must not treat a delay-only
+     *  program as a millis() consumer). */
+    usesWallClock: boolean;
     usesNullish: boolean;
     /** True when this file actually emits a cuttlefish_nullish/exists/is_nullish CALL
      *  (e.g. from a `??` lowering), as opposed to just referencing the

package/dist/ir/program-analysis.js

@@ -61,6 +61,18 @@ function analyzeExpression(expr, result, strategy) {
             if (/\bmillis\s*\(/.test(expr.value)) {
                 result.usesMillis = true;
             }
+            if (/\bmillis\s*\(/.test(expr.value) || /\bmicros\s*\(/.test(expr.value)) {
+                result.usesWallClock = true;
+            }
+            // Test-runner console helpers (@typecad/expect's preprocessor injects
+            // __tc_print/__tc_println calls into the source). Track them as polyfill
+            // helpers so frameworks can gate their definitions (and <cstdio>) on use.
+            if (expr.value.includes("__tc_println(")) {
+                result.usedPolyfillHelpers.add("__tc_println");
+            }
+            if (expr.value.includes("__tc_print(")) {
+                result.usedPolyfillHelpers.add("__tc_print");
+            }
             if (expr.value.includes('cuttlefish_nullish(') || expr.value.includes('cuttlefish_exists(') || expr.value.includes('cuttlefish_is_nullish(')) {
                 result.usesNullish = true;
                 result.usesNullishHelper = true;
@@ -100,6 +112,12 @@ function analyzeExpression(expr, result, strategy) {
             if (/\bmillis\b/.test(expr.callee) || /\bdelay\b/.test(expr.callee) || /\bmicros\b/.test(expr.callee)) {
                 result.usesMillis = true;
             }
+            if (/\bmillis\b/.test(expr.callee) || /\bmicros\b/.test(expr.callee)) {
+                result.usesWallClock = true;
+            }
+            if (expr.callee === "__tc_print" || expr.callee === "__tc_println") {
+                result.usedPolyfillHelpers.add(expr.callee);
+            }
             if (expr.callee === "Date.now" || expr.callee === "Date::now") {
                 result.usesDateNow = true;
             }
@@ -373,10 +391,17 @@ function analyzeStatement(statement, result, strategy) {
             if (statement.callee === "millis" || statement.callee === "delay") {
                 result.usesMillis = true;
             }
+            if (statement.callee === "millis") {
+                result.usesWallClock = true;
+            }
             // Awaited HAL wait markers become async state-machine poll states that
             // arm deadlines via currentTimeMillis().
             if (statement.callee === "__WIFI_WAIT__" || statement.callee === "__HTTP_WAIT__" || statement.callee === "__HAL_WAIT__") {
                 result.usesMillis = true;
+                result.usesWallClock = true;
+            }
+            if (statement.callee === "__tc_print" || statement.callee === "__tc_println") {
+                result.usedPolyfillHelpers.add(statement.callee);
             }
             // Namespace-qualified polyfill entry points used as bare call statements
             // (e.g. `Timing.delay(5);`). The expression-level analyzer (case
@@ -694,6 +719,9 @@ function analyzeStatement(statement, result, strategy) {
                     result.usesTiming = true;
                     result.usesMillis = true;
                 }
+                if (opName === "timing.millis" || opName === "timing.micros") {
+                    result.usesWallClock = true;
+                }
             }
             // Scan raw C++ code in HAL ops for polyfill helper usage
             if (statement.operation && statement.operation.operation === "raw" && typeof statement.operation.code === "string") {
@@ -722,6 +750,15 @@ function analyzeStatement(statement, result, strategy) {
                     result.usesTiming = true;
                     result.usesMillis = true;
                 }
+                if (/\b(millis|micros)\s*\(/.test(code)) {
+                    result.usesWallClock = true;
+                }
+                if (code.includes("__tc_println(")) {
+                    result.usedPolyfillHelpers.add("__tc_println");
+                }
+                if (code.includes("__tc_print(")) {
+                    result.usedPolyfillHelpers.add("__tc_print");
+                }
                 // Timer polyfill sizing — `Timing.setInterval(...)` / `Timing.setTimeout(...)`
                 // are resolved by the HAL method resolver, which reads TimingClass's
                 // rawCpp body and emits a raw hal-op whose code is e.g.
@@ -795,6 +832,7 @@ export function analyzeProgram(program, strategy) {
         usesStringConversion: false,
         usesDateNow: false,
         usesMillis: false,
+        usesWallClock: false,
         usesNullish: false,
         usesNullishHelper: false,
         usesNum: false,

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

@@ -3,6 +3,7 @@ import { isStringEnum } from "../api/shared/index.js";
 import { extractNodeComments, makeDiagnostic, makeSourceSpan } from "./ast-node-utils.js";
 import { isCompileTimeOnlyCallName, isCompileTimeOnlyClassName } from "./compile-time-only.js";
 import { TYPED_ARRAY_ELEMENT_MAP, hoistedNestedEnums, hoistedNestedInterfaces, hoistedNestedTypeAliases, nestedFunctionAliases, nestedClassAliases, mutableArrayVars, arrayLiteralSizes, activeEnumNames, activeStringEnumNames, resetFunctionScopeState } from "./build-ir-state.js";
+import { isPinFoldingEnabled, setPinFoldingEnabled, invalidatePinLevels } from "./pin-state-tracking.js";
 import { getCurrentIrTypeScope, bindIrTypeScopeLocals } from "./symbol-types.js";
 import { renderExprAsText } from "./render-expr.js";
 import { expressionToIR } from "./expression-to-ir.js";
@@ -177,6 +178,15 @@ export function lowerStatementList(statements, fileName, sourceText, diagnostics
     const lowered = [];
     const nestedNames = [];
     const nestedClassNames = [];
+    // Function/method bodies run at an unmodeled time relative to top-level
+    // flow, so pin-state constant folding must be off inside them (reads fall
+    // back to the shadow variable), and any writes they contain invalidate the
+    // top-level levels afterwards. "" and "<top-level>" are the top-level
+    // markers; everything else names a function/method/lambda body.
+    const isFunctionBodyCtx = functionNameForDiagnostics !== "" && functionNameForDiagnostics !== "<top-level>";
+    const prevPinFolding = isPinFoldingEnabled();
+    if (isFunctionBodyCtx)
+        setPinFoldingEnabled(false);
     // Phase 1: Pre-scan for nested function declarations — register aliases only.
     // This ensures sibling functions can reference each other.
     for (const statement of statements) {
@@ -345,5 +355,9 @@ export function lowerStatementList(statements, fileName, sourceText, diagnostics
     for (const name of nestedClassNames) {
         nestedClassAliases.delete(name);
     }
+    if (isFunctionBodyCtx) {
+        setPinFoldingEnabled(prevPinFolding);
+        invalidatePinLevels();
+    }
     return lowered;
 }

package/dist/ir/transformers/control-flow.js

@@ -6,6 +6,7 @@ import { parseCppType, renderCppType, isPointer, parsedIsVector, parsedElementSt
 import { expressionToIR } from "../expression-to-ir.js";
 import { lowerStatementList, expressionStatementToIR } from "../statement-to-ir.js";
 import { assignmentOperatorToString, updateLocalTypeFromAssignment, extractForInKeys } from "./variables.js";
+import { snapshotPinLevels, restorePinLevels, mergePinLevels, invalidatePinLevels } from "../pin-state-tracking.js";
 // Monotonic counter for synthetic for...of destructure loop variables.
 let forOfDestructureCounter = 0;
 /**
@@ -184,6 +185,9 @@ export function lowerControlFlowStatement(statement, fileName, sourceText, diagn
             }];
     }
     if (ts.isWhileStatement(statement)) {
+        // Loop conditions/bodies may evaluate any number of times, so tracked
+        // pin levels from before the loop are not valid inside it.
+        invalidatePinLevels();
         const comments = extractNodeComments(statement, sourceText);
         const bodyStatements = lowerStatementList(ts.isBlock(statement.statement) ? statement.statement.statements : [statement.statement], fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, pointerVars);
         return [{
@@ -196,12 +200,24 @@ export function lowerControlFlowStatement(statement, fileName, sourceText, diagn
             }];
     }
     if (ts.isIfStatement(statement)) {
+        // Branch merge: the level after the if must be the join of both branch
+        // ends (pins that disagree become unknown). The condition is lowered
+        // after the branches in this function but runs before them at runtime,
+        // so the pre-branch state is restored before the condition is evaluated
+        // and the merge is applied last.
+        const preBranchPinState = snapshotPinLevels();
         const comments = extractNodeComments(statement, sourceText);
         const thenStatements = lowerStatementList(ts.isBlock(statement.thenStatement) ? statement.thenStatement.statements : [statement.thenStatement], fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, pointerVars);
+        const thenBranchPinState = snapshotPinLevels();
+        // Restore the pre-branch state before lowering the else branch and the
+        // condition — both run before the branches at runtime... the condition
+        // before them, the else on the path where the then branch never ran.
+        restorePinLevels(preBranchPinState);
         let elseBranch;
         if (statement.elseStatement) {
             elseBranch = lowerStatementList(ts.isBlock(statement.elseStatement) ? statement.elseStatement.statements : [statement.elseStatement], fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, pointerVars);
         }
+        const elseBranchPinState = snapshotPinLevels();
         // Evaluate the condition. If it's a bare identifier that resolves to a
         // HAL alias (e.g. `if (bus2)` where bus2 = I2C0.take()), the alias is a
         // compile-time non-null reference — constant-fold to `true` so the emit
@@ -213,6 +229,10 @@ export function lowerControlFlowStatement(statement, fileName, sourceText, diagn
         else {
             condition = expressionToIR(statement.expression, sourceText, diagnostics, pointerVars);
         }
+        // Join the branch-end states into the live state. With no else branch,
+        // elseBranchPinState equals the pre-branch state, so pins written by the
+        // then branch invalidate unless the write agrees with the prior level.
+        mergePinLevels(thenBranchPinState, elseBranchPinState);
         return [{
                 kind: "if",
                 sourceSpan: makeSourceSpan(statement, fileName, sourceText),
@@ -235,6 +255,9 @@ export function lowerControlFlowStatement(statement, fileName, sourceText, diagn
                 initializer = loweredExpr;
             }
         }
+        // Loop conditions/bodies may evaluate any number of times, so tracked
+        // pin levels from before the loop are not valid inside it.
+        invalidatePinLevels();
         const condition = statement.condition
             ? expressionToIR(statement.condition, sourceText, diagnostics, pointerVars)
             : undefined;
@@ -362,6 +385,9 @@ export function lowerControlFlowStatement(statement, fileName, sourceText, diagn
     }
     // Handle do...while loops
     if (ts.isDoStatement(statement)) {
+        // Loop bodies may run more than once; pre-loop pin levels are not valid
+        // inside them.
+        invalidatePinLevels();
         const comments = extractNodeComments(statement, sourceText);
         const bodyStatements = lowerStatementList(ts.isBlock(statement.statement) ? statement.statement.statements : [statement.statement], fileName, sourceText, diagnostics, functionReturnTypes, localVariableTypes, functionNameForDiagnostics, typeAliases, pointerVars);
         return [{
@@ -375,6 +401,9 @@ export function lowerControlFlowStatement(statement, fileName, sourceText, diagn
     }
     // Handle switch statements
     if (ts.isSwitchStatement(statement)) {
+        // Exactly one case runs at runtime, but all are lowered here; pin levels
+        // from case bodies must not leak past the switch.
+        invalidatePinLevels();
         const comments = extractNodeComments(statement, sourceText);
         const cases = [];
         for (const clause of statement.caseBlock.clauses) {

package/dist/ir/transformers/ui-call-resolver.js

@@ -9,7 +9,7 @@
 // and is invoked from call-statement.ts after tryResolveHALMethod.
 // ---------------------------------------------------------------------------
 import ts from "typescript";
-import { makeSourceSpan } from "../ast-node-utils.js";
+import { makeDiagnostic, makeSourceSpan } from "../ast-node-utils.js";
 import { halOpsToIR } from "./hal-emit-helpers.js";
 import { resolveMount } from "./ui-mount.js";
 import { emitSignalDecl, recordListBinding, getListBindingsCount, recordInputBinding, getInputBindingsCount, resetInputBindings } from "./ui-reactive.js";
@@ -184,6 +184,79 @@ function matchUIWindowCall(call) {
         return undefined;
     return call.expression.name.text;
 }
+/** Detect `ui.drawer.<method>(...)` — same shape as ui.window. Returns the
+ *  method name ("open" / "close") or undefined. */
+function matchUIDrawerCall(call) {
+    if (!ts.isPropertyAccessExpression(call.expression))
+        return undefined;
+    const inner = call.expression.expression;
+    if (!ts.isPropertyAccessExpression(inner))
+        return undefined;
+    if (!ts.isIdentifier(inner.expression) || inner.expression.text !== "ui")
+        return undefined;
+    if (!ts.isIdentifier(inner.name) || inner.name.text !== "drawer")
+        return undefined;
+    return call.expression.name.text;
+}
+/** Detect ui.dialog.<method>(...) — same shape, resolves <dialog> ids. */
+function matchUIDialogCall(call) {
+    if (!ts.isPropertyAccessExpression(call.expression))
+        return undefined;
+    const inner = call.expression.expression;
+    if (!ts.isPropertyAccessExpression(inner))
+        return undefined;
+    if (!ts.isIdentifier(inner.expression) || inner.expression.text !== "ui")
+        return undefined;
+    if (!ts.isIdentifier(inner.name) || inner.name.text !== "dialog")
+        return undefined;
+    return call.expression.name.text;
+}
+/** Detect ui.toast('<id>') — show a <toast>; auto-closes via duration. */
+function matchUIToastCall(call) {
+    if (!ts.isPropertyAccessExpression(call.expression))
+        return false;
+    const inner = call.expression.expression;
+    if (!ts.isIdentifier(inner) || inner.text !== "ui")
+        return false;
+    return ts.isIdentifier(call.expression.name) && call.expression.name.text === "toast";
+}
+/** Resolve ui.drawer.open('<id>') / ui.drawer.close('<id>' | ), and the
+ *  dialog/toast aliases. The id resolves at BUILD time to the node index of
+ *  the <drawer>/<dialog>/<toast> element, emitting ui_drawer_open(N) /
+ *  ui_drawer_close(N) (or close_all with no argument) — the preview
+ *  evaluates the same call dynamically. */
+function resolveDrawerCall(method, call, sourceText, diagnostics, kind = "drawer") {
+    const sourceSpan = makeSourceSpan(call, call.getSourceFile()?.fileName ?? "", sourceText);
+    if (method !== "open" && method !== "close") {
+        diagnostics.push(makeDiagnostic(sourceText, call.pos, `ui.${kind}.${method} is not supported — use open(id) or close(id?).`, "error", "UI_DRAWER_METHOD"));
+        return { kind: "block", sourceSpan, body: [] };
+    }
+    const arg = call.arguments[0];
+    const emit = (stmt) => ({
+        kind: "call",
+        callee: "__EMIT__",
+        args: [{ kind: "string", value: stmt }],
+        sourceSpan,
+    });
+    // close() with no id closes every open drawer.
+    if (method === "close" && arg === undefined)
+        return emit("ui_drawer_close_all();");
+    let idText;
+    if (arg && ts.isStringLiteral(arg))
+        idText = arg.text;
+    if (idText === undefined) {
+        diagnostics.push(makeDiagnostic(sourceText, call.pos, `ui.${kind}.${method} needs an id string literal (e.g. ui.${kind}.open('settings')).`, "error", "UI_DRAWER_ID"));
+        return { kind: "block", sourceSpan, body: [] };
+    }
+    const nodeIdx = resolveElementValue("screen", idText);
+    if (nodeIdx === undefined) {
+        diagnostics.push(makeDiagnostic(sourceText, call.pos, `ui.${kind}.${method}('${idText}'): no <${kind} id="${idText}"> in the mounted UI tree.`, "error", "UI_DRAWER_UNKNOWN_ID"));
+        return { kind: "block", sourceSpan, body: [] };
+    }
+    return emit(method === "open"
+        ? `ui_drawer_open(${nodeIdx});`
+        : `ui_drawer_close(${nodeIdx});`);
+}
 /** Resolve ui.window.setTitle / ui.window.setIcon. Native SDL only; on hardware
  *  these are silent no-ops (a desktop-only convenience, not an error). */
 function resolveWindowCall(method, call, sourceText, diagnostics) {
@@ -308,6 +381,37 @@ export function tryResolveUICall(call, fileName, sourceText, diagnostics, option
     const windowCall = matchUIWindowCall(call);
     if (windowCall)
         return resolveWindowCall(windowCall, call, sourceText, diagnostics);
+    // ui.drawer.open('id') / ui.drawer.close('id'|) — also a two-level chain.
+    const drawerCall = matchUIDrawerCall(call);
+    if (drawerCall)
+        return resolveDrawerCall(drawerCall, call, sourceText, diagnostics);
+    const dialogCall = matchUIDialogCall(call);
+    if (dialogCall)
+        return resolveDrawerCall(dialogCall, call, sourceText, diagnostics, "dialog");
+    if (matchUIToastCall(call)) {
+        // ui.toast('<id>') — show a <toast>; the duration attribute drives the
+        // auto-close. Same open lowering as a drawer.
+        const sourceSpan = makeSourceSpan(call, call.getSourceFile()?.fileName ?? "", sourceText);
+        const arg = call.arguments[0];
+        let idText;
+        if (arg && ts.isStringLiteral(arg))
+            idText = arg.text;
+        if (idText === undefined) {
+            diagnostics.push(makeDiagnostic(sourceText, call.pos, "ui.toast needs a toast id string literal (e.g. ui.toast('saved')).", "error", "UI_TOAST_ID"));
+            return { kind: "block", sourceSpan, body: [] };
+        }
+        const nodeIdx = resolveElementValue("screen", idText);
+        if (nodeIdx === undefined) {
+            diagnostics.push(makeDiagnostic(sourceText, call.pos, `ui.toast('${idText}'): no <toast id="${idText}"> in the mounted UI tree.`, "error", "UI_TOAST_UNKNOWN_ID"));
+            return { kind: "block", sourceSpan, body: [] };
+        }
+        return {
+            kind: "call",
+            sourceSpan,
+            callee: "__EMIT__",
+            args: [{ kind: "string", value: `ui_drawer_open(${nodeIdx});` }],
+        };
+    }
     if (!isUICall(call))
         return null;
     const method = call.expression.name.text;

package/dist/ir/ui-element-auto-wire.js

@@ -99,12 +99,13 @@ function autoWireNode(treeName, node, nodeIndex) {
                 fnName: `__ui_bindval_${nodeIndex}`,
                 cppExpr: sig,
             });
-            // Write: range drag / check toggle → signal.set(value).
+            // Write: range drag / check toggle → plain assignment (signals lower
+            // to plain device variables; .set() is author-facing syntax only).
             recordClickHandler({
                 nodeIndex,
                 kind: node.tag === "check" ? "click" : "rangechange",
                 fnName: `__ui_bindval_cb_${nodeIndex}`,
-                callbackBody: `${sig}.set(__ui_nodes[${nodeIndex}].value);`,
+                callbackBody: `${sig} = __ui_nodes[${nodeIndex}].value;`,
             });
         }
     }
@@ -149,12 +150,14 @@ function autoWireNode(treeName, node, nodeIndex) {
             ? node.options.map(o => o.text)
             : (node.text || "").split(",").map(s => s.trim()).filter(Boolean);
         const count = Math.max(options.length, 2);
-        // Auto-wire: onClick cycles value 0..count-1
+        // Auto-wire: onClick opens the modal option list (ui_select_menu_open);
+        // tapping a row in the modal sets the value. Preview parity: the preview
+        // runtime opens its own overlay on tap instead of cycling.
         recordClickHandler({
             nodeIndex,
             kind: "click",
             fnName: `__ui_${node.id}_autoclick`,
-            callbackBody: `__ui_nodes[${nodeIndex}].value = (__ui_nodes[${nodeIndex}].value + 1) % ${count};`,
+            callbackBody: `ui_select_menu_open(${nodeIndex});`,
         });
         // Auto-bind text to show the current option via snprintf if/else chain.
         // Cast size to size_t to satisfy -Wformat (snprintf's n param is size_t;

package/dist/orchestrator/graph-builder.d.ts

@@ -15,4 +15,7 @@ export declare function topologicalSortFiles(files: string[], dependencies: Map<
  * @param boardPackage  When provided, `@typecad/board` imports resolve to this
  *                      board package (e.g. `'@typecad/board-arduino-uno'`).
  */
-export declare function collectTranspileGraph(entryFile: string, boardPackage?: string): TranspileGraphResult;
+export declare function collectTranspileGraph(entryFile: string, boardPackage?: string, imageDecodeOpts?: {
+    maxW?: number;
+    maxH?: number;
+}): Promise<TranspileGraphResult>;

package/dist/orchestrator/graph-builder.js

@@ -68,7 +68,7 @@ export function topologicalSortFiles(files, dependencies) {
  * @param boardPackage  When provided, `@typecad/board` imports resolve to this
  *                      board package (e.g. `'@typecad/board-arduino-uno'`).
  */
-export function collectTranspileGraph(entryFile, boardPackage) {
+export async function collectTranspileGraph(entryFile, boardPackage, imageDecodeOpts) {
     const ordered = [];
     const pending = [path.resolve(entryFile)];
     const visited = new Set();
@@ -102,6 +102,10 @@ export function collectTranspileGraph(entryFile, boardPackage) {
             const parts = ui.splitUiFile(sourceText);
             // Register the template as a UI module at <file>.ui.html (synthetic path).
             const uiHtmlPath = filePath + ".html";
+            // Prime the image-conversion cache before the (synchronous) module
+            // load — <img src="*.png|jpg|ico|…"> decodes here, and the module's
+            // asset reader + natural-size layout pull from the cache.
+            await ui.warmUpImageDecoding(parts.html, path.dirname(filePath), imageDecodeOpts ?? {});
             ui.loadUIModuleFromText(uiHtmlPath, parts.html, parts.style, filePath);
             uiModules.add(uiHtmlPath);
             // Use the <script> as the TS source for import-graph walking. Inject an
@@ -189,6 +193,8 @@ export function collectTranspileGraph(entryFile, boardPackage) {
             // .ui.html modules: load into the UI registry, record the path, and don't
             // push onto `pending` (they are never parsed as TypeScript).
             if (resolved?.uiModule) {
+                const uiHtmlText = readText(resolved.sourcePath);
+                await requireUIHook().warmUpImageDecoding(uiHtmlText, path.dirname(resolved.sourcePath), imageDecodeOpts ?? {});
                 requireUIHook().loadUIModule(resolved.sourcePath);
                 uiModules.add(resolved.sourcePath);
                 // Track the dependency edge so topological sort orders the importer

package/dist/preview/api-shared-shim.d.ts

@@ -0,0 +1 @@
+export { resolveScrollConfig } from "../api/shared/display-profile.js";