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

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

@@ -210,6 +210,30 @@ export function loadHALModules(force = false) {
 export function getCtorIncludes(className) {
     return halCtorIncludes.get(className) ?? [];
 }
+/** Map an HttpClass factory method name to its HTTP verb, or null. */
+export function httpFactoryVerb(methodName) {
+    switch (methodName) {
+        case "get": return "GET";
+        case "post": return "POST";
+        case "put": return "PUT";
+        case "del": return "DELETE";
+        case "head": return "HEAD";
+        case "patch": return "PATCH";
+        default: return null;
+    }
+}
+/** Render an Http factory URL argument as C++ expression text (string
+ *  literals quoted, identifiers/member accesses verbatim), or null when the
+ *  argument shape can't be resolved at compile time. */
+export function httpUrlArgText(arg) {
+    if (ts.isStringLiteral(arg) || ts.isNoSubstitutionTemplateLiteral(arg))
+        return JSON.stringify(arg.text);
+    if (ts.isIdentifier(arg))
+        return arg.text;
+    if (ts.isPropertyAccessExpression(arg))
+        return arg.getText();
+    return null;
+}
 /** Resolve a call receiver to a tracked HAL instance. */
 export function resolveHALReceiver(receiver) {
     const result = (() => {
@@ -336,6 +360,51 @@ export function resolveHALReceiver(receiver) {
                         return { className: "ToneChain", fieldValues };
                     }
                 }
+                // Specialized handling for Http factory chaining
+                // (Http.get(url).header(...).send()): the factory records the HTTP
+                // verb and URL into the HttpRequest instance so send() can resolve
+                // this._method / this._url.
+                if (innerInstance.className === "HttpClass") {
+                    const verb = httpFactoryVerb(methodName);
+                    if (verb && receiver.arguments.length > 0) {
+                        const urlText = httpUrlArgText(receiver.arguments[0]);
+                        if (urlText) {
+                            return {
+                                className: "HttpRequest",
+                                fieldValues: new Map([["_method", verb], ["_url", urlText]]),
+                            };
+                        }
+                    }
+                }
+                // Specialized handling for BLE factory chaining
+                // (Ble.server(name).characteristic(uuid,type,perms).onRead(handler)):
+                // server() creates a BleServer with _name, _charCount from a global
+                // counter (persists across separate server() calls so multi-char
+                // servers get unique indices), _svcCount=1.
+                // characteristic() reads _charCount for the add_char call,
+                // then sets _lastChar=_charCount and increments _charCount so the next
+                // characteristic gets the next slot. onRead/onWrite read _lastChar.
+                if (innerInstance.className === "BleClass" && methodName === "server" && receiver.arguments.length > 0) {
+                    const nameText = httpUrlArgText(receiver.arguments[0]);
+                    if (nameText) {
+                        return {
+                            className: "BleServer",
+                            fieldValues: new Map([["_name", nameText], ["_charCount", "0"], ["_lastChar", "0"], ["_svcCount", "1"]]),
+                        };
+                    }
+                }
+                if (innerInstance.className === "BleServer" && methodName === "characteristic") {
+                    // characteristic(uuid, type, perms) returns this (BleServer).
+                    // The C++ shim auto-assigns the char index at runtime via
+                    // __tc_ble.current_char, so the resolver doesn't need to track indices.
+                    return innerInstance;
+                }
+                if (innerInstance.className === "BleServer" && methodName === "service") {
+                    // service() returns this (BleServer); advance the service counter.
+                    const svc = Number(innerInstance.fieldValues.get("_svcCount") ?? "1") + 1;
+                    innerInstance.fieldValues.set("_svcCount", String(svc));
+                    return innerInstance;
+                }
                 // General fallback: if the method is known to return another HAL class, carry over fields
                 const classEntry = halClassRegistry.get(innerInstance.className);
                 const methodEntry = classEntry?.methods.get(methodName);
@@ -345,6 +414,11 @@ export function resolveHALReceiver(receiver) {
                         return { className: returnClassName, fieldValues: new Map(innerInstance.fieldValues) };
                     }
                 }
+                // Fluent `this`-returning methods (e.g. HttpRequest.header/timeout):
+                // the chain result is the same instance, so keep resolving through it.
+                if (methodEntry && methodEntry.methodNode.type && methodEntry.methodNode.type.kind === ts.SyntaxKind.ThisType) {
+                    return innerInstance;
+                }
             }
         }
         // Inline new expression: new Pin(x).method()

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

@@ -105,6 +105,44 @@ function resolveNumericOrExpression(args, idx, instance, paramNames, callArgText
         return num;
     return resolveSemanticArg(args, idx, instance, paramNames, callArgTexts, paramDefaults);
 }
+/** Normalize an optional resolved arg: an omitted optional parameter with no
+ *  default resolves to the literal text "undefined" (see resolveExpressionText);
+ *  map that to null so op builders can omit the field entirely. */
+function dropUndefined(value) {
+    return value === "undefined" ? null : value;
+}
+/** Quote a resolved string value unless it is already a quoted literal or a
+ *  plain identifier / member-access expression (i.e. a runtime variable). */
+function quoteNonIdentifier(value) {
+    const t = value.trim();
+    if (/^".*"$/.test(t))
+        return t;
+    if (/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(t))
+        return t;
+    return JSON.stringify(t);
+}
+/** Resolve a BlePerm expression to its numeric bitmask.
+ *  Handles: plain numbers (3), "BlePerm.Read", "BlePerm.Read | BlePerm.Notify". */
+const BLE_PERM_VALUES = {
+    Read: 1, Write: 2, Notify: 4,
+};
+function resolveBlePermExpr(raw) {
+    if (raw === null)
+        return 0;
+    const s = String(raw).trim();
+    if (/^\d+$/.test(s))
+        return Number(s);
+    // Extract all BlePerm.X member names and sum their values.
+    let sum = 0;
+    const re = /BlePerm\.(\w+)/g;
+    let m;
+    let matched = false;
+    while ((m = re.exec(s)) !== null) {
+        matched = true;
+        sum += BLE_PERM_VALUES[m[1]] ?? 0;
+    }
+    return matched ? sum : 0;
+}
 /** Extract the MCU port name from the current HAL instance, if available. */
 export function portFromInstance(instance) {
     const port = instance.fieldValues.get('_port');
@@ -312,6 +350,101 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
                 return null;
             return { operation: "pwm.write", port, pin, duty };
         }
+        // ── RMT ──
+        // rmtTxInit/rmtRxInit are POSITIONAL semantic primitives (the ergonomic
+        // opts-object form lives in hal/rmt.ts's RmtChannel class, which
+        // destructures opts and forwards positionally). The resolver dispatches on
+        // the literal callee name, so rmt.ts must call these by their real names
+        // (no `as _rmtTxInit` aliasing — that breaks the switch).
+        //   rmtTxInit(pin, resolutionHz, bit0Hi, bit0Lo, bit1Hi, bit1Lo, msbFirst, queueDepth)
+        case "rmtTxInit": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const resolutionHz = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            const bit0Hi = resolveNumericOrExpression(args, 2, instance, paramNames, callArgTexts, paramDefaults);
+            const bit0Lo = resolveNumericOrExpression(args, 3, instance, paramNames, callArgTexts, paramDefaults);
+            const bit1Hi = resolveNumericOrExpression(args, 4, instance, paramNames, callArgTexts, paramDefaults);
+            const bit1Lo = resolveNumericOrExpression(args, 5, instance, paramNames, callArgTexts, paramDefaults);
+            const msbFirst = resolveSemanticArg(args, 6, instance, paramNames, callArgTexts, paramDefaults);
+            const queueDepth = resolveNumericOrExpression(args, 7, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null || resolutionHz === null)
+                return null;
+            const op = { operation: "rmt.tx_init", port, pin, resolutionHz, bit0Hi, bit0Lo, bit1Hi, bit1Lo };
+            if (queueDepth !== null)
+                op.queueDepth = queueDepth;
+            if (msbFirst !== null)
+                op.msbFirst = msbFirst;
+            return op;
+        }
+        case "rmtTxWriteBytes": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            // bytes is an array literal — resolveSemanticArg renders it positionally as "1, 2, 3".
+            const bytes = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null || bytes === null)
+                return null;
+            return { operation: "rmt.tx_write_bytes", port, pin, bytes };
+        }
+        case "rmtTxWriteSymbols": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const symbols = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null || symbols === null)
+                return null;
+            return { operation: "rmt.tx_write_symbols", port, pin, symbols };
+        }
+        case "rmtTxWaitDone": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const timeoutMs = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null)
+                return null;
+            const op = { operation: "rmt.tx_wait_done", port, pin };
+            if (timeoutMs !== null)
+                op.timeoutMs = timeoutMs;
+            return op;
+        }
+        case "rmtTxDeinit": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null)
+                return null;
+            return { operation: "rmt.tx_deinit", port, pin };
+        }
+        case "rmtRxInit": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const resolutionHz = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null || resolutionHz === null)
+                return null;
+            return { operation: "rmt.rx_init", port, pin, resolutionHz };
+        }
+        case "rmtRxOnReceived": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const handler = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null || handler === null)
+                return null;
+            return { operation: "rmt.rx_on_received", port, pin, handler };
+        }
+        case "rmtRxStart": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null)
+                return null;
+            return { operation: "rmt.rx_start", port, pin };
+        }
+        case "rmtRxStop": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null)
+                return null;
+            return { operation: "rmt.rx_stop", port, pin };
+        }
+        case "rmtRxRead": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const maxCount = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null || maxCount === null)
+                return null;
+            return { operation: "rmt.rx_read", port, pin, maxCount };
+        }
+        case "rmtRxDeinit": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null)
+                return null;
+            return { operation: "rmt.rx_deinit", port, pin };
+        }
         // ── ADC ──
         case "adcRead": {
             const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
@@ -383,6 +516,434 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
                 return null;
             return { operation: "power.set_cpu_frequency", mhz };
         }
+        case "powerDeepSleepPin": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const level = resolveNumericArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null || level === null)
+                return null;
+            return { operation: "power.deep_sleep_pin", pin, level };
+        }
+        // ── WiFi ──
+        // Optional string args (password, dns) resolve to the text "undefined"
+        // when omitted at the call site (no default in the HAL signature). Treat
+        // that as absent so the backend emits its own default ("").
+        case "wifiConnect": {
+            const ssid = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const password = dropUndefined(resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults));
+            const timeoutMs = resolveSemanticArg(args, 2, instance, paramNames, callArgTexts, paramDefaults) ?? 15000;
+            if (ssid === null)
+                return null;
+            return {
+                operation: "wifi.connect",
+                ssid,
+                ...(password !== null ? { password } : {}),
+                timeoutMs,
+                blocking: true,
+            };
+        }
+        case "wifiConnectStart": {
+            const ssid = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const password = dropUndefined(resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults));
+            if (ssid === null)
+                return null;
+            return { operation: "wifi.connect_start", ssid, ...(password !== null ? { password } : {}) };
+        }
+        case "wifiDisconnect":
+            return { operation: "wifi.disconnect" };
+        case "wifiStatus":
+            return { operation: "wifi.status" };
+        case "wifiIsConnected":
+            return { operation: "wifi.is_connected" };
+        case "wifiLocalIp":
+            return { operation: "wifi.local_ip" };
+        case "wifiRssi":
+            return { operation: "wifi.rssi" };
+        case "wifiMac":
+            return { operation: "wifi.mac" };
+        case "wifiSetHostname": {
+            const name = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (name === null)
+                return null;
+            return { operation: "wifi.set_hostname", name };
+        }
+        case "wifiSetStaticIp": {
+            const ip = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const gateway = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            const subnet = resolveSemanticArg(args, 2, instance, paramNames, callArgTexts, paramDefaults);
+            const dns = dropUndefined(resolveSemanticArg(args, 3, instance, paramNames, callArgTexts, paramDefaults));
+            if (ip === null || gateway === null || subnet === null)
+                return null;
+            return { operation: "wifi.set_static_ip", ip, gateway, subnet, ...(dns !== null ? { dns } : {}) };
+        }
+        case "wifiSetAutoReconnect": {
+            const enabled = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (enabled === null)
+                return null;
+            return { operation: "wifi.set_auto_reconnect", enabled: enabled === "true" };
+        }
+        case "wifiSetPowerSave": {
+            const mode = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (mode === null)
+                return null;
+            return { operation: "wifi.set_power_save", mode };
+        }
+        case "wifiSetTxPower": {
+            const dbm = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (dbm === null)
+                return null;
+            return { operation: "wifi.set_tx_power", dbm };
+        }
+        case "wifiOnEvent": {
+            const event = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const handler = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (event === null || handler === null)
+                return null;
+            return { operation: "wifi.on_event", event: String(event).replace(/^["']|["']$/g, ""), handler };
+        }
+        case "wifiApStart": {
+            const ssid = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const password = dropUndefined(resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults));
+            const channel = dropUndefined(resolveSemanticArg(args, 2, instance, paramNames, callArgTexts, paramDefaults));
+            const hidden = dropUndefined(resolveSemanticArg(args, 3, instance, paramNames, callArgTexts, paramDefaults));
+            const maxClients = dropUndefined(resolveSemanticArg(args, 4, instance, paramNames, callArgTexts, paramDefaults));
+            if (ssid === null)
+                return null;
+            return {
+                operation: "wifi.ap_start",
+                ssid,
+                ...(password !== null ? { password } : {}),
+                ...(channel !== null ? { channel } : {}),
+                ...(hidden !== null ? { hidden } : {}),
+                ...(maxClients !== null ? { maxClients } : {}),
+            };
+        }
+        case "wifiApStop":
+            return { operation: "wifi.ap_stop" };
+        case "wifiApClientCount":
+            return { operation: "wifi.ap_client_count" };
+        case "wifiApIp":
+            return { operation: "wifi.ap_ip" };
+        case "wifiApSetChannel": {
+            const channel = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (channel === null)
+                return null;
+            return { operation: "wifi.ap_set_channel", channel };
+        }
+        case "wifiApSetHidden": {
+            const hidden = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (hidden === null)
+                return null;
+            return { operation: "wifi.ap_set_hidden", hidden };
+        }
+        case "wifiApSetMaxClients": {
+            const maxClients = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (maxClients === null)
+                return null;
+            return { operation: "wifi.ap_set_max_clients", maxClients };
+        }
+        case "wifiScan":
+            return { operation: "wifi.scan" };
+        case "wifiScanStart":
+            return { operation: "wifi.scan_start" };
+        case "wifiScanCount":
+            return { operation: "wifi.scan_count" };
+        case "wifiScanSsid": {
+            const index = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (index === null)
+                return null;
+            return { operation: "wifi.scan_ssid", index };
+        }
+        case "wifiScanRssi": {
+            const index = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (index === null)
+                return null;
+            return { operation: "wifi.scan_rssi", index };
+        }
+        case "wifiScanEncryption": {
+            const index = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (index === null)
+                return null;
+            return { operation: "wifi.scan_encryption", index };
+        }
+        case "wifiScanChannel": {
+            const index = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (index === null)
+                return null;
+            return { operation: "wifi.scan_channel", index };
+        }
+        case "wifiSaveCredentials": {
+            const ssid = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const password = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (ssid === null || password === null)
+                return null;
+            return { operation: "wifi.save_credentials", ssid, password };
+        }
+        case "wifiConnectSaved": {
+            const timeoutMs = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults) ?? 15000;
+            return { operation: "wifi.connect_saved", timeoutMs };
+        }
+        case "wifiClearCredentials":
+            return { operation: "wifi.clear_credentials" };
+        case "wifiWaitConnected": {
+            const timeoutMs = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults) ?? 15000;
+            return { operation: "wifi.wait_connected", timeoutMs };
+        }
+        case "wifiWaitDisconnected":
+            return { operation: "wifi.wait_disconnected" };
+        // ── HTTP ──
+        case "httpBegin": {
+            const method = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const url = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (method === null || url === null)
+                return null;
+            // this._url resolved through `new HttpRequest(...)` ctor fields stores
+            // string literals without quotes; re-quote anything that isn't already
+            // a quoted literal or a plain identifier/member expression so the
+            // lowering emits valid C++.
+            return { operation: "http.begin", method, url: quoteNonIdentifier(url) };
+        }
+        case "httpReset":
+            return { operation: "http.reset" };
+        case "httpSetHeader": {
+            const name = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const value = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (name === null || value === null)
+                return null;
+            return { operation: "http.set_header", name, value };
+        }
+        case "httpSetTimeout": {
+            const ms = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (ms === null)
+                return null;
+            return { operation: "http.set_timeout", ms };
+        }
+        case "httpSetMaxBody": {
+            const bytes = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (bytes === null)
+                return null;
+            return { operation: "http.set_max_body", bytes };
+        }
+        case "httpSetBody": {
+            const data = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const json = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (data === null)
+                return null;
+            return { operation: "http.set_body", data, json: json === "true" };
+        }
+        case "httpSetInsecure":
+            return { operation: "http.set_insecure" };
+        case "httpSetCaCert": {
+            const pem = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (pem === null)
+                return null;
+            return { operation: "http.set_ca_cert", pem };
+        }
+        case "httpSend":
+            return { operation: "http.send", blocking: true };
+        case "httpSendStart":
+            return { operation: "http.send_start" };
+        case "httpStatus":
+            return { operation: "http.status" };
+        case "httpOk":
+            return { operation: "http.ok" };
+        case "httpBody":
+            return { operation: "http.body" };
+        case "httpContentLength":
+            return { operation: "http.content_length" };
+        case "httpResponseHeader": {
+            const name = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (name === null)
+                return null;
+            return { operation: "http.response_header", name };
+        }
+        // ── BLE (NimBLE GATT peripheral) ──
+        case "bleServerBegin": {
+            const name = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (name === null)
+                return null;
+            return { operation: "ble.server_begin", name: quoteNonIdentifier(name) };
+        }
+        case "bleAdvertiseStart":
+            return { operation: "ble.advertise_start" };
+        case "bleAdvertiseStop":
+            return { operation: "ble.advertise_stop" };
+        case "bleAddService": {
+            const uuid = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (uuid === null)
+                return null;
+            return { operation: "ble.add_service", uuid: quoteNonIdentifier(uuid) };
+        }
+        case "bleAddChar": {
+            const index = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const uuid = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            const type = resolveSemanticArg(args, 2, instance, paramNames, callArgTexts, paramDefaults);
+            const perms = resolveNumericOrExpression(args, 3, instance, paramNames, callArgTexts, paramDefaults);
+            const svcIndex = resolveNumericOrExpression(args, 4, instance, paramNames, callArgTexts, paramDefaults);
+            if (uuid === null || type === null)
+                return null;
+            // Resolve BleValueType.X → the enum's string value (e.g. Int16 → 'int16').
+            const resolvedType = type.startsWith("BleValueType.")
+                ? JSON.stringify(type.replace(/^BleValueType\./, "").toLowerCase())
+                : quoteNonIdentifier(type);
+            // Resolve BlePerm.X | BlePerm.Y → numeric bitmask.
+            // The | expression renders as "BlePerm.Read | BlePerm.Notify" via the
+            // binary-expression handler in resolveExpressionText, which keeps the
+            // raw text. Evaluate it by extracting member names and mapping to values.
+            const resolvedPerms = resolveBlePermExpr(perms);
+            return {
+                operation: "ble.add_char",
+                index: index ?? 0,
+                uuid: quoteNonIdentifier(uuid),
+                type: resolvedType,
+                perms: resolvedPerms,
+                svcIndex: svcIndex ?? 0,
+            };
+        }
+        case "bleOnRead": {
+            const index = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const handler = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (handler === null)
+                return null;
+            return { operation: "ble.on_read", index: index ?? 0, handler };
+        }
+        case "bleOnWrite": {
+            const index = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const handler = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (handler === null)
+                return null;
+            return { operation: "ble.on_write", index: index ?? 0, handler };
+        }
+        case "bleOnConnect": {
+            const handler = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (handler === null)
+                return null;
+            return { operation: "ble.on_connect", handler };
+        }
+        case "bleOnDisconnect": {
+            const handler = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (handler === null)
+                return null;
+            return { operation: "ble.on_disconnect", handler };
+        }
+        case "bleNotify": {
+            const index = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const value = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (value === null)
+                return null;
+            return { operation: "ble.notify", index: index ?? 0, value };
+        }
+        case "bleIsConnected":
+            return { operation: "ble.is_connected" };
+        case "bleClientCount":
+            return { operation: "ble.client_count" };
+        case "bleStatus":
+            return { operation: "ble.status" };
+        case "bleSetName": {
+            const name = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (name === null)
+                return null;
+            return { operation: "ble.set_name", name: quoteNonIdentifier(name) };
+        }
+        case "bleUntilConnected": {
+            const timeoutMs = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults) ?? 0;
+            return { operation: "ble.until_connected", timeoutMs, blocking: true };
+        }
+        case "bleUntilConnectedStart":
+            return { operation: "ble.until_connected_start" };
+        case "bleSetTxPower": {
+            const dbm = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (dbm === null)
+                return null;
+            return { operation: "ble.set_tx_power", dbm };
+        }
+        // ── Preferences (NVS key/value store) ──
+        case "preferencesBegin": {
+            const ns = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const ro = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (ns === null)
+                return null;
+            return { operation: "preferences.begin", namespace: quoteNonIdentifier(ns), readOnly: ro === "true" };
+        }
+        case "preferencesEnd":
+            return { operation: "preferences.end" };
+        case "preferencesClear":
+            return { operation: "preferences.clear" };
+        case "preferencesRemove": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (key === null)
+                return null;
+            return { operation: "preferences.remove", key: quoteNonIdentifier(key) };
+        }
+        case "preferencesPutInt": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const value = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (key === null || value === null)
+                return null;
+            return { operation: "preferences.put_int", key: quoteNonIdentifier(key), value };
+        }
+        case "preferencesGetInt": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const def = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults) ?? 0;
+            if (key === null)
+                return null;
+            return { operation: "preferences.get_int", key: quoteNonIdentifier(key), defaultValue: def };
+        }
+        case "preferencesPutUInt": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const value = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (key === null || value === null)
+                return null;
+            return { operation: "preferences.put_uint", key: quoteNonIdentifier(key), value };
+        }
+        case "preferencesGetUInt": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const def = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults) ?? 0;
+            if (key === null)
+                return null;
+            return { operation: "preferences.get_uint", key: quoteNonIdentifier(key), defaultValue: def };
+        }
+        case "preferencesPutBool": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const value = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (key === null || value === null)
+                return null;
+            return { operation: "preferences.put_bool", key: quoteNonIdentifier(key), value: value === "true" };
+        }
+        case "preferencesGetBool": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const def = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (key === null)
+                return null;
+            return { operation: "preferences.get_bool", key: quoteNonIdentifier(key), defaultValue: def === "true" };
+        }
+        case "preferencesPutFloat": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const value = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (key === null || value === null)
+                return null;
+            return { operation: "preferences.put_float", key: quoteNonIdentifier(key), value };
+        }
+        case "preferencesGetFloat": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const def = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults) ?? 0;
+            if (key === null)
+                return null;
+            return { operation: "preferences.get_float", key: quoteNonIdentifier(key), defaultValue: def };
+        }
+        case "preferencesPutString": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const value = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (key === null || value === null)
+                return null;
+            return { operation: "preferences.put_string", key: quoteNonIdentifier(key), value: quoteNonIdentifier(value) };
+        }
+        case "preferencesGetString": {
+            const key = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const def = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults) ?? '""';
+            if (key === null)
+                return null;
+            return { operation: "preferences.get_string", key: quoteNonIdentifier(key), defaultValue: quoteNonIdentifier(def) };
+        }
         // ── Interrupts ──
         case "interruptAttach": {
             const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);