unified-ble-manager 4.0.10 → 4.0.11

package/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to `unified-ble-manager` are documented here.
 
 No changes yet.
 
+## [4.0.11] - 2026-08-30
+
+### Documentation
+
+- Document adapter interruption recovery through `manager.adapter.watchState()`
+  in the README and connection guide, and add the same flow to the Expo
+  example. UBM invalidates affected generations and leaves reconnect policy
+  with the host; the example displays live adapter power, availability, and
+  authorization instead of polling or silently reconnecting.
+
 ## [4.0.10] - 2026-08-30
 
 ### Fixes

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-This source targets `4.0.10`. The `4.0.0` release is a new package and a new contract. It is **not a source-compatible rename**. There is no `new BleManager()` facade, no Base64 characteristic values, and no public transaction IDs.
+This source targets `4.0.11`. The `4.0.0` release is a new package and a new contract. It is **not a source-compatible rename**. There is no `new BleManager()` facade, no Base64 characteristic values, and no public transaction IDs.
 
 This page is for a React Native app that already uses `react-native-ble-plx`. Web, Electron, Node, and Tauri are new hosts — use those pages after you understand the RN rewrite.
 

package/README.md

@@ -12,7 +12,7 @@ root import does not pick a radio. Package SemVer and backend support labels are
 independent: each radio backend keeps its evidence-derived label. See
 [`docs/PLATFORMS.md`](docs/PLATFORMS.md).
 
-This source tree is versioned `4.0.10`. Install the exact version shown in the npm
+This source tree is versioned `4.0.11`. Install the exact version shown in the npm
 registry. During release preparation, the version in `package.json` can be ahead
 of npm until the matching tag-driven workflow publishes it; the registry and
 GitHub release remain authoritative.
@@ -62,7 +62,7 @@ The root import selects no radio. Import the host you actually run.
 | ---------------------------------------- | ------------------------------------------------------------------------------ |
 | `unified-ble-manager`                    | Host-neutral manager, handles, helpers, and shared types                       |
 | `unified-ble-manager/react-native`       | React Native Android / Apple manager                                           |
-| `unified-ble-manager/react`               | React provider, hooks, and React-facing type utilities                         |
+| `unified-ble-manager/react`              | React provider, hooks, and React-facing type utilities                         |
 | `unified-ble-manager/expo`               | Expo development-build manager, readiness, and native configuration checks     |
 | `unified-ble-manager/web`                | Web Bluetooth chooser + matched manager                                        |
 | `unified-ble-manager/electron/main`      | Trusted Electron-main radio + IPC router                                       |
@@ -106,6 +106,31 @@ On Android, `manager.peers.bonded()` lists paired system peers and
 reachable. See [`docs/PEERS.md`](docs/PEERS.md) for the persistence and error
 semantics.
 
+### Recovering after an adapter interruption
+
+Adapter power and authorization changes are observable through the same public
+contract on every backend:
+
+```ts
+const watch = await manager.adapter.watchState()
+let previous = watch.initial
+for await (const item of watch.values) {
+  if (item.kind !== 'value') continue
+  const state = item.value
+  const restored = previous.power !== 'on' && state.power === 'on'
+  previous = state
+  if (restored && state.availability === 'available' && state.authorization === 'granted') {
+    // Reconcile your saved peer/reference and reconnect using your product policy.
+  }
+}
+await watch.stop()
+```
+
+UBM invalidates affected connections when the adapter is unavailable and does
+not reconnect silently. The host observes `watchState()`, resolves a fresh
+peer/reference, and starts a new connection generation. Do not poll, create a
+second manager, or reuse old GATT/database handles.
+
 ### Expo plugin
 
 Use an Expo development build, never Expo Go. Plugin options live in
@@ -174,7 +199,7 @@ try {
 
 Battery Level and Heart Rate Control Point are optional or conditional; see [`docs/TUTORIALS.md`](docs/TUTORIALS.md). Persistent subscriptions also live there.
 
-Web Bluetooth replaces the scan with `ble.choose(...)` from a user gesture. Tauri and the Electron renderer use different host entrypoints — see those host pages.
+Web Bluetooth replaces the scan with `ble.choose(...)` from a user gesture. The [complete Web Bluetooth guide](docs/WEB.md) and [TypeScript/Vite example](example-web/) cover chooser permissions, authorized peers, bounded operations, notifications, structured errors, and safe cleanup. Tauri and the Electron renderer use different host entrypoints — see those host pages.
 
 ## Why the API looks like this
 
@@ -293,17 +318,17 @@ after disconnect, service change, or rediscovery.
 
 ### Host factories
 
-| Factory                                                                                | Returns                                                                                         |
-| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `createReactNativeBleManager`                                                          | Zero-plumbing public React Native manager                                                       |
-| `createReactNativeBleManagerWithEnvironment`                                           | Injectable RN factory for tests                                                                 |
-| `createExpoBleManager`                                                                 | Expo development-build manager with readiness and native configuration checks                   |
-| `createWebBleManager`                                                                  | Zero-plumbing public Web manager; use `ble.choose()` from a user gesture                        |
-| `createCoreBluetoothBleManager` / `createWinRtBleManager` / `createBluezBleManager`    | One-call Node managers                                                                          |
-| `createElectronMainCoreBluetoothBackendProvider` / `WinRt`                             | Main-process provider; you still build a `BleManager`                                           |
-| `createElectronRendererBleManager` / `createElectronRendererBleManagerWithEnvironment` | Public renderer `BleManager` over a preload transport; the renderer never loads a radio backend |
-| `createTauriBleManager`                                                                | Zero-plumbing Tauri `BleManager`; tests use `createTauriBleManagerWithEnvironment`              |
-| `createBleManagerFromProvider`                                                         | Advanced provider construction                                                                  |
+| Factory                                                                                | Returns                                                                                                                         |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `createReactNativeBleManager`                                                          | Zero-plumbing public React Native manager                                                                                       |
+| `createReactNativeBleManagerWithEnvironment`                                           | Injectable RN factory for tests                                                                                                 |
+| `createExpoBleManager`                                                                 | Expo development-build manager with readiness and native configuration checks                                                   |
+| `createWebBleManager`                                                                  | Zero-plumbing public Web manager; use `ble.choose()` from a user gesture                                                        |
+| `createCoreBluetoothBleManager` / `createWinRtBleManager` / `createBluezBleManager`    | One-call Node managers                                                                                                          |
+| `createElectronMainCoreBluetoothBackendProvider` / `WinRt`                             | Main-process provider; you still build a `BleManager`                                                                           |
+| `createElectronRendererBleManager` / `createElectronRendererBleManagerWithEnvironment` | Public renderer `BleManager` over a preload transport; the renderer never loads a radio backend                                 |
+| `createTauriBleManager`                                                                | Zero-plumbing Tauri `BleManager`; tests use `createTauriBleManagerWithEnvironment`                                              |
+| `createBleManagerFromProvider`                                                         | Advanced provider construction                                                                                                  |
 | `createPublicBleManagerFacade`                                                         | Projects an already-owned `/advanced` manager into the root public `BleManager`; creates no advanced manager, backend, or radio |
 
 ## Other hosts

package/RELEASE.md

@@ -81,7 +81,7 @@ Active `4.0.0-rc.*` release-train candidates publish to npm `latest` so a bare `
 
 On release day, set `release_candidate` to the exact candidate required by the
 release plan. RC2, RC3, RC4, `4.0.0-rc.4.1`, and RC5 are already immutable
-once tagged. Stable `4.0.0` through `4.0.9` are immutable. `4.0.10` is the current train head.
+once tagged. Stable `4.0.0` through `4.0.10` are immutable. `4.0.11` is the current train head.
 
 ```sh
 release_candidate=4.0.0-rc.N
@@ -133,6 +133,27 @@ The `v4.0.3` tag is immutable published history. Do not recreate or move it.
 git tag -a v4.0.3 -m "v4.0.3"
 ```
 
+## Releasing 4.0.11
+
+The `v4.0.11` tag must identify the exact current `main` commit after canonical
+CI passes. Do not tag this feature branch directly.
+
+```sh
+git fetch origin --tags
+git checkout main
+git pull --ff-only origin main
+
+test "$(git branch --show-current)" = "main"
+test "$(node -p "require('./package.json').version")" = "4.0.11"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.11 -m "v4.0.11"
+git push origin v4.0.11
+```
+
+Before tagging, confirm release-note extraction finds `## [4.0.11]`.
+
 ## Releasing 4.0.10
 
 The `v4.0.10` tag must identify the exact current `main` commit after canonical
@@ -277,7 +298,7 @@ a green publish job and a package a consumer can actually install are not the
 same claim.
 
 ```sh
-version=4.0.10
+version=4.0.11
 
 npm view "unified-ble-manager@$version" version
 npm view unified-ble-manager dist-tags --json

package/SBOM.cdx.json

@@ -6,20 +6,20 @@
   "metadata": {
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/unified-ble-manager@4.0.10",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.11",
       "name": "unified-ble-manager",
-      "version": "4.0.10",
+      "version": "4.0.11",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.10"
+      "purl": "pkg:npm/unified-ble-manager@4.0.11"
     },
     "properties": [
       {
         "name": "unified-ble-manager:pnpm-lock-sha256",
-        "value": "38ee8dcc8420316a625d4572ab163111ac9aef51065626ce8a747298b85819dd"
+        "value": "58c2b09c18f10de1e250a357e5ce9445fe6bcace614e3778bc60166b9db31fa1"
       },
       {
         "name": "unified-ble-manager:dependency-scope",
@@ -537,7 +537,7 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.10",
+      "ref": "pkg:npm/unified-ble-manager@4.0.11",
       "dependsOn": [
         "pkg:npm/%40babel/runtime@7.29.7",
         "pkg:npm/node-addon-api@8.9.0",

package/THIRD_PARTY_LICENSES.json

@@ -4,12 +4,12 @@
   "schemaVersion": "1.0.0",
   "package": {
     "name": "unified-ble-manager",
-    "version": "4.0.10"
+    "version": "4.0.11"
   },
   "source": {
     "method": "pnpm-lock production graph with installed-manifest license audit",
     "lockfile": "pnpm-lock.yaml",
-    "lockfileSha256": "38ee8dcc8420316a625d4572ab163111ac9aef51065626ce8a747298b85819dd"
+    "lockfileSha256": "58c2b09c18f10de1e250a357e5ce9445fe6bcace614e3778bc60166b9db31fa1"
   },
   "reviewedOverrides": [
     {

package/docs/CONNECTION_MANAGER.md

@@ -95,6 +95,40 @@ reconnect. See [`BACKGROUND.md`](BACKGROUND.md) and
 [`EXPO_PLUGIN.md`](EXPO_PLUGIN.md). Electron renderer resources remain owned by
 their authorized renderer lease; the main process owns the physical backend.
 
+## Adapter interruption and recovery
+
+An adapter power transition is not a peer disappearance. UBM publishes the
+typed transition through `manager.adapter.watchState()` and invalidates active
+connection generations while the adapter is unavailable. This behavior is
+shared by the React Native Android, React Native Apple, BlueZ, WinRT, Electron,
+Tauri, and Web backends wherever the platform exposes adapter state.
+
+The application remains the reconnect authority:
+
+```ts
+const watch = await manager.adapter.watchState()
+let prior = watch.initial
+for await (const item of watch.values) {
+  if (item.kind !== 'value') continue
+  const current = item.value
+  const becameReady = prior.power !== 'on'
+    && current.power === 'on'
+    && current.availability === 'available'
+    && current.authorization === 'granted'
+  prior = current
+  if (becameReady) {
+    // Resolve a fresh peer/reference and invoke the caller-owned retry policy.
+  }
+}
+await watch.stop()
+```
+
+Do not create a second manager or reuse a connection/database from before the
+adapter loss. A backend may report a cleanup retry while native operations are
+settling; wait for a ready state and retry the application operation with a new
+generation. Backends that cannot observe a given adapter transition expose the
+truthful snapshot they have and never fabricate reconnect behavior.
+
 ## Cleanup failures
 
 Cleanup records are data. A `release-failed` result retains retry ownership and

package/docs/ELECTRON.md

@@ -4,7 +4,7 @@
 
 Main owns the radio. The renderer uses a versioned IPC client and never loads a native addon.
 
-This source targets `4.0.10`. Tagged releases ship Node-API v8 prebuilds covering macOS and Windows `arm64`/`x64` for both Node and modern Electron.
+This source targets `4.0.11`. Tagged releases ship Node-API v8 prebuilds covering macOS and Windows `arm64`/`x64` for both Node and modern Electron.
 
 `unified-ble-manager/electron/main` and
 `unified-ble-manager/electron/renderer` are the only Electron entrypoints.

package/docs/EXPO_PLUGIN.md

@@ -7,7 +7,7 @@ start a radio, request runtime permissions during prebuild, or prove physical
 radio/restoration reliability. Expo Go is not a supported BLE execution
 environment because it cannot contain this native module.
 
-Use the v2 plugin options in this `4.0.10` source. Those options match
+Use the v2 plugin options in this `4.0.11` source. Those options match
 the schema introduced at `4.0.0-rc.4`. Expo Go cannot load this native module.
 
 ## Installation and development build

package/docs/GAPS.4.0.md

@@ -14,7 +14,7 @@ This file tracks platform code, CI, package, lab, and live-radio evidence. It do
 
 The clean-baseline contract, unified core, public manager, deterministic backend, TCK, native protocol, first-party backend implementations, host-isolated package exports, SDK/CLI, and legacy-absence gates exist in the 4.0 source. Passing deterministic, compile, ABI, or package tests are implementation proof; they do not become physical-radio support evidence unless a retained record proves the corresponding live scenario.
 
-This source targets `unified-ble-manager@4.0.10`; the npm registry and release
+This source targets `unified-ble-manager@4.0.11`; the npm registry and release
 provenance, not a source version string, determine whether it is published.
 Earlier stable releases remain immutable published history. Backend support labels remain
 evidence-derived. This package does not rewrite the evidence inventory: a backend remains at the support level

package/docs/GETTING_STARTED.md

@@ -4,7 +4,7 @@
 
 This page gets you to a first scan, connect, read, notify, and teardown on React Native. Other hosts are linked at the bottom. The root import does not turn Bluetooth on.
 
-This source targets `4.0.10`; verify the published version in the npm registry.
+This source targets `4.0.11`; verify the published version in the npm registry.
 
 ## Pick a host
 
@@ -38,11 +38,11 @@ request runtime permissions on Android 12+, add
 #### Expo / CNG v2
 
 The Expo v2 schema and `unified-ble-manager/expo` factory are in this source.
-After the npm registry lists `4.0.10`, install that exact version and keep it in
+After the npm registry lists `4.0.11`, install that exact version and keep it in
 your lockfile while validating the native build:
 
 ```sh
-pnpm add unified-ble-manager@4.0.10
+pnpm add unified-ble-manager@4.0.11
 ```
 
 The package does not run in Expo Go.

package/docs/NODE.md

@@ -10,7 +10,7 @@ The root import does not open an adapter. Pick one backend:
 | `unified-ble-manager/node/winrt`         | Windows                                      |
 | `unified-ble-manager/node/bluez`         | Linux (needs `dbus-next@^0.10.2` in the app) |
 
-This source targets `4.0.10`. Tagged releases ship Node-API v8 prebuilds for macOS and Windows on `arm64` and `x64`. A normal install should not compile native code. BlueZ talks D-Bus and has no addon.
+This source targets `4.0.11`. Tagged releases ship Node-API v8 prebuilds for macOS and Windows on `arm64` and `x64`. A normal install should not compile native code. BlueZ talks D-Bus and has no addon.
 
 ## One-call factories
 

package/docs/WEB.md

@@ -2,112 +2,252 @@
 
 # Web Bluetooth
 
-Use `unified-ble-manager/web` in a secure context (HTTPS or localhost) from a user gesture. There is no background scan and no process-level restoration.
+Use `unified-ble-manager/web` to run the public UBM manager directly in a browser. The Web backend uses the browser’s device chooser instead of continuous scanning, then exposes the same connection and GATT handles as the other UBM hosts.
 
-This source targets `4.0.10`. The backend is Experimental until artifact-bound physical-hardware validation says otherwise. See [`PLATFORMS.md`](PLATFORMS.md).
+The complete runnable TypeScript/Vite application is in [`example-web/`](../example-web/).
 
-## Create the manager
+This guide targets `4.0.11`. Web Bluetooth support still depends on the browser, operating system, adapter, and peripheral. UBM reports those runtime boundaries; it does not fabricate a fallback backend.
+
+## Requirements
+
+- Use Chrome or another browser that implements Web Bluetooth.
+- Serve the page over HTTPS. `http://localhost` is also treated as a secure development context.
+- Start the system chooser from a click or another transient user activation.
+- If the page is inside an iframe, its container must grant the `bluetooth` Permissions Policy.
+- Keep the requested peripheral near the browser and ensure another central is not already occupying its connection.
+
+Web Bluetooth does not provide UBM’s continuous `scan()` capability, background monitoring after the page closes, or process-level restoration. `manager.scan()` therefore rejects with `capability.unsupported`; use `manager.choose()` (often named `ble.choose()` in smaller examples).
+
+## Install and create the manager
+
+```sh
+pnpm add unified-ble-manager
+```
 
 ```ts
 import { createWebBleManager } from 'unified-ble-manager/web'
 
-const ble = await createWebBleManager()
+const manager = await createWebBleManager()
 ```
 
-Call `ble.choose()` from a click handler. Chromium's
-`navigator.bluetooth.getDevices()` can return previously granted devices; this
-package does not wrap that browser API. Iframes need the `bluetooth`
-Permissions Policy. Then connect and use the generation-bound GATT objects.
+The factory returns the same host-neutral `BleManager` interface used elsewhere. Importing `unified-ble-manager/web` is explicit: failure to load Web Bluetooth never substitutes React Native, Node, a simulator, or a mock.
+
+## Complete browser lifecycle
 
-Inject `environment` only for tests or unusual hosts:
+This example chooses a standard Heart Rate Service peripheral, grants optional access to Battery Service, connects, discovers GATT, reads Battery Level, and consumes Heart Rate notifications.
 
 ```ts
-import { createWebBleManagerWithEnvironment } from 'unified-ble-manager/web'
-
-const timers = new Map<object, ReturnType<typeof window.setTimeout>>()
-
-const ble = await createWebBleManagerWithEnvironment({
-  environment: {
-    implementationVersion: '1',
-    browserEngine: navigator.userAgent,
-    bluetooth: {
-      getAvailability:
-        typeof navigator.bluetooth?.getAvailability === 'function'
-          ? () => navigator.bluetooth.getAvailability()
-          : undefined,
-      requestDevice: options => navigator.bluetooth.requestDevice(options)
-    },
-    isSecureContext: () => window.isSecureContext,
-    hasTransientUserActivation: () => navigator.userActivation?.isActive ?? false,
-    now: () => performance.now(),
-    setTimer: (callback, delayMilliseconds) => {
-      const handle = Object.freeze({})
-      const timer = window.setTimeout(() => {
-        timers.delete(handle)
-        callback()
-      }, delayMilliseconds)
-      timers.set(handle, timer)
-      return handle
-    },
-    clearTimer: handle => {
-      const timer = timers.get(handle)
-      if (timer === undefined) {
-        return
-      }
-      timers.delete(handle)
-      window.clearTimeout(timer)
-    },
-    addPageLifecycleListener: listener => {
-      const onVisibilityChange = () => {
-        if (document.visibilityState === 'hidden') listener('page-hidden')
-      }
-      const onPageHide = () => listener('page-unloaded')
-      document.addEventListener('visibilitychange', onVisibilityChange)
-      window.addEventListener('pagehide', onPageHide)
-      return () => {
-        document.removeEventListener('visibilitychange', onVisibilityChange)
-        window.removeEventListener('pagehide', onPageHide)
+import { BleError, type BleManager } from 'unified-ble-manager'
+import { createWebBleManager } from 'unified-ble-manager/web'
+import {
+  BATTERY_LEVEL_CHARACTERISTIC,
+  BATTERY_SERVICE,
+  parseBatteryLevel
+} from 'unified-ble-manager/profiles/battery-service'
+import {
+  HEART_RATE_MEASUREMENT_CHARACTERISTIC,
+  HEART_RATE_SERVICE,
+  parseHeartRateMeasurement
+} from 'unified-ble-manager/profiles/heart-rate'
+
+let manager: BleManager | null = null
+
+async function chooseReadAndSubscribe(): Promise<void> {
+  manager = await createWebBleManager()
+
+  try {
+    // Keep this call directly in the click-handler path.
+    const peer = await manager.choose({
+      filters: [{ serviceUuids: [HEART_RATE_SERVICE] }],
+      optionalServices: [BATTERY_SERVICE],
+      timeoutMs: 60_000
+    })
+
+    const connection = await manager.connect(peer, { timeoutMs: 60_000 })
+
+    try {
+      const gatt = await connection.discover({ timeoutMs: 20_000 })
+
+      const battery = gatt.characteristic(BATTERY_SERVICE, BATTERY_LEVEL_CHARACTERISTIC)
+      const batteryPercent = parseBatteryLevel(await battery.read({ timeoutMs: 10_000 }))
+      console.log('Battery', batteryPercent)
+
+      const heartRate = gatt.characteristic(HEART_RATE_SERVICE, HEART_RATE_MEASUREMENT_CHARACTERISTIC)
+      const subscription = await heartRate.subscribe({
+        timeoutMs: 10_000,
+        delivery: 'prefer-notification',
+        stream: 'balanced'
+      })
+
+      try {
+        for await (const event of subscription.values) {
+          if (event.kind === 'value') {
+            const measurement = parseHeartRateMeasurement(event.value.value)
+            console.log('Heart rate', measurement.beatsPerMinute)
+          } else if (event.kind === 'overflow') {
+            console.warn('Dropped notification items', event.droppedItems)
+          } else {
+            console.log('Subscription ended', event.reason)
+            break
+          }
+        }
+      } finally {
+        await subscription.remove()
       }
+    } finally {
+      await connection.disconnect()
+    }
+  } catch (error) {
+    if (error instanceof BleError) {
+      console.error({
+        code: error.code,
+        domain: error.domain,
+        operation: error.operation,
+        browserCause: error.platform?.metadata.browserErrorName,
+        recovery: error.recovery
+      })
     }
+    throw error
+  } finally {
+    await manager.destroy()
+    manager = null
   }
+}
+
+document.querySelector('#connect')?.addEventListener('click', () => {
+  void chooseReadAndSubscribe()
 })
 ```
 
-`ble` is the same host-neutral `BleManager` as other hosts. `ble.choose()` is the browser picker.
+For an application with separate Connect, Disconnect, Reconnect, and Destroy controls, use the runnable [`example-web/src/main.ts`](../example-web/src/main.ts).
 
-## Choose a device, then connect
+## Filters and service permission
 
-Call `ble.choose()` from a click or other transient user activation. Then use the normal GATT loop.
+Chooser `filters` decide which devices the browser may display. Separate filter objects are OR branches; the fields inside one filter are AND constraints.
 
 ```ts
-import { HEART_RATE_SERVICE } from 'unified-ble-manager/profiles/heart-rate'
-import { BATTERY_SERVICE } from 'unified-ble-manager/profiles/battery-service'
-import { createWebBleManager } from 'unified-ble-manager/web'
-
-const ble = await createWebBleManager()
-
-const peer = await ble.choose({
-  filters: [{ serviceUuids: [HEART_RATE_SERVICE] }],
+const peer = await manager.choose({
+  filters: [{ serviceUuids: [HEART_RATE_SERVICE], namePrefix: 'My device' }],
   optionalServices: [BATTERY_SERVICE],
-  timeoutMs: 20_000
+  timeoutMs: 60_000
 })
+```
+
+`optionalServices` grants later GATT access to services that were not part of the matching filter. It accepts service UUIDs, not characteristic UUIDs. Request every service the application will access, but do not request unrelated services.
+
+The chooser itself belongs to the browser. UBM cannot auto-select a new device, extend the browser’s native discovery UI, or tell whether Chrome’s `NotFoundError` came from an explicit Cancel action versus the chooser closing without a compatible selection. UBM preserves the browser cause in `error.platform` and reports the stable public code `chooser.cancelled`.
 
-const connection = await ble.connect(peer, { timeoutMs: 15_000 })
-const database = await connection.discover({ timeoutMs: 15_000 })
-const battery = database.characteristic(BATTERY_SERVICE, '2A19')
-const bytes = await battery.read({ timeoutMs: 10_000 })
+## Previously authorized devices
+
+When the browser exposes `navigator.bluetooth.getDevices()`, UBM projects those origin grants through the peer directory:
+
+```ts
+const manager = await createWebBleManager()
+const authorized = await manager.peers.authorized({ timeoutMs: 10_000 })
+
+if (authorized.length === 1) {
+  const connection = await manager.connect(authorized[0], { timeoutMs: 60_000 })
+  await connection.disconnect()
+}
 ```
 
-`ble.scan()` fails with `capability.unsupported`. Keep a real chooser button.
+An authorized Web peer means the current origin has permission to address that browser device. It is not an Android-style system bond, proof that the device is nearby, or proof that another central is not connected. Do not guess when several authorized peers exist; ask the user to choose explicitly or use an application-owned persisted `PeerReference` and `manager.peers.resolve()`.
+
+Origin authorization can survive a reload, but an in-memory peer or connection handle cannot. Create a new manager after reload and query or resolve the peer again.
+
+## Deadlines, cancellation, and safe retry
 
-When the page session ends:
+All public operations accept `timeoutMs`; cancellable operations also accept `signal`. Each timeout applies to that operation, not to an entire multi-step journey.
 
 ```ts
-await ble.destroy()
+const abort = new AbortController()
+const connection = await manager.connect(peer, {
+  signal: abort.signal,
+  timeoutMs: 60_000
+})
+```
+
+There is one important browser boundary: `BluetoothRemoteGATTServer.connect()` returns a native promise with no cancellation API. If `manager.connect()` reaches its deadline, UBM reports `operation.timed-out` but retains pending ownership so a second native connection cannot race the first one.
+
+Do not immediately call `connect()` again on that same manager and peer. That correctly fails with `connection.already-owned`. Instead, destroy the manager, await cleanup, then start a fresh user-driven attempt:
+
+```ts
+try {
+  await manager.connect(peer, { timeoutMs: 60_000 })
+} catch (error) {
+  if (
+    error instanceof BleError &&
+    error.code === 'operation.timed-out' &&
+    error.operation === 'web-connection.connect'
+  ) {
+    await manager.destroy()
+    manager = await createWebBleManager()
+  }
+  throw error
+}
+```
+
+Destroy compensation also handles a late native success by disconnecting it. Clearing ownership early would permit overlapping browser connections and is intentionally not supported.
+
+## Notifications and cleanup
+
+Subscription values are a bounded async stream. Handle all three event kinds:
+
+- `value`: a notification or indication payload;
+- `overflow`: visible data loss because the consumer did not drain fast enough;
+- `terminal`: the stream ended because of removal, disconnect, adapter loss, or teardown.
+
+Release resources from the inside out:
+
+1. `await subscription.remove()`;
+2. `await connection.disconnect()`;
+3. `await manager.destroy()`.
+
+Each cleanup returns a receipt. Production applications should verify `state === 'released'` and preserve any reported cleanup failures. Also destroy the manager during page teardown as a best-effort safeguard, while keeping primary cleanup in explicit application actions.
+
+## Errors users can act on
+
+Catch `BleError` from the root package and retain its structured fields. Do not replace every failure with one generic message.
+
+| Field       | Meaning                                                                                        |
+| ----------- | ---------------------------------------------------------------------------------------------- |
+| `code`      | Stable UBM category such as `chooser.cancelled`, `operation.timed-out`, or `connection.failed` |
+| `domain`    | UBM subsystem such as `chooser`, `connection`, or `gatt`                                       |
+| `operation` | Exact operation boundary, for example `web-connection.connect`                                 |
+| `platform`  | Safe browser detail, including `browserErrorName` when Chrome supplies one                     |
+| `recovery`  | Deterministic recovery disposition and suggested actions                                       |
+
+Common boundaries:
+
+- `chooser.cancelled` + `NotFoundError`: the chooser ended without returning a compatible device;
+- `connection.failed` + `NetworkError`: Chrome selected the device but could not open GATT;
+- `operation.timed-out` at `web-connection.connect`: the bounded native connection did not settle;
+- `gatt.not-found`: the connection opened, but a requested service or characteristic was unavailable or not granted;
+- `operation.disconnected`: the link ended during another operation.
+
+## Iframes and deployment
+
+A top-level HTTPS page needs no extra header. An embedded application needs its container to allow Bluetooth, for example:
+
+```html
+<iframe src="https://example.test/app" allow="bluetooth"></iframe>
+```
+
+The embedding server may also restrict or grant access using the `Permissions-Policy` response header. Browser and administrator policies can still disable Web Bluetooth.
+
+## Testing
+
+Application tests should inject `createWebBleManagerWithEnvironment()` only at a test boundary. Production code should use `createWebBleManager()`.
+
+The repository example builds against the public package entrypoints:
+
+```sh
+pnpm build:example:web
+pnpm example:web
 ```
 
-A working Chrome harness lives in [`example-web/`](../example-web/). It is a live check, not a support claim.
+Open <http://localhost:5173>. A successful local run is useful evidence, but it is not by itself a cross-browser or cross-platform support claim.
 
 ## Maintainers
 
-[`UNIFIED_BLE_4.0_IMPLEMENTATION_PLAN.md`](UNIFIED_BLE_4.0_IMPLEMENTATION_PLAN.md)
+See [`PLATFORMS.md`](PLATFORMS.md), [`PEERS.md`](PEERS.md), and [`UNIFIED_BLE_4.0_IMPLEMENTATION_PLAN.md`](UNIFIED_BLE_4.0_IMPLEMENTATION_PLAN.md).

package/docs/generated/PLATFORM_SUPPORT.md

@@ -6,7 +6,7 @@ This page is generated by `scripts/docs/generate-platform-support.js` from valid
 
 ## Current package
 
-`unified-ble-manager@4.0.10`
+`unified-ble-manager@4.0.11`
 
 No evidence record is bound to this exact package version and artifact. Consequently, this generated page makes no Preview, Live Preview, Supported, or Reliability-qualified platform claim for the current package.
 

package/lib/commonjs/implementation-version.js

@@ -7,5 +7,5 @@ exports.UNIFIED_BLE_IMPLEMENTATION_VERSION = void 0;
 // src/implementation-version.ts
 
 /** The one production version stamped into every first-party backend identity. */
-const UNIFIED_BLE_IMPLEMENTATION_VERSION = exports.UNIFIED_BLE_IMPLEMENTATION_VERSION = '4.0.10';
+const UNIFIED_BLE_IMPLEMENTATION_VERSION = exports.UNIFIED_BLE_IMPLEMENTATION_VERSION = '4.0.11';
 //# sourceMappingURL=implementation-version.js.map

package/lib/module/implementation-version.js

@@ -3,5 +3,5 @@
 // src/implementation-version.ts
 
 /** The one production version stamped into every first-party backend identity. */
-export const UNIFIED_BLE_IMPLEMENTATION_VERSION = '4.0.10';
+export const UNIFIED_BLE_IMPLEMENTATION_VERSION = '4.0.11';
 //# sourceMappingURL=implementation-version.js.map

package/lib/typescript/commonjs/src/backends/bluez/bluez-backend-provider.d.ts

@@ -4,7 +4,7 @@ import { type BackendCompatibilityOffer } from '../../backend-contract/primitive
 import { type BluezBusKind, type BluezDbusBoundaryFactory } from './bluez-dbus-contract';
 export declare const BLUEZ_BACKEND_ID = "unified-ble:bluez-dbus";
 export declare const BLUEZ_PLATFORM_ID = "unified-ble:linux-bluez";
-export declare const BLUEZ_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const BLUEZ_IMPLEMENTATION_VERSION = "4.0.11";
 export declare const bluezCompatibility: BackendCompatibilityOffer;
 export interface BluezBackendProviderOptions {
     readonly busKind: BluezBusKind;

package/lib/typescript/commonjs/src/backends/corebluetooth/corebluetooth-identity.d.ts

@@ -1,7 +1,7 @@
 import { type FeatureRegistry } from '../../backend-contract/capabilities';
 export declare const COREBLUETOOTH_BACKEND_ID = "unified-ble:corebluetooth";
 export declare const COREBLUETOOTH_PLATFORM_ID = "unified-ble:macos-corebluetooth";
-export declare const COREBLUETOOTH_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const COREBLUETOOTH_IMPLEMENTATION_VERSION = "4.0.11";
 /** Identity metadata for a direct-GATT boundary that shares this backend core. */
 export interface DirectGattBackendIdentityOptions {
     readonly registeredBackendId: string;

package/lib/typescript/commonjs/src/backends/reactnative/react-native-android-provider.d.ts

@@ -9,7 +9,7 @@ import { ReactNativeAndroidProtocolBoundary } from '../../native-protocol/rn-and
 import { ReactNativeRestorationCoordinator, type ReactNativeRestorationActivation, type ReactNativeRestorationBackendProvider } from './react-native-restoration';
 export declare const REACT_NATIVE_ANDROID_BACKEND_ID = "unified-ble:react-native-android";
 export declare const REACT_NATIVE_ANDROID_PLATFORM_ID = "unified-ble:android-gatt";
-export declare const REACT_NATIVE_ANDROID_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const REACT_NATIVE_ANDROID_IMPLEMENTATION_VERSION = "4.0.11";
 export declare const REACT_NATIVE_ANDROID_DEFAULT_ADAPTER_NATIVE_ID = "android-default-adapter";
 export declare const reactNativeAndroidCompatibility: NativeCompatibilityOffer;
 export interface ReactNativeAndroidBackendProviderOptions {

package/lib/typescript/commonjs/src/backends/reactnative/react-native-apple-provider.d.ts

@@ -3,7 +3,7 @@ import type { Spec as NativeProtocolControl } from '../../NativeUnifiedBleProtoc
 import { type ReactNativeRestorationBackendProvider } from './react-native-restoration';
 export declare const REACT_NATIVE_APPLE_BACKEND_ID = "unified-ble:react-native-apple";
 export declare const REACT_NATIVE_APPLE_PLATFORM_ID = "unified-ble:apple-corebluetooth";
-export declare const REACT_NATIVE_APPLE_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const REACT_NATIVE_APPLE_IMPLEMENTATION_VERSION = "4.0.11";
 export declare const REACT_NATIVE_APPLE_DEFAULT_ADAPTER_NATIVE_ID = "apple-corebluetooth-default-adapter";
 export declare const reactNativeAppleCompatibility: NativeCompatibilityOffer;
 export interface ReactNativeAppleBackendProviderOptions {

package/lib/typescript/commonjs/src/backends/winrt/winrt-provider.d.ts

@@ -3,7 +3,7 @@ import { type BackendCompatibilityOffer } from '../../backend-contract/primitive
 import { type WinRtAdapterRecord, type WinRtBoundary } from './winrt-boundary';
 export declare const WINRT_BACKEND_ID = "unified-ble:winrt";
 export declare const WINRT_PLATFORM_ID = "unified-ble:windows-winrt";
-export declare const WINRT_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const WINRT_IMPLEMENTATION_VERSION = "4.0.11";
 export declare const winRtCompatibility: BackendCompatibilityOffer;
 export interface WinRtBackendProviderOptions {
     readonly boundaryFactory: () => WinRtBoundary;

package/lib/typescript/commonjs/src/implementation-version.d.ts

@@ -1,3 +1,3 @@
 /** The one production version stamped into every first-party backend identity. */
-export declare const UNIFIED_BLE_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const UNIFIED_BLE_IMPLEMENTATION_VERSION = "4.0.11";
 //# sourceMappingURL=implementation-version.d.ts.map

package/lib/typescript/module/src/backends/bluez/bluez-backend-provider.d.ts

@@ -4,7 +4,7 @@ import { type BackendCompatibilityOffer } from '../../backend-contract/primitive
 import { type BluezBusKind, type BluezDbusBoundaryFactory } from './bluez-dbus-contract.js';
 export declare const BLUEZ_BACKEND_ID = "unified-ble:bluez-dbus";
 export declare const BLUEZ_PLATFORM_ID = "unified-ble:linux-bluez";
-export declare const BLUEZ_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const BLUEZ_IMPLEMENTATION_VERSION = "4.0.11";
 export declare const bluezCompatibility: BackendCompatibilityOffer;
 export interface BluezBackendProviderOptions {
     readonly busKind: BluezBusKind;

package/lib/typescript/module/src/backends/corebluetooth/corebluetooth-identity.d.ts

@@ -1,7 +1,7 @@
 import { type FeatureRegistry } from '../../backend-contract/capabilities.js';
 export declare const COREBLUETOOTH_BACKEND_ID = "unified-ble:corebluetooth";
 export declare const COREBLUETOOTH_PLATFORM_ID = "unified-ble:macos-corebluetooth";
-export declare const COREBLUETOOTH_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const COREBLUETOOTH_IMPLEMENTATION_VERSION = "4.0.11";
 /** Identity metadata for a direct-GATT boundary that shares this backend core. */
 export interface DirectGattBackendIdentityOptions {
     readonly registeredBackendId: string;

package/lib/typescript/module/src/backends/reactnative/react-native-android-provider.d.ts

@@ -9,7 +9,7 @@ import { ReactNativeAndroidProtocolBoundary } from '../../native-protocol/rn-and
 import { ReactNativeRestorationCoordinator, type ReactNativeRestorationActivation, type ReactNativeRestorationBackendProvider } from './react-native-restoration.js';
 export declare const REACT_NATIVE_ANDROID_BACKEND_ID = "unified-ble:react-native-android";
 export declare const REACT_NATIVE_ANDROID_PLATFORM_ID = "unified-ble:android-gatt";
-export declare const REACT_NATIVE_ANDROID_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const REACT_NATIVE_ANDROID_IMPLEMENTATION_VERSION = "4.0.11";
 export declare const REACT_NATIVE_ANDROID_DEFAULT_ADAPTER_NATIVE_ID = "android-default-adapter";
 export declare const reactNativeAndroidCompatibility: NativeCompatibilityOffer;
 export interface ReactNativeAndroidBackendProviderOptions {

package/lib/typescript/module/src/backends/reactnative/react-native-apple-provider.d.ts

@@ -3,7 +3,7 @@ import type { Spec as NativeProtocolControl } from '../../NativeUnifiedBleProtoc
 import { type ReactNativeRestorationBackendProvider } from './react-native-restoration.js';
 export declare const REACT_NATIVE_APPLE_BACKEND_ID = "unified-ble:react-native-apple";
 export declare const REACT_NATIVE_APPLE_PLATFORM_ID = "unified-ble:apple-corebluetooth";
-export declare const REACT_NATIVE_APPLE_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const REACT_NATIVE_APPLE_IMPLEMENTATION_VERSION = "4.0.11";
 export declare const REACT_NATIVE_APPLE_DEFAULT_ADAPTER_NATIVE_ID = "apple-corebluetooth-default-adapter";
 export declare const reactNativeAppleCompatibility: NativeCompatibilityOffer;
 export interface ReactNativeAppleBackendProviderOptions {

package/lib/typescript/module/src/backends/winrt/winrt-provider.d.ts

@@ -3,7 +3,7 @@ import { type BackendCompatibilityOffer } from '../../backend-contract/primitive
 import { type WinRtAdapterRecord, type WinRtBoundary } from './winrt-boundary.js';
 export declare const WINRT_BACKEND_ID = "unified-ble:winrt";
 export declare const WINRT_PLATFORM_ID = "unified-ble:windows-winrt";
-export declare const WINRT_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const WINRT_IMPLEMENTATION_VERSION = "4.0.11";
 export declare const winRtCompatibility: BackendCompatibilityOffer;
 export interface WinRtBackendProviderOptions {
     readonly boundaryFactory: () => WinRtBoundary;

package/lib/typescript/module/src/implementation-version.d.ts

@@ -1,3 +1,3 @@
 /** The one production version stamped into every first-party backend identity. */
-export declare const UNIFIED_BLE_IMPLEMENTATION_VERSION = "4.0.10";
+export declare const UNIFIED_BLE_IMPLEMENTATION_VERSION = "4.0.11";
 //# sourceMappingURL=implementation-version.d.ts.map

package/native/PREBUILDS.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "package": "unified-ble-manager@4.0.10",
+  "package": "unified-ble-manager@4.0.11",
   "nodeApiVersion": 8,
   "entries": [
     {
@@ -10,7 +10,7 @@
       "nodeApiVersion": 8,
       "path": "native/electron/corebluetooth/prebuilds/darwin-arm64/unified_ble_corebluetooth.node",
       "bytes": 332368,
-      "sha256": "f9e631984d0d552e1581829add0ea45be8bdd27d3bdefb8803fda506f00a621d"
+      "sha256": "a92a962daa5414838ebdfd2ac4af42eea610856839099425a5906e8550537bc2"
     },
     {
       "backend": "corebluetooth",
@@ -19,7 +19,7 @@
       "nodeApiVersion": 8,
       "path": "native/electron/corebluetooth/prebuilds/darwin-x64/unified_ble_corebluetooth.node",
       "bytes": 314872,
-      "sha256": "b821193ff6f3b4347bd5c0e220f20ef41cf3529934955e8449bbdac95bb6e2ac"
+      "sha256": "592b048bcc6288066ce199bfdc55ce5fe36e40539bc6cbd8db90dc0b541d975e"
     },
     {
       "backend": "winrt",
@@ -28,7 +28,7 @@
       "nodeApiVersion": 8,
       "path": "native/electron/winrt/prebuilds/win32-arm64/unified_ble_winrt.node",
       "bytes": 644608,
-      "sha256": "ad1e486a2ed2c57f40dea1ad31734287a213da93d96bbe4780370d608e8ebe64"
+      "sha256": "c16ed73cc4600077e1eae1fd94e264b826c729b8cdb3b6a74b29e9a457327b9d"
     },
     {
       "backend": "winrt",
@@ -37,7 +37,7 @@
       "nodeApiVersion": 8,
       "path": "native/electron/winrt/prebuilds/win32-x64/unified_ble_winrt.node",
       "bytes": 614400,
-      "sha256": "13ea0724ff7a05969d1411d28b67c895cc9973d44020977518df028653659275"
+      "sha256": "e617546d3b1b3f71f583cd27fcf5f5cd4923e4eee08f0ad66fd864fabb6215c1"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unified-ble-manager",
-  "version": "4.0.10",
+  "version": "4.0.11",
   "description": "Unified Bluetooth Low Energy manager for React Native, Electron, Tauri, Web, and desktop",
   "packageManager": "pnpm@10.14.0",
   "main": "lib/commonjs/index.js",
@@ -100,8 +100,8 @@
     "native-prebuild:build": "node scripts/native-prebuilds/build.js",
     "native-prebuild:verify": "node scripts/native-prebuilds/verify.js",
     "example:electron": "pnpm prepack && node example-electron/smoke.js",
-    "build:example:web": "node scripts/examples/build-web-example.js",
-    "example:web": "pnpm prepack && pnpm build:example:web && node scripts/examples/serve-web-example.js",
+    "build:example:web": "tsc --noEmit -p example-web/tsconfig.json && vite build --config example-web/vite.config.mts",
+    "example:web": "pnpm prepack && vite --config example-web/vite.config.mts",
     "prepare": "pnpm clean:plugin && pnpm build:plugin && pnpm exec bob build",
     "lint:plugin": "eslint plugin/src/*"
   },
@@ -188,6 +188,7 @@
     "styled-components": "^6.1.11",
     "turbo": "^1.10.7",
     "typescript": "^5.2.2",
+    "vite": "^8.2.2",
     "webpack": "5.109.2",
     "yaml": "2.9.0"
   },

package/src/implementation-version.ts

@@ -1,4 +1,4 @@
 // src/implementation-version.ts
 
 /** The one production version stamped into every first-party backend identity. */
-export const UNIFIED_BLE_IMPLEMENTATION_VERSION = '4.0.10'
+export const UNIFIED_BLE_IMPLEMENTATION_VERSION = '4.0.11'