@cero-base/core 1.2.0 → 1.4.0

package/src/network/transports/ble.js

@@ -0,0 +1,779 @@
+import ReadyResource from 'ready-resource'
+import b4a from 'b4a'
+import { hash, randomBytes } from 'hypercore-crypto'
+import safetyCatch from 'safety-catch'
+
+import { GattStream } from './gatt.js'
+
+// iOS never answers an L2CAP channel opened by a Mac central and gives no L2CAP
+// disconnect signal, so one data characteristic (write + notify) carries a
+// framed byte stream both ways instead.
+const DATA_UUID = 'ce1a0004-0000-1000-8000-00805f9b34fb'
+
+// Wire frame both directions: [type:1][sessionId:8][payload].
+const TYPE_OPEN = 1
+const TYPE_DATA = 2
+const TYPE_CLOSE = 3
+const TYPE_HELLO = 4
+const SID_LEN = 8
+const HEADER = 1 + SID_LEN
+
+const DEFAULT_CAP = 4
+const CONNECT_TIMEOUT = 15000
+// per-peer dial backoff: eager while unlinked, patient once linked; the cooldown
+// grows exponentially per consecutive failure.
+const DIAL_COOLDOWN_BASE = 8000
+const DIAL_COOLDOWN_BASE_LONELY = 2000
+const DIAL_COOLDOWN_MAX = 30000
+// one radio can't usefully dial faster than this
+const DIAL_MIN_INTERVAL = 500
+// iOS reports a peripheral once per scan session; restart to re-report a
+// re-advertised peer.
+const SCAN_RESTART_LONELY = 5000
+// linked: continuous scanning is the dominant battery cost, so duty-cycle it.
+const SCAN_DUTY_ON = 5000
+const SCAN_DUTY_OFF = 25000
+// suspend() drain window: let goodbye frames flush before hanging up.
+const DRAIN_MS = 300
+
+const EMPTY = b4a.alloc(0)
+
+/**
+ * Build a wire frame [type][sessionId][payload].
+ *
+ * @param {number} type
+ * @param {Uint8Array} sid  8-byte session id.
+ * @param {Uint8Array} [payload]
+ * @returns {Buffer}
+ */
+function frame(type, sid, payload = EMPTY) {
+  const out = b4a.allocUnsafe(HEADER + payload.byteLength)
+  out[0] = type
+  b4a.copy(sid, out, 1)
+  if (payload.byteLength) b4a.copy(payload, out, HEADER)
+  return out
+}
+
+/**
+ * Parse a wire frame. Short/empty buffers → null (caller drops).
+ *
+ * @param {Uint8Array} buf
+ * @returns {{ type: number, sid: Uint8Array, sidHex: string, payload: Uint8Array } | null}
+ */
+function parseFrame(buf) {
+  if (!buf || buf.byteLength < HEADER) return null
+  const sid = buf.subarray(1, HEADER)
+  return {
+    type: buf[0],
+    sid,
+    sidHex: b4a.toString(sid, 'hex'),
+    payload: buf.subarray(HEADER)
+  }
+}
+
+/**
+ * Derive a stable 128-bit BLE service UUID from a topic. Only devices that
+ * compute the same UUID (same channel / same invite) ever discover each other.
+ *
+ * @param {Uint8Array} topic
+ * @param {string} [tag]  Namespace so channel and invite meshes never collide.
+ * @returns {string}
+ */
+export function toServiceUUID(topic, tag = 'cero-ble') {
+  const h = hash([b4a.from(tag), topic])
+  const hex = b4a.toString(h.subarray(0, 16), 'hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+// Backend adapter state → the app-facing state the facade exposes.
+const STATE = {
+  poweredOn: 'on',
+  poweredOff: 'waiting',
+  unauthorized: 'unauthorized',
+  unsupported: 'unsupported',
+  resetting: 'waiting',
+  unknown: 'waiting'
+}
+
+const uuidEq = (a, b) =>
+  String(a || '')
+    .toLowerCase()
+    .replace(/-/g, '') ===
+  String(b || '')
+    .toLowerCase()
+    .replace(/-/g, '')
+
+const findByUUID = (items, uuid) => (items || []).find((i) => uuidEq(i.uuid, uuid)) || null
+
+/**
+ * Dual-role BLE transport: advertises + scans one service UUID, opens a GATT
+ * byte-stream to each discovered peer, and feeds it into `network.inject`. From
+ * there replication and pairing are transport-agnostic (see Network.inject).
+ *
+ * The server adds one data characteristic (write + notify) and advertises. The
+ * central connects, discovers the characteristic, subscribes, then framed bytes
+ * flow both ways — central→server as GATT writes, server→central as
+ * notifications — each tagged with an 8-byte session id. `backend` is
+ * bare-bluetooth in production and a mock in tests.
+ *
+ * @extends ReadyResource
+ */
+export class BLETransport extends ReadyResource {
+  /**
+   * @param {object} opts
+   * @param {any} opts.backend            bare-bluetooth-shaped module (Central, Server, Service, Characteristic).
+   * @param {import('../index.js').Network} opts.network
+   * @param {Uint8Array} opts.uuid        The 32-byte topic the service UUID derives from.
+   * @param {Uint8Array} opts.nodeId      Stable local id (identity/device key) for the initiate tie-break.
+   * @param {string} [opts.tag]           UUID namespace (channel mesh vs invite mesh).
+   * @param {number} [opts.cap]           Max concurrent links; gossip covers the rest.
+   * @param {{ scanMode?: any }} [opts.scanOptions]  Platform scan options (e.g. Android low-power).
+   * @param {boolean} [opts.keepLinks]    On close, stop the radio but leave established links alive (invite rendezvous: the link outlives the QR and carries the initial replication).
+   * @param {string} [opts.name]          Local app-user display name, sent to peers over a hello frame.
+   */
+  constructor({
+    backend,
+    network,
+    uuid,
+    nodeId,
+    tag = 'cero-ble',
+    cap = DEFAULT_CAP,
+    scanOptions,
+    keepLinks = false,
+    name
+  }) {
+    super()
+    this.backend = backend
+    this.network = network
+    this.name = name || ''
+    this.nodeId = nodeId
+    this.nodeHex = b4a.toString(nodeId, 'hex')
+    this.serviceUUID = toServiceUUID(uuid, tag)
+    this.cap = cap
+    this.scanOptions = scanOptions
+    this.keepLinks = keepLinks
+
+    this.state = 'off'
+    this.central = null
+    this.server = null
+    this._dataChar = null
+    /** sessionId hex → { stream, sid } for server-side (peripheral) sessions */
+    this._sessions = new Map()
+    /** serialized server notify queue: { frame, resolve, reject } */
+    this._notifyQueue = []
+    this._scanning = false
+    this._advertising = false
+    this._serviceAdded = false
+    /** peripheral id → per-peer dial state { timer, linked, coolUntil, failures, peerKey, peripheral } */
+    this._devices = new Map()
+    /** last central.connect timestamp — global inter-dial rate limit */
+    this._lastDial = 0
+    this._scanTimer = null
+    this._suspended = false
+    /** live injected links keyed by remote node id hex */
+    this.peers = new Map()
+  }
+
+  /**
+   * Whether we should be the one to open the connection to `peerNodeId`. The
+   * lexicographically smaller id initiates; the larger waits — so a pair
+   * connects once, not twice. Equal (our own reflection) → false.
+   *
+   * @param {Uint8Array} peerNodeId
+   * @returns {boolean}
+   */
+  shouldInitiate(peerNodeId) {
+    return b4a.compare(this.nodeId, peerNodeId) < 0
+  }
+
+  get linkCount() {
+    return this.peers.size
+  }
+
+  _device(id) {
+    let d = this._devices.get(id)
+    if (!d) {
+      d = { timer: null, linked: false, coolUntil: 0, failures: 0, peerKey: null, peripheral: null }
+      this._devices.set(id, d)
+    }
+    return d
+  }
+
+  _prune(id) {
+    const d = this._devices.get(id)
+    if (d && !d.timer && !d.linked && !d.coolUntil && !d.failures && !d.peerKey && !d.peripheral) {
+      this._devices.delete(id)
+    }
+  }
+
+  async _open() {
+    const { Central, Server, Service, Characteristic } = this.backend
+
+    this.server = new Server()
+    this.server.on('stateChange', (s) => {
+      this._onState(s)
+      if (s === 'poweredOn') this._startServer(Service, Characteristic)
+    })
+    this.server.on('serviceAdd', () => {
+      this._serviceAdded = true
+      this._maybeAdvertise()
+    })
+    this.server.on('writeRequest', (reqs) => this._onWriteRequests(reqs))
+    this.server.on('readyToUpdate', () => this._drainNotify())
+    // writeRequests carry no central identifier, so an unsubscribe can't be
+    // mapped to a session; teardown is left to _onChannel's keepalive/timeout.
+    this.server.on('unsubscribe', () => {})
+    this.server.on('error', safetyCatch)
+
+    this.central = new Central()
+    this.central.on('stateChange', (s) => {
+      this._onState(s)
+      if (s === 'poweredOn') this._startScan()
+    })
+    this.central.on('discover', (peripheral) => this._onDiscover(peripheral))
+    this.central.on('connect', (peripheral) => this._onConnect(peripheral))
+    this.central.on('disconnect', () => {})
+    this.central.on('error', (err) => this._onCentralError(err))
+
+    this._startServer(Service, Characteristic)
+    this._startScan()
+    this.state = 'starting'
+  }
+
+  _startServer(Service, Characteristic) {
+    if (this.server.state !== 'poweredOn') return
+    if (!this._serviceAdded) {
+      this._dataChar = new Characteristic(DATA_UUID, { write: true, notify: true })
+      this.server.addService(new Service(this.serviceUUID, [this._dataChar]))
+    }
+  }
+
+  _maybeAdvertise() {
+    if (this._advertising || !this._serviceAdded) return
+    this._advertising = true
+    this.server.startAdvertising({ serviceUUIDs: [this.serviceUUID] })
+  }
+
+  // ─── server (peripheral) side ─────────────────────────────────────────────
+
+  _onWriteRequests(requests) {
+    const ok = this.server.constructor.ATT_SUCCESS ?? 0
+    for (const req of requests) {
+      // must respond within ms or the central times out — before any parsing
+      if (req.responseNeeded !== false) this.server.respondToRequest(req, ok)
+      if (this._suspended) continue
+      this._onServerFrame(req.data)
+    }
+  }
+
+  _onServerFrame(data) {
+    const f = parseFrame(data)
+    if (!f) return
+    if (f.type === TYPE_OPEN) {
+      if (this._sessions.has(f.sidHex)) return
+      const sid = b4a.from(f.sid) // copy: f.sid views the transient request buffer
+      const stream = new GattStream({
+        send: (payload) => this._enqueueNotify(frame(TYPE_DATA, sid, payload)),
+        onclose: () => this._closeServerSession(f.sidHex, sid)
+      })
+      const session = { stream, sid, conn: null, name: null }
+      this._sessions.set(f.sidHex, session)
+      session.conn = this._onChannel(stream, false, null)
+      this._enqueueNotify(frame(TYPE_HELLO, sid, this._helloPayload())).catch(safetyCatch)
+    } else if (f.type === TYPE_DATA) {
+      const s = this._sessions.get(f.sidHex)
+      if (s) s.stream.receive(b4a.from(f.payload))
+    } else if (f.type === TYPE_HELLO) {
+      const s = this._sessions.get(f.sidHex)
+      if (s) this._applyPeerName(s, f.payload)
+    } else if (f.type === TYPE_CLOSE) {
+      const s = this._sessions.get(f.sidHex)
+      if (s) {
+        this._sessions.delete(f.sidHex)
+        s.stream.remoteEnd()
+      }
+    }
+  }
+
+  _closeServerSession(sidHex, sid) {
+    if (!this._sessions.has(sidHex)) return
+    this._sessions.delete(sidHex)
+    this._enqueueNotify(frame(TYPE_CLOSE, sid)).catch(safetyCatch)
+  }
+
+  // ─── peer display name (hello frame) ──────────────────────────────────────
+
+  _helloPayload() {
+    return b4a.from(JSON.stringify({ n: this.name || '' }))
+  }
+
+  _parseHello(payload) {
+    try {
+      const { n } = JSON.parse(b4a.toString(payload))
+      return typeof n === 'string' ? n : ''
+    } catch {
+      return null
+    }
+  }
+
+  _applyPeerName(session, payload) {
+    const name = this._parseHello(payload)
+    if (name === null) return
+    session.name = name
+    if (session.conn) session.conn._peerName = name
+    this.emit('update')
+  }
+
+  // Serialize notifications through the single characteristic: updateValue
+  // returns false when the peripheral's queue is full — hold the head frame and
+  // retry on the next 'readyToUpdate', preserving order.
+  _enqueueNotify(f) {
+    return new Promise((resolve, reject) => {
+      this._notifyQueue.push({ frame: f, resolve, reject })
+      this._drainNotify()
+    })
+  }
+
+  _drainNotify() {
+    while (this._notifyQueue.length) {
+      const item = this._notifyQueue[0]
+      let ok
+      try {
+        ok = this.server.updateValue(this._dataChar, item.frame)
+      } catch (err) {
+        this._notifyQueue.shift()
+        item.reject(err)
+        continue
+      }
+      if (!ok) return
+      this._notifyQueue.shift()
+      item.resolve()
+    }
+  }
+
+  _startScan() {
+    if (this._scanning || this.central.state !== 'poweredOn') return
+    this._scanning = true
+    this.central.startScan([this.serviceUUID], this.scanOptions)
+    this._armScanRestart()
+  }
+
+  // Lonely: cycle the scan every SCAN_RESTART_LONELY so a re-advertised peer is
+  // re-reported. Linked: duty-cycle SCAN_DUTY_ON on / SCAN_DUTY_OFF dark to save
+  // battery. One timer drives the whole cycle; the next delay derives from phase.
+  _armScanRestart() {
+    if (this._scanTimer) clearTimeout(this._scanTimer)
+    const delay =
+      this.linkCount > 0 ? (this._scanning ? SCAN_DUTY_ON : SCAN_DUTY_OFF) : SCAN_RESTART_LONELY
+    this._scanTimer = setTimeout(() => {
+      this._scanTimer = null
+      if (this.closing || this.closed || this._suspended) return
+      // never toggle the scan mid-dial (would kill the connect) — defer a phase
+      if (this._isDialing()) {
+        this._armScanRestart()
+        return
+      }
+      if (this.linkCount > 0) {
+        if (this._scanning) {
+          this._stopScan()
+          this._armScanRestart()
+        } else {
+          this._startScan()
+        }
+      } else {
+        this._stopScan()
+        this._startScan()
+      }
+    }, delay)
+    if (this._scanTimer.unref) this._scanTimer.unref()
+  }
+
+  _stopScan() {
+    if (!this._scanning) return
+    this._scanning = false
+    try {
+      this.central.stopScan()
+    } catch (err) {
+      safetyCatch(err)
+    }
+  }
+
+  _onState(raw) {
+    const next = STATE[raw] ?? 'waiting'
+    if (next === this.state) return
+    this.state = next
+    this.emit('update')
+  }
+
+  _onDiscover(peripheral) {
+    if (this.closing || this.closed || this._suspended) return
+    const d = this._devices.get(peripheral.id)
+    if (d) {
+      if (d.linked) return
+      if (d.peerKey && this.peers.has(d.peerKey)) return // linked via another channel
+      if (d.coolUntil > Date.now()) return // failed recently — back off
+      if (d.timer) return // already connecting to this one
+    }
+    if (this.linkCount >= this.cap) return // gossip covers the rest
+    if (Date.now() - this._lastDial < DIAL_MIN_INTERVAL) return
+    // dial every discovery and open a session; a redundant link is dropped by
+    // _track's dedup
+    this._lastDial = Date.now()
+    const timer = setTimeout(() => this._abortDial(peripheral, 'timeout'), CONNECT_TIMEOUT)
+    this._device(peripheral.id).timer = timer
+    try {
+      this._stopScan()
+      this.central.connect(peripheral)
+    } catch (err) {
+      this._abortDial(peripheral, err)
+    }
+  }
+
+  _onConnect(peripheral) {
+    this._device(peripheral.id).peripheral = peripheral
+    peripheral.on('error', () => this._abortDial(peripheral, 'peripheral-error'))
+    peripheral.once('servicesDiscover', (services) => {
+      const svc = findByUUID(services, this.serviceUUID)
+      if (svc) peripheral.discoverCharacteristics(svc, [DATA_UUID])
+      else this._abortDial(peripheral, 'no-service')
+    })
+    peripheral.once('characteristicsDiscover', (_svc, chars) => {
+      const dataChar = findByUUID(chars, DATA_UUID)
+      if (dataChar) peripheral.subscribe(dataChar)
+      else this._abortDial(peripheral, 'no-data-char')
+    })
+    peripheral.once('notifyState', (char, isNotifying) => {
+      if (!isNotifying) {
+        this._abortDial(peripheral, 'subscribe-failed')
+        return
+      }
+      this._startCentralSession(peripheral, char)
+    })
+    // both sides open a session: on iOS the peer id isn't known until after
+    // connect, so a tie-break yields only post-handshake and deadlocks if the
+    // other side never dials back. _track keeps the first, drops the dup.
+    peripheral.discoverServices([this.serviceUUID])
+  }
+
+  // ─── central side ─────────────────────────────────────────────────────────
+
+  _startCentralSession(peripheral, char) {
+    const sid = randomBytes(SID_LEN)
+    const sidHex = b4a.toString(sid, 'hex')
+    peripheral._session = { sidHex, sid }
+    peripheral._char = char // suspend's goodbye writes reuse it
+    peripheral.on('notify', (_char, data) => this._onCentralNotify(peripheral, data))
+    const stream = new GattStream({
+      send: (payload) => this._centralSend(peripheral, char, frame(TYPE_DATA, sid, payload)),
+      onclose: () => {
+        this._centralSend(peripheral, char, frame(TYPE_CLOSE, sid)).catch(safetyCatch)
+        const d = this._devices.get(peripheral.id)
+        if (d) d.peripheral = null
+        try {
+          this.central.disconnect(peripheral)
+        } catch (err) {
+          safetyCatch(err)
+        }
+      }
+    })
+    peripheral._stream = stream
+    // open frame first: it registers the session on the server before any data
+    this._centralSend(peripheral, char, frame(TYPE_OPEN, sid)).catch(safetyCatch)
+    this._centralSend(peripheral, char, frame(TYPE_HELLO, sid, this._helloPayload())).catch(
+      safetyCatch
+    )
+    this._clearDial(peripheral.id)
+    peripheral._conn = this._onChannel(stream, true, peripheral.id)
+  }
+
+  _onCentralNotify(peripheral, data) {
+    const sess = peripheral._session
+    if (!sess || !peripheral._stream) return
+    const f = parseFrame(data)
+    if (!f) return
+    if (f.sidHex !== sess.sidHex) return // not our session
+    if (f.type === TYPE_DATA) peripheral._stream.receive(b4a.from(f.payload))
+    else if (f.type === TYPE_HELLO) {
+      const name = this._parseHello(f.payload)
+      if (name === null) return
+      peripheral._peerName = name
+      if (peripheral._conn) peripheral._conn._peerName = name
+      this.emit('update')
+    } else if (f.type === TYPE_CLOSE) {
+      peripheral._session = null
+      peripheral._stream.remoteEnd()
+    }
+  }
+
+  // One write in flight per peripheral: chain each write behind the previous,
+  // resolving on the 'write' completion event before the next is issued.
+  _centralSend(peripheral, char, f) {
+    const prev = peripheral._writeChain || Promise.resolve()
+    const next = prev.then(() => this._writeOnce(peripheral, char, f))
+    peripheral._writeChain = next.catch(safetyCatch) // keep the chain alive
+    return next
+  }
+
+  _writeOnce(peripheral, char, f) {
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        peripheral.removeListener('write', onWrite)
+        peripheral.removeListener('error', onErr)
+      }
+      const onWrite = () => {
+        cleanup()
+        resolve()
+      }
+      const onErr = (err) => {
+        cleanup()
+        reject(err)
+      }
+      peripheral.once('write', onWrite)
+      peripheral.once('error', onErr)
+      try {
+        peripheral.write(char, f, true)
+      } catch (err) {
+        cleanup()
+        reject(err)
+      }
+    })
+  }
+
+  _abortDial(peripheral, _reason) {
+    const id = peripheral?.id
+    if (id != null) {
+      const d = this._device(id)
+      d.failures += 1
+      const base = this.linkCount === 0 ? DIAL_COOLDOWN_BASE_LONELY : DIAL_COOLDOWN_BASE
+      d.coolUntil =
+        Date.now() + Math.min(DIAL_COOLDOWN_MAX, base * 2 ** Math.min(4, d.failures - 1))
+      d.peripheral = null
+    }
+    this._clearDial(id)
+    try {
+      this.central.disconnect(peripheral)
+    } catch (err) {
+      safetyCatch(err)
+    }
+    this._startScan()
+  }
+
+  _clearDial(id) {
+    if (id == null) return
+    const d = this._devices.get(id)
+    if (!d) return
+    if (d.timer) clearTimeout(d.timer)
+    d.timer = null
+    this._prune(id)
+  }
+
+  _isDialing() {
+    for (const d of this._devices.values()) if (d.timer) return true
+    return false
+  }
+
+  // iOS & Android report errored connects as 'error' with a code, not
+  // 'disconnect' — without this a failed dial pins the peripheral forever.
+  _onCentralError(err) {
+    safetyCatch(err)
+    const code = err && err.code
+    if (code === 'CONNECTION_FAILED' || code === 'DISCONNECT') {
+      for (const [id, d] of this._devices) if (d.timer) this._clearDial(id)
+    }
+  }
+
+  _onChannel(stream, isInitiator, peripheralId) {
+    if (this.closing || this.closed || this._suspended) {
+      stream.destroy()
+      return
+    }
+    const conn = this.network.inject(stream, { isInitiator })
+    // iOS never signals a disconnect for a vanished peer: keepalive pings and the
+    // timeout are the liveness detector (keepalive refreshes the timeout).
+    conn.setKeepAlive(5000)
+    conn.setTimeout(15000)
+    stream.on('error', safetyCatch)
+    // marked at channel-open (not handshake-open): rediscovery must not dial a
+    // peripheral whose channel is still handshaking
+    if (peripheralId != null) {
+      const d = this._device(peripheralId)
+      d.linked = true
+      d.coolUntil = 0
+      d.failures = 0 // reached a live session — reset backoff
+      conn.once('close', () => {
+        const rec = this._devices.get(peripheralId)
+        if (rec) {
+          rec.linked = false
+          this._prune(peripheralId)
+        }
+      })
+    }
+    conn.on('open', () => this._track(conn, peripheralId, isInitiator))
+    conn.on('close', () => this._untrack(conn))
+    this._startScan()
+    return conn
+  }
+
+  _track(conn, peripheralId, isInitiator) {
+    if (peripheralId != null && conn.remotePublicKey) {
+      this._device(peripheralId).peerKey = b4a.toString(conn.remotePublicKey, 'hex')
+    }
+    if (this.closing || this.closed) return
+    const key = b4a.toString(conn.remotePublicKey, 'hex')
+    const existing = this.peers.get(key)
+    if (existing && existing !== conn) {
+      // Both sides dial, so a pair links twice. Dropping a channel closes it for
+      // BOTH devices, so both must retire the SAME channel. Deterministic winner:
+      // keep the channel whose initiator has the smaller static key — computed
+      // identically on both ends, so the loser drops on both and never cascades.
+      const initiatorIsUsSmaller = b4a.compare(conn.publicKey, conn.remotePublicKey) < 0
+      const preferred = isInitiator === initiatorIsUsSmaller
+      if (!preferred) {
+        conn.destroy()
+        return
+      }
+    }
+    conn._peripheralId = peripheralId
+    conn._peerKey = key
+    this.peers.set(key, conn)
+    if (existing && existing !== conn) existing.destroy() // retire the loser channel
+    this.emit('update')
+  }
+
+  _untrack(conn) {
+    const key = conn._peerKey
+    if (key && this.peers.get(key) === conn) this.peers.delete(key)
+    if (!this.closing && !this.closed) {
+      // last link gone → hunt immediately instead of waiting out a dark window
+      if (this.linkCount === 0 && !this._suspended) this._startScan()
+      this.emit('update')
+    }
+  }
+
+  // Best-effort TYPE_CLOSE to every live session — server sessions over notify,
+  // central sessions over write — then wait up to DRAIN_MS for the frames to
+  // flush. Resolves regardless: suspend must never hang on a wedged radio.
+  async _sayGoodbye() {
+    const sent = []
+    for (const { sid } of this._sessions.values()) {
+      sent.push(this._enqueueNotify(frame(TYPE_CLOSE, sid)).catch(safetyCatch))
+    }
+    for (const d of this._devices.values()) {
+      const peripheral = d.peripheral
+      const sess = peripheral && peripheral._session
+      if (!sess || !peripheral._char) continue
+      const f = frame(TYPE_CLOSE, sess.sid)
+      sent.push(this._centralSend(peripheral, peripheral._char, f).catch(safetyCatch))
+    }
+    if (!sent.length) return
+    await Promise.race([Promise.all(sent), new Promise((r) => setTimeout(r, DRAIN_MS))])
+  }
+
+  /**
+   * Pause radio activity but KEEP the Server/Central instances and the
+   * registered GATT service alive — the toggle-friendly counterpart to _close.
+   * CoreBluetooth managers can't be destroy()ed (native double-free), so one
+   * transport is reused across toggles rather than recreated. Idempotent.
+   */
+  async suspend() {
+    this._suspended = true
+    if (this._scanTimer) clearTimeout(this._scanTimer)
+    this._scanTimer = null
+    for (const d of this._devices.values()) if (d.timer) clearTimeout(d.timer)
+    // say goodbye BEFORE teardown so the remote reacts in <1s instead of waiting
+    // out the 15s keepalive: close frames, a short drain, then an ACL disconnect
+    // (an instant OS-level signal on both roles).
+    await this._sayGoodbye()
+    for (const d of this._devices.values()) {
+      if (!d.peripheral) continue
+      try {
+        this.central.disconnect(d.peripheral)
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+    this._devices.clear()
+    try {
+      this._stopScan()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    try {
+      this.server?.stopAdvertising()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    this._advertising = false
+    for (const conn of this.peers.values()) {
+      try {
+        conn.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+    this.peers.clear()
+    for (const { stream } of this._sessions.values()) {
+      try {
+        stream.destroy()
+      } catch (err) {
+        safetyCatch(err)
+      }
+    }
+    this._sessions.clear()
+    for (const item of this._notifyQueue) item.reject(new Error('suspended'))
+    this._notifyQueue = []
+    this.state = 'off'
+    this.emit('update')
+  }
+
+  /**
+   * Restart advertising + scanning on the SAME Server/Central. `_serviceAdded`
+   * is still true (the service was never removed) so advertising resumes
+   * immediately. Safe to call repeatedly; no-op once closing/closed.
+   */
+  resume() {
+    this._suspended = false
+    if (this.closing || this.closed) return
+    this._advertising = false
+    this._maybeAdvertise()
+    this._startScan()
+    const raw = this.central?.state ?? this.server?.state
+    this.state = STATE[raw] ?? 'waiting'
+    this.emit('update')
+  }
+
+  async _close() {
+    if (this._scanTimer) clearTimeout(this._scanTimer)
+    this._scanTimer = null
+    // never call central/server.destroy() — it double-frees in native teardown;
+    // stop advertising/scanning and let the runtime reclaim.
+    for (const d of this._devices.values()) if (d.timer) clearTimeout(d.timer)
+    this._devices.clear()
+    try {
+      this.central?.stopScan()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    try {
+      this.server?.stopAdvertising()
+    } catch (err) {
+      safetyCatch(err)
+    }
+    if (!this.keepLinks) {
+      for (const conn of this.peers.values()) {
+        try {
+          conn.destroy()
+        } catch (err) {
+          safetyCatch(err)
+        }
+      }
+      // kept links keep carrying frames through their sessions/notify queue; only
+      // tear this down when we're actually dropping the links
+      for (const item of this._notifyQueue) item.reject(new Error('closed'))
+      this._notifyQueue = []
+      this._sessions.clear()
+    }
+    this.peers.clear()
+    this.state = 'off'
+  }
+}