@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.10

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

@@ -1,7 +1,8 @@
 import ts from "typescript";
-import { getCurrentBoardConstants, halInstances } from "../build-ir-state.js";
+import { getCurrentBoardConstants, halInstances, getContext } from "../build-ir-state.js";
 import { resolveExpressionText } from "./hal-emitter.js";
 import { renderExprAsText } from "../render-expr.js";
+import { hasSafetyHook, requireSafetyHook } from "../../safety-hook.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
@@ -105,6 +106,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');
@@ -265,6 +304,17 @@ export function tryResolveCompoundSemanticReturn(expr, instance, paramNames, cal
  * Returns the HALOpIR if the function name is recognized, or null.
  */
 export function tryResolveSemanticCall(fnName, args, instance, paramNames, callArgTexts, paramDefaults, callArgs) {
+    // ── Safety (@typecad/safety — safe.read) ────────────────────────────────
+    // The safety package owns lowering for `safe.*` callees (v2: only safe.read;
+    // safe.pinMode was removed — mode config is the HAL's job via Pin.asInput()
+    // etc.). Check the hook before the switch so safety calls never fall
+    // through to GPIO/etc. hasSafetyHook() guards the call site (no-op when
+    // @typecad/safety absent).
+    if (hasSafetyHook()) {
+        const op = requireSafetyHook().resolveSemanticCall?.(fnName, callArgs ?? []);
+        if (op)
+            return op;
+    }
     // Extract MCU port name from instance (set by Pin.fromPort())
     const port = portFromInstance(instance);
     switch (fnName) {
@@ -312,6 +362,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 +528,583 @@ 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": {
+            // The characteristic index is assigned HERE from a per-file counter, not
+            // resolved from `this._charCount`. resolveHALReceiver re-resolves the
+            // receiver (Ble.server(name)) freshly for each chain level when emitting,
+            // so a value stamped onto the instance field in the resolver would be
+            // dropped — leaving every characteristic on slot 0, clobbering the
+            // previous on_read/on_write handler. Consuming the counter at the single
+            // emit site (this plugin, called once per characteristic in declaration
+            // order) makes indices sequential (0,1,2,…) and stable. The counter is
+            // per-file (reset in resetHALResolver). onRead/onWrite/onConnect don't
+            // need a compile-time index — the C++ shim keys them off
+            // __tc_ble.current_char, which __tc_ble_add_char sets at runtime from
+            // this index.
+            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: getContext().bleCharCounter++,
+                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) };
+        }
+        // ── FS (filesystem) ──
+        case "fsBegin":
+            return { operation: "fs.begin" };
+        case "fsReadText": {
+            const path = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (path === null)
+                return null;
+            return { operation: "fs.read_text", path };
+        }
+        case "fsWriteText": {
+            const path = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const content = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (path === null || content === null)
+                return null;
+            return { operation: "fs.write_text", path, content };
+        }
+        case "fsExists": {
+            const path = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (path === null)
+                return null;
+            return { operation: "fs.exists", path };
+        }
+        case "fsRemove": {
+            const path = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (path === null)
+                return null;
+            return { operation: "fs.remove", path };
+        }
+        // ── mDNS ──
+        case "mdnsStart": {
+            const hostname = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (hostname === null)
+                return null;
+            return { operation: "mdns.start", hostname };
+        }
+        case "mdnsSetHostname": {
+            const name = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (name === null)
+                return null;
+            return { operation: "mdns.set_hostname", name };
+        }
+        case "mdnsAddService": {
+            const instanceName = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const proto = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            const port = resolveNumericOrExpression(args, 2, instance, paramNames, callArgTexts, paramDefaults);
+            if (instanceName === null || proto === null || port === null)
+                return null;
+            return { operation: "mdns.add_service", instance: instanceName, proto, port };
+        }
+        case "mdnsAnnounce":
+            return { operation: "mdns.announce" };
+        case "mdnsStop":
+            return { operation: "mdns.stop" };
+        // ── MQTT ──
+        case "mqttConnect": {
+            const brokerUri = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const clientId = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (brokerUri === null || clientId === null)
+                return null;
+            return { operation: "mqtt.connect", brokerUri, clientId };
+        }
+        case "mqttOnMessage": {
+            const handler = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (handler === null)
+                return null;
+            return { operation: "mqtt.on_message", handler };
+        }
+        case "mqttSubscribe": {
+            const topic = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (topic === null)
+                return null;
+            return { operation: "mqtt.subscribe", topic };
+        }
+        case "mqttPublish": {
+            const topic = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const data = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (topic === null || data === null)
+                return null;
+            return { operation: "mqtt.publish", topic, data };
+        }
+        case "mqttConnected":
+            return { operation: "mqtt.connected" };
+        case "mqttDisconnect":
+            return { operation: "mqtt.disconnect" };
+        // ── OTA ──
+        case "otaFromUrl": {
+            const url = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (url === null)
+                return null;
+            return { operation: "ota.from_url", url };
+        }
+        case "otaBegin":
+            return { operation: "ota.begin" };
+        case "otaWrite": {
+            const chunk = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (chunk === null)
+                return null;
+            return { operation: "ota.write", chunk };
+        }
+        case "otaApply":
+            return { operation: "ota.apply" };
+        // ── Temperature (die temp) ──
+        case "tempRead":
+            return { operation: "temp.read" };
+        // ── Hardware timer (GPTimer) ──
+        case "hwtimerSetFrequency": {
+            const inst = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const hz = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (inst === null || hz === null)
+                return null;
+            return { operation: "hwtimer.set_frequency", instance: inst, hz };
+        }
+        case "hwtimerOnOverflow": {
+            const inst = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const handler = resolveSemanticArg(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (inst === null || handler === null)
+                return null;
+            return { operation: "hwtimer.on_overflow", instance: inst, handler };
+        }
+        case "hwtimerStart": {
+            const inst = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (inst === null)
+                return null;
+            return { operation: "hwtimer.start", instance: inst };
+        }
+        case "hwtimerStop": {
+            const inst = resolveNumericOrExpression(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (inst === null)
+                return null;
+            return { operation: "hwtimer.stop", instance: inst };
+        }
+        // ── Capacitive touch pins ──
+        case "capacitiveRead": {
+            const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            if (pin === null)
+                return null;
+            return { operation: "capacitive.read", port, pin };
+        }
         // ── Interrupts ──
         case "interruptAttach": {
             const pin = resolveNumericArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
@@ -580,6 +1302,16 @@ export function tryResolveSemanticCall(fnName, args, instance, paramNames, callA
                 return null;
             return { operation: "spi.set_bit_order", bus, order };
         }
+        case "spiReadBuffer": {
+            const bus = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);
+            const count = resolveNumericOrExpression(args, 1, instance, paramNames, callArgTexts, paramDefaults);
+            if (bus === null || count === null)
+                return null;
+            // The buffer arg (args[2]) is only a placeholder for type resolution;
+            // the real target is the caller's variable, rewritten from
+            // __HAL_READ_BUF__ by replaceHalReadBufferPlaceholder.
+            return { operation: "spi.read_buffer", bus, count, buffer: "__HAL_READ_BUF__" };
+        }
         // ── UART ──
         case "uartBegin": {
             const port = resolveSemanticArg(args, 0, instance, paramNames, callArgTexts, paramDefaults);