@cero-base/cero 1.19.0 → 2.1.0

package/README.md

@@ -1,681 +1,76 @@
-# cero
+# @cero-base/cero
 
-Define your data. Use it. cero handles storage, sync between devices, and sharing with others — no server.
+> [!IMPORTANT]
+> This project is experimental. The API is subject to change and may break at any time.
 
-Describe your data, compile it to a spec once, then open a cero against the **built spec**:
+A simple peer-to-peer SDK on top of the [Pear](https://pears.com) stack by [Holepunch](https://holepunch.to).
 
-```js
-// schema.js
-import { cero } from '@cero-base/cero'
-
-export const schema = cero.schema({
-  profile: cero.t.single({ name: cero.t.string }),
-  room: { messages: cero.t.collection({ text: cero.t.string }) }
-})
-```
-
-```js
-// build.js — run once; re-run when the schema changes
-import { build } from '@cero-base/cero/build'
-import { schema } from './schema.js'
-
-await build('./spec', schema)
-```
-
-```js
-import { cero } from '@cero-base/cero'
-import { spec } from './spec/index.js'
-
-const me = await cero('./data', spec)
-await cero.set(me.profile, { name: 'Alice' })
-
-const room = await cero.open(me.room, { name: 'general' })
-const invite = await room.invite()
-// room.revoke(invite)  ← invalidate it before anyone joins
-```
-
-On another device — same built spec, its own identity and data dir:
-
-```js
-const peer = await cero('./peer-data', spec)
-const joined = await cero.open(peer.room, invite)
-await cero.put(joined.messages, { text: 'hi' })
-```
-
-Ships with TypeScript declarations (`.d.ts`) generated from JSDoc.
-
-## `cero(dir, spec, opts?)`
-
-| Opt                 | Meaning                                                                                                                                                                                                                                                                |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bootstrap`         | Hyperswarm bootstrap nodes.                                                                                                                                                                                                                                            |
-| `channel`           | Optional network-isolation label. Peers connect only to peers on the **same** channel (it salts every swarm topic); omit it for the global network. A storage remembers its channel and refuses to reopen under a different one. Any string works.                     |
-| `name` / `isMobile` | Stamped on the device's `add-writer` event.                                                                                                                                                                                                                            |
-| `seed` / `phrase`   | Restore from explicit 16-/32-byte entropy or a BIP-39 mnemonic. Without either, a stored identity is loaded if present, else a fresh one is generated.                                                                                                                 |
-| `key`               | Existing database key to recover into, skipping the pointer lookup.                                                                                                                                                                                                    |
-| `recoveryTimeout`   | Max wait to find another device and be admitted, in ms. Defaults to 30000. A supplied `seed`/`phrase` on a device with no writer recovers — there is no flag.                                                                                                          |
-| `routes`            | Custom action handlers keyed by route name.                                                                                                                                                                                                                            |
-| `encryptionKey`     | Override the per-identity encryption key.                                                                                                                                                                                                                              |
-| `storageKey`        | 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it, and the same key must be passed on every open. Without it, key material sits plaintext on disk: rely on full-disk encryption. |
-| `onerror`           | Called with background/async failures that would otherwise be swallowed (failed after-hooks, `onApply` callbacks, pairing candidate errors); the app decides how to log or report them.                                                                                |
-
-Reads `me.id`, `me.device`, `me.identity` for canonical metadata. `me.identity.toPhrase()` renders the seed phrase.
-
-## `cero.peek(dir, spec)`
-
-```js
-const initialized = await cero.peek('./data', def) // true if an identity is stored
-```
-
-Cheap probe — opens the local store, reads the master row, closes. Use it before deciding whether to show a setup screen or jump straight in.
-
-## `cero.restore(me, phrase)`
-
-Wipe the current data and re-open with a different identity from a BIP-39 mnemonic. Used when a user signs back in on a fresh device or recovers from a phrase backup.
-
-```js
-const me = await cero('./data', def)
-const recovered = await cero.restore(me, 'twelve words …')
-```
-
-## Schema
-
-| Shape                      | Meaning                                         |
-| -------------------------- | ----------------------------------------------- |
-| `cero.t.single({ … })`     | one row (e.g. profile, settings)                |
-| `cero.t.collection({ … })` | many rows with auto ids (e.g. messages)         |
-| `{ … }` (plain object)     | a child handle — its own scope, share by invite |
-| `local: { … }`             | device-only — never leaves this device          |
-
-A collection can declare **secondary indexes** for fast exact-field lookups:
-
-```js
-cero.t.collection(
-  { text: cero.t.string },
-  { indexes: { 'by-text': ['text'] } } // name → field(s); query via `cero.get(ref, { text: '…' })`
-)
-```
-
-## Operators
-
-Every operator takes a `ref` (e.g. `me.profile`, `room.messages`) as the first arg.
-
-### `cero.put(ref, row)`
-
-Append a row to a collection. Generates an `id`, `createdAt`, and `updatedAt` if you don't provide them.
-
-```js
-const { data } = await cero.put(room.messages, { text: 'hi' })
-data.id // → 'abc…'  (plus createdAt / updatedAt)
-// `memberId` (the writer→member backlink) is stamped in the apply layer, so it
-// surfaces on a later `cero.get`, not on the row this call returns.
-```
-
-### `cero.set(ref, row)`
-
-Insert-or-update. For a `single` ref it replaces; for a `collection` it upserts by `id`.
-
-```js
-await cero.set(me.profile, { name: 'Alice' }) // single
-await cero.set(room.messages, { id: 'abc', text: 'edited' }) // upsert by id
-```
-
-### `cero.get(ref, q?)`
-
-Read. The shape of `q` decides what comes back:
-
-```js
-const { data } = await cero.get(me.profile) // single → the row (or null)
-const { data } = await cero.get(room.messages, 'abc') // by id  → the row (or null)
-
-// collection → paginated, with range filters
-const { data, total, size } = await cero.get(room.messages, {
-  gt: 'm-2025', // range: gt / gte / lt / lte
-  limit: 20,
-  reverse: true
-})
-
-// search → case-insensitive substring across string fields
-const { data } = await cero.get(room.messages, { search: 'jo sm' })
-// every space-separated term must match (AND); folds case + diacritics ('jose' ⇢ 'José').
-// `fields` restricts which fields are searched (default: all string fields):
-const { data } = await cero.get(room.guests, { search: 'jose', fields: ['name'] })
-
-// exact field match → routed through a declared secondary index when the field has one
-const { data } = await cero.get(room.messages, { text: 'alpha' })
-```
-
-`total` is the unfiltered row count; `size` is what came back after `limit`. `search` and exact-field filters compose with `limit` / `reverse`, and `cero.count(ref, q)` honors them too.
-
-### `cero.del(ref, id)`
-
-Delete by id (collection) or clear (single).
-
-```js
-await cero.del(room.messages, 'abc')
-await cero.del(me.profile)
-```
-
-### `cero.count(ref, q?)`
-
-```js
-const { data: n } = await cero.count(room.messages)
-const { data: n } = await cero.count(room.messages, { gt: 'm-2025' })
-```
-
-### `cero.watch(ref, q?, opts?)`
-
-A Readable stream that re-emits the latest snapshot on every change. Always emits an initial snapshot. The stream is **tied to the ref's handle** — closing the handle destroys it, so a watch never outlives its store and you don't track cleanup. Pass `{ signal }` to bind it to a finer scope instead.
-
-```js
-const stream = cero.watch(room.messages, { limit: 50, reverse: true })
-for await (const { data, total, size } of stream) {
-  /* render */
-}
-// stops on room.close(), on stream.destroy(), or on `signal` abort:
-const ac = new AbortController()
-cero.watch(room.messages, null, { signal: ac.signal }) // ac.abort() ⇒ destroyed
-```
-
-### `cero.changes(ref, q?, opts?)`
-
-Delta subscription: instead of full snapshots, batches of `{ prev, next }` row pairs — insert (`prev: null`), update (both), delete (`next: null`). Self-contained: the first batch (and any batch after recovery or an upgrade rebuild) replays the current matching rows as inserts with `reset: true`, so folding every batch into a Map always reconstructs current state — no separate `get`, no attach race:
-
-```js
-const rows = new Map()
-for await (const { changes, reset } of cero.changes(room.messages)) {
-  if (reset) rows.clear()
-  for (const { prev, next } of changes) {
-    if (next) rows.set(next.id, next)
-    else rows.delete(prev.id)
-  }
-}
-```
-
-Lossless under backpressure — a slow consumer gets fewer, bigger batches, never dropped ones. Query `gt/gte/lt/lte`, equality fields, and `search` scope the deltas (a row updated out of the filter arrives as `prev`-only); `limit`/`reverse` are not applied — deltas are unwindowed, windowing is `watch`'s job. Over RPC the wire carries only the changed rows, not the result set. Prefer `changes` for accumulating UIs (chat logs, ever-growing lists); prefer `watch` for windowed views. File-typed fields resolve on both sides. Handle refs are not supported.
-
-### `cero.call(actionRef, data)`
-
-Invoke an action defined in your schema with `t.action({ … })`. Custom write paths; the dispatcher handles encoding/decoding.
-
-```js
-await cero.call(room.promote, { memberId: 'xyz', role: 'admin' })
-```
-
-### `cero.open(handleRef, arg)`
-
-The universal handle entry point. Dispatch is based on `arg`:
-
-```js
-await cero.open(me.room, { name: 'general' }) // create — opts go through to _create
-await cero.open(me.room, inviteString) // join — `arg` is the invite string
-await cero.open(me.room, { invite: inviteString }) // join — explicit form
-await cero.open(me.room, { id: existingRoomId }) // load an existing room by id
-```
-
-Returns the child handle, ready to operate on (`cero.put(joined.messages, …)` etc.).
-
-### `cero.rotate(handle)`
-
-Rotate the handle's encryption epoch. A fresh secret is sealed to every current
-member and announced through the log — members removed **before** the rotation
-cannot decrypt anything written after it (rows **and** files). Requires the
-`remove` permission (admin or owner). Returns `{ epoch }`.
-
-```js
-await cero.del(room.members, memberId) // revoke write access
-await cero.rotate(room) // revoke read access for everything that follows
-```
-
-Rotation is opt-in per room: without it, `del` alone is a soft removal (write
-revocation only). Once a room has rotated at least once, later removals
-self-heal — a `del` without an explicit `rotate` triggers an automatic re-key
-from any online admin device. Standalone rotations (no removal) are valid too,
-as periodic key hygiene. Full design: [`docs/key-rotation.md`](../../docs/key-rotation.md).
-
-### Watching removals
-
-There is no separate removal event — `members` is a collection, so the normal
-streams already are the membership feed. A removal arrives as an ordinary
-delete (`next: null`), carrying the row that was removed:
-
-```js
-for await (const { changes } of cero.changes(room.members)) {
-  for (const { prev, next } of changes) {
-    if (next === null) console.log('removed:', prev.name)
-  }
-}
-```
-
-To detect **your own** removal — the signal an app renders as "you were removed
-from this room" — listen for the store losing writability:
-
-```js
-room.store.on('unwritable', () => onRemoved()) // freeze the UI, close the room
-```
-
-This works even when the removal is followed by a rotation: the removal lands
-before the new key, so a removed member always receives it. After that their
-streams stay open but go silent — reads freeze at the moment of removal and
-writes reject with `NOT_WRITABLE`.
-
-### Store events
-
-Beyond the ref streams, the store reports its own lifecycle:
-
-```js
-room.store.on('writable', () => {}) // admitted — this device can write
-room.store.on('unwritable', () => {}) // access ended (removed)
-room.store.on('update', () => {}) // an apply batch committed
-room.store.on('behind', (v) => {}) // ops from a newer app version — see below
-room.store.on('rebuild', () => {}) // view replayed after catching up
-```
-
-`before`/`after` hooks only fire on the device performing the write. To observe
-**every** applied op — local _and_ replicated — use `onApply`, which returns an
-unsubscribe fn:
-
-```js
-const off = room.store.onApply(({ op, name, row, writerKey, seq }) => {
-  if (op === 'del' && name === 'member') auditLog(row)
-})
-```
-
-The callback runs synchronously inside apply, so keep it cheap — enqueue and
-return. It costs nothing when nobody is subscribed.
-
-### `cero.before(ref, fn, opts?)` / `cero.after(ref, fn, opts?)`
-
-Hook into writes to a ref. `before` runs **in-path** before the write commits — return `false` to cancel, or mutate `ctx.row`. `after` is a non-blocking **event** that fires once the write has committed. Both return an unsubscribe fn — call it to stop early, ignore it for a subscription that lives as long as the handle, or pass `{ signal }` to unsubscribe when an `AbortSignal` fires (e.g. `{ signal: me.signal }` to stop on close).
-
-```js
-const off = cero.before(room.messages, (ctx) => {
-  if (!ctx.row.text?.trim()) return false // reject empty messages
-})
-
-cero.after(me.profile, ({ row }) => {
-  /* react to your profile changing */
-})
-```
-
-`ctx` is `{ op, name, row }` (plus `result` in `after`).
-
-## Files
-
-Store a file (avatar, image, attachment) and get a ready-to-render URL. Bytes live in a per-handle blob core — replicated to members on demand, never inlined into the log — so rows carry only a small self-describing id.
-
-Every handle has a builtin `files` collection. `cero.put(handle.files, …)` uploads bytes (a `Buffer` or a `Readable`) and returns a file with a `.url`:
+Describe your data. cero stores it on the device, syncs it across your devices and shares it with the people you invite. No server.
 
-```js
-const { data: file } = await cero.put(me.files, {
-  data: bytes, // Buffer | Readable
-  name: 'cat.jpg',
-  type: 'image/jpeg'
-})
-
-img.src = file.url
-```
-
-Read them back — every row carries a fresh `.url`:
-
-```js
-const { data: files } = await cero.get(me.files) // list all
-const { data: one } = await cero.get(me.files, file.id) // one, by id
-cero.watch(me.files).on('data', ({ data }) => render(data)) // live
+```sh
+npm install @cero-base/cero
 ```
 
-### The `file()` column type
-
-For a file referenced from a row — an avatar, a room icon, a message attachment — declare the field `cero.t.file` (a bare marker, not a call). Store the file's `id`; read it back already resolved to `{ id, name, type, size, url }`, with **no extra lookup**:
+A cero app is three files.
 
 ```js
 // schema.js
-profile: cero.t.single({ name: cero.t.string, avatar: cero.t.file })
-
-// save: upload, then store the id on the row
-const { data: pic } = await cero.put(me.files, { data: bytes, type: 'image/png' })
-await cero.set(me.profile, { avatar: pic.id })
-
-// read: the avatar comes back url-ready
-const { data: profile } = await cero.get(me.profile)
-img.src = profile.avatar.url
-```
+import { cero, t } from '@cero-base/cero'
 
-### URLs are local and ephemeral
-
-A `.url` points at a localhost server this device runs, with a per-session token — it changes across restarts and is **not** shareable to other peers. Never persist a `.url`: store the **id** (cero does), and re-read to get a current one. Each member derives their own url from the same id, and the bytes download on demand when the url is first fetched.
-
-## Custom operators
-
-Your app's business logic lives as **custom operators** — plain functions whose first arg is the handle they act on, composing the built-ins. Because the built-ins resolve through the handle (a real DB on the core, an RPC proxy on the client), custom operators are symmetric over RPC for free.
-
-```js
-// guest.js — pure functions, one per export
-import { put, del } from '@cero-base/cero'
-import { ensureGuestId } from './ids.js'
-
-export const create = (room, data) => put(room.guests, { ...data, id: ensureGuestId(data.id) })
-export const remove = (room, id) => del(room.guests, id)
-```
-
-### `cero.define(map)`
-
-Register custom operators by **scope**, once, and cero puts them on every matching handle — the root and each child as it opens, on both the core and the client. A **bare key** binds on the root handle; a key that names a **child-handle type** binds on each handle of that type:
-
-```js
-import * as user from './user.js'
-import * as guest from './guest.js'
-import * as station from './station.js'
-
-cero.define({
-  user, // bound on the root  → me.user.rename(…)
-  room: { guest, station } // bound on each room → room.guest.create(…)
+export const schema = cero.schema({
+  notes: t.collection({ title: t.string, body: t.string }),
+  room: { messages: t.collection({ text: t.string }) }
 })
-
-const room = await cero.open(me.room, { id })
-await room.guest.create({ name: 'Bob' }) // no binding at the call site
 ```
 
-cero reads the spec to tell root namespaces from child-handle types, so there is no `root` wrapper. Call `cero.define(...)` once at startup — in the build/server process **and** the client — the same as extensions.
-
-### `cero.bind(handle, map)`
-
-The primitive `define` uses. Curry a handle onto a `{ ns: module }` map yourself — for a handle you opened manually, or to bind operators you don't want globally registered:
-
 ```js
-import * as guest from './guest.js'
-
-cero.bind(room, { guest })
-await room.guest.create({ name: 'Bob' }) // → guest.create(room, …)
-```
-
-Non-functions in the map are skipped; the handle is returned.
-
-## Extensions
-
-An extension bundles **schema** (build-time) with **behavior** (runtime). Register it with `cero.use()` — `build()` folds in its schema and `cero()` runs its `setup` once the handle is ready.
-
-The two bundled extensions (`profileSync`, `handleSync`) are **on by default** — no `cero.use()` needed. To reconfigure one, `cero.use(profileSync({ fields }))` replaces the default (named extensions replace by name, so double registration is harmless). To leave them out entirely, pass `{ extensions: false }` to **both** `build()` and `cero()` — the built spec and the runtime must agree.
-
-```js
-import { profileSync } from '@cero-base/cero/extensions'
+// build.js, run once and after every schema change
+import { build } from '@cero-base/cero/build'
+import { schema } from './schema.js'
 
-cero.use(profileSync({ fields: { status: cero.t.string } })) // reconfigure the default
 await build('./spec', schema)
 ```
 
-An extension is two optional parts:
-
-```js
-function myExtension() {
-  return {
-    schema: { members: cero.t.extend({ status: cero.t.string }) }, // merged into your schema
-    setup(me) {
-      const onHandle = (room, opts) => {
-        /* opts carries the open args (e.g. opts.name on create); me.children is the set of open rooms */
-      }
-      me.on('handle', onHandle, { signal: me.signal }) // dropped on me.close()
-    }
-  }
-}
-```
-
-For a behavior-only extension (no schema), pass a function directly — it's shorthand for `{ setup }`:
-
-```js
-cero.use((me) => {
-  me.on('handle', (room) => {
-    /* … */
-  })
-})
-```
-
-Build and the running app are separate processes, so `cero.use()` runs in both — your build script (for the schema) and once at app startup before `cero()` (for the behavior).
-
-### Cleanup
-
-You rarely write teardown — a handle's subscriptions follow the same "dies with the node" model as DOM events:
-
-- **`cero.watch(ref)` streams** are destroyed automatically when the ref's handle closes.
-- **`me.on(...)`, `before`, `after`** take `{ signal }` to drop themselves when an `AbortSignal` fires.
-- **`me.signal`** is an `AbortSignal` that aborts on `me.close()`. Pass it to tie a subscription to the handle's life, or use your own `AbortController` for a finer scope (drop it before the handle closes):
-
-```js
-setup(me) {
-  me.on('handle', onHandle, { signal: me.signal }) // dropped when me closes
-  cero.after(me.profile, onProfile, { signal: me.signal })
-}
-```
-
-For anything the close cascade won't reach — a timer, an external connection, a stream you made yourself — hand it to **`me.own(resource)`** (destroyed on close) or return a disposer from `setup`:
-
-```js
-setup(me) {
-  const timer = setInterval(() => ping(me), 30_000)
-  me.own({ destroy: () => clearInterval(timer) }) // tied to me.close()
-  // …or: return () => clearInterval(timer)
-}
-```
-
-### `profileSync` (bundled)
-
-On by default. Mirrors your `profile` onto your `member` row in every room, so others see your name and avatar. It **declares its own `profile` single** (`name` + the synced fields) and extends `member` with them — no app schema required. Defaults to syncing `avatar`:
-
-```js
-cero.use(profileSync({ fields: { status: cero.t.string } })) // sync extra fields
-```
-
-Want a richer profile (e.g. a `bio` that doesn't sync)? Declare your own `profile` single — the app schema wins, and `profileSync` still adds the member side.
-
-### `handleSync` (bundled)
-
-On by default. Mirrors a child handle's `profile` (name + avatar) onto its row in the parent's `handles` list — so a handle/room list renders names and photos without opening each handle. Adds `avatar` (or your `fields`) to the `handle` builtin and reflects the handle's own `profile` (which your app owns) onto the row.
-
-```js
-// your handle type declares a `profile`; your app sets it:
-const room = await cero.open(me.room)
-await cero.set(room.profile, { name: 'general', avatar: 'pic.png' })
-// → the me.handles row now carries name + avatar — render the room list, no opens
-```
-
-Requires your handle types to declare a `profile` single; handles without one are left untouched.
-
-## RPC
-
-cero runs in one process; your UI runs in another. Connect them with any duplex stream (Bare IPC, Electron `contextBridge`, a worker port, even a TCP socket).
-
-The client side gets the **same operator API** as a local cero — `cero.put`, `cero.set`, `cero.open`, etc. all work over the wire.
-
-### Server (the process that owns the data)
-
-```js
-// workers/main.js — e.g. a Bare worker or Node background process
-import { serve } from '@cero-base/cero/server'
-import { spec } from './spec/index.js'
-
-// serve builds and owns the root cero — pass storage + the built spec, not a handle.
-// Returns a Server instance (call server.close() to shut down).
-const server = await serve(Bare.IPC, spec, { storage: './data', phrase: '…' })
-```
-
-### Client (the UI process)
-
 ```js
-// renderer.js — runs in Electron renderer, React Native, etc.
+// index.js
 import { cero } from '@cero-base/cero'
-import { connect } from '@cero-base/cero/client'
 import { spec } from './spec/index.js'
 
-const me = await connect(ipcStream, spec)
+const me = await cero('./data', spec)
+await cero.put(me.notes, { title: 'first', body: 'hello' })
 
-await cero.set(me.profile, { name: 'Alice' })
 const room = await cero.open(me.room, { name: 'general' })
-const inviteStr = await room.invite()
-cero.watch(room.messages).on('data', ({ data }) => render(data))
+console.log(await room.invite()) // give this to a friend
 ```
 
-The same `spec/index.js` is imported on both sides. `@cero-base/cero/build` emits one file; its imports (hyperdb/runtime, hyperdispatch/runtime, hyperschema/runtime) are all pure JS — no native deps — so bundlers like vite handle the renderer bundle fine.
-
-### What you can do over RPC
-
-Everything the local API offers, plus lifecycle methods on returned handles:
-
-| Operator / method                                                                                              | Works over RPC |
-| -------------------------------------------------------------------------------------------------------------- | -------------- |
-| `cero.put` / `set` / `get` / `del` / `count` / `watch` / `call`                                                | ✓              |
-| `cero.open(ref, …)` — create, join, load by id                                                                 | ✓              |
-| `room.invite({ role, expiresIn, reuse })` — mint an invite (`reuse: true` keeps it alive after the first join) | ✓              |
-| `room.revoke(invite)` — invalidate an outstanding invite; `true` if it existed                                 | ✓              |
-| `room.close()` — release the handle on the server                                                              | ✓              |
-| `room.leave()` — remove yourself from the room and from your handles list                                      | ✓              |
-
-`cero.watch(ref)` returns a Readable on both sides; snapshots flow as a server-streamed RPC.
-
-### Wiring up a stream
-
-A duplex stream is anything with `write(buf, cb)` and that emits `data`. Some real cases:
+Your friend, on their own machine:
 
 ```js
-// Bare worker → renderer
-import { Duplex } from 'streamx'
-const ipc = new Duplex({
-  write(data, cb) {
-    window.bridge.writeWorkerIPC('/main.js', data)
-    cb()
-  }
-})
-window.bridge.onWorkerIPC('/main.js', (data) => ipc.push(data))
-const me = await connect(ipc, spec)
-
-// Two ceros in the same process (tests)
-function streamPair() {
-  let a, b
-  a = new Duplex({
-    write(d, cb) {
-      b.push(d)
-      cb()
-    }
-  })
-  b = new Duplex({
-    write(d, cb) {
-      a.push(d)
-      cb()
-    }
-  })
-  return [a, b]
-}
-const [s, c] = streamPair()
-await serve(s, spec, { storage: './data' })
-const remote = await connect(c, spec)
+const room = await cero.open(me.room, { invite })
+for await (const { data } of cero.watch(room.messages)) console.log(data)
 ```
 
-## Nearby sync (Bluetooth)
-
-Sync with no internet at all. Bluetooth is a transport, not a parallel API — it only changes _how peers meet and carry bytes_; the same refs, guards, roles, and reactivity ride over it unchanged. Volunteers in range converge; hop-by-hop gossip heals partitions as people move.
-
-```js
-const me = await cero(dir, spec, { channel, bluetooth: true })
-
-me.bluetooth.state // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'on'
-await me.bluetooth.start() // runtime toggle
-await me.bluetooth.stop()
-me.bluetooth.peers // Map of live BLE links
-me.bluetooth.on('update', () => {}) // state / peer changes
-```
+That is a working, encrypted, offline-first, peer-to-peer app. Your phrase, `me.identity.toPhrase()`, opens the same identity on any other device.
 
-Inherited for free from the stack: `channel` isolation (the BLE service UUID is derived from the channel, so only same-channel devices discover each other), capability-gated replication (a connected stranger syncs nothing), and offline invite→join. Requires `bare-bluetooth` (an optional peer dep, bundled into the mobile/desktop worklet); absent it, `state` is `'unsupported'` — loud, never silent. macOS + iOS + Android; Linux desktop has no BLE backend today.
+## Docs
 
-**Offline join** — a late volunteer incorporates on the spot, zero internet. Both sides derive a rendezvous UUID from the invite itself; the join side is automatic:
-
-```js
-// organizer, while the invite QR is on screen:
-const invite = await room.invite({ role: 'member', expiresIn: 3600_000 })
-const stop = me.bluetooth.announce(invite)
-// … QR closed:
-stop() // stops the rendezvous; an established link stays and carries the initial replication
-
-// late volunteer — the exact same code as online:
-const room = await cero.open(me.room, invite) // rendezvouses over BLE automatically
-```
-
-The advertisement auto-stops at the invite's `expiresIn` — a photographed QR must not stay an ambient admission ticket.
-
-## App versions & rollouts
-
-Rooms are permanent replicated logs, and after release your users will run
-different app versions side by side. Every op cero writes carries the app's
-contract version (stamped into the generated spec by `build` — it advances
-automatically whenever the schema changes). Peers handle version skew
-deterministically:
-
-- Ops from a **newer** version are skipped — they stay in the log, they are
-  not errors, and nothing diverges. The store reports it:
-
-```js
-me.store.behind // highest future version seen, or null
-me.store.on('behind', (version) => showUpdatePrompt())
-```
-
-- After the app **upgrades** past everything it skipped, the next open
-  rebuilds the local view from the log through the new handlers — the
-  previously-skipped ops apply, nothing is lost, and the store emits
-  `'rebuild'` once.
-- Apps built before versioned ops existed read as version 0 and interoperate
-  unchanged.
-
-Ship gradual rollouts freely; old peers keep working on everything they
-understand and know when to prompt for an update.
-
-## Mirrors (offline sync)
-
-Two peers can only sync while both are online. A **blind peer** is an always-on relay that holds your rooms' encrypted blocks and serves them to other members — so a peer can pick up messages that were sent while it was offline. It's _blind_: rooms are end-to-end encrypted, so the mirror stores ciphertext and never sees your data.
-
-Pass mirror public keys and every room and file is mirrored automatically:
-
-```js
-const me = await cero(dir, spec, {
-  mirrors: ['<blind-peer-public-key>'] // hex or z32
-})
-```
-
-Nothing else changes — the operators, invites, and roles work exactly as before; mirrors only add availability. Keys carry through account recovery (`cero.restore`).
-
-**Running a mirror.** The `blind-peer` package is the server (a library — see `holepunchto/blind-peer-cli` for a turnkey host). A minimal self-hosted mirror:
-
-```js
-import Hyperswarm from 'hyperswarm'
-import BlindPeer from 'blind-peer'
-
-const swarm = new Hyperswarm()
-const mirror = new BlindPeer('./mirror-store', { swarm })
-await mirror.listen()
-console.log('mirror key:', mirror.publicKey.toString('hex')) // give this to cero({ mirrors })
-```
-
-Point your app's `mirrors` at that key. Storage grows with the rooms it holds; `blind-peer` GCs least-recently-used data past its `maxBytes` limit.
+- [Quickstart](https://github.com/lekinox/cero-base/blob/main/docs/quickstart.md)
+- [Guides](https://github.com/lekinox/cero-base/blob/main/docs/README.md#guides): schema, data, rooms, identity, apps, extensions, files, network
+- [API reference](https://github.com/lekinox/cero-base/blob/main/docs/api.md)
+- [Examples](https://github.com/lekinox/cero-base/blob/main/docs/examples.md)
 
 ## Exports
 
-| Path                         | What you get                                                             |
-| ---------------------------- | ------------------------------------------------------------------------ |
-| `@cero-base/cero`            | factory + operators + schema DSL + `define`/`bind`                       |
-| `@cero-base/cero/client`     | `connect(ipc, spec)` — talk to a cero running in another process         |
-| `@cero-base/cero/server`     | `serve(ipc, spec, { storage })` — run + expose a cero over an IPC stream |
-| `@cero-base/cero/build`      | `build(specDir, schema)` — generate the on-disk spec                     |
-| `@cero-base/cero/extensions` | bundled extensions (`profileSync`, …)                                    |
-
-## Tests
-
-```sh
-npm test
-```
-
-Runs the test files in parallel via `xargs -P2 -n1 brittle-node` (brittle v4). `npm run build:test` regenerates the test fixture spec.
+| Subpath                      | What it gives you                                                            |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `@cero-base/cero`            | `cero`, `t`, `schema`, `restore`, `peek`, `Handle`, `Ref`, `Local`           |
+| `@cero-base/cero/build`      | `build(specDir, schema, opts)`                                               |
+| `@cero-base/cero/server`     | `serve(ipc, spec, opts)` and `Server`, the process that owns the data        |
+| `@cero-base/cero/client`     | `connect(ipc, spec)`, `Client`, `restore` and the operators for a UI process |
+| `@cero-base/cero/extensions` | `profileSync`, `handleSync`                                                  |
 
-## Types
+Built on the [Pear](https://pears.com) stack by [Holepunch](https://holepunch.to): Hypercore, Autobee, HyperDB, Hyperblobs, Hyperswarm, blind-pairing, blind-peering and Bare. Runs on Node and Bare, with TypeScript declarations.
 
-```sh
-npm run build:types
-```
+## License
 
-Emits `.d.ts` from JSDoc into `types/`. Runs automatically on `npm publish` via `prepublishOnly`.
+Apache-2.0