@typecad/hal 1.0.0-alpha.13 → 1.0.0-alpha.15

package/src/i2c-target.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// I2CTarget — the thin Zephyr-shaped I2C device
+//
+// One address on a bus, Zephyr's register verbs verbatim: writeReg/readReg
+// are i2c_reg_write_byte / i2c_reg_read_byte, updateReg is the native
+// read-modify-write (i2c_reg_update_byte — mask and all, no read-back race),
+// and write() is i2c_write. No begin/end transaction dance, no Wire
+// vocabulary — the controller device handle and the per-call address are all
+// Zephyr needs.
+//
+// `bus` is the board's bus instance export (I2C0/I2C1); the address is the
+// 7-bit form (0x44). The optional bus `hz` applies once (i2c_configure,
+// guarded) — Zephyr's own I2C_SPEED_SET mapping.
+// ----------------------------------------------------------------------------
+
+import { i2cRegWrite, i2cRegRead, i2cRegUpdate, i2cDevWrite } from './emit.js';
+
+export class I2CTarget {
+  private readonly _bus: string;
+  private readonly _address: number;
+  private readonly _hz: number;
+
+  /** Construct a device handle. `bus` is the bus instance (I2C0, I2C1, …);
+   *  `address` is the 7-bit I2C address; `hz` optionally sets the bus speed
+   *  once at first use (100k/400k/1M map to Zephyr's I2C_SPEED_* tiers). */
+  constructor(bus: string, address: number, opts?: { hz?: number }) {
+    this._bus = bus;
+    this._address = address;
+    this._hz = opts?.hz ?? 0;
+  }
+
+  /** Write one register byte (i2c_reg_write_byte). */
+  writeReg(reg: number, value: number): void {
+    i2cRegWrite(this._bus, this._address, this._hz, reg, value);
+  }
+
+  /** Read one register byte (i2c_reg_read_byte). */
+  readReg(reg: number): number {
+    return i2cRegRead(this._bus, this._address, this._hz, reg);
+  }
+
+  /** Read-modify-write one register field (i2c_reg_update_byte): the bits in
+   *  `mask` are replaced by `value`. Atomic on the wire — no read-back race. */
+  updateReg(reg: number, mask: number, value: number): void {
+    i2cRegUpdate(this._bus, this._address, this._hz, reg, mask, value);
+  }
+
+  /** Write raw bytes (i2c_write) — commands and data with no register
+   *  convention. */
+  write(data: number[] | Uint8Array): void {
+    i2cDevWrite(this._bus, this._address, this._hz, data);
+  }
+
+  /** The 7-bit I2C address this target addresses. Exposed so I2CTarget
+   *  structurally satisfies the @typecad/simulator II2CDeviceAccessor
+   *  contract (`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;
+  }
+}

package/src/i2c.ts

@@ -1,167 +1,29 @@
-import { i2cBegin, i2cEnd, i2cSetClock, i2cBeginTx, i2cWrite, i2cWriteBuffer, i2cEndTx, i2cRequestFrom, i2cAvailable, i2cRead, i2cReadBuffer, rawCpp } from './emit.js';
-import { include } from './include.js';
-
-export class I2CDevice {
-  private _bus: string;
-  private _address: number;
-
-  constructor(bus: string, address: number) {
-    this._bus = bus;
-    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);
-    i2cWrite(this._bus, register);
-    i2cWrite(this._bus, value);
-    i2cEndTx(this._bus, true);
-  }
-
-  readByte(register: number): number {
-    include("<Wire.h>");
-    i2cBeginTx(this._bus, this._address);
-    i2cWrite(this._bus, register);
-    i2cEndTx(this._bus, false);
-    i2cRequestFrom(this._bus, this._address, 1);
-    return i2cRead(this._bus);
-  }
-
-  writeBytes(register: number, data: number[] | Uint8Array): void {
-    include("<Wire.h>");
-    i2cBeginTx(this._bus, this._address);
-    i2cWrite(this._bus, register);
-    i2cWriteBuffer(this._bus, data);
-    i2cEndTx(this._bus, true);
-  }
-
-  readBytes(register: number, count: number): Uint8Array {
-    include("<Wire.h>");
-    i2cBeginTx(this._bus, this._address);
-    i2cWrite(this._bus, register);
-    i2cEndTx(this._bus, false);
-    i2cRequestFrom(this._bus, this._address, count, true);
-    // 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);
-  }
-}
-
-export class I2CBus {
-  static readonly __includes = ["<Wire.h>"];
-  private _bus: string;
-
-  constructor(bus: string) {
-    this._bus = bus;
-  }
-
-  device(address: number): I2CDevice {
-    return new I2CDevice(this._bus, address);
-  }
-
-  begin(): this {
-    include("<Wire.h>");
-    i2cBegin(this._bus);
-    return this;
-  }
-
-  beginSlave(address: number): void {
-    i2cBegin(this._bus, address);
-  }
-
-  end(): void {
-    i2cEnd(this._bus);
-  }
-
-  setClock(hz: number): void {
-    i2cSetClock(this._bus, hz);
-  }
-
-  /** Recover a locked I2C bus by clocking SCL until the stuck slave releases SDA.
-   *
-   *  NOTE: This references the board-defined `SCL` pin macro. All current MCU
-   *  packages (atmega328p, esp32, esp32c3, esp32c6, esp32s3) export SCL, so
-   *  this works in practice. A fully portable version would resolve the SCL
-   *  pin number via a board constant (e.g. peripherals.i2c.0.sclPin), but that
-   *  requires adding resolved numeric pin fields to the board-constants
-   *  pipeline — deferred for now. */
-  recover(): void {
-    include("<Wire.h>");
-    rawCpp(`pinMode(SCL, OUTPUT);`);
-    rawCpp(`for (int i = 0; i < 16; i++) {`);
-    rawCpp(`  digitalWrite(SCL, LOW);`);
-    rawCpp(`  delayMicroseconds(10);`);
-    rawCpp(`  digitalWrite(SCL, HIGH);`);
-    rawCpp(`  delayMicroseconds(10);`);
-    rawCpp(`}`);
-    rawCpp(`${this._bus}.begin();`);
-  }
-
-  take(): this | null {
-    include("<Wire.h>");
-    return this;
-  }
-
-  release(): void {
-    // No-op for standard Arduino.
-  }
-
-  writeByte(address: number, register: number, value: number): void {
-    i2cBeginTx(this._bus, address);
-    i2cWrite(this._bus, register);
-    i2cWrite(this._bus, value);
-    i2cEndTx(this._bus, true);
-  }
-
-  readByte(address: number, register: number): number {
-    i2cBeginTx(this._bus, address);
-    i2cWrite(this._bus, register);
-    i2cEndTx(this._bus, false);
-    i2cRequestFrom(this._bus, address, 1);
-    return i2cRead(this._bus);
-  }
-
-  // Low-level Wire API pass-through methods
-  beginTransmission(address: number): void {
-    i2cBeginTx(this._bus, address);
-  }
-
-  write(data: number | number[] | Uint8Array): void {
-    i2cWrite(this._bus, data);
-  }
-
-  endTransmission(stop?: boolean): number {
-    return i2cEndTx(this._bus, stop ?? true);
-  }
-
-  requestFrom(address: number, quantity: number, stop?: boolean): number {
-    return i2cRequestFrom(this._bus, address, quantity, stop ?? true);
-  }
-
-  available(): number {
-    return i2cAvailable(this._bus);
-  }
-
-  read(): number {
-    return i2cRead(this._bus);
-  }
-}
-
-
-/** Map TypeCAD I2C instance number to Arduino C++ object name. I2C0→Wire, I2C1→Wire1 */
-export function i2cName(instance: number): string {
-  return instance === 0 ? "Wire" : `Wire${instance}`;
-}
+// ---------------------------------------------------------------------------
+// I2C — controller selector (legacy Wire API removed)
+//
+// The bus singletons (I2C0/I2C1…) are CONTROLLER SELECTORS; device(address)
+// hands back the FUNCTIONAL I2CTarget directly — register verbs callable with
+// no further construction (`I2C0.device(0x44).writeReg(...)`) and the same
+// fact-carrier `new Sensor(SENSOR.x, I2C0.device(0x44))` consumes. Explicit
+// construction `new I2CTarget(I2C0, 0x44)` is equivalent. The former
+// begin/endTransmission/requestFrom Wire reconstruction was removed with the
+// legacy Arduino surface; the standalone I2CDevice fact-carrier was absorbed
+// by I2CTarget (same facts, plus the verbs).
+// ----------------------------------------------------------------------------
+
+import { I2CTarget } from './i2c-target.js';
+
+export class I2CBus {
+  private _bus: string;
+
+  constructor(bus: string) {
+    this._bus = bus;
+  }
+
+  /** The functional device target at `address` on this controller —
+   *  register verbs callable directly, and the fact-carrier `new Sensor(...)`
+   *  accepts. Equivalent to `new I2CTarget(this, address)`. */
+  device(address: number): I2CTarget {
+    return new I2CTarget(this._bus, address);
+  }
+}

package/src/index.ts

@@ -4,65 +4,51 @@
 // status enums, capability guards, PinCapabilityFlags, IToneAttachment, ...)
 // now live in @typecad/simulator. Import them from there.
 export type { DigitalValue, AnalogValue } from './types.js';
-export { PinMode, InterruptMode } from './types.js';
-export type { IPinGroup, PinGroupMember } from './types.js';
-export { createPinGroup } from './types.js';
+export { PinMode } from './types.js';
 
 export type { InterruptHandler } from './types.js';
 
 export type { ArchitectureIdentifier } from './types.js';
 
-// Protocol-shape types (re-exported downstream by @typecad/framework-arduino)
-export type { I2CAddress } from './types.js';
-export type { SPIBitOrder, SPIMode, SPISettings } from './types.js';
+export type { SerialValue } from './types.js';
 
 export { include } from './include.js';
 export { board } from './board.js';
 export { callback } from './callback.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';
-export { abs, min, max, NumClass, Num, MapChain, ConstrainChain } from './math.js';
-export { Pulse, pulseIn, pulseInLong } from './pulse.js';
-export { Shift, shiftIn, shiftOut } from './shift.js';
+export { TimeClass, Time } from './time.js';
+export { abs, min, max, NumClass, Num } from './math.js';
+
 export { Random } from './random.js';
-export { randomSeed, random } from './random.js';
-export { noInterrupts, interrupts, attachInterrupt, detachInterrupt } from './interrupts.js';
-export { Pin, OutputPin, InputPin, ToneChain } from './gpio.js';
-export { I2CBus, I2CDevice, i2cName } from './i2c.js';
-export { SPIBus, SPIDevice, spiName } from './spi.js';
-export { SerialPort, serialName } from './uart.js';
-export { createHALInstances } from './utils.js';
+export { Pin } from './gpio.js';
+export { GPIO } from './gpio-pin.js';
+export { shiftOut, shiftIn } from './shift-pin.js';
+export { PWM } from './pwm-pin.js';
+export { ADC } from './adc-pin.js';
+export { DAC } from './dac-pin.js';
+export { Watchdog } from './watchdog.js';
+export { Counter } from './counter.js';
+export { I2CTarget } from './i2c-target.js';
+export { SPITarget } from './spi-target.js';
+export { UART } from './uart-port.js';
+export { Thread } from './thread.js';
+export { I2CBus } from './i2c.js';
+export { Sensor } from './sensor.js';
+export { SENSOR, CHAN, SENSOR_PART_INFO } from './sensor-catalog.generated.js';
+export { ZEPHYR_ADC_GAINS, ZEPHYR_ADC_REFERENCES, ZEPHYR_GPIO_FLAGS, ZEPHYR_GPIO_INTS } from './zephyr-tokens.generated.js';
+export type { SensorToken, SensorChannelName, SensorPartInfo } from './sensor-catalog.generated.js';
+export { SPIBus } from './spi.js';
+export { USBConsole } from './usb.js';
 // Register-mapped struct decorators (compile-time markers, erased by transpiler)
 export type { Bit, Bits } from './register.js';
 export { register, bits } from './register.js';
-export { EEPROMClass, EEPROM } from './eeprom.js';
-export { WDTClass, WDT } from './wdt.js';
-export { ADCClass, ADC } from './adc.js';
-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 { Store } from './preferences.js';
+export { File } from './fs.js';
+export { Mqtt } from './mqtt.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 { WiFi, Scan, WiFiAP } from './wifi.js';
+export { Request } from './http.js';
+export type { RequestOpts } from './http.js';
+export { BLE, BleChain, BleValueType, BlePerm, GATT } from './ble.js';
 export type { GattCharacteristicDef, CharValue } from './ble.js';
-export { RmtChannel } from './rmt.js';

package/src/math.ts

@@ -1,15 +1,12 @@
-export class MapChain {
-  constructor(value: number) {}
-  from(low: number, high: number): MapChain { return this; }
-  to(low: number, high: number): number { return 0; }
-  toPercent(): number { return 0; }
-  toByte(): number { return 0; }
-}
-
-export class ConstrainChain {
-  constructor(value: number) {}
-  between(low: number, high: number): number { return 0; }
-}
+// ---------------------------------------------------------------------------
+// Num — numeric conveniences over the strategy polyfill.
+//
+// The fluent map/constrain chains (Num.map(x).from(a,b).to(c,d)) were dropped
+// with the free map()/constrain() functions in the Zephyr-first cleanup —
+// the remap/clamp arithmetic is a three-line helper in user code, and no
+// backend honors it natively. abs/min/max stay (bare-call polyfills exist on
+// every framework).
+// ---------------------------------------------------------------------------
 
 export class NumClass {
   // No __instance_name — Num methods must NOT be intercepted by the HAL
@@ -21,8 +18,6 @@ export class NumClass {
   abs(x: number): number { return 0; }
   min(a: number, b: number): number { return 0; }
   max(a: number, b: number): number { return 0; }
-  constrain(value: number): ConstrainChain { return new ConstrainChain(value); }
-  map(value: number): MapChain { return new MapChain(value); }
 }
 
 export const Num = new NumClass();

package/src/mqtt.ts

@@ -1,26 +1,44 @@
+// ---------------------------------------------------------------------------
+// Mqtt — the thin pub/sub client
+//
+// The broker URI and client id are CONSTRUCTION facts; the verbs map onto
+// the Zephyr MQTT client (mqtt_connect / mqtt_publish / mqtt_subscribe,
+// with a poll thread feeding mqtt_input/mqtt_live):
+//
+//   connect()     → establish the broker session (poll linked() after —
+//                   the Zephyr client connects in its poll thread)
+//   onMessage(cb) → handler for every received PUBLISH on a subscribed
+//                   topic — receives (topic, payload)
+//   subscribe(t)  → subscribe to a topic filter ("sensors/#")
+//   publish(t, s) → publish a message
+//   linked()      → the broker session is up
+//   disconnect()  → disconnect and free the client
+// ----------------------------------------------------------------------------
+
 import { callback } from './callback.js';
+import {
+  mqttConnect, mqttOnMessage, mqttSubscribe, mqttPublish, mqttConnected, mqttDisconnect,
+} from './emit.js';
+
+export class Mqtt {
+  private readonly _uri: string;
+  private readonly _clientId: string;
+
+  /** Construct the client for a broker ("mqtt://broker.local" or
+   *  "mqtts://..." for TLS). */
+  constructor(uri: string, opts: { clientId: string }) {
+    this._uri = uri;
+    this._clientId = opts.clientId;
+  }
 
-/**
- * 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;
+  /** Connect to the broker. Requires a network connection (WiFi) first.
+   *  The Zephyr client completes the session in its poll thread — poll
+   *  linked() afterwards. */
+  connect(): void {
+    mqttConnect(this._uri, this._clientId);
   }
 
-  /** Set a handler invoked for every received PUBLISH on a subscribed topic.
-   *  The handler receives (topic, payload). */
+  /** Handler invoked for every received PUBLISH on a subscribed topic. */
   onMessage(handler: (topic: string, payload: string) => void): void {
     mqttOnMessage(callback(handler));
   }
@@ -35,8 +53,8 @@ export class MqttClass {
     mqttPublish(topic, data);
   }
 
-  /** True if the client is currently connected to the broker. */
-  connected(): boolean {
+  /** True while the broker session is up. */
+  linked(): boolean {
     return mqttConnected();
   }
 
@@ -45,13 +63,3 @@ export class MqttClass {
     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/preferences.ts

@@ -1,87 +1,78 @@
+// ---------------------------------------------------------------------------
+// Store — the thin persistent key/value store
+//
+// The namespace is the CONSTRUCTION fact: `new Store('app')` rides every op
+// as the settings subtree prefix (tc/app/<key> on Zephyr's settings/ZMS
+// backend). There is no session to open or close — the backend loads once at
+// boot and every verb maps 1:1 onto a settings write/read/delete:
+//
+//   setInt/getInt, setFloat/getFloat, setBool/getBool,
+//   setString/getString  — typed pairs; get takes a REQUIRED default (no
+//                          hidden = 0 magic value)
+//   remove(key)          → settings_delete
+//   clear()              → delete every tc/<ns>/* key this app wrote
+//
+// Values survive re-flashing the application: they live in the board's
+// storage partition, not the app image.
+// ----------------------------------------------------------------------------
+
 import {
-  preferencesBegin,
-  preferencesEnd,
-  preferencesClear,
-  preferencesRemove,
-  preferencesPutInt,
-  preferencesGetInt,
-  preferencesPutUInt,
-  preferencesGetUInt,
-  preferencesPutBool,
-  preferencesGetBool,
-  preferencesPutFloat,
-  preferencesGetFloat,
-  preferencesPutString,
-  preferencesGetString,
+  preferencesPutInt, preferencesGetInt,
+  preferencesPutFloat, preferencesGetFloat,
+  preferencesPutBool, preferencesGetBool,
+  preferencesPutString, preferencesGetString,
+  preferencesRemove, preferencesClear,
 } from './emit.js';
 
-/**
- * Preferences — a persistent key/value store, lowered to native NVS
- * (nvs_flash / nvs_open / nvs_set_* / nvs_get_*) by framework-esp32.
- *
- * No include() calls here — NVS headers are framework-owned and added via
- * forcedIncludes when the program uses preferences.* ops. Method bodies pass
- * parameters directly into semantic calls so the resolver can statically track
- * every argument (matching the WiFi/HTTP HAL pattern).
- */
-export class PreferencesClass {
-  static readonly __instance_name = "Preferences";
-
-  begin(name: string, readOnly: boolean = false): void {
-    preferencesBegin(name, readOnly);
-  }
-
-  end(): void {
-    preferencesEnd();
-  }
-
-  clear(): void {
-    preferencesClear();
-  }
+export class Store {
+  private readonly _ns: string;
 
-  remove(key: string): void {
-    preferencesRemove(key);
+  /** Construct the store for a namespace ('app' → settings subtree tc/app/). */
+  constructor(ns: string) {
+    this._ns = ns;
   }
 
-  putInt(key: string, value: number): void {
-    preferencesPutInt(key, value);
+  setInt(key: string, value: number): void {
+    preferencesPutInt(this._ns, key, value);
   }
 
-  getInt(key: string, defaultValue: number = 0): number {
-    return preferencesGetInt(key, defaultValue);
+  getInt(key: string, defaultValue: number): number {
+    return preferencesGetInt(this._ns, key, defaultValue);
   }
 
-  putUInt(key: string, value: number): void {
-    preferencesPutUInt(key, value);
+  setFloat(key: string, value: number): void {
+    preferencesPutFloat(this._ns, key, value);
   }
 
-  getUInt(key: string, defaultValue: number = 0): number {
-    return preferencesGetUInt(key, defaultValue);
+  getFloat(key: string, defaultValue: number): number {
+    return preferencesGetFloat(this._ns, key, defaultValue);
   }
 
-  putBool(key: string, value: boolean): void {
-    preferencesPutBool(key, value);
+  setBool(key: string, value: boolean): void {
+    preferencesPutBool(this._ns, key, value);
   }
 
-  getBool(key: string, defaultValue: boolean = false): boolean {
-    return preferencesGetBool(key, defaultValue);
+  getBool(key: string, defaultValue: boolean): boolean {
+    return preferencesGetBool(this._ns, key, defaultValue);
   }
 
-  putFloat(key: string, value: number): void {
-    preferencesPutFloat(key, value);
+  setString(key: string, value: string): void {
+    preferencesPutString(this._ns, key, value);
   }
 
-  getFloat(key: string, defaultValue: number = 0): number {
-    return preferencesGetFloat(key, defaultValue);
+  /** Read a string back. The value lands in the shim's ring buffer — copy
+   *  what you need before the next get on the same key. */
+  getString(key: string, defaultValue: string): string {
+    return preferencesGetString(this._ns, key, defaultValue);
   }
 
-  putString(key: string, value: string): void {
-    preferencesPutString(key, value);
+  /** Delete one key (flash + cache). No-op when absent. */
+  remove(key: string): void {
+    preferencesRemove(this._ns, key);
   }
 
-  getString(key: string, defaultValue: string = ""): string {
-    return preferencesGetString(key, defaultValue);
+  /** Delete every key under this store's namespace. */
+  clear(): void {
+    preferencesClear(this._ns);
   }
 }
-
-export const Preferences = new PreferencesClass();