unified-ble-manager 4.0.9 → 4.0.11

package/CHANGELOG.md

@@ -6,6 +6,28 @@ 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
+
+- Preserve the originating native platform details when a shared direct-GATT
+  cleanup failure is normalized. React Native Android adapter-loss diagnostics
+  now retain their Android domain and code instead of being mislabeled as
+  CoreBluetooth; Apple retains its CoreBluetooth domain, and host-neutral
+  cleanup records keep the same public operation and retry-ownership contract.
+- Build the complete package during `prepare`, so an explicitly pinned Git
+  release branch exposes the same public entrypoints as the packed artifact.
+
 ## [4.0.9] - 2026-08-29
 
 ### Documentation

package/MIGRATION_4.0.md

@@ -2,7 +2,7 @@
 
 # Migrating from react-native-ble-plx
 
-This source targets `4.0.9`. 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.9`. 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.8` are immutable. `4.0.9` 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,48 @@ 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
+CI passes. Do not tag this release 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.10"
+git diff --exit-code
+git diff --cached --exit-code
+
+git tag -a v4.0.10 -m "v4.0.10"
+git push origin v4.0.10
+```
+
+Before tagging, confirm release-note extraction finds `## [4.0.10]`.
+
 ## Releasing 4.0.9
 
 The `v4.0.9` tag must identify the exact current `main` commit after canonical
@@ -256,7 +298,7 @@ a green publish job and a package a consumer can actually install are not the
 same claim.
 
 ```sh
-version=4.0.6
+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.9",
+      "bom-ref": "pkg:npm/unified-ble-manager@4.0.11",
       "name": "unified-ble-manager",
-      "version": "4.0.9",
+      "version": "4.0.11",
       "licenses": [
         {
           "expression": "Apache-2.0"
         }
       ],
-      "purl": "pkg:npm/unified-ble-manager@4.0.9"
+      "purl": "pkg:npm/unified-ble-manager@4.0.11"
     },
     "properties": [
       {
         "name": "unified-ble-manager:pnpm-lock-sha256",
-        "value": "5fb778bd200cb93f552ec61264d53829dca5bdd27623ccc692d4d9bcbf9ec296"
+        "value": "58c2b09c18f10de1e250a357e5ce9445fe6bcace614e3778bc60166b9db31fa1"
       },
       {
         "name": "unified-ble-manager:dependency-scope",
@@ -66,25 +66,6 @@
         }
       ]
     },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/%40tauri-apps/api@2.11.1",
-      "group": "@tauri-apps",
-      "name": "api",
-      "version": "2.11.1",
-      "licenses": [
-        {
-          "expression": "Apache-2.0 OR MIT"
-        }
-      ],
-      "purl": "pkg:npm/%40tauri-apps/api@2.11.1",
-      "properties": [
-        {
-          "name": "unified-ble-manager:license-source",
-          "value": "package-metadata"
-        }
-      ]
-    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/abbrev@4.0.0",
@@ -457,10 +438,6 @@
         "pkg:npm/minipass@7.1.3"
       ]
     },
-    {
-      "ref": "pkg:npm/%40tauri-apps/api@2.11.1",
-      "dependsOn": []
-    },
     {
       "ref": "pkg:npm/abbrev@4.0.0",
       "dependsOn": []
@@ -560,10 +537,9 @@
       "dependsOn": []
     },
     {
-      "ref": "pkg:npm/unified-ble-manager@4.0.9",
+      "ref": "pkg:npm/unified-ble-manager@4.0.11",
       "dependsOn": [
         "pkg:npm/%40babel/runtime@7.29.7",
-        "pkg:npm/%40tauri-apps/api@2.11.1",
         "pkg:npm/node-addon-api@8.9.0",
         "pkg:npm/node-gyp@12.4.0"
       ]

package/THIRD_PARTY_LICENSES.json

@@ -4,12 +4,12 @@
   "schemaVersion": "1.0.0",
   "package": {
     "name": "unified-ble-manager",
-    "version": "4.0.9"
+    "version": "4.0.11"
   },
   "source": {
     "method": "pnpm-lock production graph with installed-manifest license audit",
     "lockfile": "pnpm-lock.yaml",
-    "lockfileSha256": "5fb778bd200cb93f552ec61264d53829dca5bdd27623ccc692d4d9bcbf9ec296"
+    "lockfileSha256": "58c2b09c18f10de1e250a357e5ce9445fe6bcace614e3778bc60166b9db31fa1"
   },
   "reviewedOverrides": [
     {
@@ -41,13 +41,6 @@
       "licenseSource": "package-metadata",
       "purl": "pkg:npm/%40isaacs/fs-minipass@4.0.1"
     },
-    {
-      "name": "@tauri-apps/api",
-      "version": "2.11.1",
-      "license": "Apache-2.0 OR MIT",
-      "licenseSource": "package-metadata",
-      "purl": "pkg:npm/%40tauri-apps/api@2.11.1"
-    },
     {
       "name": "abbrev",
       "version": "4.0.0",

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.9`. 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.9` 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.9`; 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.9`; 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.9`, 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.9
+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.9`. 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