nsd-ble 0.3.3 → 0.4.1

package/README.md

@@ -0,0 +1,887 @@
+# nsd-ble
+
+A TypeScript library for communicating with NotSoDoom Bluetooth standees via the Web Bluetooth API. Connect to one standee and communicate with the entire mesh network.
+
+## Installation
+
+```bash
+npm install nsd-ble
+```
+
+## Quick Start
+
+```typescript
+import { useMesh, useStandees } from "nsd-ble";
+
+const mesh = useMesh();
+const { standees, onChange } = useStandees();
+
+// connect() must be called from a user gesture (e.g. button click)
+document.getElementById("connect").addEventListener("click", async () => {
+    await mesh.connect();
+});
+
+// React to standees joining the mesh
+onChange.attach((list) => {
+    console.log(
+        "Standees:",
+        list.map((s) => s.name()),
+    );
+});
+```
+
+## Requirements
+
+- A browser that supports the [Web Bluetooth API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Bluetooth_API) (Chrome, Edge, Opera)
+- `connect()` must be called from a user-initiated event (click, tap, etc.) due to Web Bluetooth security requirements
+
+## Imports
+
+The package exposes four entry points:
+
+```typescript
+// Core composables
+import {
+    useMesh,
+    useStandees,
+    useGraphics,
+    useLoader,
+    useDisplay,
+    useStandeeElements,
+    useActions,
+    useButtons,
+    useConverter,
+    useBinary,
+    useImage,
+    useUtils,
+    useDebug,
+    useMockBluetooth,
+} from "nsd-ble";
+
+// Display elements
+import { Rectangle, Image, Text, DisplayElement } from "nsd-ble/elements";
+
+// Object types
+import { Standee, ButtonResult, Buffer } from "nsd-ble/objects";
+
+// Enums
+import {
+    Font,
+    Button,
+    ActionType,
+    ElementData,
+    ActionCondition,
+    ActionDataType,
+    HandshakeType,
+    DataType,
+    FloodTypes,
+    Data,
+} from "nsd-ble/enums";
+```
+
+## Core Concepts
+
+### Mesh Network
+
+Standees form a Bluetooth mesh network. You only need to connect to a single standee — messages are automatically flooded to all reachable nodes.
+
+### Composable Pattern
+
+All functionality is accessed through `useX()` composable functions. Some composables are global (`useMesh`, `useDisplay`) while others are scoped to a specific standee (`useGraphics(standee)`, `useLoader(standee)`).
+
+### Buffer System
+
+Most operations return a `Buffer` object. Call `.send()` on it to transmit the data over BLE:
+
+```typescript
+const buffer = useDisplay().draw(standee);
+await buffer.send();
+```
+
+Buffers can also be chained with `.then()`:
+
+```typescript
+useDisplay()
+    .clear(standee)
+    .then(() => {
+        console.log("Screen cleared");
+    })
+    .send();
+```
+
+## API Reference
+
+### useMesh()
+
+Main entry point. Manages the BLE connection and mesh-level events. Auto-reconnect with exponential backoff is enabled automatically after the first successful connection.
+
+```typescript
+const {
+    connect,           // () => Promise<void>  — opens the BLE device picker
+    reconnect,         // () => Promise<void>  — reconnects to the last device
+    onConnect,         // SyncEvent<void>      — fires when connected
+    onDisconnect,      // SyncEvent<void>      — fires when disconnected
+    onReconnecting,    // SyncEvent<ReconnectStatus> — auto-reconnect attempt in progress
+    onReconnectFailed, // SyncEvent<void>      — all auto-reconnect retries exhausted
+    onNodes,           // SyncEvent<Map<number, number[]>> — all discovered nodes
+    onNode,            // SyncEvent<Map<number, number[]>> — new node joined
+    onNodeLost,        // SyncEvent<number>    — node left the mesh
+    onPlusButton,      // SyncEvent<ButtonResult>
+    onMinButton,       // SyncEvent<ButtonResult>
+    onEitherButton,    // SyncEvent<ButtonResult>
+    onMessageDone,     // SyncEvent<number>    — message transmission complete
+} = useMesh();
+```
+
+Auto-reconnect uses exponential backoff starting at 2 seconds, doubling each attempt up to 30 seconds, with a maximum of 5 retries. Subscribe to `onReconnecting` to track reconnect attempts:
+
+```typescript
+mesh.onReconnecting.attach((status) => {
+    // status.attempt    — current attempt number
+    // status.maxRetries — maximum retries (5)
+    // status.delay      — delay before this attempt in ms
+    console.log(`Reconnecting: attempt ${status.attempt}/${status.maxRetries}`);
+});
+
+mesh.onReconnectFailed.attach(() => {
+    console.log("All reconnect attempts failed");
+});
+```
+
+### useStandees()
+
+Tracks discovered standees as a reactive list.
+
+```typescript
+const {
+    standees, // Standee[] — current list of standees
+    onChange,  // SyncEvent<Standee[]> — fires when the list changes
+} = useStandees();
+```
+
+### useGraphics(standee)
+
+Upload images to a standee's memory. Images are stored by numeric ID (0-255) and can later be referenced by display elements.
+
+```typescript
+const { upload, clear } = useGraphics(standee);
+
+// Convert an image to bytes and upload it as ID 0
+const bytes = await useConverter().imageToBytes("/images/icon.png");
+await upload(0, bytes).send();
+
+// Clear all uploaded graphics
+await clear().send();
+```
+
+### useLoader(standee)
+
+Sends multiple buffers in sequence with progress tracking. Useful for uploading a batch of images.
+
+```typescript
+const loader = useLoader(standee).load(buffers);
+
+loader.onProgress.attach((progress) => {
+    // progress.current    — buffers completed so far
+    // progress.total      — total buffers
+    // progress.percentage — 0 to 1
+    console.log(`${Math.round(progress.percentage * 100)}%`);
+});
+
+loader.onError.attach((error) => {
+    // error.buffer — index of the buffer that failed
+    // error.error  — the Error object
+    console.error(`Buffer ${error.buffer} failed:`, error.error);
+});
+
+await loader.send();
+```
+
+### useStandeeElements(standee)
+
+Add and remove display elements on a standee. Elements are auto-assigned an ID.
+
+```typescript
+const { add, remove } = useStandeeElements(standee);
+
+const rect = add(new Rectangle(0, 0, 128, 64));
+const text = add(new Text(10, 30, "Hello", Font.u8g2_font_5x7_mf));
+const img = add(new Image(80, 10, 32, 32, 0)); // references uploaded image ID 0
+
+remove(rect.id);
+```
+
+### useDisplay()
+
+Draw elements to the standee's screen or clear it.
+
+```typescript
+const { draw, clear } = useDisplay();
+
+// Draw all dirty elements
+await draw(standee).send();
+
+// Clear the screen
+await clear(standee).send();
+```
+
+Only elements marked as `dirty` are redrawn. Modifying any element property (e.g. `rect.x = 50`) automatically marks it dirty.
+
+### useActions() and useButtons(standee)
+
+Define interactive behavior triggered by the standee's physical buttons.
+
+```typescript
+const actions = useActions();
+const { setButton } = useButtons(standee);
+
+// Create a target: which element property to affect
+const target = actions.target(textElement.id, ElementData.X);
+
+// Assign actions to the plus button
+await setButton(Button.PLUS, [actions.increment(target)]).send();
+```
+
+Available actions:
+
+| Action                                                 | Description                        |
+| ------------------------------------------------------ | ---------------------------------- |
+| `increment(target)`                                    | Increment a property value         |
+| `decrement(target)`                                    | Decrement a property value         |
+| `show(elementId)`                                      | Show an element                    |
+| `hide(elementId)`                                      | Hide an element                    |
+| `set(target, value)`                                   | Set a property to a specific value |
+| `broadcast(target?)`                                   | Broadcast a value across the mesh  |
+| `stop()`                                               | Break the action chain             |
+| `timer(ms, resetable, onComplete)`                     | Run actions after a delay          |
+| `condition(left, op, right, actions)`                  | Conditional action execution       |
+| `map(value, fromLow, fromHigh, toLow, toHigh, target)` | Map a value between ranges         |
+
+The `condition` action supports comparing targets, numbers, and strings. The `op` parameter uses `ActionCondition` values:
+
+```typescript
+// Show an element when HP equals 0
+const hp = actions.target(label.id, ElementData.TEXT);
+actions.condition(hp, ActionCondition.EQUAL, 0, [actions.show(gameOverElement.id)]);
+```
+
+### useConverter()
+
+Converts images to the monochrome byte format the standees expect.
+
+```typescript
+const { imageToBytes } = useConverter();
+const bytes = await imageToBytes("/path/to/image.png");
+```
+
+### useBinary()
+
+Low-level binary utilities for pixel data conversion.
+
+```typescript
+const { pixelsToBytes, bitswap, flattenUint8Arrays } = useBinary();
+
+// Convert pixel array to monochrome byte format
+const bytes = pixelsToBytes(pixels, width);
+
+// Concatenate multiple Uint8Arrays into one
+const combined = flattenUint8Arrays([array1, array2]);
+```
+
+### useImage()
+
+Low-level image processing utilities used internally by `useConverter()`.
+
+```typescript
+const { createImage, getImageData, imageDataToPixels } = useImage();
+
+// Load an image from URL
+const image = await createImage("/path/to/image.png");
+
+// Get raw ImageData from an HTMLImageElement
+const imageData = getImageData(image);
+
+// Convert ImageData to monochrome pixel array
+const pixels = imageDataToPixels(imageData);
+// { width, height, pixels: number[] }  — pixels are 0 (black) or 1 (white)
+```
+
+### useUtils()
+
+General-purpose utility functions.
+
+```typescript
+const { map } = useUtils();
+
+// Map a value from one range to another
+const mapped = map(value, fromLow, fromHigh, toLow, toHigh);
+```
+
+### useDebug()
+
+Message inspector and debug mode. Logs decoded packet contents, retransmission events, and message timing in a structured format. Emits events for building debug UIs.
+
+```typescript
+const debug = useDebug();
+
+// Enable debug logging (no overhead when disabled)
+debug.enable();
+
+// Check if debug mode is active
+debug.isEnabled(); // true
+
+// Subscribe to all debug events in real-time
+debug.onDebugEvent.attach((entry) => {
+    console.log(`[${entry.type}]`, entry.data);
+});
+
+// Track message latency
+debug.onTimingUpdate.attach((timing) => {
+    if (timing.latencyMs !== null) {
+        console.log(`Cache ${timing.cacheId}: ${timing.latencyMs}ms`);
+    }
+});
+
+// Read the full event log
+const log = debug.getLog();
+
+// Get timing records for all messages
+const timings = debug.getTimings();
+
+// Get timing for a specific cache ID
+const timing = debug.getTimingForCache(cacheId);
+
+// Decode a raw BLE packet into a structured object
+const decoded = debug.decodePacket(rawPacket);
+// { cacheId, targetId, ttl, position, dataSize, typeName, typeValue, payloadBytes, raw }
+
+// Control
+debug.disable();           // Pause logging
+debug.clear();             // Clear log and timing data
+debug.setMaxLogSize(1000); // Adjust log buffer size (default: 500)
+```
+
+Event types logged: `message_queued`, `packet_sent`, `retransmit`, `timeout`, `message_complete`, `message_done`, `received_packets`, `node_discovered`, `node_lost`, `connected`, `disconnected`.
+
+### useMockBluetooth()
+
+Offline simulator that replaces the real BLE layer with an in-memory mock. Enables development without physical standees and makes integration testing possible.
+
+```typescript
+const mock = useMockBluetooth();
+
+// Activate the mock before connecting
+mock.activate({
+    standees: [
+        { id: 1, neighbors: [2, 3] },
+        { id: 2, neighbors: [1] },
+        { id: 3, neighbors: [1] },
+    ],
+    responseDelay: 10,      // ms before MESSAGE_DONE response (default: 10)
+    dropRate: 0,            // 0-1 packet drop probability (default: 0)
+    partialDelivery: false, // simulate DATA_FEEDBACK for incomplete messages (default: false)
+});
+
+// Now connect normally — all BLE calls go through the mock
+await useMesh().connect();
+// onNodes fires with the configured standee topology
+
+// Simulate button presses from virtual standees
+mock.pressButton(1, "plus");           // triggers onPlusButton
+mock.pressButton(2, "minus", "data");  // triggers onMinButton with text data
+mock.pressButton(3, "either");         // triggers onEitherButton
+
+// Simulate mesh topology changes
+mock.simulateNodeJoin({ id: 4, neighbors: [1] }); // triggers onNode
+mock.simulateNodeLost(3);                          // triggers onNodeLost
+
+// Simulate disconnection
+mock.disconnect();                     // triggers onDisconnect
+
+// Control reconnect behavior
+mock.reconnectable(false);             // makes reconnect() reject
+mock.reconnectable(true);              // restore (default)
+
+// Update config at runtime
+mock.updateConfig({ responseDelay: 50, dropRate: 0.2 });
+
+// Check state
+mock.isActive();  // true
+mock.getConfig(); // current config
+
+// Restore real BLE
+mock.deactivate();
+```
+
+When `writeCharacteristic` is called (via `Buffer.send()`), the mock tracks incoming packets and automatically fires `MESSAGE_DONE` through the flood characteristic once all packets for a message are received. With `partialDelivery: true`, it sends `DATA_FEEDBACK` after a batch of writes, triggering the retransmission flow.
+
+## Display Elements
+
+All elements extend `DisplayElement` and share common properties:
+
+| Property     | Type    | Description                                           |
+| ------------ | ------- | ----------------------------------------------------- |
+| `id`         | number  | Auto-assigned by `useStandeeElements().add()`         |
+| `x`          | number  | X position                                            |
+| `y`          | number  | Y position                                            |
+| `show`       | boolean | Visibility (default: `true`)                          |
+| `colorBlack` | boolean | Draw in black when `true`, white when `false`         |
+| `dirty`      | boolean | Automatically set to `true` when any property changes |
+
+Setting any property automatically marks the element as `dirty`, so it will be included in the next `draw()` call.
+
+### Rectangle
+
+```typescript
+new Rectangle(x, y, width, height, radius?, fill?, show?, colorBlack?)
+```
+
+| Property | Type    | Default | Description                     |
+| -------- | ------- | ------- | ------------------------------- |
+| `width`  | number  |         | Rectangle width                 |
+| `height` | number  |         | Rectangle height                |
+| `radius` | number  | `0`     | Corner radius for rounded edges |
+| `fill`   | boolean | `false` | Fill the rectangle when `true`  |
+
+### Text
+
+```typescript
+new Text(x, y, text, font, center?, show?, colorBlack?)
+```
+
+| Property | Type    | Default | Description                              |
+| -------- | ------- | ------- | ---------------------------------------- |
+| `text`   | string  |         | The text content                         |
+| `font`   | number  |         | Font from the `Font` enum                |
+| `center` | boolean | `false` | Center the text at the given coordinates |
+
+Available fonts (from `Font` enum):
+
+- `u8g2_font_5x7_mf` — small
+- `u8g2_font_crox2c_tr` — medium
+- `u8g2_font_10x20_tn` — numeric
+- `u8g2_font_inr33_t_cyrillic` — large
+
+### Image
+
+```typescript
+new Image(x, y, width, height, data, show?, colorBlack?)
+```
+
+| Property | Type   | Description                                       |
+| -------- | ------ | ------------------------------------------------- |
+| `width`  | number | Image width                                       |
+| `height` | number | Image height                                      |
+| `data`   | number | Image ID (0-255) matching a previously uploaded graphic |
+
+## Objects
+
+### Standee
+
+Represents a discovered standee in the mesh network.
+
+| Property     | Type              | Description                              |
+| ------------ | ----------------- | ---------------------------------------- |
+| `id`         | number            | Unique standee identifier                |
+| `neighbors`  | number[]          | IDs of neighboring standees in the mesh  |
+| `elements`   | DisplayElement[]  | Display elements assigned to this standee|
+| `onPlus`     | SyncEvent\<void\> | Fires when the plus button is pressed    |
+| `onMin`      | SyncEvent\<void\> | Fires when the minus button is pressed   |
+
+| Method   | Returns | Description                                  |
+| -------- | ------- | -------------------------------------------- |
+| `name()` | string  | Hex-formatted ID (e.g. `"0a"` for id `10`)  |
+
+### ButtonResult
+
+Returned by button press events (`onPlusButton`, `onMinButton`, `onEitherButton`).
+
+| Property | Type   | Description                     |
+| -------- | ------ | ------------------------------- |
+| `id`     | number | ID of the standee that was pressed |
+| `data`   | string | Optional data sent with the press  |
+
+### Buffer
+
+Wraps BLE message data for transmission. Created internally by composable methods.
+
+| Property  | Type         | Description                             |
+| --------- | ------------ | --------------------------------------- |
+| `cache`   | number       | Auto-generated cache ID for tracking    |
+| `type`    | DataType     | The message type                        |
+| `id`      | number       | Target standee ID                       |
+| `packets` | Uint8Array[] | The message split into BLE-sized packets|
+
+| Method                    | Returns        | Description                          |
+| ------------------------- | -------------- | ------------------------------------ |
+| `send()`                  | Promise\<void\>| Transmit the buffer over BLE         |
+| `then(callback)`          | Buffer         | Chain a callback for after send completes |
+
+## Enums
+
+### Core Enums
+
+#### Font
+
+| Value                         | ID | Description |
+| ----------------------------- | -- | ----------- |
+| `u8g2_font_5x7_mf`           | 0  | Small       |
+| `u8g2_font_inr33_t_cyrillic` | 1  | Large       |
+| `u8g2_font_10x20_tn`         | 2  | Numeric     |
+| `u8g2_font_crox2c_tr`        | 3  | Medium      |
+
+#### Button
+
+| Value   | ID | Description   |
+| ------- | -- | ------------- |
+| `MINUS` | 0  | Minus button  |
+| `PLUS`  | 1  | Plus button   |
+| `EITHER`| 2  | Either button |
+
+#### ActionType
+
+| Value       | ID | Description          |
+| ----------- | -- | -------------------- |
+| `INCREMENT` | 0  | Increment a value    |
+| `DECREMENT` | 1  | Decrement a value    |
+| `SHOW`      | 2  | Show an element      |
+| `HIDE`      | 3  | Hide an element      |
+| `SET`       | 4  | Set a value          |
+| `BROADCAST` | 5  | Broadcast to mesh    |
+| `TIMER`     | 6  | Delayed action       |
+| `CONDITION` | 7  | Conditional action   |
+| `BREAK`     | 8  | Break action chain   |
+| `MAP`       | 9  | Map value to range   |
+
+#### ElementData
+
+Target properties for actions.
+
+| Value    | ID | Description      |
+| -------- | -- | ---------------- |
+| `TYPE`   | 0  | Element type     |
+| `ID`     | 1  | Element ID       |
+| `SHOW`   | 2  | Visibility       |
+| `X`      | 3  | X position       |
+| `Y`      | 4  | Y position       |
+| `WIDTH`  | 5  | Width            |
+| `HEIGHT` | 6  | Height           |
+| `RADIUS` | 7  | Corner radius    |
+| `FILL`   | 8  | Fill mode        |
+| `DATA`   | 9  | Data/image ID    |
+| `FONT`   | 10 | Font             |
+
+#### ActionCondition
+
+Comparison operators for `condition()` actions.
+
+| Value           | ID | Description      |
+| --------------- | -- | ---------------- |
+| `EQUAL`         | 0  | Equal to         |
+| `GREATER`       | 1  | Greater than     |
+| `LESS`          | 2  | Less than        |
+| `GREATER_EQUAL` | 3  | Greater or equal |
+| `LESS_EQUAL`    | 4  | Less or equal    |
+
+#### ActionDataType
+
+Value types used in `set()` and `condition()` actions.
+
+| Value     | ID | Description           |
+| --------- | -- | --------------------- |
+| `STRING`  | 0  | String value          |
+| `NUMBER`  | 1  | Numeric value         |
+| `ELEMENT` | 2  | Element property ref  |
+
+### Protocol Enums
+
+These enums are used internally by the BLE protocol layer but are exported for advanced use cases and debugging.
+
+#### DataType
+
+Message types sent over BLE.
+
+| Value            | ID | Description              |
+| ---------------- | -- | ------------------------ |
+| `UPLOAD`         | 0  | Image upload             |
+| `DRAW_IMAGE`     | 1  | Draw an image element    |
+| `DRAW_RECTANGLE` | 2  | Draw a rectangle element |
+| `BUTTON_PRESS`   | 3  | Button press event       |
+| `DRAW_TEXT`      | 4  | Draw a text element      |
+| `ALL`            | 5  | Draw all elements        |
+| `CLEAR_GRAPHICS` | 6  | Clear uploaded graphics  |
+| `ACTIONS`        | 7  | Button action assignment |
+| `CLEAR_SCREEN`   | 8  | Clear the screen         |
+| `LOADER`         | 10 | Loader header            |
+
+#### FloodTypes
+
+Flood message types for mesh-level communication.
+
+| Value            | ID | Description                        |
+| ---------------- | -- | ---------------------------------- |
+| `NODES`          | 0  | Node discovery                     |
+| `LOST_NODE`      | 1  | Node left the mesh                 |
+| `MESSAGE_DONE`   | 2  | Message fully received by target   |
+| `DATA_FEEDBACK`  | 3  | Partial delivery feedback          |
+
+#### HandshakeType
+
+Handshake protocol types for initial connection.
+
+| Value        | ID | Description           |
+| ------------ | -- | --------------------- |
+| `FLOOD_NODES`| 2  | Flood node discovery  |
+| `STEP_ONE`   | 4  | Handshake step one    |
+| `STEP_TWO`   | 5  | Handshake step two    |
+
+#### Data
+
+Byte positions within a BLE packet. Useful for manual packet inspection with `useDebug().decodePacket()`.
+
+| Value       | Byte Position | Description                       |
+| ----------- | ------------- | --------------------------------- |
+| `ID`        | 0             | Target standee ID                 |
+| `CACHE`     | 1             | Cache ID for message tracking     |
+| `TTL`       | 2             | Time to live (mesh hops)          |
+| `POSITION`  | 3-4           | Packet position (uint16 LE)       |
+| `DATA_SIZE` | 5-6           | Total data size (uint16 LE)       |
+| `TYPE`      | 7             | Message type (DataType)           |
+| `DATA`      | 8+            | Payload data                      |
+
+## TypeScript Types
+
+The library exports the following type definitions for use in your application:
+
+### Connection & Reconnect
+
+```typescript
+interface ReconnectStatus {
+    attempt: number;      // Current attempt number
+    maxRetries: number;   // Maximum retries allowed
+    delay: number;        // Delay before this attempt in ms
+}
+```
+
+### Debug Types
+
+```typescript
+interface DebugLogEntry {
+    type: DebugEventType;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+
+type DebugEventType =
+    | "packet_sent" | "message_queued" | "retransmit" | "timeout"
+    | "message_complete" | "message_done" | "received_packets"
+    | "node_discovered" | "node_lost" | "connected" | "disconnected";
+
+interface DecodedPacket {
+    cacheId: number;
+    targetId: number;
+    ttl: number;
+    position: number;
+    dataSize: number;
+    typeName: string;
+    typeValue: number;
+    payloadBytes: number;
+    raw: number[];
+}
+
+interface MessageTimingRecord {
+    cacheId: number;
+    queuedAt: number;
+    firstPacketAt: number | null;
+    completedAt: number | null;
+    latencyMs: number | null;
+    retransmitCount: number;
+    timeoutCount: number;
+    packetsSent: number;
+    totalPackets: number;
+}
+```
+
+### MeshWriter Events
+
+```typescript
+interface PacketSentEvent {
+    cacheId: number;
+    position: number;
+    dataSize: number;
+    packetBytes: number;
+    batchIndex: number;
+    timestamp: number;
+}
+
+interface MessageQueuedEvent {
+    cacheId: number;
+    type: number;
+    targetId: number;
+    packetCount: number;
+    totalBytes: number;
+    timestamp: number;
+}
+
+interface RetransmitEvent {
+    cacheId: number;
+    packetCount: number;
+    reason: "feedback" | "timeout";
+    timestamp: number;
+}
+
+interface TimeoutEvent {
+    cacheId: number;
+    retryCount: number;
+    maxRetries: number;
+    willRetry: boolean;
+    timestamp: number;
+}
+
+interface MessageCompleteEvent {
+    cacheId: number;
+    timestamp: number;
+}
+```
+
+### Loader Types
+
+```typescript
+interface LoaderProgress {
+    current: number;     // Buffers completed so far
+    total: number;       // Total buffers
+    percentage: number;  // 0 to 1
+}
+
+interface LoaderError {
+    buffer: number;      // Index of the buffer that failed
+    error: Error;        // The Error object
+}
+```
+
+### Mock Types
+
+```typescript
+interface VirtualStandee {
+    id: number;
+    neighbors: number[];
+}
+
+interface MockMeshConfig {
+    standees: VirtualStandee[];
+    responseDelay?: number;      // Default: 10
+    dropRate?: number;           // Default: 0
+    partialDelivery?: boolean;   // Default: false
+}
+```
+
+### Image Types
+
+```typescript
+type ImagePixels = {
+    width: number;
+    height: number;
+    pixels: number[];   // 0 (black) or 1 (white)
+}
+```
+
+## Configuration
+
+The BLE protocol uses these internal constants (via `useBluetoothSettings()`):
+
+| Constant                | Value  | Description                                       |
+| ----------------------- | ------ | ------------------------------------------------- |
+| `PACKET_SIZE`           | 13     | Max payload bytes per BLE packet                  |
+| `BATCH_SIZE`            | 20     | Packets sent per batch before waiting for ack     |
+| `ACK_TIMEOUT`           | 5000   | Milliseconds to wait for acknowledgment           |
+| `MAX_RETRIES`           | 3      | Retransmission attempts before giving up          |
+| `TTL`                   | 10     | Time to live (max mesh hops)                      |
+| `RECONNECT_DELAY`       | 2000   | Base delay for auto-reconnect (doubles each try)  |
+| `RECONNECT_MAX_RETRIES` | 5      | Maximum auto-reconnect attempts                   |
+
+## Events
+
+The library uses [`ts-events`](https://github.com/rogierschouten/ts-events) for event handling:
+
+```typescript
+// Subscribe
+mesh.onConnect.attach(() => console.log("Connected"));
+
+// Unsubscribe
+const handler = () => console.log("Connected");
+mesh.onConnect.attach(handler);
+mesh.onConnect.detach(handler);
+```
+
+## Full Example
+
+A complete example that connects to the mesh, uploads images, creates a UI, and configures button interaction:
+
+```typescript
+import {
+    useMesh,
+    useStandees,
+    useStandeeElements,
+    useDisplay,
+    useGraphics,
+    useLoader,
+    useConverter,
+    useActions,
+    useButtons,
+} from "nsd-ble";
+import { Rectangle, Text, Image } from "nsd-ble/elements";
+import { Font, Button, ElementData } from "nsd-ble/enums";
+
+const mesh = useMesh();
+const { standees, onChange } = useStandees();
+const { draw, clear } = useDisplay();
+
+// Connect on button click
+document.getElementById("connect").addEventListener("click", () => {
+    mesh.connect();
+});
+
+onChange.attach(async (list) => {
+    const standee = list[0];
+
+    // 1. Upload images
+    const images = ["/img/icon-a.png", "/img/icon-b.png"];
+    const buffers = await Promise.all(
+        images.map(async (path, i) => {
+            const bytes = await useConverter().imageToBytes(path);
+            return useGraphics(standee).upload(i, bytes);
+        }),
+    );
+
+    const loader = useLoader(standee).load(buffers);
+    loader.onProgress.attach((p) => {
+        console.log(`Uploading: ${Math.round(p.percentage * 100)}%`);
+    });
+    await loader.send();
+
+    // 2. Build the display
+    const { add } = useStandeeElements(standee);
+    const bg = add(new Rectangle(0, 0, 128, 64, 0, true));
+    const icon = add(new Image(10, 16, 32, 32, 0));
+    const label = add(new Text(64, 40, "HP: 10", Font.u8g2_font_5x7_mf, true));
+
+    await draw(standee).send();
+
+    // 3. Wire up buttons
+    const actions = useActions();
+    const hpTarget = actions.target(label.id, ElementData.TEXT);
+
+    await useButtons(standee)
+        .setButton(Button.PLUS, [actions.increment(hpTarget)])
+        .send();
+
+    await useButtons(standee)
+        .setButton(Button.MINUS, [actions.decrement(hpTarget)])
+        .send();
+});
+
+// Listen for button presses from the app side
+mesh.onPlusButton.attach((result) => {
+    console.log(`Plus pressed on standee ${result.id}`);
+});
+```