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

package/src/emit.ts

@@ -5,6 +5,11 @@
 // resolver.  The framework strategy translates each operation into
 // framework-specific C++ at code generation time.
 //
+// EMIT BOUNDARY: This file is a canonical entry point of the HAL lowering
+// surface (A) — its C++ output lands in user sketches. The emitted bytes are
+// covered by the TypeCAD Runtime Exception (see RUNTIME_EXCEPTION.md at the
+// repository root) and are not subject to the license of this tool source.
+//
 // Pin parameters accept both `number` (legacy framework pin number) and
 // `string` (MCU port name like "PB5"). The transpiler resolves port names
 // to framework pin numbers via the MCU package's pin mapping.
@@ -30,6 +35,49 @@ export function gpioSetMode(pin: number | string, mode: string): void {}
 /** Write PWM duty cycle to a pin. */
 export function pwmWrite(pin: number | string, duty: number): void {}
 
+// ---------------------------------------------------------------------------
+// RMT — Remote Control Transceiver (addressable LEDs, IR, raw digital waveforms)
+// ---------------------------------------------------------------------------
+// rmtTxInit/rmtRxInit are POSITIONAL semantic primitives — the ergonomic
+// opts-object form lives in hal/rmt.ts (which destructures and forwards). The
+// resolver collapses object literals, so HALOpIR fields must be scalars; the
+// rmt.ts wrapper bridges the ergonomic API to these positional calls.
+//
+// Pin params accept Pin | number | string so callers can pass a board alias
+// like LED (a Pin object) directly; the transpiler resolves it to its number.
+import type { Pin } from './gpio.js';
+type RmtPin = Pin | number | string;
+
+/** Positional semantic primitive. Args: pin, resolutionHz, bit0Hi, bit0Lo,
+ *  bit1Hi, bit1Lo, msbFirst, queueDepth. Use rmtTxInit() from hal/rmt.ts. */
+export function rmtTxInit(
+  pin: RmtPin,
+  resolutionHz: number,
+  bit0Hi: number, bit0Lo: number, bit1Hi: number, bit1Lo: number,
+  msbFirst: boolean, queueDepth: number,
+): void {}
+/** Write bytes via the channel's bytes-encoder (timings fixed at init). */
+export function rmtTxWriteBytes(pin: RmtPin, bytes: number[] | Uint8Array): void {}
+/** Write raw RMT symbols — arbitrary [hiTicks, loTicks] pairs. */
+export function rmtTxWriteSymbols(pin: RmtPin, symbols: [number, number][]): void {}
+/** Block until the queued TX completes. */
+export function rmtTxWaitDone(pin: RmtPin, timeoutMs?: number): void {}
+/** Tear down the TX channel and release its slot. */
+export function rmtTxDeinit(pin: RmtPin): void {}
+
+/** Positional semantic primitive — use rmtRxInit() from hal/rmt.ts. */
+export function rmtRxInit(pin: RmtPin, resolutionHz: number): void {}
+/** Register a callback-by-name invoked when an RX burst completes. */
+export function rmtRxOnReceived(pin: RmtPin, handler: string): void {}
+/** Start receiving. */
+export function rmtRxStart(pin: RmtPin): void {}
+/** Stop receiving. */
+export function rmtRxStop(pin: RmtPin): void {}
+/** Blocking read — returns flattened symbols [d0,l0,d1,l1,…] in ticks. */
+export function rmtRxRead(pin: RmtPin, maxCount: number): number[] { return []; }
+/** Tear down the RX channel and release its slot. */
+export function rmtRxDeinit(pin: RmtPin): void {}
+
 // ---------------------------------------------------------------------------
 // ADC — analog-to-digital conversion
 // ---------------------------------------------------------------------------
@@ -99,6 +147,15 @@ export function i2cRequestFrom(bus: string, address: number, quantity: number, s
 export function i2cAvailable(bus: string): number { return 0; }
 /** Read a byte from I2C. */
 export function i2cRead(bus: string): number { return 0; }
+/**
+ * Drain `count` bytes requested from the I2C bus into a caller-provided buffer.
+ * Semantic primitive: lowers to the `i2c.read_buffer` HAL op. The `buffer`
+ * argument is emitted as a placeholder (`__HAL_READ_BUF__`) that the var-init
+ * transformer rewrites to the caller's own buffer variable, so bytes land in
+ * the `uint8_t data[N]` declared in user scope — NOT an internal temp that
+ * decays to a pointer on return. Keeps `data.length` / `data[i]` valid.
+ */
+export function i2cReadBuffer(bus: string, count: number, buffer: number[] | Uint8Array): void {}
 
 // ---------------------------------------------------------------------------
 // SPI — serial peripheral interface
@@ -118,6 +175,14 @@ export function spiEndTx(bus: string): void {}
 export function spiCsLow(pin: number | string): void {}
 /** Set SPI chip-select pin HIGH. */
 export function spiCsHigh(pin: number | string): void {}
+/**
+ * Read `count` bytes from the SPI bus into a caller-provided buffer by clocking
+ * dummy (0x00) transfers. Semantic primitive: lowers to the `spi.read_buffer`
+ * HAL op (per-byte `bus.transfer(0)` read loop). The `buffer` placeholder is
+ * rewritten to the caller's variable. Mirrors i2cReadBuffer. The caller is
+ * responsible for asserting/de-asserting chip-select around it.
+ */
+export function spiReadBuffer(bus: string, count: number, buffer: number[] | Uint8Array): void {}
 /** Set SPI data mode. */
 export function spiSetMode(bus: string, mode: number): void {}
 /** Set SPI bit order. */
@@ -201,6 +266,104 @@ export function powerDeepSleep(ms: number): void {}
 export function powerLightSleep(): void {}
 /** Set the CPU frequency (MHz). */
 export function powerSetCpuFrequency(mhz: number): void {}
+/** Enter deep sleep until `pin` reaches `level` (pin wakeup). Architecture-aware:
+ *  ext0 on Xtensa (RTC pins), gpio-wakeup on RISC-V. */
+export function powerDeepSleepPin(pin: number, level: number): void {}
+
+// ---------------------------------------------------------------------------
+// Preferences (NVS-backed key/value store)
+// ---------------------------------------------------------------------------
+
+export function preferencesBegin(namespace: string, readOnly: boolean): void {}
+export function preferencesEnd(): void {}
+export function preferencesClear(): void {}
+export function preferencesRemove(key: string): void {}
+export function preferencesPutInt(key: string, value: number): void {}
+export function preferencesGetInt(key: string, defaultValue: number): number { return 0; }
+export function preferencesPutUInt(key: string, value: number): void {}
+export function preferencesGetUInt(key: string, defaultValue: number): number { return 0; }
+export function preferencesPutBool(key: string, value: boolean): void {}
+export function preferencesGetBool(key: string, defaultValue: boolean): boolean { return false; }
+export function preferencesPutFloat(key: string, value: number): void {}
+export function preferencesGetFloat(key: string, defaultValue: number): number { return 0; }
+export function preferencesPutString(key: string, value: string): void {}
+export function preferencesGetString(key: string, defaultValue: string): string { return ""; }
+
+export function wifiConnect(ssid: string, password?: string, timeoutMs?: number): boolean { return false; }
+export function wifiConnectStart(ssid: string, password?: string): void {}
+export function wifiDisconnect(): void {}
+export function wifiStatus(): number { return 0; }
+export function wifiIsConnected(): boolean { return false; }
+export function wifiLocalIp(): string { return ""; }
+export function wifiRssi(): number { return 0; }
+export function wifiMac(): string { return ""; }
+export function wifiSetHostname(name: string): void {}
+export function wifiSetStaticIp(ip: string, gateway: string, subnet: string, dns?: string): void {}
+export function wifiSetAutoReconnect(enabled: boolean): void {}
+export function wifiSetPowerSave(mode: string): void {}
+export function wifiSetTxPower(dbm: number): void {}
+export function wifiOnEvent(event: string, handler: string): void {}
+export function wifiApStart(ssid: string, password?: string, channel?: number, hidden?: boolean, maxClients?: number): boolean { return false; }
+export function wifiApStop(): void {}
+export function wifiApClientCount(): number { return 0; }
+export function wifiApIp(): string { return ""; }
+export function wifiApSetChannel(channel: number): void {}
+export function wifiApSetHidden(hidden: boolean): void {}
+export function wifiApSetMaxClients(maxClients: number): void {}
+export function wifiScan(): number { return 0; }
+export function wifiScanStart(): void {}
+export function wifiScanCount(): number { return 0; }
+export function wifiScanSsid(index: number): string { return ""; }
+export function wifiScanRssi(index: number): number { return 0; }
+export function wifiScanEncryption(index: number): number { return 0; }
+export function wifiScanChannel(index: number): number { return 0; }
+export function wifiSaveCredentials(ssid: string, password: string): void {}
+export function wifiConnectSaved(timeoutMs?: number): boolean { return false; }
+export function wifiClearCredentials(): void {}
+export function wifiWaitConnected(timeoutMs?: number): boolean { return false; }
+export function wifiWaitDisconnected(): void {}
+
+// ---------------------------------------------------------------------------
+// HTTP client
+// ---------------------------------------------------------------------------
+
+export function httpBegin(method: string, url: string): void {}
+export function httpReset(): void {}
+export function httpSetHeader(name: string, value: string): void {}
+export function httpSetTimeout(ms: number): void {}
+export function httpSetMaxBody(bytes: number): void {}
+export function httpSetBody(data: string, json?: boolean): void {}
+export function httpSetInsecure(): void {}
+export function httpSetCaCert(pem: string): void {}
+export function httpSend(): boolean { return false; }
+export function httpSendStart(): void {}
+export function httpStatus(): number { return 0; }
+export function httpOk(): boolean { return false; }
+export function httpBody(): string { return ""; }
+export function httpContentLength(): number { return 0; }
+export function httpResponseHeader(name: string): string { return ""; }
+
+// ---------------------------------------------------------------------------
+// BLE (NimBLE GATT peripheral)
+// ---------------------------------------------------------------------------
+
+export function bleServerBegin(name: string): void {}
+export function bleAdvertiseStart(): void {}
+export function bleAdvertiseStop(): void {}
+export function bleAddService(uuid: string): void {}
+export function bleAddChar(index: number, uuid: string, type: string, perms: number, svcIndex: number): void {}
+export function bleOnRead(index: number, handler: string): void {}
+export function bleOnWrite(index: number, handler: string): void {}
+export function bleOnConnect(handler: string): void {}
+export function bleOnDisconnect(handler: string): void {}
+export function bleNotify(index: number, value: number | string): void {}
+export function bleIsConnected(): boolean { return false; }
+export function bleClientCount(): number { return 0; }
+export function bleSetName(name: string): void {}
+export function bleUntilConnected(timeoutMs?: number): boolean { return false; }
+export function bleUntilConnectedStart(): void {}
+export function bleSetTxPower(dbm: number): void {}
+export function bleStatus(): number { return 0; }
 
 // ---------------------------------------------------------------------------
 // Raw C++ escape hatch
@@ -208,3 +371,20 @@ export function powerSetCpuFrequency(mhz: number): void {}
 
 /** Emit raw C++ code (escape hatch for unsupported operations). */
 export function rawCpp(code: string): void {}
+
+/**
+ * Emit raw C++ in expression context. Use when an IDF macro or constructor
+ * must produce a value (e.g. `WIFI_INIT_CONFIG_DEFAULT()` expands to a struct
+ * initializer; there's no TS-side way to construct it). The type parameter
+ * is purely a TS hint — the transpiler doesn't check it; it just emits the
+ * raw text in expression position.
+ *
+ *   const cfg = rawCpp<wifi_init_config_t>('WIFI_INIT_CONFIG_DEFAULT()');
+ *
+ * lowers to:
+ *
+ *   wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+ */
+export function rawCppExpr<T>(code: string): T {
+  return undefined as unknown as T;
+}

package/src/fs.ts

@@ -1,46 +1,54 @@
-import { rawCpp } from './emit.js';
-import { include } from './include.js';
-
 /**
  * FSClass provides a high-level abstraction for filesystem operations.
- * Maps to SD.h or LittleFS depending on the board configuration.
+ *
+ * Lowered to native filesystem HAL ops (fs.*): ESP-IDF mounts an SD card via
+ * esp_vfs_fat_sdmmc_mount (FAT on SDMMC/SDSPI); Arduino uses SD.h / LittleFS.
+ * The per-framework runtime shim owns the open/read/write/close dance and
+ * returns heap strings for readText.
+ *
+ * The semantic primitives (fsBegin / fsReadText / ...) are resolved to fs.*
+ * HAL ops by the transpiler's hal-plugins switch; this class is the
+ * ergonomic, type-checking surface.
  */
 export class FSClass {
   static readonly __instance_name = "FS";
 
+  /** Mount the filesystem. Returns true on success. */
   begin(): boolean {
-    include("<FS.h>");
-    rawCpp(`return FS.begin();`);
+    fsBegin();
     return true;
   }
 
+  /** Read a UTF-8 text file into a string. Returns "" if the file is missing
+   *  or unreadable. The returned buffer is caller-owned. */
   readText(path: string): string {
-    include("<FS.h>");
-    rawCpp(`File f = FS.open(${path}.c_str(), "r");`);
-    rawCpp(`if (!f) return "";`);
-    rawCpp(`String s = f.readString();`);
-    rawCpp(`f.close();`);
-    rawCpp(`return s.c_str();`);
-    return "";
+    return fsReadText(path);
   }
 
+  /** Write a string to a file (overwrites). Silently no-ops if the file
+   *  cannot be opened for writing. */
   writeText(path: string, content: string): void {
-    include("<FS.h>");
-    rawCpp(`File f = FS.open(${path}.c_str(), "w");`);
-    rawCpp(`if (f) { f.print(${content}.c_str()); f.close(); }`);
+    fsWriteText(path, content);
   }
 
+  /** True if a file exists at the path. */
   exists(path: string): boolean {
-    include("<FS.h>");
-    rawCpp(`return FS.exists(${path}.c_str());`);
-    return false;
+    return fsExists(path);
   }
 
+  /** Delete a file. Returns true if deleted. */
   remove(path: string): boolean {
-    include("<FS.h>");
-    rawCpp(`return FS.remove(${path}.c_str());`);
-    return false;
+    return fsRemove(path);
   }
 }
 
 export const FS = new FSClass();
+
+// ── Semantic primitives (resolved to fs.* HAL ops by the transpiler) ──
+// These are inert at runtime (tests, type-checking); the cuttlefish transpiler
+// intercepts calls by name and lowers them to typed HAL op IR.
+export function fsBegin(): void {}
+export function fsReadText(path: string): string { return ""; }
+export function fsWriteText(path: string, content: string): void {}
+export function fsExists(path: string): boolean { return false; }
+export function fsRemove(path: string): boolean { return false; }

package/src/http.ts

@@ -0,0 +1,144 @@
+import {
+  httpBegin,
+  httpReset,
+  httpSetHeader,
+  httpSetTimeout,
+  httpSetMaxBody,
+  httpSetBody,
+  httpSetInsecure,
+  httpSetCaCert,
+  httpSend,
+  httpStatus,
+  httpOk,
+  httpBody,
+  httpContentLength,
+  httpResponseHeader,
+} from './emit.js';
+
+export enum HttpMethod {
+  GET = 0,
+  POST = 1,
+  PUT = 2,
+  DELETE = 3,
+  HEAD = 4,
+  PATCH = 5,
+}
+
+/**
+ * Fluent HTTP/S request builder, lowered to native ESP-IDF
+ * `esp_http_client` by framework-esp32 (TLS via esp-tls / mbedTLS bundle).
+ * Response fields are read from this object after send() — mirrors
+ * `await WiFi.connect(); WiFi.localIP()`.
+ *
+ * No `include()` calls here — ESP-IDF headers are framework-owned and added
+ * via forcedIncludes when the program uses http.* ops.
+ */
+export class HttpRequest {
+  private _method: string;
+  private _url: string;
+
+  constructor(method: string, url: string) {
+    this._method = method;
+    this._url = url;
+  }
+
+  header(name: string, value: string): this {
+    httpSetHeader(name, value);
+    return this;
+  }
+
+  timeout(ms: number): this {
+    httpSetTimeout(ms);
+    return this;
+  }
+
+  maxBody(bytes: number): this {
+    httpSetMaxBody(bytes);
+    return this;
+  }
+
+  body(data: string): this {
+    httpSetBody(data, false);
+    return this;
+  }
+
+  jsonBody(json: string): this {
+    httpSetBody(json, true);
+    return this;
+  }
+
+  /** Skip TLS certificate verification (development only). */
+  insecure(): this {
+    httpSetInsecure();
+    return this;
+  }
+
+  caCert(pem: string): this {
+    httpSetCaCert(pem);
+    return this;
+  }
+
+  /** Blocking at top level; cooperatively awaitable inside async functions. */
+  send(): Promise<boolean> {
+    httpBegin(this._method, this._url);
+    httpSend();
+    return Promise.resolve(false);
+  }
+
+  status(): number {
+    return httpStatus();
+  }
+
+  ok(): boolean {
+    return httpOk();
+  }
+
+  /** Response body as a C string (valid until the next request). */
+  text(): string {
+    return httpBody();
+  }
+
+  contentLength(): number {
+    return httpContentLength();
+  }
+
+  responseHeader(name: string): string {
+    return httpResponseHeader(name);
+  }
+}
+
+export class HttpClass {
+  static readonly __instance_name = "Http";
+
+  get(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("GET", url);
+  }
+
+  post(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("POST", url);
+  }
+
+  put(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("PUT", url);
+  }
+
+  del(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("DELETE", url);
+  }
+
+  head(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("HEAD", url);
+  }
+
+  patch(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("PATCH", url);
+  }
+}
+
+export const Http = new HttpClass();

package/src/i2c.ts

@@ -1,4 +1,4 @@
-import { i2cBegin, i2cEnd, i2cSetClock, i2cBeginTx, i2cWrite, i2cWriteBuffer, i2cEndTx, i2cRequestFrom, i2cAvailable, i2cRead, rawCpp } from './emit.js';
+import { i2cBegin, i2cEnd, i2cSetClock, i2cBeginTx, i2cWrite, i2cWriteBuffer, i2cEndTx, i2cRequestFrom, i2cAvailable, i2cRead, i2cReadBuffer, rawCpp } from './emit.js';
 import { include } from './include.js';
 
 export class I2CDevice {
@@ -10,6 +10,16 @@ export class I2CDevice {
     this._address = address;
   }
 
+  /** The 7-bit I2C address this accessor targets. Exposed so I2CDevice
+   *  structurally satisfies the @typecad/simulator II2CDeviceAccessor contract
+   *  (which declares `readonly address`), letting the same driver function be
+   *  typed against the contract and accept either a real board device or a
+   *  simulated one. The transpiler strips HAL class bodies to IR, so this
+   *  getter carries no runtime cost in the generated C++. */
+  get address(): number {
+    return this._address;
+  }
+
   writeByte(register: number, value: number): void {
     include("<Wire.h>");
     i2cBeginTx(this._bus, this._address);
@@ -41,9 +51,11 @@ export class I2CDevice {
     i2cWrite(this._bus, register);
     i2cEndTx(this._bus, false);
     i2cRequestFrom(this._bus, this._address, count, true);
-    rawCpp(`static uint8_t __buf[${count}];`);
-    rawCpp(`for (int __i = 0; __i < ${count}; __i++) __buf[__i] = ${this._bus}.read();`);
-    rawCpp(`return __buf;`);
+    // Drain the requested bytes into the caller's buffer (declared by the
+    // Uint8Array return marker as `uint8_t data[count]`). Using the semantic
+    // primitive — NOT rawCpp — keeps the buffer in user scope so it survives
+    // the return (no decayed pointer) and `data.length` / `data[i]` work.
+    i2cReadBuffer(this._bus, count, new Uint8Array(count));
     return new Uint8Array(count);
   }
 }

package/src/index.ts

@@ -19,7 +19,7 @@ export type { SPIBitOrder, SPIMode, SPISettings } from './types.js';
 export { include } from './include.js';
 export { board } from './board.js';
 export { callback } from './callback.js';
-export { rawCpp, boardResolve } from './emit.js';
+export { rawCpp, rawCppExpr, boardResolve } from './emit.js';
 export { HIGH, LOW, OUTPUT, INPUT, INPUT_PULLUP, INPUT_PULLDOWN, OUTPUT_OPEN_DRAIN, ANALOG, LED_BUILTIN, LSBFIRST, MSBFIRST, WDTO_15MS, WDTO_30MS, WDTO_60MS, WDTO_120MS, WDTO_250MS, WDTO_500MS, WDTO_1S, WDTO_2S, WDTO_4S, WDTO_8S } from './constants.js';
 export { delay, millis, micros, delayMicroseconds, map, constrain, TimingClass, Timing } from './timing.js';
 export { freeHeap, setInterval, setTimeout, clearInterval, clearTimeout } from './timing.js';
@@ -44,5 +44,25 @@ export { DACClass, DAC } from './dac.js';
 export { PreferencesClass, Preferences } from './preferences.js';
 export { HardwareTimer, Timer0, Timer1, Timer2 } from './timer.js';
 export { FSClass, FS } from './fs.js';
+export { fsBegin, fsReadText, fsWriteText, fsExists, fsRemove } from './fs.js';
+export { MdnsClass, MDNS } from './mdns.js';
+export { mdnsStart, mdnsSetHostname, mdnsAddService, mdnsAnnounce, mdnsStop } from './mdns.js';
+export { MqttClass, MQTT } from './mqtt.js';
+export { mqttConnect, mqttOnMessage, mqttSubscribe, mqttPublish, mqttConnected, mqttDisconnect } from './mqtt.js';
+export { OtaClass, OTA } from './ota.js';
+export { otaFromUrl, otaBegin, otaWrite, otaApply } from './ota.js';
+export { TemperatureClass, Temperature } from './temperature.js';
+export { tempRead } from './temperature.js';
+export { hwtimerSetFrequency, hwtimerOnOverflow, hwtimerStart, hwtimerStop } from './timer.js';
+export { CapacitiveClass, Capacitive } from './capacitive.js';
+export { capacitiveRead } from './capacitive.js';
 export { PowerClass, Power } from './power.js';
 export { AsyncClass, Async } from './async.js';
+export { WiFiClass, WiFi, WiFiStatus, WiFiEncryption } from './wifi.js';
+export { HttpClass, Http, HttpRequest, HttpMethod } from './http.js';
+export {
+  BleClass, Ble, BleServer,
+  BleValueType, BlePerm, BleStatus, BleAdvertisingMode, GATT,
+} from './ble.js';
+export type { GattCharacteristicDef, CharValue } from './ble.js';
+export { RmtChannel } from './rmt.js';

package/src/mdns.ts

@@ -0,0 +1,50 @@
+/**
+ * MdnsClass — mDNS service discovery (ESP-IDF esp_mdns).
+ *
+ * Lowered to native mDNS HAL ops (mdns.*): ESP-IDF's esp_mdns component
+ * advertises the device on the local network as `<hostname>.local` and
+ * publishes services (e.g. `_http._tcp`) for discovery by Bonjour/Avahi.
+ *
+ * The semantic primitives (mdnsStart / mdnsAddService / ...) are resolved to
+ * mdns.* HAL ops by the transpiler; this class is the ergonomic surface.
+ *
+ * Requires WiFi to be connected (mDNS rides on the station interface).
+ */
+export class MdnsClass {
+  static readonly __instance_name = "MDNS";
+
+  /** Initialize mDNS and set the host name (advertised as <name>.local). */
+  start(hostname: string): boolean {
+    mdnsStart(hostname);
+    return true;
+  }
+
+  /** Set/override the host name after start(). */
+  setHostname(name: string): void {
+    mdnsSetHostname(name);
+  }
+
+  /** Publish a service instance. proto is "_tcp" or "_udp". */
+  addService(instance: string, proto: string, port: number): void {
+    mdnsAddService(instance, proto, port);
+  }
+
+  /** Advertise that the device is reachable (sends a probe/announce). */
+  announce(): void {
+    mdnsAnnounce();
+  }
+
+  /** Tear down the mDNS responder. */
+  stop(): void {
+    mdnsStop();
+  }
+}
+
+export const MDNS = new MdnsClass();
+
+// ── Semantic primitives (resolved to mdns.* HAL ops by the transpiler) ──
+export function mdnsStart(hostname: string): void {}
+export function mdnsSetHostname(name: string): void {}
+export function mdnsAddService(instance: string, proto: string, port: number): void {}
+export function mdnsAnnounce(): void {}
+export function mdnsStop(): void {}

package/src/mqtt.ts

@@ -0,0 +1,57 @@
+import { callback } from './callback.js';
+
+/**
+ * MqttClass — MQTT 3.1.1 pub/sub client (ESP-IDF esp_mqtt).
+ *
+ * Lowered to native MQTT HAL ops (mqtt.*): ESP-IDF's esp_mqtt_client_* API.
+ * Covers the common IoT pub/sub path: connect to a broker, publish, subscribe
+ * with an onMessage callback, and disconnect. The runtime shim owns the event
+ * loop translation (ESP-IDF's MQTT event handler → the user's TS callback).
+ *
+ * Requires a network connection (WiFi) before connect().
+ */
+export class MqttClass {
+  static readonly __instance_name = "MQTT";
+
+  /** Connect to a broker URI (e.g. "mqtt://broker.local" or "mqtts://..."). */
+  connect(brokerUri: string, clientId: string): boolean {
+    mqttConnect(brokerUri, clientId);
+    return true;
+  }
+
+  /** Set a handler invoked for every received PUBLISH on a subscribed topic.
+   *  The handler receives (topic, payload). */
+  onMessage(handler: (topic: string, payload: string) => void): void {
+    mqttOnMessage(callback(handler));
+  }
+
+  /** Subscribe to a topic filter (e.g. "sensors/#"). */
+  subscribe(topic: string): void {
+    mqttSubscribe(topic);
+  }
+
+  /** Publish a message to a topic. */
+  publish(topic: string, data: string): void {
+    mqttPublish(topic, data);
+  }
+
+  /** True if the client is currently connected to the broker. */
+  connected(): boolean {
+    return mqttConnected();
+  }
+
+  /** Disconnect from the broker and free the client. */
+  disconnect(): void {
+    mqttDisconnect();
+  }
+}
+
+export const MQTT = new MqttClass();
+
+// ── Semantic primitives (resolved to mqtt.* HAL ops by the transpiler) ──
+export function mqttConnect(brokerUri: string, clientId: string): void {}
+export function mqttOnMessage(handler: string): void {}
+export function mqttSubscribe(topic: string): void {}
+export function mqttPublish(topic: string, data: string): void {}
+export function mqttConnected(): boolean { return false; }
+export function mqttDisconnect(): void {}

package/src/ota.ts

@@ -0,0 +1,44 @@
+/**
+ * OtaClass — over-the-air firmware update (ESP-IDF esp_https_ota / esp_app_format).
+ *
+ * Lowered to native OTA HAL ops (ota.*): ESP-IDF's esp_https_ota downloads a
+ * firmware image over HTTPS and writes it to the OTA partition, then reboots
+ * into it. The runtime shim owns the session/progress/verification dance.
+ *
+ * Requires a network connection (WiFi) and that the partition table defines
+ * at least two OTA app slots (the framework's default partitions.csv does).
+ */
+export class OtaClass {
+  static readonly __instance_name = "OTA";
+
+  /** Download and apply a firmware image from an HTTPS URL, then reboot.
+   *  Blocks until the update is written and verified. Returns true on success
+   *  (the reboot happens inside the shim on success, so a true return means
+   *  the new firmware is about to boot). */
+  fromUrl(url: string): boolean {
+    return otaFromUrl(url);
+  }
+
+  /** Begin a manual update session (caller writes chunks via write()). */
+  begin(): boolean {
+    return otaBegin();
+  }
+
+  /** Write a chunk of firmware data to the OTA partition. */
+  write(chunk: string): void {
+    otaWrite(chunk);
+  }
+
+  /** Finalize the update: verify, set the boot partition, and reboot. */
+  apply(): void {
+    otaApply();
+  }
+}
+
+export const OTA = new OtaClass();
+
+// ── Semantic primitives (resolved to ota.* HAL ops by the transpiler) ──
+export function otaFromUrl(url: string): boolean { return false; }
+export function otaBegin(): boolean { return false; }
+export function otaWrite(chunk: string): void {}
+export function otaApply(): void {}