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

package/dist/capacitive.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare 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;
+    /** True when the pin's reading exceeds `threshold` (a convenience over read()). */
+    isTouched(pin: number, threshold: number): boolean;
+}
+export declare const Capacitive: CapacitiveClass;
+export declare function capacitiveRead(pin: number): number;

package/dist/capacitive.js

@@ -0,0 +1,27 @@
+/**
+ * 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 {
+    /** 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) {
+        return capacitiveRead(pin);
+    }
+    /** True when the pin's reading exceeds `threshold` (a convenience over read()). */
+    isTouched(pin, threshold) {
+        return capacitiveRead(pin) > threshold;
+    }
+}
+CapacitiveClass.__instance_name = "Capacitive";
+export const Capacitive = new CapacitiveClass();
+// ── Semantic primitive (resolved to capacitive.* HAL op by the transpiler) ──
+export function capacitiveRead(pin) { return 0; }

package/dist/emit.js

@@ -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.

package/dist/fs.d.ts

@@ -1,13 +1,33 @@
 /**
  * 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 declare class FSClass {
     static readonly __instance_name = "FS";
+    /** Mount the filesystem. Returns true on success. */
     begin(): boolean;
+    /** 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;
+    /** Write a string to a file (overwrites). Silently no-ops if the file
+     *  cannot be opened for writing. */
     writeText(path: string, content: string): void;
+    /** True if a file exists at the path. */
     exists(path: string): boolean;
+    /** Delete a file. Returns true if deleted. */
     remove(path: string): boolean;
 }
 export declare const FS: FSClass;
+export declare function fsBegin(): void;
+export declare function fsReadText(path: string): string;
+export declare function fsWriteText(path: string, content: string): void;
+export declare function fsExists(path: string): boolean;
+export declare function fsRemove(path: string): boolean;

package/dist/fs.js

@@ -1,39 +1,47 @@
-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 {
+    /** Mount the filesystem. Returns true on success. */
     begin() {
-        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) {
-        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, content) {
-        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) {
-        include("<FS.h>");
-        rawCpp(`return FS.exists(${path}.c_str());`);
-        return false;
+        return fsExists(path);
     }
+    /** Delete a file. Returns true if deleted. */
     remove(path) {
-        include("<FS.h>");
-        rawCpp(`return FS.remove(${path}.c_str());`);
-        return false;
+        return fsRemove(path);
     }
 }
 FSClass.__instance_name = "FS";
 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() { }
+export function fsReadText(path) { return ""; }
+export function fsWriteText(path, content) { }
+export function fsExists(path) { return false; }
+export function fsRemove(path) { return false; }

package/dist/index.d.ts

@@ -33,6 +33,18 @@ 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';

package/dist/index.js

@@ -26,6 +26,18 @@ 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';

package/dist/mdns.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare class MdnsClass {
+    static readonly __instance_name = "MDNS";
+    /** Initialize mDNS and set the host name (advertised as <name>.local). */
+    start(hostname: string): boolean;
+    /** Set/override the host name after start(). */
+    setHostname(name: string): void;
+    /** Publish a service instance. proto is "_tcp" or "_udp". */
+    addService(instance: string, proto: string, port: number): void;
+    /** Advertise that the device is reachable (sends a probe/announce). */
+    announce(): void;
+    /** Tear down the mDNS responder. */
+    stop(): void;
+}
+export declare const MDNS: MdnsClass;
+export declare function mdnsStart(hostname: string): void;
+export declare function mdnsSetHostname(name: string): void;
+export declare function mdnsAddService(instance: string, proto: string, port: number): void;
+export declare function mdnsAnnounce(): void;
+export declare function mdnsStop(): void;

package/dist/mdns.js

@@ -0,0 +1,43 @@
+/**
+ * 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 {
+    /** Initialize mDNS and set the host name (advertised as <name>.local). */
+    start(hostname) {
+        mdnsStart(hostname);
+        return true;
+    }
+    /** Set/override the host name after start(). */
+    setHostname(name) {
+        mdnsSetHostname(name);
+    }
+    /** Publish a service instance. proto is "_tcp" or "_udp". */
+    addService(instance, proto, port) {
+        mdnsAddService(instance, proto, port);
+    }
+    /** Advertise that the device is reachable (sends a probe/announce). */
+    announce() {
+        mdnsAnnounce();
+    }
+    /** Tear down the mDNS responder. */
+    stop() {
+        mdnsStop();
+    }
+}
+MdnsClass.__instance_name = "MDNS";
+export const MDNS = new MdnsClass();
+// ── Semantic primitives (resolved to mdns.* HAL ops by the transpiler) ──
+export function mdnsStart(hostname) { }
+export function mdnsSetHostname(name) { }
+export function mdnsAddService(instance, proto, port) { }
+export function mdnsAnnounce() { }
+export function mdnsStop() { }

package/dist/mqtt.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare 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;
+    /** 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;
+    /** Subscribe to a topic filter (e.g. "sensors/#"). */
+    subscribe(topic: string): void;
+    /** Publish a message to a topic. */
+    publish(topic: string, data: string): void;
+    /** True if the client is currently connected to the broker. */
+    connected(): boolean;
+    /** Disconnect from the broker and free the client. */
+    disconnect(): void;
+}
+export declare const MQTT: MqttClass;
+export declare function mqttConnect(brokerUri: string, clientId: string): void;
+export declare function mqttOnMessage(handler: string): void;
+export declare function mqttSubscribe(topic: string): void;
+export declare function mqttPublish(topic: string, data: string): void;
+export declare function mqttConnected(): boolean;
+export declare function mqttDisconnect(): void;

package/dist/mqtt.js

@@ -0,0 +1,48 @@
+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 {
+    /** Connect to a broker URI (e.g. "mqtt://broker.local" or "mqtts://..."). */
+    connect(brokerUri, clientId) {
+        mqttConnect(brokerUri, clientId);
+        return true;
+    }
+    /** Set a handler invoked for every received PUBLISH on a subscribed topic.
+     *  The handler receives (topic, payload). */
+    onMessage(handler) {
+        mqttOnMessage(callback(handler));
+    }
+    /** Subscribe to a topic filter (e.g. "sensors/#"). */
+    subscribe(topic) {
+        mqttSubscribe(topic);
+    }
+    /** Publish a message to a topic. */
+    publish(topic, data) {
+        mqttPublish(topic, data);
+    }
+    /** True if the client is currently connected to the broker. */
+    connected() {
+        return mqttConnected();
+    }
+    /** Disconnect from the broker and free the client. */
+    disconnect() {
+        mqttDisconnect();
+    }
+}
+MqttClass.__instance_name = "MQTT";
+export const MQTT = new MqttClass();
+// ── Semantic primitives (resolved to mqtt.* HAL ops by the transpiler) ──
+export function mqttConnect(brokerUri, clientId) { }
+export function mqttOnMessage(handler) { }
+export function mqttSubscribe(topic) { }
+export function mqttPublish(topic, data) { }
+export function mqttConnected() { return false; }
+export function mqttDisconnect() { }

package/dist/ota.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare 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;
+    /** Begin a manual update session (caller writes chunks via write()). */
+    begin(): boolean;
+    /** Write a chunk of firmware data to the OTA partition. */
+    write(chunk: string): void;
+    /** Finalize the update: verify, set the boot partition, and reboot. */
+    apply(): void;
+}
+export declare const OTA: OtaClass;
+export declare function otaFromUrl(url: string): boolean;
+export declare function otaBegin(): boolean;
+export declare function otaWrite(chunk: string): void;
+export declare function otaApply(): void;

package/dist/ota.js

@@ -0,0 +1,38 @@
+/**
+ * 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 {
+    /** 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) {
+        return otaFromUrl(url);
+    }
+    /** Begin a manual update session (caller writes chunks via write()). */
+    begin() {
+        return otaBegin();
+    }
+    /** Write a chunk of firmware data to the OTA partition. */
+    write(chunk) {
+        otaWrite(chunk);
+    }
+    /** Finalize the update: verify, set the boot partition, and reboot. */
+    apply() {
+        otaApply();
+    }
+}
+OtaClass.__instance_name = "OTA";
+export const OTA = new OtaClass();
+// ── Semantic primitives (resolved to ota.* HAL ops by the transpiler) ──
+export function otaFromUrl(url) { return false; }
+export function otaBegin() { return false; }
+export function otaWrite(chunk) { }
+export function otaApply() { }

package/dist/temperature.d.ts

@@ -0,0 +1,14 @@
+/**
+ * TemperatureClass — on-chip die temperature sensor.
+ *
+ * Lowered to the temp.* HAL op: ESP-IDF's temperature_sensor driver reads the
+ * internal die temperature in °C. Useful for thermal monitoring and
+ * compensation. No external components required.
+ */
+export declare class TemperatureClass {
+    static readonly __instance_name = "Temperature";
+    /** Read the on-chip die temperature in degrees Celsius. */
+    read(): number;
+}
+export declare const Temperature: TemperatureClass;
+export declare function tempRead(): number;

package/dist/temperature.js

@@ -0,0 +1,17 @@
+/**
+ * TemperatureClass — on-chip die temperature sensor.
+ *
+ * Lowered to the temp.* HAL op: ESP-IDF's temperature_sensor driver reads the
+ * internal die temperature in °C. Useful for thermal monitoring and
+ * compensation. No external components required.
+ */
+export class TemperatureClass {
+    /** Read the on-chip die temperature in degrees Celsius. */
+    read() {
+        return tempRead();
+    }
+}
+TemperatureClass.__instance_name = "Temperature";
+export const Temperature = new TemperatureClass();
+// ── Semantic primitive (resolved to temp.* HAL op by the transpiler) ──
+export function tempRead() { return 0; }

package/dist/timer.d.ts

@@ -3,33 +3,30 @@
  *
  * Hardware timers are distinct from the software-based setInterval/setTimeout
  * and are typically used for high-precision timing, PWM generation, or
- * interrupt-driven tasks.
+ * interrupt-driven tasks. Lowered to hwtimer.* HAL ops: ESP-IDF's GPTimer
+ * driver (driver/gptimer.h); Arduino's HardwareTimer (Timer0/1/2 on STM32).
+ *
+ * The instance index maps to the platform's timer numbering (ESP-IDF GPTimer
+ * unit 0..n, STM32 TIM0..n).
  */
 export declare class HardwareTimer {
     private _instance;
     constructor(instance: number);
-    /**
-     * Sets the timer frequency in Hertz.
-     * Note: The actual frequency may be limited by the hardware's clock dividers.
-     */
+    /** Sets the timer frequency in Hertz. */
     setFrequency(hz: number): void;
-    /**
-     * Attaches an interrupt handler that executes when the timer overflows.
-     */
+    /** Attaches an interrupt handler that executes when the timer overflows. */
     onOverflow(handler: () => void): void;
-    /**
-     * Starts the timer.
-     */
+    /** Starts the timer. */
     start(): void;
-    /**
-     * Stops the timer.
-     */
+    /** Stops the timer. */
     stop(): void;
-    /**
-     * Returns the bit resolution of the timer (e.g., 8, 16, 32).
-     */
+    /** Returns the bit resolution of the timer (e.g., 8, 16, 32). */
     getBits(): number;
 }
 export declare const Timer0: HardwareTimer;
 export declare const Timer1: HardwareTimer;
 export declare const Timer2: HardwareTimer;
+export declare function hwtimerSetFrequency(instance: number, hz: number): void;
+export declare function hwtimerOnOverflow(instance: number, handler: string): void;
+export declare function hwtimerStart(instance: number): void;
+export declare function hwtimerStop(instance: number): void;

package/dist/timer.js

@@ -1,44 +1,37 @@
-import { rawCpp, boardResolve } from './emit.js';
+import { boardResolve } from './emit.js';
 import { callback } from './callback.js';
 /**
  * HardwareTimer provides direct control over the board's hardware timers.
  *
  * Hardware timers are distinct from the software-based setInterval/setTimeout
  * and are typically used for high-precision timing, PWM generation, or
- * interrupt-driven tasks.
+ * interrupt-driven tasks. Lowered to hwtimer.* HAL ops: ESP-IDF's GPTimer
+ * driver (driver/gptimer.h); Arduino's HardwareTimer (Timer0/1/2 on STM32).
+ *
+ * The instance index maps to the platform's timer numbering (ESP-IDF GPTimer
+ * unit 0..n, STM32 TIM0..n).
  */
 export class HardwareTimer {
     constructor(instance) {
         this._instance = instance;
     }
-    /**
-     * Sets the timer frequency in Hertz.
-     * Note: The actual frequency may be limited by the hardware's clock dividers.
-     */
+    /** Sets the timer frequency in Hertz. */
     setFrequency(hz) {
-        rawCpp(`Timer${this._instance}.setFrequency(${hz});`);
+        hwtimerSetFrequency(this._instance, hz);
     }
-    /**
-     * Attaches an interrupt handler that executes when the timer overflows.
-     */
+    /** Attaches an interrupt handler that executes when the timer overflows. */
     onOverflow(handler) {
-        rawCpp(`Timer${this._instance}.onOverflow(${callback(handler)});`);
+        hwtimerOnOverflow(this._instance, callback(handler));
     }
-    /**
-     * Starts the timer.
-     */
+    /** Starts the timer. */
     start() {
-        rawCpp(`Timer${this._instance}.start();`);
+        hwtimerStart(this._instance);
     }
-    /**
-     * Stops the timer.
-     */
+    /** Stops the timer. */
     stop() {
-        rawCpp(`Timer${this._instance}.stop();`);
+        hwtimerStop(this._instance);
     }
-    /**
-     * Returns the bit resolution of the timer (e.g., 8, 16, 32).
-     */
+    /** Returns the bit resolution of the timer (e.g., 8, 16, 32). */
     getBits() {
         // "peripherals.timer" (singular) matches the board-resolver's array-key
         // derivation (TIMER_INSTANCES → peripherals.timer.<index>.*).
@@ -48,3 +41,8 @@ export class HardwareTimer {
 export const Timer0 = new HardwareTimer(0);
 export const Timer1 = new HardwareTimer(1);
 export const Timer2 = new HardwareTimer(2);
+// ── Semantic primitives (resolved to hwtimer.* HAL ops by the transpiler) ──
+export function hwtimerSetFrequency(instance, hz) { }
+export function hwtimerOnOverflow(instance, handler) { }
+export function hwtimerStart(instance) { }
+export function hwtimerStop(instance) { }

package/dist/wifi.d.ts

@@ -49,7 +49,6 @@ export declare class WiFiClass {
     clearCredentials(): void;
     onConnect(handler: () => void): void;
     onDisconnect(handler: () => void): void;
-    onGotIP(handler: () => void): void;
     startAP(ssid: string, password?: string): boolean;
     apChannel(ch: number): this;
     apHidden(hidden: boolean): this;

package/dist/wifi.js

@@ -100,9 +100,6 @@ export class WiFiClass {
     onDisconnect(handler) {
         wifiOnEvent("disconnect", callback(handler));
     }
-    onGotIP(handler) {
-        wifiOnEvent("got_ip", callback(handler));
-    }
     startAP(ssid, password) {
         return wifiApStart(ssid, password);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/hal",
-  "version": "1.0.0-alpha.7",
+  "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.7",
-    "@typecad/board-arduino-uno": "1.0.0-alpha.7",
-    "@typecad/mcu-atmega328p": "1.0.0-alpha.7"
+    "@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/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.

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/index.ts

@@ -44,6 +44,18 @@ 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';

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 {}

package/src/temperature.ts

@@ -0,0 +1,20 @@
+/**
+ * TemperatureClass — on-chip die temperature sensor.
+ *
+ * Lowered to the temp.* HAL op: ESP-IDF's temperature_sensor driver reads the
+ * internal die temperature in °C. Useful for thermal monitoring and
+ * compensation. No external components required.
+ */
+export class TemperatureClass {
+  static readonly __instance_name = "Temperature";
+
+  /** Read the on-chip die temperature in degrees Celsius. */
+  read(): number {
+    return tempRead();
+  }
+}
+
+export const Temperature = new TemperatureClass();
+
+// ── Semantic primitive (resolved to temp.* HAL op by the transpiler) ──
+export function tempRead(): number { return 0; }

package/src/timer.ts

@@ -1,12 +1,16 @@
-import { rawCpp, boardResolve } from './emit.js';
+import { boardResolve } from './emit.js';
 import { callback } from './callback.js';
 
 /**
  * HardwareTimer provides direct control over the board's hardware timers.
- * 
+ *
  * Hardware timers are distinct from the software-based setInterval/setTimeout
  * and are typically used for high-precision timing, PWM generation, or
- * interrupt-driven tasks.
+ * interrupt-driven tasks. Lowered to hwtimer.* HAL ops: ESP-IDF's GPTimer
+ * driver (driver/gptimer.h); Arduino's HardwareTimer (Timer0/1/2 on STM32).
+ *
+ * The instance index maps to the platform's timer numbering (ESP-IDF GPTimer
+ * unit 0..n, STM32 TIM0..n).
  */
 export class HardwareTimer {
   private _instance: number;
@@ -15,38 +19,27 @@ export class HardwareTimer {
     this._instance = instance;
   }
 
-  /**
-   * Sets the timer frequency in Hertz.
-   * Note: The actual frequency may be limited by the hardware's clock dividers.
-   */
+  /** Sets the timer frequency in Hertz. */
   setFrequency(hz: number): void {
-    rawCpp(`Timer${this._instance}.setFrequency(${hz});`);
+    hwtimerSetFrequency(this._instance, hz);
   }
 
-  /**
-   * Attaches an interrupt handler that executes when the timer overflows.
-   */
+  /** Attaches an interrupt handler that executes when the timer overflows. */
   onOverflow(handler: () => void): void {
-    rawCpp(`Timer${this._instance}.onOverflow(${callback(handler)});`);
+    hwtimerOnOverflow(this._instance, callback(handler));
   }
 
-  /**
-   * Starts the timer.
-   */
+  /** Starts the timer. */
   start(): void {
-    rawCpp(`Timer${this._instance}.start();`);
+    hwtimerStart(this._instance);
   }
 
-  /**
-   * Stops the timer.
-   */
+  /** Stops the timer. */
   stop(): void {
-    rawCpp(`Timer${this._instance}.stop();`);
+    hwtimerStop(this._instance);
   }
 
-  /**
-   * Returns the bit resolution of the timer (e.g., 8, 16, 32).
-   */
+  /** Returns the bit resolution of the timer (e.g., 8, 16, 32). */
   getBits(): number {
     // "peripherals.timer" (singular) matches the board-resolver's array-key
     // derivation (TIMER_INSTANCES → peripherals.timer.<index>.*).
@@ -57,3 +50,9 @@ export class HardwareTimer {
 export const Timer0 = new HardwareTimer(0);
 export const Timer1 = new HardwareTimer(1);
 export const Timer2 = new HardwareTimer(2);
+
+// ── Semantic primitives (resolved to hwtimer.* HAL ops by the transpiler) ──
+export function hwtimerSetFrequency(instance: number, hz: number): void {}
+export function hwtimerOnOverflow(instance: number, handler: string): void {}
+export function hwtimerStart(instance: number): void {}
+export function hwtimerStop(instance: number): void {}

package/src/wifi.ts

@@ -157,10 +157,6 @@ export class WiFiClass {
     wifiOnEvent("disconnect", callback(handler));
   }
 
-  onGotIP(handler: () => void): void {
-    wifiOnEvent("got_ip", callback(handler));
-  }
-
   startAP(ssid: string, password?: string): boolean {
     return wifiApStart(ssid, password);
   }