@typecad/hal 1.0.0-alpha.14 → 1.0.0-alpha.16

package/README.md

@@ -1,127 +1,185 @@
 # `@typecad/hal`
 
 Hardware abstraction layer for [TypeCAD](https://cuttlefish.typecad.net) —
-GPIO, I2C, SPI, UART, timers, ADC/DAC, EEPROM, WiFi/HTTP, and more, written as
-regular TypeScript.
+GPIO, timing, threads, PWM/ADC/DAC, I2C/SPI/UART/USB, persistent storage,
+sensors, and WiFi/HTTP/MQTT/BLE, written as regular TypeScript.
 
 `@typecad/hal` is what firmware code imports to talk to hardware. You write
-normal TypeScript (`pin.high()`, `i2c.write(...)`, `Serial0.print(...)`); the
-TypeCAD transpiler (`@typecad/cuttlefish`) resolves each HAL call against the
-active MCU/board packages and emits the equivalent C++ at build time.
+normal TypeScript (`led.toggle()`, `bus.writeReg(...)`, `Time.sleep(250)`);
+the transpiler (`@typecad/cuttlefish`) resolves each HAL call against the
+active board's facts and emits the equivalent C++ at build time. There are
+no runtime fallbacks — if the HAL doesn't lower it, it doesn't appear in the
+firmware.
 
 ## Install
 
+HAL projects are scaffolded by cuttlefish, which wires the framework,
+board target, and the Zephyr SDK for you:
+
 ```bash
-npm install @typecad/hal @typecad/cuttlefish
+npx @typecad/cuttlefish create my-firmware
+cd my-firmware && npx cuttlefish build --compile
 ```
 
-You'll also want an MCU package (e.g. `@typecad/mcu-esp32`) and a board package
-(e.g. `@typecad/board-esp32-devkit`) to pin and bus definitions for your target.
-
-## Overview
-
-The HAL is built on three compile-time directives that look like ordinary
-TypeScript but are intercepted by the transpiler:
-
-- **`emit(text)`** — appends a line of C++ to the output (with parameter/field substitution).
-- **`include(header)`** — adds a deduplicated `#include` to the output.
-- **`board(path)`** — looks up a board-specific constant (e.g. pin numbers) inside an `emit()` template.
-
-This means there are no runtime fallbacks: if the HAL doesn't `emit()` it, it
-doesn't appear in the firmware. See [`HAL-GUIDE.md`](./HAL-GUIDE.md) for how to
-add new HAL features.
+A project imports hardware from **`@typecad/board`** — the module cuttlefish
+generates per project from the Zephyr board catalog. That module is the
+narrowed gateway: it re-exports a hardware class only when this board's
+facts support it, so importing unavailable hardware fails at module
+resolution (editor and transpile), not at a deep diagnostic. `@typecad/hal`
+is the implementation package.
 
 ## What's included
 
+Every class is thin and Zephyr-shaped: construction carries the facts, and
+each method maps onto the kernel/driver API verbatim — no Arduino
+vocabulary, no transaction dance.
+
 | Area | Exports |
 | --- | --- |
-| **Digital I/O** | `Pin`, `OutputPin`, `InputPin`, `PinMode`, `HIGH`, `LOW`, `INPUT`, `OUTPUT`, `INPUT_PULLUP` |
-| **Pin groups** | `createPinGroup`, `IPinGroup`, `PinCapabilityFlags` |
-| **Analog** | `ADC`, `ADCClass`, `DAC`, `DACClass`, `AnalogValue` |
-| **I2C** | `I2CBus`, `II2CBus`, `I2CStatus`, `i2cName` |
-| **SPI** | `SPIBus`, `ISPIBus`, `SPIStatus`, `SPISettings`, `spiName` |
-| **UART / Serial** | `SerialPort`, `IUARTBus`, `UARTStatus`, `serialName` |
-| **Networking** | `WiFi`, `WiFiClass`, `WiFiStatus`, `WiFiEncryption`, `Http`, `HttpClass`, `HttpRequest`, `HttpMethod` |
-| **Timing** | `delay`, `millis`, `micros`, `delayMicroseconds`, `Timing`, `map`, `constrain` |
-| **Pulse / Shift** | `pulseIn`, `shiftIn`, `shiftOut` |
-| **Interrupts** | `attachInterrupt`, `detachInterrupt`, `noInterrupts`, `interrupts`, `InterruptMode` |
-| **Timers** | `HardwareTimer`, `Timer0`, `Timer1`, `Timer2` |
-| **Storage** | `EEPROM`, `Preferences` (NVFlash), `FS` |
-| **Power / Watchdog** | `Power`, `WDT` (`WDTO_1S`, …) |
-| **Math / Random** | `abs`, `min`, `max`, `Num`, `random`, `randomSeed` |
-| **Async** | `Async` (cooperative scheduling) |
-| **Directives** | `emit`, `include`, `board`, `callback` |
+| **Digital I/O** | `Pin` (identity), `GPIO` (configure/read/write/toggle, `onInterrupt`/`offInterrupt`), `shiftOut`/`shiftIn` |
+| **Timing** | `Time` (`sleep`/`now`/`nowUs`/`busyWaitUs`) |
+| **Concurrency** | `Thread` (kernel threads), `Async` (cooperative await), `Counter` (hardware timers) |
+| **PWM** | `PWM` (`setPulse`/`setDuty`/`setPeriod`; ns-true verbs) |
+| **Analog in** | `ADC` (`read`/`readMillivolts`, gain/reference tokens; every ADC controller the SoC declares) |
+| **Analog out** | `DAC` (`write`) |
+| **I2C** | `I2CTarget` (register verbs; also the Sensor fact-carrier), `I2CBus` (controller selector: `I2C0.device(0x44)` returns a ready target) |
+| **SPI** | `SPITarget` (transceive/register verbs), `SPIBus` (controller selector: `SPI0.device(PA4)` returns a ready target) |
+| **UART** | `UART` (writeLine/read ring) — the board exports ready-to-use instances (`UART0.writeLine(...)`) |
+| **USB** | `USBConsole` (CDC console: open/write/read/linked) |
+| **Storage** | `Store` (persistent typed keys), `File` (littlefs text files) |
+| **Watchdog** | `Watchdog` |
+| **Sensors** | `Sensor` + the generated `SENSOR`/`CHAN` catalog |
+| **Networking** | `WiFi`, `Request` (HTTP), `Mqtt`, `BLE` (GATT peripheral) |
+| **Math / Random** | `abs`/`min`/`max`/`Num`, `Random` (`seed`/`upTo`/`between`/`int`) |
+| **Registers** | `@register`/`@bits` (memory-mapped struct decorators) |
+| **Zephyr tokens** | `ZEPHYR_ADC_GAINS`, `ZEPHYR_ADC_REFERENCES`, `ZEPHYR_GPIO_FLAGS`, `ZEPHYR_GPIO_INTS` (generated from the pinned tree's headers) |
+
+Periodic and deferred work is a `Thread` (or a `Counter` for hardware
+timers) — there are no JS-named timers (`setInterval`/`setTimeout`) on
+embedded targets.
+
+## Compile-time directives
+
+Directives look like ordinary TypeScript but are intercepted by the
+transpiler:
+
+- **`rawCpp(text)`** — appends a line of C++ to the output (with field/parameter substitution).
+- **`rawCppExpr(text)`** — the same, in expression position.
+- **`include(header)`** — adds a deduplicated `#include` to the output.
+- **`board(path)`** — resolves a board-fact constant inside a template.
+
+`callback(fn)` registers a function value so it can be passed to APIs that
+take handlers (interrupts, threads, bus events). See
+[`HAL-GUIDE.md`](./HAL-GUIDE.md) for how HAL features are built.
 
 ## Example
 
 ```ts
-import { OutputPin, HIGH, LOW, delay } from '@typecad/hal';
+import { LED } from '@typecad/board';
+import { GPIO, Time, Thread } from '@typecad/hal';
+
+const led = new GPIO(LED, GPIO.OUTPUT);
+
+// A kernel thread blinks concurrently with main.
+const blinker = new Thread(0, { stackKb: 2 });
+blinker.start((): void => {
+  while (true) {
+    led.toggle();
+    Time.sleep(250);
+  }
+});
+blinker.join();
+```
 
-const led = new OutputPin('LED_BUILTIN');
+Bus singletons from `@typecad/board` are directly usable — the board
+exports functional instances (no strings, no construction, and unavailable
+buses are simply not exported):
 
-export function setup() {
-  led.mode();
-}
+```ts
+import { UART0 } from '@typecad/board';
 
-export function loop() {
-  led.write(HIGH);
-  delay(500);
-  led.write(LOW);
-  delay(500);
-}
+UART0.writeLine('hello');         // usart1, default 115200
 ```
 
-For I2C/SPI/UART, instantiate the bus class with the board's pinned instance
-(see your `@typecad/board-*` package for available bus names).
-
-## Hardware tests
+Explicit construction remains for non-default facts, and takes the board
+instance or the name; targets and sensors carry the bus instance and the
+7-bit address / chip-select from construction:
 
-The [`tests/`](./tests/) directory contains a hardware test suite that
-exercises every AVR-compilable HAL subsystem against real Arduino Uno hardware,
-using [`@typecad/expect`](https://cuttlefish.typecad.net)
-(`describe()` / `.it()` / `.expect()` / `done()`) over serial. Each file covers
-one subsystem: GPIO, timing, math, random, pulse, shift, interrupts, UART,
-I2C, SPI, ADC, EEPROM, WDT, Preferences, async, and constants.
+```ts
+import { I2C0, SENSOR, CHAN } from '@typecad/board';
 
-ESP32-only subsystems (DAC, `FS`, `Power`, `HardwareTimer`) are intentionally
-omitted — they require an ESP32 target.
+// device() hands back the FUNCTIONAL target — verbs callable immediately,
+// and the same object is the Sensor fact-carrier.
+const dev = I2C0.device(0x44);
+dev.writeReg(0x30, 0xA2);   // i2c_reg_write_byte
 
-Run on a connected Uno:
+const sht3x = new Sensor(SENSOR.sensirion_sht3xd, I2C0.device(0x44));
+sht3x.fetch();
+const temp = sht3x.get(CHAN.AMBIENT_TEMP);
 
-```bash
-npm exec --workspace @typecad/hal -- cuttlefish-test
+// Explicit construction is equivalent: new I2CTarget(I2C0, 0x44).
 ```
 
-The suite is configured by [`cuttlefish.config.ts`](./cuttlefish.config.ts).
-Like the [`@typecad/framework-arduino`](https://cuttlefish.typecad.net)
-tests, it imports through `@typecad/board` (the board package) and ambient globals
-declared in `cuttlefish-env.d.ts`, never directly from `@typecad/board`, so the
-transpiler resolves each call against the active MCU/board packages.
-
-### Skipped on AVR
-
-One file is skipped on AVR by a `@typecad-skip-target` directive, for a
-genuine hardware reason (not a transpiler limitation):
+## Hardware tests
 
-- **`08-uart`** — the Uno has a single hardware UART, which the test runner
-  itself uses as the `[TC:...]` protocol channel. Any `UART0` call disrupts
-  that channel. Runs on multi-UART targets (ESP32).
+The [`tests/`](./tests/) directory is the HAL hardware suite — the on-metal
+proof that the HAL works. It runs via
+[`@typecad/expect`](../expect/README.md) (`describe()` / `.it()` /
+`.expect()` / `done()`) over the board's console, and one shared suite
+covers every board:
+
+- **`tests/common/`** — board-agnostic groups, one file per subsystem:
+  timing, math, random, shift, interrupts, UART, I2C, ADC, WDT, Store,
+  File, async, constants, Counter.
+- **`tests/board/`** — board-level groups (GPIO, PWM, SPI, LED). These
+  import **role names** from the `@typecad/test-pins` virtual module
+  (`GPIO_OUT`, `PWM_PIN`, `ADC_PIN`, `I2C_BUS`, …); each board's
+  `boards/<name>/test-pins.json` declares which pins fill each role, and the
+  runner substitutes them before transpiling. A file whose required roles
+  (declared with `// @typecad-requires-roles …`) are absent skips cleanly —
+  coverage differences are data, never per-board test copies.
+- **`tests/network/`** — on-hardware HTTP/MQTT/BLE suites against a local
+  host server (see [`tests/network/README.md`](./tests/network/README.md)).
+- **`tests/wired/`** — opt-in loopback tier (jumper `gpioOut` → `gpioIn`);
+  not part of the default runs.
+
+Each board has a config in [`boards/`](./boards/) (currently the WeAct
+Black Pill STM32F411 and the ESP32-S3 DevKitC). Run a suite:
 
-The async test (`15-async`) **runs on AVR**: on heap-less targets the
-transpiler emits a fixed-capacity, allocation-free static timer/task runtime
-(`async-runtime-static.ts`) in place of the full `Promise<T>` runtime used on
-ESP32, so `Async.sleep`/`yield`/`sleepUntil`/`currentTask` link and run on the
-ATmega328P.
+```bash
+npm run test:hw --workspace @typecad/hal            # Black Pill (ST-Link + console UART)
+npm run test:hw:esp32s3 --workspace @typecad/hal    # DevKitC (esptool + CH34x console)
+```
 
-ESP32-only subsystems (DAC, `FS`, `Power`, `HardwareTimer`) are omitted
-entirely — they require an ESP32 target.
+The `[TC:...]` test protocol rides the board's console (its devicetree
+`zephyr,console` node). Port resolution: `--port` / `CUTTLEFISH_PORT` wins,
+then `test.port` in the board's config, then USB-identity discovery
+(`test-pins.json` carries `usb: { vid, pid }` — e.g. the DevKitC's CH34x
+bridge `1A86:55D3`), and the port re-resolves after every flash
+re-enumeration. A program that also constructs `USB0` composes a CDC device
+enumerating at the shared Zephyr-test identity `2FE3:0001`.
+
+### Board parity and documented hardware limits
+
+Every board runs every group its silicon supports. Gaps are hard hardware
+limits expressed as role skips: the ESP32-S3 DevKitC declares no I2C
+controller and no `led0` node (and its UART0 is the protocol channel), so
+those groups skip there by role. Everything else — GPIO, PWM, ADC (both
+SARADC units), SPI, timing, math, random, shift, interrupts, WDT, Store,
+File, async, constants, Counter — runs on both boards.
+
+`Sensor` and `DAC` have a full pipeline (catalog → devicetree
+synthesis → Zephyr driver API) but no sensor or DAC-capable board on the
+current rig, so they are compile-verified only until one is attached. The
+network tier needs the host server (`npm run test:http`) and credentials in
+`tests/network/secrets.ts`.
 
 ## Ecosystem
 
-- [`@typecad/cuttlefish`](https://cuttlefish.typecad.net) — the transpiler that resolves HAL calls to C++.
-- [`@typecad/ui`](https://cuttlefish.typecad.net) — HTML/CSS-driven display graphics.
-- `@typecad/mcu-*` — silicon pin/port/peripheral definitions.
-- `@typecad/board-*` — board-level pin mappings and bus aliases.
+- [`@typecad/cuttlefish`](../../README.md) — the transpiler that resolves HAL calls to C++.
+- [`@typecad/framework-zephyr`](../framework-zephyr/README.md) — the Zephyr lowering, board catalog, and toolchain.
+- [`@typecad/expect`](../expect/README.md) — the on-hardware test framework.
+- [`@typecad/ui`](../ui/README.md) — HTML/CSS-driven display graphics.
 
 ## License
 

package/dist/adc-pin.d.ts

@@ -0,0 +1,53 @@
+import type { Pin } from './gpio.js';
+export declare class ADC {
+    static readonly GAIN_1_6 = 1;
+    static readonly GAIN_1_5 = 2;
+    static readonly GAIN_1_4 = 3;
+    static readonly GAIN_2_7 = 4;
+    static readonly GAIN_1_3 = 5;
+    static readonly GAIN_2_5 = 6;
+    static readonly GAIN_1_2 = 7;
+    static readonly GAIN_2_3 = 8;
+    static readonly GAIN_4_5 = 9;
+    static readonly GAIN_1 = 10;
+    static readonly GAIN_2 = 11;
+    static readonly GAIN_3 = 12;
+    static readonly GAIN_4 = 13;
+    static readonly GAIN_6 = 14;
+    static readonly GAIN_8 = 15;
+    static readonly GAIN_12 = 16;
+    static readonly GAIN_16 = 17;
+    static readonly GAIN_24 = 18;
+    static readonly GAIN_32 = 19;
+    static readonly GAIN_64 = 20;
+    static readonly GAIN_128 = 21;
+    static readonly REF_VDD_1 = 256;
+    static readonly REF_VDD_1_2 = 257;
+    static readonly REF_VDD_1_3 = 258;
+    static readonly REF_VDD_1_4 = 259;
+    static readonly REF_INTERNAL = 260;
+    static readonly REF_EXTERNAL0 = 261;
+    static readonly REF_EXTERNAL1 = 262;
+    private readonly _pin;
+    private readonly _gain;
+    private readonly _reference;
+    private readonly _channel;
+    private readonly _device;
+    private readonly _pinctrl;
+    /** Construct an analog input channel. Omitted gain/reference fall back to
+     *  the chip descriptor's pair (the values the platform's driver validates
+     *  against, e.g. STM32's ADC_GAIN_1 + ADC_REF_INTERNAL). */
+    constructor(pin: number | Pin, opts?: {
+        gain?: number;
+        reference?: number;
+        channel?: number;
+        device?: string;
+        pinctrl?: string;
+    });
+    /** Read raw counts at the chip's resolution (adc_channel_setup on first
+     *  use with the construction gain/reference, then adc_read). */
+    read(): number;
+    /** Read millivolts (adc_raw_to_millivolts against the descriptor's
+     *  vref). Returns mV. */
+    readMillivolts(): number;
+}

package/dist/adc-pin.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// ADC — the thin Zephyr-shaped analog input
+//
+// Construction IS the channel setup: gain and reference are constructor
+// options (exactly struct adc_channel_cfg), defaulting to the chip
+// descriptor's pair when omitted. read() returns raw counts at the chip's
+// resolution; readMillivolts() applies adc_raw_to_millivolts. There is no
+// setReference() — Zephyr applies the reference at channel-setup time, and
+// this surface doesn't promise otherwise.
+//
+// Gain/reference tokens are Zephyr's enum names under the ADC
+// namespace (ADC_GAIN_1_4 ↔ ADC.GAIN_1_4, ADC_REF_INTERNAL ↔
+// ADC.REF_INTERNAL); the lowering maps token names to macros.
+// ----------------------------------------------------------------------------
+import { adcReadRaw, adcReadMv } from './emit.js';
+export class ADC {
+    /** Construct an analog input channel. Omitted gain/reference fall back to
+     *  the chip descriptor's pair (the values the platform's driver validates
+     *  against, e.g. STM32's ADC_GAIN_1 + ADC_REF_INTERNAL). */
+    constructor(pin, opts) {
+        this._pin = typeof pin === 'number' ? pin : pin.number;
+        this._gain = opts?.gain ?? '';
+        this._reference = opts?.reference ?? '';
+        this._channel = opts?.channel ?? -1;
+        this._device = opts?.device ?? '';
+        this._pinctrl = opts?.pinctrl ?? '';
+    }
+    /** Read raw counts at the chip's resolution (adc_channel_setup on first
+     *  use with the construction gain/reference, then adc_read). */
+    read() {
+        return adcReadRaw(this._pin, this._gain, this._reference, this._channel, this._device, this._pinctrl);
+    }
+    /** Read millivolts (adc_raw_to_millivolts against the descriptor's
+     *  vref). Returns mV. */
+    readMillivolts() {
+        return adcReadMv(this._pin, this._gain, this._reference, this._channel, this._device, this._pinctrl);
+    }
+}
+// ── Gain tokens (enum adc_gain, verbatim — generated set, see the
+//    token-sync test) ───────────────────────────────────────────────────
+ADC.GAIN_1_6 = 0x01;
+ADC.GAIN_1_5 = 0x02;
+ADC.GAIN_1_4 = 0x03;
+ADC.GAIN_2_7 = 0x04;
+ADC.GAIN_1_3 = 0x05;
+ADC.GAIN_2_5 = 0x06;
+ADC.GAIN_1_2 = 0x07;
+ADC.GAIN_2_3 = 0x08;
+ADC.GAIN_4_5 = 0x09;
+ADC.GAIN_1 = 0x0a;
+ADC.GAIN_2 = 0x0b;
+ADC.GAIN_3 = 0x0c;
+ADC.GAIN_4 = 0x0d;
+ADC.GAIN_6 = 0x0e;
+ADC.GAIN_8 = 0x0f;
+ADC.GAIN_12 = 0x10;
+ADC.GAIN_16 = 0x11;
+ADC.GAIN_24 = 0x12;
+ADC.GAIN_32 = 0x13;
+ADC.GAIN_64 = 0x14;
+ADC.GAIN_128 = 0x15;
+// ── Reference tokens (enum adc_reference, verbatim) ────────────────────
+ADC.REF_VDD_1 = 0x100;
+ADC.REF_VDD_1_2 = 0x101;
+ADC.REF_VDD_1_3 = 0x102;
+ADC.REF_VDD_1_4 = 0x103;
+ADC.REF_INTERNAL = 0x104;
+ADC.REF_EXTERNAL0 = 0x105;
+ADC.REF_EXTERNAL1 = 0x106;

package/dist/async.d.ts

@@ -2,10 +2,9 @@ export declare class AsyncClass {
     static readonly __instance_name = "Async";
     /**
      * Non-blocking sleep for `ms` milliseconds.
-     * Returns a Promise<void> that resolves after the given delay.
-     * The underlying C++ implementation uses the platform's timer/microtask
-     * mechanism (e.g. millis-based polling on Arduino, std::this_thread::sleep_for
-     * on native, or a FreeRTOS vTaskDelay in the future).
+     * Returns a Promise<void> that resolves after the given delay. The async
+     * runtime resolves it cooperatively (the static state machine on
+     * heap-less targets polls the clock in the scheduler loop).
      */
     sleep(ms: number): Promise<void>;
     /**
@@ -13,13 +12,6 @@ export declare class AsyncClass {
      * (microtasks, timers) to run. Resumes on the next microtask pump cycle.
      */
     yield(): Promise<void>;
-    /**
-     * Await a polling condition.
-     * Repeatedly checks `condition()` every `pollIntervalMs` milliseconds
-     * until it returns true, then resolves.
-     * The underlying implementation uses the platform's timer mechanism.
-     */
-    sleepUntil(condition: () => boolean, pollIntervalMs?: number): Promise<void>;
     /**
      * Return a human-readable description of the currently executing async task.
      * Useful for debugging / logging in cooperative multitasking environments.

package/dist/async.js

@@ -4,7 +4,6 @@
 // Provides a platform-independent API for:
 //   - sleep(ms)      — non-blocking delay via Promise + microtask
 //   - yield()        — cooperative yield to other tasks
-//   - sleepUntil(condition) — await a condition (promise-based)
 //   - currentTask()  — return a description of the currently executing task
 //
 // Framework packages (Arduino, Native, etc.) provide the C++ runtime behind
@@ -15,10 +14,9 @@ import { rawCpp } from './emit.js';
 export class AsyncClass {
     /**
      * Non-blocking sleep for `ms` milliseconds.
-     * Returns a Promise<void> that resolves after the given delay.
-     * The underlying C++ implementation uses the platform's timer/microtask
-     * mechanism (e.g. millis-based polling on Arduino, std::this_thread::sleep_for
-     * on native, or a FreeRTOS vTaskDelay in the future).
+     * Returns a Promise<void> that resolves after the given delay. The async
+     * runtime resolves it cooperatively (the static state machine on
+     * heap-less targets polls the clock in the scheduler loop).
      */
     sleep(ms) {
         rawCpp(`__cuttlefish_async_sleep(${ms});`);
@@ -32,16 +30,6 @@ export class AsyncClass {
         rawCpp(`__cuttlefish_async_yield();`);
         return Promise.resolve();
     }
-    /**
-     * Await a polling condition.
-     * Repeatedly checks `condition()` every `pollIntervalMs` milliseconds
-     * until it returns true, then resolves.
-     * The underlying implementation uses the platform's timer mechanism.
-     */
-    sleepUntil(condition, pollIntervalMs = 10) {
-        rawCpp(`__cuttlefish_async_sleep_until(${pollIntervalMs});`);
-        return Promise.resolve();
-    }
     /**
      * Return a human-readable description of the currently executing async task.
      * Useful for debugging / logging in cooperative multitasking environments.

package/dist/ble.d.ts

@@ -17,18 +17,6 @@ export declare enum BlePerm {
     Write = 2,
     Notify = 4
 }
-/** BLE peripheral status (mirrored by the runtime shim). */
-export declare enum BleStatus {
-    Idle = 0,
-    Initializing = 1,
-    Advertising = 2,
-    Connected = 3,
-    Error = 4
-}
-export declare enum BleAdvertisingMode {
-    Connectable = "connectable",
-    NonConnectable = "non_connectable"
-}
 /** A well-known GATT characteristic entry in the catalog. */
 export interface GattCharacteristicDef {
     readonly uuid: string;
@@ -38,9 +26,10 @@ export interface GattCharacteristicDef {
     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().
+ * Standard GATT services/characteristics — uuid/type/perms reference data.
+ * Pass the pieces explicitly to char():
+ *   GATT.ENVIRONMENTAL.TEMPERATURE →
+ *     char('2A6E', BleValueType.Int16, BlePerm.Read | BlePerm.Notify)
  */
 export declare const GATT: {
     readonly DEVICE_INFO: {
@@ -92,69 +81,44 @@ export declare const GATT: {
 /** 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.
+ * The GATT declaration chain returned by BLE.service()/BLE.char(). Each char()
+ * appends a characteristic; onRead/onWrite/notify bind to the most recent one.
  */
-export declare class BleClass {
-    static readonly __instance_name = "Ble";
-    /** Begin building a GATT server with the given advertised device name. */
-    server(name: string): BleServer;
-    /** Initialize NimBLE, register services, and start advertising. */
-    begin(): void;
-    advertise(): void;
-    stopAdvertising(): void;
-    /** Blocking at top level; cooperatively awaitable inside async functions. */
-    untilConnected(timeoutMs?: number): Promise<boolean>;
-    untilConnectedStart(): void;
-    isConnected(): boolean;
-    status(): BleStatus;
-    clientCount(): number;
-    txPower(dbm: number): this;
-    notify(index: number, value: number): void;
+export declare class BleChain {
+    /** Begin a new service grouping; subsequent char() calls attach to it. */
+    service(uuid: string): BleChain;
+    /** Append a characteristic by uuid, value type, and permissions
+     *  (`BlePerm.Read | BlePerm.Notify`). Returns this for chaining. */
+    char(uuid: string, type: BleValueType, perms: number): BleChain;
+    /** Read handler for the most recently declared characteristic. */
+    onRead(handler: () => CharValue): BleChain;
+    /** Write handler for the most recently declared characteristic. */
+    onWrite(handler: (value: number) => void): BleChain;
 }
-/**
- * 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 declare class BleServer {
-    private _name;
-    private _charCount;
-    private _lastChar;
-    private _svcCount;
-    constructor(name: string, charCount: number, svcCount: number);
-    /** 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;
-    /** Begin a new service grouping. Subsequent characteristics attach to it. */
-    service(uuid: string): this;
-    /** Register a read handler for the most recently added characteristic. */
-    onRead(handler: () => CharValue): this;
-    /** Register a write handler for the most recently added characteristic. */
-    onWrite(handler: (value: number) => void): this;
-    /** Register a connect handler (called when a central connects). */
-    onConnect(handler: () => void): this;
-    /** Register a disconnect handler (called when a central disconnects). */
-    onDisconnect(handler: () => void): this;
-    /** Push a new value to subscribed clients on the most recently added characteristic. */
-    notify(value: number): void;
-    /** Initialize NimBLE, register services, and start advertising. */
-    begin(): void;
+/** A GATT peripheral. The advertised device name is the construction fact. */
+export declare class BLE {
+    private readonly _name;
+    constructor(name: string);
+    /** Begin a service grouping; chain char() declarations off it. */
+    service(uuid: string): BleChain;
+    /** Append a characteristic under the default (Environmental Sensing)
+     *  service — the common single-service case. */
+    char(uuid: string, type: BleValueType, perms: number): BleChain;
+    /** Register the declared GATT database, enable the stack, and start
+     *  advertising the construction name. */
+    start(): void;
+    /** Stop advertising (the GATT database and any link stay up). */
+    stop(): void;
+    /** True while a central is connected. */
+    linked(): boolean;
+    /** Number of connected centrals (0 or 1 — the shim is single-connection). */
+    clients(): number;
+    /** Fires when a central connects. */
+    onConnect(handler: () => void): void;
+    /** Fires when the central disconnects. */
+    onDrop(handler: () => void): void;
+    /** Push a value to subscribed clients on a characteristic
+     *  (bt_gatt_notify). `index` is the characteristic's declaration order
+     *  (0-based — the first char() is 0). */
+    notify(index: number, value: number): void;
 }
-export declare const Ble: BleClass;