@cero-base/cero 1.12.0 → 1.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "1.12.0",
+  "version": "1.13.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.13.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": "github:holepunchto/ble-swarm#63566f02d4b3a1f3849b9fb009e18666411592a5",
     "compact-encoding": "^3.3.2",
     "corestore": "^7.12.0",
     "hrpc": "^4.3.1",
@@ -124,14 +125,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,90 @@ 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
+    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 +130,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

@@ -837,6 +837,7 @@ export class Handle extends ReadyResource {
     if (this.parent || this.closing || this.closed || this._suspended) return
     this._suspended = true
     await Promise.all([...this.children].map((c) => c.pair?.suspend()))
+    await this.bluetooth?.suspend()
     await this.network.suspend()
     try {
       await this.store.store.suspend()
@@ -859,6 +860,7 @@ export class Handle extends ReadyResource {
       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

@@ -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';