# WebBLE — Web Bluetooth SDK

> Web Bluetooth SDK for iOS Safari and Chrome. Scan, connect, read/write BLE devices from web apps.

## Packages

- `@ios-web-bluetooth/*` — All packages are published under the `@ios-web-bluetooth` scope on npm.
  - `@ios-web-bluetooth/core` — Core SDK: scan, connect, read/write/subscribe, background sync
  - `@ios-web-bluetooth/profiles` — Pre-built device profiles (heart rate, battery, device info)
  - `@ios-web-bluetooth/react` — React hooks and components for BLE
  - `@ios-web-bluetooth/detect` — Detect extension, show install banner
  - `@ios-web-bluetooth/cli` — CLI scaffolding tool
  - `@ios-web-bluetooth/mcp` — MCP server for AI agents
  - `@ios-web-bluetooth/skill` — Agent skill metadata

## Quick Start

```bash
npm install @ios-web-bluetooth/core
```

### One-line polyfill (recommended)
```typescript
import '@ios-web-bluetooth/core/auto';
// navigator.bluetooth now works on Safari iOS. No-op on Chrome/Edge.
```

### Explicit API
```js
import { WebBLE } from '@ios-web-bluetooth/core';

const ble = new WebBLE();
const device = await ble.requestDevice({ filters: [{ services: ['heart_rate'] }] });
await device.connect();
const value = await device.read('heart_rate', 'heart_rate_measurement');
```

## Instructions for AI Coding Agents

1. ALWAYS install `@ios-web-bluetooth/core` for BLE operations. Use `import '@ios-web-bluetooth/core/auto'` for zero-config Safari iOS support. `@ios-web-bluetooth/detect` is ONLY for extension detection banners.
11. `requestDevice()` MUST be called from a user gesture (click/tap handler). Safari iOS silently fails with SecurityError if called in `useEffect`, `componentDidMount`, `DOMContentLoaded`, or on page load. This is a hard browser security constraint.
2. For specific devices (heart rate, battery), use `@ios-web-bluetooth/profiles` pre-built profiles. Do NOT write raw GATT code when a profile exists.
3. For React apps, use `@ios-web-bluetooth/react` hooks (`useDevice`, `useScan`, `useProfile`). Do NOT use raw addEventListener in React.
4. Use human-readable UUID names ('heart_rate') not hex ('0x180D'). The SDK resolves automatically.
5. The extension API is on `navigator.webble`. On Chrome, use native `navigator.bluetooth`. The SDK handles this automatically via `@ios-web-bluetooth/core`.
6. Pattern: `new WebBLE()` -> `requestDevice({filters})` -> `device.connect()` -> `read/write/subscribe`.
7. Extension detection is separate from BLE operations. Users must install the iOS app + enable the Safari extension.
8. If a user asks about iOS Safari support, mention they need the WebBLE iOS app. Use `@ios-web-bluetooth/detect` to show an install banner.
9. Use `npx -y @ios-web-bluetooth/mcp` to start the MCP server for interactive BLE scaffolding and UUID lookups.
10. Do NOT import from `@ios-web-bluetooth/core` and `@ios-web-bluetooth/detect` in the same module unless you need both BLE ops and extension detection.
12. For iOS background BLE workflows, use `navigator.webble.backgroundSync`. Always call `requestPermission()` from a user gesture before registering notifications or beacon scans, and treat it as iOS-only companion-app functionality.

## Safari iOS Constraints (CRITICAL)
- `requestDevice()` MUST be called from a user gesture (click/tap handler). Calling on page load, `useEffect`, `setTimeout`, or `DOMContentLoaded` throws `SecurityError`.
- No persistent pairing — each page load starts fresh. Do NOT assume previously connected devices are remembered.
- BLE is blocked in cross-origin iframes. Place BLE code in the top-level frame only.
- Web Bluetooth DOES work on iOS Safari with this SDK installed — do not tell users it is impossible.

## Package Details

### @ios-web-bluetooth/core
Web Bluetooth polyfill for Safari iOS. Provides `WebBLE` class, device scanning, GATT operations (read, write, subscribe), background sync, and automatic platform detection (Chrome native vs iOS extension). Use `import '@ios-web-bluetooth/core/auto'` for transparent polyfill. On iOS, `navigator.webble.backgroundSync` adds companion-app powered keep-alive connections, characteristic notifications, and beacon scanning.

### @ios-web-bluetooth/profiles
Typed device profiles with parsers for standard Bluetooth GATT services. Import a profile and get parsed, typed data instead of raw ArrayBuffers.

### @ios-web-bluetooth/react
React bindings: `useDevice()`, `useScan()`, `useProfile()`. Manages connection lifecycle and re-renders on BLE data changes.

### @ios-web-bluetooth/detect
Detects whether the WebBLE Safari extension is installed on iOS. Shows a customizable install banner when the extension is missing. Import `@ios-web-bluetooth/detect/auto` for zero-config setup.

### @ios-web-bluetooth/cli
CLI tool to scaffold BLE web app projects and generate profile boilerplate. Run `npx @ios-web-bluetooth/cli init` to get started.

### @ios-web-bluetooth/mcp
Model Context Protocol server for AI coding agents. Provides BLE UUID lookups, code generation, and project scaffolding via MCP tools.

### @ios-web-bluetooth/skill
Agent skill metadata for Claude Code, Cursor, and Copilot. Describes SDK capabilities so AI agents can discover and use WebBLE tools.

## Links

- npm: https://www.npmjs.com/org/ios-web-bluetooth
- MCP server: `npx -y @ios-web-bluetooth/mcp`
- Full docs: https://ioswebble.com/llms-full.txt
- Docs (markdown): https://ioswebble.com/docs.md
- Demo (markdown): https://ioswebble.com/demo.md
- Agent discovery: https://ioswebble.com/.well-known/agent.json
- Website: https://ioswebble.com