@cero-base/cero 1.12.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "sideEffects": false,
@@ -95,12 +95,13 @@
     "test:node": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^1.12.0",
+    "@cero-base/core": "^1.14.0",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",
     "bare-fs": "^4.8.0",
     "bare-path": "^3.1.1",
+    "ble-swarm": "^2.2.0",
     "compact-encoding": "^3.3.2",
     "corestore": "^7.12.0",
     "hrpc": "^4.3.1",
@@ -113,6 +114,7 @@
     "ready-resource": "^1.2.0",
     "safety-catch": "^1.0.3",
     "streamx": "^2.28.0",
+    "suspendify": "^1.7.2",
     "z32": "^1.1.0"
   },
   "devDependencies": {
@@ -124,14 +126,5 @@
     "brittle": "^4.1.0",
     "typescript": "^5.9.3"
   },
-  "license": "Apache-2.0",
-  "x": 1,
-  "peerDependencies": {
-    "bare-bluetooth": ">=0.2.0"
-  },
-  "peerDependenciesMeta": {
-    "bare-bluetooth": {
-      "optional": true
-    }
-  }
+  "license": "Apache-2.0"
 }

package/src/bluetooth.js

@@ -1,33 +1,22 @@
 import ReadyResource from 'ready-resource'
+import BluetoothSwarm from 'ble-swarm'
+import crypto from 'hypercore-crypto'
 import safetyCatch from 'safety-catch'
+import b4a from 'b4a'
 
-import { BLETransport } from '@cero-base/core/network/transports/ble'
 import { Pairing } from '@cero-base/core/pairing'
 import { Invite } from '@cero-base/core/invite'
 
 /**
- * Lazily resolve the bare-bluetooth backend. Absent (Linux, or dep not
- * bundled) → null, which the facade reports as `state: 'unsupported'`.
- * Never throws — a missing optional dep is a state, not a crash.
- *
- * @returns {Promise<any | null>}
- */
-async function loadBackend() {
-  try {
-    return await import('bare-bluetooth')
-  } catch {
-    return null
-  }
-}
-
-/**
- * `me.bluetooth` — the whole app-facing surface for nearby (Bluetooth) sync.
- * Bluetooth is a cero feature, not a parallel API: it only changes how peers
- * meet and carry bytes; capability-gated replication still decides what syncs.
+ * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin
+ * facade over ble-swarm. Bluetooth only changes how peers meet and carry
+ * bytes; capability-gated replication still decides what syncs. Discovery is
+ * one topic-derived service UUID at a time (tag `cero-ble`) — the data service
+ * sits on a fixed per-tag UUID, so switching topics only retunes the radio.
  *
  * ```js
  * const me = await cero(dir, spec, { channel, bluetooth: true })
- * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'on'
+ * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'starting' | 'on'
  * await me.bluetooth.start()
  * me.bluetooth.peers          // Map of live BLE links
  * me.bluetooth.on('update', () => {})
@@ -39,7 +28,7 @@ export class Bluetooth extends ReadyResource {
   /**
    * @param {object} handle           Root cero Handle (network + identity + channel).
    * @param {object} [opts]
-   * @param {any} [opts.backend]      Injected bare-bluetooth-shaped backend (tests); lazy-loaded when absent.
+   * @param {any} [opts.backend]      Injected bare-bluetooth-shaped backend (tests); omitted → ble-swarm loads its own, null/false → unsupported.
    * @param {boolean} [opts.autoStart]  Start on handle open (from `cero({ bluetooth: true })`).
    * @param {number} [opts.maxOutbound]  Max concurrent outbound links; gossip covers the rest.
    * @param {number} [opts.maxInbound]   Max concurrent inbound sessions; newcomers past this are refused.
@@ -48,28 +37,91 @@ export class Bluetooth extends ReadyResource {
   constructor(handle, { backend, autoStart, maxOutbound, maxInbound, pipe } = {}) {
     super()
     this._handle = handle
-    // explicit null/false disables bluetooth; only an omitted backend lazy-loads
-    this._backend = backend || null
-    this._lazy = backend === undefined
     this._autoStart = autoStart === true
-    this._maxOutbound = maxOutbound
-    this._maxInbound = maxInbound
-    this._pipe = pipe
-    this._transport = null
-    this._name = null
-    this._announces = new Set()
-    /** @type {'unsupported'|'unauthorized'|'off'|'waiting'|'starting'|'on'} */
-    this.state = 'off'
+    /** @type {{ hex: string, count: number, timer: any } | null} active invite rendezvous (single topic — one at a time) */
+    this._announce = null
+    this._restorePending = false
+
+    const identity = handle.identity
+    // the mesh topic: one per channel, or a fixed global topic when
+    // channelless — any nearby cero device links (global nearby; strangers
+    // still sync zero bytes, replication is capability-gated)
+    this._topic = crypto.hash(b4a.from(handle.network.channel || 'cero-ble'))
+    this.swarm = new BluetoothSwarm({
+      backend,
+      // injected links authenticate with the same long-lived identity as the
+      // swarm, so one person reached over Wi-Fi and BLE dedupes to one peer
+      keyPair: { publicKey: identity.publicKey, secretKey: identity.secretKey },
+      topic: this._topic,
+      tag: 'cero-ble',
+      pipe,
+      maxOutbound,
+      maxInbound
+    })
+    this.swarm.on('update', () => {
+      // an ended rendezvous retunes back to the mesh only once its links
+      // drain — retuning drops links, and the pairing link still carries
+      // the joiner's initial replication
+      if (this._restorePending && this.swarm.peers.size === 0) {
+        this._restorePending = false
+        this.swarm.setTopic(this._topic).catch(safetyCatch)
+      }
+      this.emit('update')
+    })
+    this.swarm.on('connection', (conn) => {
+      // the same treatment as any transport: wakeup, replication, pairing
+      this._handle.network.inject(conn)
+    })
+  }
+
+  /** @returns {'unsupported'|'unauthorized'|'off'|'waiting'|'starting'|'on'} */
+  get state() {
+    return this.swarm.state
+  }
+
+  /** @returns {Map<string, any>} Live BLE links, keyed by peer public key. */
+  get peers() {
+    return this.swarm.peers
+  }
+
+  async _open() {
+    if (this._autoStart) await this.start()
+  }
+
+  /**
+   * Begin advertising + scanning. Idempotent; no-op when unsupported.
+   *
+   * @returns {Promise<void>}
+   */
+  async start() {
+    await this.swarm.start()
   }
 
   /**
-   * Offline join rendezvous. Both sides derive the same BLE service UUID from
-   * the invite, so they find each other with zero DHT: the host calls this
-   * while the invite QR is on screen; the joiner's `open(me.room, invite)`
-   * calls it automatically for the duration of the join. Returns a stop
-   * function — closing the QR must stop the advertisement so a photographed
-   * invite doesn't stay an ambient admission ticket. Auto-stops at the
-   * invite's expiry, on `bluetooth.stop()`, and on close.
+   * Stop advertising/scanning and drop links; open invite rendezvous end with
+   * the radio. Idempotent. Local data and the rest of the network (DHT) are
+   * untouched.
+   *
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    this._clearAnnounce()
+    await this.swarm.stop()
+    // while stopped setTopic just sticks — the next start() is back on the
+    // mesh. A start() + announce() that landed during the await wins.
+    if (!this._announce) await this.swarm.setTopic(this._topic)
+  }
+
+  /**
+   * Offline join rendezvous: retune the radio to the invite-derived topic so
+   * holder and joiner find each other with zero DHT. One topic at a time —
+   * announcing a new invite replaces the previous rendezvous. Returns a stop
+   * function — closing the QR must stop the rendezvous so a photographed
+   * invite doesn't stay an ambient discovery beacon (admission itself is
+   * always gated by blind-pairing verifying the invite). The retune back to
+   * the mesh topic waits for live links to drain: the link a join just
+   * established survives and carries the joiner's initial replication.
+   * Auto-stops at the invite's expiry, on `stop()`, and on close.
    *
    * Only active while nearby sync is on: before `start()` (and after `stop()`)
    * this is a no-op — the user controls the radio, and a join must not touch
@@ -79,141 +131,70 @@ export class Bluetooth extends ReadyResource {
    * @returns {() => void}
    */
   announce(invite) {
-    if (!this._backend || this.state === 'unsupported') return () => {}
-    if (
-      !this._transport ||
-      (this.state !== 'on' && this.state !== 'waiting' && this.state !== 'starting')
-    )
+    if (!this.swarm.supported) return () => {}
+    if (this.state !== 'on' && this.state !== 'waiting' && this.state !== 'starting') {
       return () => {}
+    }
     const topic = Pairing.inviteTopic(invite)
     if (!topic) return () => {}
 
-    const transport = new BLETransport({
-      backend: this._backend,
-      network: this._handle.network,
-      uuid: topic,
-      nodeId: this._handle.identity.publicKey,
-      tag: 'cero-ble-invite',
-      pipe: this._pipe,
-      // the QR closing stops the rendezvous, not the just-established link —
-      // that link carries the joiner's initial replication
-      keepLinks: true
-    })
-    transport.ready().catch(safetyCatch)
-    this._announces.add(transport)
-
-    const { expires } = Invite.parse(invite)
-    const timer = expires > 0 ? setTimeout(() => stop(), Math.max(0, expires - Date.now())) : null
+    const hex = b4a.toString(topic, 'hex')
+    if (this._announce && this._announce.hex !== hex) this._stopAnnounce()
+    if (!this._announce) {
+      const entry = { hex, count: 0, timer: null }
+      const { expires } = Invite.parse(invite)
+      if (expires > 0) {
+        entry.timer = setTimeout(() => this._stopAnnounce(), Math.max(0, expires - Date.now()))
+      }
+      this._announce = entry
+      this._restorePending = false
+      this.swarm.setTopic(topic).catch(safetyCatch)
+    }
+    const entry = this._announce
+    entry.count++
 
-    const stop = () => {
-      if (timer) clearTimeout(timer)
-      if (!this._announces.delete(transport)) return
-      transport.close().catch(safetyCatch)
+    let stopped = false
+    return () => {
+      if (stopped) return
+      stopped = true
+      if (this._announce === entry && --entry.count <= 0) this._stopAnnounce()
     }
-    return stop
   }
 
-  /** @returns {Map<string, any>} Live BLE links, keyed by peer node id. */
-  get peers() {
-    return this._transport ? this._transport.peers : new Map()
+  _stopAnnounce() {
+    this._clearAnnounce()
+    if (this.swarm.peers.size > 0) this._restorePending = true
+    else this.swarm.setTopic(this._topic).catch(safetyCatch)
   }
 
-  async _open() {
-    if (this._backend === null && this._lazy) this._backend = await loadBackend()
-    if (!this._backend) {
-      this.state = 'unsupported'
-      return
-    }
-    if (this._autoStart) await this.start()
+  _clearAnnounce() {
+    const e = this._announce
+    if (!e) return
+    if (e.timer) clearTimeout(e.timer)
+    this._announce = null
+    this._restorePending = false
   }
 
   /**
-   * Begin advertising + scanning on the channel-derived UUID. Idempotent.
-   * No-op (stays `unsupported`) when no backend is present.
+   * Host-lifecycle pause (app backgrounded): radio down, user intent kept.
    *
    * @returns {Promise<void>}
    */
-  async start({ name } = {}) {
-    if (name !== undefined) this._name = name
-    if (this.state === 'unsupported') return
-    if (this._transport) {
-      // reuse one transport across toggles — recreating leaks iOS CoreBluetooth
-      // managers (can't destroy()) and their stale GATT service
-      this._transport.name = this._name || ''
-      this._transport.resume()
-      this.state = this._transport.state
-      this.emit('update')
-      return
-    }
-    const handle = this._handle
-
-    this._transport = new BLETransport({
-      backend: this._backend,
-      network: handle.network,
-      // channel isolation for free: same channel → same UUID, like the swarm.
-      // No channel → the identity topic (unchanged global-mesh semantics).
-      uuid: handle.network.channel
-        ? Buffer.from(handle.network.channel)
-        : handle.identity.publicKey,
-      nodeId: handle.identity.publicKey,
-      name: this._name || '',
-      pipe: this._pipe,
-      maxOutbound: this._maxOutbound,
-      maxInbound: this._maxInbound,
-      // Android scans in a battery-saver mode by default — too slow for a mesh
-      scanOptions:
-        typeof Bare !== 'undefined' && Bare.platform === 'android'
-          ? { scanMode: this._backend.Central.SCAN_MODE_LOW_LATENCY }
-          : undefined
-    })
-    const transport = this._transport
-    transport.on('update', () => {
-      // a torn-down or replaced transport can still emit late adapter events
-      if (this._transport !== transport) return
-      this.state = transport.state
-      this.emit('update')
-    })
-    try {
-      await this._transport.ready()
-      this.state = this._transport.state
-    } catch (err) {
-      this._transport = null
-      this.state = 'off'
-      throw err
-    }
-    this.emit('update')
+  async suspend() {
+    await this.swarm.suspend()
   }
 
   /**
-   * Stop advertising/scanning and drop links. Idempotent. Sync stops; local
-   * data and the rest of the network (DHT) are untouched.
+   * Resume after a host-lifecycle pause.
    *
    * @returns {Promise<void>}
    */
-  async stop() {
-    for (const t of [...this._announces]) {
-      this._announces.delete(t)
-      await t.close().catch(safetyCatch)
-    }
-    if (!this._transport) return
-    // suspend, don't close: keep the transport (and its GATT service) so a later
-    // start() resumes the same instance instead of leaking a new one. suspend()
-    // is async (it says goodbye + drains before hanging up); await it.
-    await this._transport.suspend()
-    this.state = 'off'
-    this.emit('update')
+  async resume() {
+    await this.swarm.resume()
   }
 
   async _close() {
-    for (const t of [...this._announces]) {
-      this._announces.delete(t)
-      await t.close().catch(safetyCatch)
-    }
-    if (this._transport) {
-      await this._transport.close().catch(safetyCatch)
-      this._transport = null
-    }
-    this.state = 'off'
-    this.emit('update')
+    this._clearAnnounce()
+    await this.swarm.destroy()
   }
 }

package/src/handle/index.js

@@ -5,6 +5,7 @@ import Hypercore from 'hypercore'
 import { discoveryKey } from 'hypercore-crypto'
 import ReadyResource from 'ready-resource'
 import safetyCatch from 'safety-catch'
+import Suspendify from 'suspendify'
 import z32 from 'z32'
 
 import { Identity } from '@cero-base/core/identity'
@@ -127,6 +128,10 @@ export class Handle extends ReadyResource {
     this._fileServer = null
     this._blobs = null
     this._epochBlobs = null
+    // root only — serializes suspend/resume, converges rapid bounces
+    this._sus = parent
+      ? null
+      : new Suspendify({ suspend: () => this._suspend(), resume: () => this._resume() })
     this._owned = new Set()
 
     this.store = new Database({
@@ -348,7 +353,10 @@ export class Handle extends ReadyResource {
     blobs
       .ready()
       .then(() => {
-        if (blobs.key) this.root._coreKeys.set(b4a.toString(blobs.key, 'hex'), encryptionKey)
+        // close prunes _coreKeys first — a ready() resolving after that must
+        // not re-insert the entry (it would outlive the handle on the root)
+        if (this.closing || this.closed || !blobs.key) return
+        this.root._coreKeys.set(b4a.toString(blobs.key, 'hex'), encryptionKey)
       })
       .catch(this._onerror)
     return blobs
@@ -374,7 +382,9 @@ export class Handle extends ReadyResource {
         if (stamp === undefined) {
           this.store
             .get('files', id)
-            .then(({ data }) => data && this._registerBlobCore(id, data.stamp || 0))
+            .then(({ data }) => {
+              if (data && !this.closing && !this.closed) this._registerBlobCore(id, data.stamp || 0)
+            })
             .catch(safetyCatch)
           return
         }
@@ -412,7 +422,7 @@ export class Handle extends ReadyResource {
   }
 
   get suspended() {
-    return this._suspended === true
+    return this._sus?.suspended === true
   }
 
   /**
@@ -571,14 +581,14 @@ export class Handle extends ReadyResource {
     const sig = this.identity.sign(
       addWriterPayload(this.store.key, writerKey, this.store.writerKey)
     )
-    await this.store.tx(async () => {
-      await this.store.call('add-writer', {
+    await this.store.tx(async (tx) => {
+      await tx.call('add-writer', {
         sig,
         master: this.identity.publicKey,
         writer: writerKey,
         ts: member.updatedAt || Date.now()
       })
-      await this.store.call('add-member', member)
+      await tx.call('add-member', member)
     })
   }
 
@@ -619,11 +629,25 @@ export class Handle extends ReadyResource {
     )
     // a failure after the child opens must close it — else it leaks its Database,
     // swarm session and attached bee, never reaped by the parent (not yet a child)
+    let publish = null
+    let abort = null
+    let inflightId = null
     try {
       await child.ready()
       child.name = name
 
       const id = toId(child.store.key)
+      // Close the create/open race: the `add-handle` write below makes the row
+      // visible before this create finishes, so a concurrent _load for the id
+      // must share this child — a duplicate Handle over the same core
+      // deadlocks in ready().
+      const inflight = new Promise((resolve, reject) => {
+        publish = resolve
+        abort = reject
+      })
+      inflight.catch(safetyCatch)
+      inflightId = id
+      this._loading?.set(id, inflight)
       await this._saveKeyPair(id, writer)
 
       const ts = Date.now()
@@ -658,8 +682,12 @@ export class Handle extends ReadyResource {
       bind(child, type)
       this.children.add(child)
       this.emit('handle', child, { name, role })
+      publish(child)
+      this._loading?.delete(id)
       return child
     } catch (err) {
+      if (abort) abort(err)
+      if (inflightId) this._loading?.delete(inflightId)
       await child.close().catch(safetyCatch)
       throw err
     }
@@ -738,11 +766,23 @@ export class Handle extends ReadyResource {
     )
     // whenWritable timing out (host offline) is a normal failure — close the
     // fully-opened child rather than leak its Database/pairing/swarm session
+    let publish = null
+    let abort = null
+    let inflightId = null
     try {
       await child.ready()
       if (!child.store.writable) await child.store.whenWritable({ timeout: deadline })
 
       const id = toId(child.store.key)
+      // same create/open race as _create: the add-handle row is visible before
+      // this join finishes — a concurrent _load must share this child
+      const inflight = new Promise((resolve, reject) => {
+        publish = resolve
+        abort = reject
+      })
+      inflight.catch(safetyCatch)
+      inflightId = id
+      this._loading?.set(id, inflight)
       await this._saveKeyPair(id, child.store.keyPair)
 
       const ts = Date.now()
@@ -759,8 +799,12 @@ export class Handle extends ReadyResource {
       bind(child, type)
       this.children.add(child)
       this.emit('handle', child, {})
+      publish(child)
+      this._loading?.delete(id)
       return child
     } catch (err) {
+      if (abort) abort(err)
+      if (inflightId) this._loading?.delete(inflightId)
       await child.close().catch(safetyCatch)
       throw err
     }
@@ -834,9 +878,13 @@ export class Handle extends ReadyResource {
    * @returns {Promise<void>}
    */
   async suspend() {
-    if (this.parent || this.closing || this.closed || this._suspended) return
-    this._suspended = true
+    if (this._sus) await this._sus.suspend()
+  }
+
+  async _suspend() {
+    if (this.closing || this.closed) return
     await Promise.all([...this.children].map((c) => c.pair?.suspend()))
+    await this.bluetooth?.suspend()
     await this.network.suspend()
     try {
       await this.store.store.suspend()
@@ -851,14 +899,18 @@ export class Handle extends ReadyResource {
    * @returns {Promise<void>}
    */
   async resume() {
-    if (this.parent || this.closing || this.closed || !this._suspended) return
-    this._suspended = false
+    if (this._sus) await this._sus.resume()
+  }
+
+  async _resume() {
+    if (this.closing || this.closed) return
     try {
       await this.store.store.resume()
     } catch (err) {
       this._onerror(err)
     }
     await this.network.resume()
+    await this.bluetooth?.resume()
     await Promise.all([...this.children].map((child) => child.pair?.resume()))
   }
 

package/src/index.js

@@ -74,7 +74,7 @@ export { t, schema } from './lib/spec.js'
  * @property {number} [recoveryTimeout]                Max wait for peer data + writer capability during recovery.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
  * @property {boolean} [extensions]                    `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
- * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
+ * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number, pipe?: 'l2cap' | 'gatt' }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
  */
 
 /**
@@ -202,7 +202,8 @@ export async function cero(dir, spec, opts = {}) {
         backend: bt.backend,
         autoStart: bt.autoStart !== false,
         maxOutbound: bt.maxOutbound,
-        maxInbound: bt.maxInbound
+        maxInbound: bt.maxInbound,
+        pipe: bt.pipe
       })
       me.once('close', () => me.bluetooth.close().catch(safetyCatch))
       await me.bluetooth.ready()

package/types/bluetooth.d.ts

@@ -1,11 +1,13 @@
 /**
- * `me.bluetooth` — the whole app-facing surface for nearby (Bluetooth) sync.
- * Bluetooth is a cero feature, not a parallel API: it only changes how peers
- * meet and carry bytes; capability-gated replication still decides what syncs.
+ * `me.bluetooth` — the app-facing surface for nearby (Bluetooth) sync, a thin
+ * facade over ble-swarm. Bluetooth only changes how peers meet and carry
+ * bytes; capability-gated replication still decides what syncs. Discovery is
+ * one topic-derived service UUID at a time (tag `cero-ble`) — the data service
+ * sits on a fixed per-tag UUID, so switching topics only retunes the radio.
  *
  * ```js
  * const me = await cero(dir, spec, { channel, bluetooth: true })
- * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'on'
+ * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'starting' | 'on'
  * await me.bluetooth.start()
  * me.bluetooth.peers          // Map of live BLE links
  * me.bluetooth.on('update', () => {})
@@ -17,7 +19,7 @@ export class Bluetooth extends ReadyResource {
     /**
      * @param {object} handle           Root cero Handle (network + identity + channel).
      * @param {object} [opts]
-     * @param {any} [opts.backend]      Injected bare-bluetooth-shaped backend (tests); lazy-loaded when absent.
+     * @param {any} [opts.backend]      Injected bare-bluetooth-shaped backend (tests); omitted → ble-swarm loads its own, null/false → unsupported.
      * @param {boolean} [opts.autoStart]  Start on handle open (from `cero({ bluetooth: true })`).
      * @param {number} [opts.maxOutbound]  Max concurrent outbound links; gossip covers the rest.
      * @param {number} [opts.maxInbound]   Max concurrent inbound sessions; newcomers past this are refused.
@@ -31,25 +33,44 @@ export class Bluetooth extends ReadyResource {
         pipe?: "l2cap" | "gatt";
     });
     _handle: any;
-    _backend: any;
-    _lazy: boolean;
     _autoStart: boolean;
-    _maxOutbound: number;
-    _maxInbound: number;
-    _pipe: "l2cap" | "gatt";
-    _transport: BLETransport;
-    _name: any;
-    _announces: Set<any>;
-    /** @type {'unsupported'|'unauthorized'|'off'|'waiting'|'starting'|'on'} */
-    state: "unsupported" | "unauthorized" | "off" | "waiting" | "starting" | "on";
+    /** @type {{ hex: string, count: number, timer: any } | null} active invite rendezvous (single topic — one at a time) */
+    _announce: {
+        hex: string;
+        count: number;
+        timer: any;
+    } | null;
+    _restorePending: boolean;
+    _topic: any;
+    swarm: any;
+    /** @returns {'unsupported'|'unauthorized'|'off'|'waiting'|'starting'|'on'} */
+    get state(): "unsupported" | "unauthorized" | "off" | "waiting" | "starting" | "on";
+    /** @returns {Map<string, any>} Live BLE links, keyed by peer public key. */
+    get peers(): Map<string, any>;
+    /**
+     * Begin advertising + scanning. Idempotent; no-op when unsupported.
+     *
+     * @returns {Promise<void>}
+     */
+    start(): Promise<void>;
+    /**
+     * Stop advertising/scanning and drop links; open invite rendezvous end with
+     * the radio. Idempotent. Local data and the rest of the network (DHT) are
+     * untouched.
+     *
+     * @returns {Promise<void>}
+     */
+    stop(): Promise<void>;
     /**
-     * Offline join rendezvous. Both sides derive the same BLE service UUID from
-     * the invite, so they find each other with zero DHT: the host calls this
-     * while the invite QR is on screen; the joiner's `open(me.room, invite)`
-     * calls it automatically for the duration of the join. Returns a stop
-     * function — closing the QR must stop the advertisement so a photographed
-     * invite doesn't stay an ambient admission ticket. Auto-stops at the
-     * invite's expiry, on `bluetooth.stop()`, and on close.
+     * Offline join rendezvous: retune the radio to the invite-derived topic so
+     * holder and joiner find each other with zero DHT. One topic at a time —
+     * announcing a new invite replaces the previous rendezvous. Returns a stop
+     * function — closing the QR must stop the rendezvous so a photographed
+     * invite doesn't stay an ambient discovery beacon (admission itself is
+     * always gated by blind-pairing verifying the invite). The retune back to
+     * the mesh topic waits for live links to drain: the link a join just
+     * established survives and carries the joiner's initial replication.
+     * Auto-stops at the invite's expiry, on `stop()`, and on close.
      *
      * Only active while nearby sync is on: before `start()` (and after `stop()`)
      * this is a no-op — the user controls the radio, and a join must not touch
@@ -59,22 +80,19 @@ export class Bluetooth extends ReadyResource {
      * @returns {() => void}
      */
     announce(invite: string): () => void;
-    /** @returns {Map<string, any>} Live BLE links, keyed by peer node id. */
-    get peers(): Map<string, any>;
+    _stopAnnounce(): void;
+    _clearAnnounce(): void;
     /**
-     * Begin advertising + scanning on the channel-derived UUID. Idempotent.
-     * No-op (stays `unsupported`) when no backend is present.
+     * Host-lifecycle pause (app backgrounded): radio down, user intent kept.
      *
      * @returns {Promise<void>}
      */
-    start({ name }?: {}): Promise<void>;
+    suspend(): Promise<void>;
     /**
-     * Stop advertising/scanning and drop links. Idempotent. Sync stops; local
-     * data and the rest of the network (DHT) are untouched.
+     * Resume after a host-lifecycle pause.
      *
      * @returns {Promise<void>}
      */
-    stop(): Promise<void>;
+    resume(): Promise<void>;
 }
 import ReadyResource from 'ready-resource';
-import { BLETransport } from '@cero-base/core/network/transports/ble';

package/types/handle/index.d.ts

@@ -96,6 +96,7 @@ export class Handle extends ReadyResource {
     _fileServer: FileServer;
     _blobs: Blobs;
     _epochBlobs: any;
+    _sus: any;
     _owned: Set<any>;
     store: Database;
     pair: Pairing;
@@ -314,13 +315,14 @@ export class Handle extends ReadyResource {
      * @returns {Promise<void>}
      */
     suspend(): Promise<void>;
-    _suspended: boolean;
+    _suspend(): Promise<void>;
     /**
      * Resume a suspended root handle. Idempotent; no-op on child handles.
      *
      * @returns {Promise<void>}
      */
     resume(): Promise<void>;
+    _resume(): Promise<void>;
     /**
      * @param {Handle} child
      * @param {{ role?: string }} [opts]

package/types/index.d.ts

@@ -20,7 +20,7 @@
  * @property {number} [recoveryTimeout]                Max wait for peer data + writer capability during recovery.
  * @property {Uint8Array} [storageKey]                 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it.
  * @property {boolean} [extensions]                    `false` disables the bundled extensions (profileSync, handleSync) for this instance. Build with `{ extensions: false }` too so the spec matches.
- * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
+ * @property {boolean | { autoStart?: boolean, backend?: any, maxOutbound?: number, maxInbound?: number, pipe?: 'l2cap' | 'gatt' }} [bluetooth]  `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
  */
 /**
  * Open (or create) a cero handle at `dir`. Sets up storage, network and
@@ -140,13 +140,14 @@ export type CeroOpts = {
      */
     extensions?: boolean;
     /**
-     * `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
+     * `true` enables nearby (Bluetooth) sync via `me.bluetooth` (auto-started). `{ autoStart: false }` creates the facade without starting the radio — the app calls `me.bluetooth.start()`/`stop()` (user toggle). `backend` injects a bare-bluetooth-shaped backend (tests). `maxOutbound`/`maxInbound` cap concurrent outbound links and inbound sessions. `pipe` picks the data pipe — `'l2cap'` (default, faster) or `'gatt'`; both peers must match. Absent backend on an unsupported host → `me.bluetooth.state === 'unsupported'`.
      */
     bluetooth?: boolean | {
         autoStart?: boolean;
         backend?: any;
         maxOutbound?: number;
         maxInbound?: number;
+        pipe?: "l2cap" | "gatt";
     };
 };
 import { t } from './lib/spec.js';