@typecad/hal 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/wifi.js

@@ -0,0 +1,151 @@
+import { wifiConnect, wifiConnectStart, wifiDisconnect, wifiStatus, wifiIsConnected, wifiLocalIp, wifiRssi, wifiMac, wifiSetHostname, wifiSetStaticIp, wifiSetAutoReconnect, wifiSetPowerSave, wifiSetTxPower, wifiOnEvent, wifiApStart, wifiApStop, wifiApClientCount, wifiApIp, wifiApSetChannel, wifiApSetHidden, wifiApSetMaxClients, wifiScan, wifiScanStart, wifiScanCount, wifiScanSsid, wifiScanRssi, wifiScanEncryption, wifiScanChannel, wifiSaveCredentials, wifiConnectSaved, wifiClearCredentials, wifiWaitConnected, wifiWaitDisconnected, } from './emit.js';
+import { callback } from './callback.js';
+/** Normalized WiFi link status (mapped from esp_wifi events by the runtime shim). */
+export var WiFiStatus;
+(function (WiFiStatus) {
+    WiFiStatus[WiFiStatus["Idle"] = 0] = "Idle";
+    WiFiStatus[WiFiStatus["Connecting"] = 1] = "Connecting";
+    WiFiStatus[WiFiStatus["Connected"] = 2] = "Connected";
+    WiFiStatus[WiFiStatus["ConnectFailed"] = 3] = "ConnectFailed";
+    WiFiStatus[WiFiStatus["Disconnected"] = 4] = "Disconnected";
+})(WiFiStatus || (WiFiStatus = {}));
+export var WiFiEncryption;
+(function (WiFiEncryption) {
+    WiFiEncryption[WiFiEncryption["Open"] = 0] = "Open";
+    WiFiEncryption[WiFiEncryption["WEP"] = 1] = "WEP";
+    WiFiEncryption[WiFiEncryption["WPA"] = 2] = "WPA";
+    WiFiEncryption[WiFiEncryption["WPA2"] = 3] = "WPA2";
+    WiFiEncryption[WiFiEncryption["WPA3"] = 4] = "WPA3";
+    WiFiEncryption[WiFiEncryption["Enterprise"] = 5] = "Enterprise";
+})(WiFiEncryption || (WiFiEncryption = {}));
+/**
+ * WiFi radio / link control, lowered to native ESP-IDF (`esp_wifi` /
+ * `esp_netif` / `esp_event` / `nvs_flash`) by framework-esp32.
+ *
+ * No `include()` calls here — ESP-IDF headers are framework-owned and added
+ * via forcedIncludes when the program uses wifi.* ops (the Preferences
+ * lesson: HAL files must not carry platform headers). Frameworks without a
+ * wifi lowering reject these ops with a diagnostic.
+ */
+export class WiFiClass {
+    /** Blocking at top level; cooperatively awaitable inside async functions. */
+    connect(ssid, password, timeoutMs = 15000) {
+        wifiConnect(ssid, password, timeoutMs);
+        return Promise.resolve(false);
+    }
+    /** Fire-and-forget STA begin; poll status() / untilConnected(). */
+    connectAsync(ssid, password) {
+        wifiConnectStart(ssid, password);
+    }
+    untilConnected(timeoutMs = 15000) {
+        wifiWaitConnected(timeoutMs);
+        return Promise.resolve(false);
+    }
+    untilDisconnected() {
+        wifiWaitDisconnected();
+        return Promise.resolve();
+    }
+    disconnect() {
+        wifiDisconnect();
+    }
+    isConnected() {
+        return wifiIsConnected();
+    }
+    status() {
+        return wifiStatus();
+    }
+    localIP() {
+        return wifiLocalIp();
+    }
+    rssi() {
+        return wifiRssi();
+    }
+    macAddress() {
+        return wifiMac();
+    }
+    hostname(name) {
+        wifiSetHostname(name);
+        return this;
+    }
+    staticIP(ip, gateway, subnet, dns) {
+        wifiSetStaticIp(ip, gateway, subnet, dns);
+        return this;
+    }
+    autoReconnect(enabled) {
+        wifiSetAutoReconnect(enabled);
+        return this;
+    }
+    powerSave(mode) {
+        wifiSetPowerSave(mode);
+        return this;
+    }
+    /** Cap TX power in dBm (roughly 2–20). Safe to call before connect() —
+     *  the value is applied after the radio starts. */
+    txPower(dbm) {
+        wifiSetTxPower(dbm);
+        return this;
+    }
+    saveCredentials(ssid, password) {
+        wifiSaveCredentials(ssid, password);
+    }
+    connectSaved(timeoutMs = 15000) {
+        return wifiConnectSaved(timeoutMs);
+    }
+    clearCredentials() {
+        wifiClearCredentials();
+    }
+    onConnect(handler) {
+        wifiOnEvent("connect", callback(handler));
+    }
+    onDisconnect(handler) {
+        wifiOnEvent("disconnect", callback(handler));
+    }
+    startAP(ssid, password) {
+        return wifiApStart(ssid, password);
+    }
+    apChannel(ch) {
+        wifiApSetChannel(ch);
+        return this;
+    }
+    apHidden(hidden) {
+        wifiApSetHidden(hidden);
+        return this;
+    }
+    apMaxClients(n) {
+        wifiApSetMaxClients(n);
+        return this;
+    }
+    stopAP() {
+        wifiApStop();
+    }
+    apClientCount() {
+        return wifiApClientCount();
+    }
+    apIP() {
+        return wifiApIp();
+    }
+    scan() {
+        return wifiScan();
+    }
+    scanAsync() {
+        wifiScanStart();
+        return Promise.resolve();
+    }
+    scanCount() {
+        return wifiScanCount();
+    }
+    scanSSID(i) {
+        return wifiScanSsid(i);
+    }
+    scanRSSI(i) {
+        return wifiScanRssi(i);
+    }
+    scanEncryption(i) {
+        return wifiScanEncryption(i);
+    }
+    scanChannel(i) {
+        return wifiScanChannel(i);
+    }
+}
+WiFiClass.__instance_name = "WiFi";
+export const WiFi = new WiFiClass();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/hal",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "description": "TypeCAD hardware abstraction layer — GPIO, I2C, SPI, UART as regular TypeScript",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,8 @@
     "build": "tsc",
     "prepublishOnly": "npm run build",
     "test:hw": "npm exec -- cuttlefish-test",
-    "test:hw:basics": "npm exec -- cuttlefish-test tests/01-gpio.test.ts"
+    "test:hw:basics": "npm exec -- cuttlefish-test tests/01-gpio.test.ts",
+    "test:hw:preferences": "npm exec -- cuttlefish-test tests/14-preferences.test.ts"
   },
   "license": "MIT",
   "publishConfig": {
@@ -49,9 +50,9 @@
   },
   "author": "typecad0",
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.6",
-    "@typecad/board-arduino-uno": "1.0.0-alpha.6",
-    "@typecad/mcu-atmega328p": "1.0.0-alpha.6"
+    "@typecad/expect": "1.0.0-alpha.8",
+    "@typecad/board-arduino-uno": "1.0.0-alpha.8",
+    "@typecad/mcu-atmega328p": "1.0.0-alpha.8"
   },
   "sideEffects": false,
   "exports": {

package/src/ble.ts

@@ -0,0 +1,209 @@
+import {
+  bleServerBegin,
+  bleAdvertiseStart,
+  bleAdvertiseStop,
+  bleAddService,
+  bleAddChar,
+  bleOnRead,
+  bleOnWrite,
+  bleOnConnect,
+  bleOnDisconnect,
+  bleNotify,
+  bleIsConnected,
+  bleClientCount,
+  bleSetName,
+  bleUntilConnected,
+  bleUntilConnectedStart,
+  bleSetTxPower,
+  bleStatus,
+} from './emit.js';
+import { callback } from './callback.js';
+
+/** Characteristic value encoding — drives both TS callback types and C++ marshalling. */
+export enum BleValueType {
+  Uint8 = 'uint8',
+  Uint16 = 'uint16',
+  Uint32 = 'uint32',
+  Int8 = 'int8',
+  Int16 = 'int16',
+  Int32 = 'int32',
+  Float32 = 'float32',
+  Utf8 = 'utf8',
+  Boolean = 'boolean',
+  Bytes = 'bytes',
+}
+
+/** GATT characteristic permission flags. Combine with `|`. */
+export enum BlePerm {
+  Read = 1,
+  Write = 2,
+  Notify = 4,
+}
+
+/** BLE peripheral status (mirrored by the runtime shim). */
+export enum BleStatus {
+  Idle = 0,
+  Initializing = 1,
+  Advertising = 2,
+  Connected = 3,
+  Error = 4,
+}
+
+export enum BleAdvertisingMode {
+  Connectable = 'connectable',
+  NonConnectable = 'non_connectable',
+}
+
+/** A well-known GATT characteristic entry in the catalog. */
+export interface GattCharacteristicDef {
+  readonly uuid: string;
+  readonly type: BleValueType;
+  readonly read?: boolean;
+  readonly write?: boolean;
+  readonly notify?: boolean;
+}
+
+/**
+ * Standard GATT services/characteristics. Autocomplete walks the hierarchy:
+ *   GATT.ENVIRONMENTAL. -> TEMPERATURE, HUMIDITY, ...
+ * Pass the .uuid, .type, and computed perms to BleServer.characteristic().
+ */
+export const GATT = {
+  DEVICE_INFO: {
+    MANUFACTURER_NAME: { uuid: '2A29', type: BleValueType.Utf8, read: true },
+    MODEL_NUMBER: { uuid: '2A24', type: BleValueType.Utf8, read: true },
+    FIRMWARE_REVISION: { uuid: '2A26', type: BleValueType.Utf8, read: true },
+  },
+  ENVIRONMENTAL: {
+    TEMPERATURE: { uuid: '2A6E', type: BleValueType.Int16, read: true, notify: true },
+    HUMIDITY: { uuid: '2A6F', type: BleValueType.Uint16, read: true, notify: true },
+    PRESSURE: { uuid: '2A6D', type: BleValueType.Uint32, read: true, notify: true },
+  },
+  BATTERY: {
+    LEVEL: { uuid: '2A19', type: BleValueType.Uint8, read: true, notify: true },
+  },
+} as const;
+
+/** The value passed to/from callbacks — narrowed per characteristic by type. */
+export type CharValue = number | string | boolean | Uint8Array;
+
+/**
+ * BLE GATT peripheral control, lowered to native ESP-IDF NimBLE
+ * (`nimble_host` / `ble_gap` / `ble_gatts`) by framework-esp32.
+ *
+ * No `include()` calls here — NimBLE headers are framework-owned and added via
+ * forcedIncludes when the program uses ble.* ops.
+ *
+ * Transpiler note: method bodies pass parameters directly into semantic calls
+ * (no local consts / module counters) so the resolver can statically track every
+ * argument. The characteristic index is carried through the chain via
+ * `this._charCount` fieldValues, mirroring how HttpRequest carries _method/_url.
+ */
+export class BleClass {
+  static readonly __instance_name = "Ble";
+
+  /** Begin building a GATT server with the given advertised device name. */
+  server(name: string): BleServer {
+    bleSetName(name);
+    return new BleServer(name, 0, 1);
+  }
+
+  /** Initialize NimBLE, register services, and start advertising. */
+  begin(): void {
+    bleServerBegin("TypeCAD");
+    bleAdvertiseStart();
+  }
+
+  advertise(): void { bleAdvertiseStart(); }
+  stopAdvertising(): void { bleAdvertiseStop(); }
+
+  /** Blocking at top level; cooperatively awaitable inside async functions. */
+  untilConnected(timeoutMs: number = 0): Promise<boolean> {
+    bleUntilConnected(timeoutMs);
+    return Promise.resolve(false);
+  }
+
+  untilConnectedStart(): void { bleUntilConnectedStart(); }
+  isConnected(): boolean { return bleIsConnected(); }
+  status(): BleStatus { return bleStatus() as BleStatus; }
+  clientCount(): number { return bleClientCount(); }
+  txPower(dbm: number): this { bleSetTxPower(dbm); return this; }
+  notify(index: number, value: number): void { bleNotify(index, value); }
+}
+
+/**
+ * Fluent GATT server builder. Returned by `Ble.server()`.
+ *
+ * Single-class fluent chain (like HttpRequest): characteristic() returns `this`,
+ * so onRead/onWrite/onSubscribe chain directly. The _charCount field tracks
+ * which characteristic slot the callbacks attach to.
+ *
+ * Field tracking (read by the transpiler resolver via ctor field assignment):
+ *   _name      — advertised device name
+ *   _charCount — current characteristic index (the last characteristic() target)
+ *   _svcCount  — current service index
+ */
+export class BleServer {
+  private _name: string;
+  private _charCount: number;
+  private _lastChar: number;
+  private _svcCount: number;
+
+  constructor(name: string, charCount: number, svcCount: number) {
+    this._name = name;
+    this._charCount = charCount;
+    this._lastChar = charCount;
+    this._svcCount = svcCount;
+  }
+
+  /** Add a characteristic by UUID, value type, and permissions.
+   *  Combine permissions with `|`: `BlePerm.Read | BlePerm.Notify`.
+   *  Returns this for chaining. */
+  characteristic(uuid: string, type: BleValueType, perms: number): this {
+    bleAddChar(this._charCount, uuid, type, perms, this._svcCount);
+    return this;
+  }
+
+  /** Begin a new service grouping. Subsequent characteristics attach to it. */
+  service(uuid: string): this {
+    bleAddService(uuid);
+    return this;
+  }
+
+  /** Register a read handler for the most recently added characteristic. */
+  onRead(handler: () => CharValue): this {
+    bleOnRead(this._lastChar, callback(handler));
+    return this;
+  }
+
+  /** Register a write handler for the most recently added characteristic. */
+  onWrite(handler: (value: number) => void): this {
+    bleOnWrite(this._lastChar, callback(handler));
+    return this;
+  }
+
+  /** Register a connect handler (called when a central connects). */
+  onConnect(handler: () => void): this {
+    bleOnConnect(callback(handler));
+    return this;
+  }
+
+  /** Register a disconnect handler (called when a central disconnects). */
+  onDisconnect(handler: () => void): this {
+    bleOnDisconnect(callback(handler));
+    return this;
+  }
+
+  /** Push a new value to subscribed clients on the most recently added characteristic. */
+  notify(value: number): void {
+    bleNotify(this._lastChar, value);
+  }
+
+  /** Initialize NimBLE, register services, and start advertising. */
+  begin(): void {
+    bleServerBegin(this._name);
+    bleAdvertiseStart();
+  }
+}
+
+export const Ble = new BleClass();

package/src/capacitive.ts

@@ -0,0 +1,31 @@
+/**
+ * CapacitiveClass — ESP32 on-chip capacitive touch pins.
+ *
+ * ESP32-family chips have dedicated capacitive-sensing GPIOs (10 on classic
+ * ESP32, up to 14 on S3) that read touch/proximity without external
+ * components — distinct from the I2C/SPI touch *display* controllers (FT6336U,
+ * GT911, etc.). Lowered to capacitive.* HAL ops: ESP-IDF's touch_sensor driver.
+ *
+ * Pin numbers are the touch-pad-capable GPIOs (GPIO4, GPIO0, GPIO2, ... on
+ * classic ESP32); the framework maps them to touch_channel indices.
+ */
+export class CapacitiveClass {
+  static readonly __instance_name = "Capacitive";
+
+  /** Read the raw capacitive value of a touch pin. Higher = more capacitance
+   *  (touched). The raw scale is chip-dependent; use a threshold calibrated
+   *  against the untouched reading. */
+  read(pin: number): number {
+    return capacitiveRead(pin);
+  }
+
+  /** True when the pin's reading exceeds `threshold` (a convenience over read()). */
+  isTouched(pin: number, threshold: number): boolean {
+    return capacitiveRead(pin) > threshold;
+  }
+}
+
+export const Capacitive = new CapacitiveClass();
+
+// ── Semantic primitive (resolved to capacitive.* HAL op by the transpiler) ──
+export function capacitiveRead(pin: number): number { return 0; }

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
 // ---------------------------------------------------------------------------
@@ -218,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
@@ -225,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; }