@basictech/react 0.8.0-beta.4 → 0.9.0-beta.1

package/readme.md

@@ -1,6 +1,32 @@
 # @basictech/react
 
-React SDK for [Basic](https://basic.tech) - add authentication and real-time database to your React app in minutes.
+React SDK for [Basic](https://basic.tech) — authentication and an offline-first, synced database for your React app.
+
+Basic gives every user their own personal datastore (a PDS). Your app authenticates with OAuth, gets its own sandboxed slice of the user's datastore, and this SDK keeps a local replica of that data in the browser — reads are instant and local, writes work offline, and everything syncs live across the user's devices over the Basic **Sync/2** protocol.
+
+> **Breaking change (0.9):** this version is a ground-up rewrite for the new Basic auth system and the Sync/2 sync engine. The 0.8.x sync client speaks a protocol the server no longer supports. See [Migrating from 0.8](#migrating-from-08).
+
+---
+
+## Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Anonymous & local-first](#anonymous--local-first)
+- [Multiple users](#multiple-users)
+- [Authentication](#authentication)
+- [Database](#database)
+- [Live queries](#live-queries)
+- [Sync status, offline behavior & errors](#sync-status-offline-behavior--errors)
+- [Shares (multiplayer)](#shares-multiplayer)
+- [Typed schemas](#typed-schemas)
+- [REST mode](#rest-mode)
+- [API reference](#api-reference)
+- [Advanced usage](#advanced-usage)
+- [Migrating from 0.8](#migrating-from-08)
+
+---
 
 ## Installation
 
@@ -8,13 +34,16 @@ React SDK for [Basic](https://basic.tech) - add authentication and real-time dat
 npm install @basictech/react
 ```
 
-## Quick Start
+Requires React 16.8+ (hooks). React 17, 18, and 19 are supported.
+
+## Quick start
 
-### 1. Create a Schema
+### 1. Define your schema
 
-Create a `basic.config.ts` file with your project configuration:
+Create a `basic.config.ts` with your project id (from [app.basic.tech](https://app.basic.tech)) and your tables:
 
 ```typescript
+// basic.config.ts
 export const schema = {
   project_id: "YOUR_PROJECT_ID",
   version: 1,
@@ -22,7 +51,7 @@ export const schema = {
     todos: {
       type: "collection",
       fields: {
-        title: { type: "string", indexed: true },
+        title: { type: "string", indexed: true, required: true },
         completed: { type: "boolean", indexed: true },
       },
     },
@@ -30,319 +59,407 @@ export const schema = {
 };
 ```
 
-### 2. Add the Provider
+Field types: `string`, `number`, `boolean`, `json`. Publish the schema from the Basic dashboard — sync is enabled once the published version matches your local one.
 
-Wrap your app with `BasicProvider`:
+### 2. Wrap your app
 
 ```tsx
+// main.tsx
 import { BasicProvider } from "@basictech/react";
 import { schema } from "./basic.config";
 
-function App() {
-  return (
-    <BasicProvider schema={schema}>
-      <YourApp />
-    </BasicProvider>
-  );
-}
+createRoot(document.getElementById("root")!).render(
+  <BasicProvider schema={schema} devToolbar>
+    <App />
+  </BasicProvider>,
+);
 ```
 
-### 3. Use the Hook
-
-Access auth and database in any component:
+### 3. Sign in and use the database
 
 ```tsx
 import { useBasic, useQuery } from "@basictech/react";
 
-function TodoList() {
-  const { db, isSignedIn, signIn, signOut, user } = useBasic();
-
-  // Live query - automatically updates when data changes
-  const todos = useQuery(() => db.collection("todos").getAll());
-
-  const addTodo = async () => {
-    await db.collection("todos").add({
-      title: "New todo",
-      completed: false,
-    });
-  };
+function Todos() {
+  const { isSignedIn, signIn, signOut, user, db } = useBasic();
+  const todos = useQuery(() => db.table("todos").getAll());
 
   if (!isSignedIn) {
-    return <button onClick={signIn}>Sign In</button>;
+    return <button onClick={() => signIn()}>Sign in with Basic</button>;
   }
 
   return (
     <div>
-      <p>Welcome, {user?.email}</p>
-      <button onClick={addTodo}>Add Todo</button>
-      <ul>
-        {todos?.map((todo) => (
-          <li key={todo.id}>{todo.title}</li>
-        ))}
-      </ul>
-      <button onClick={signOut}>Sign Out</button>
+      <p>hi {user?.email} <button onClick={() => signOut()}>sign out</button></p>
+
+      <button onClick={() => db.table("todos").create({ title: "hello", completed: false })}>
+        add todo
+      </button>
+
+      {todos?.map((todo) => (
+        <label key={todo.id}>
+          <input
+            type="checkbox"
+            checked={!!todo.completed}
+            onChange={() => db.table("todos").patch(todo.id, { completed: !todo.completed })}
+          />
+          {String(todo.title)}
+          <button onClick={() => db.table("todos").delete(todo.id)}>×</button>
+        </label>
+      ))}
     </div>
   );
 }
 ```
 
----
+That's the whole loop — and note the app **works before sign-in too**: `db.table(...)` writes go to a local anonymous workspace and merge into the account automatically when the user signs in (see [Anonymous & local-first](#anonymous--local-first)). `useQuery` re-renders whenever local data changes — whether the change came from this tab, another device, or another user via a share.
+
+## How it works
+
+In the default `sync` mode, the SDK maintains a **local replica** of your app's slice of the user's datastore, in IndexedDB, and syncs it over one WebSocket:
+
+1. **Local first** — the local database opens immediately, with no session and no network. Reads and writes work from the first render, including offline cold starts.
+2. **Writes are ops** — every write is a `put` (create/replace), `patch` (shallow field merge), or `delete` operation with a client-minted unique id. Ops apply to the local view immediately (optimistic), queue in IndexedDB, and push to the server when online. Retries are always safe: the server deduplicates by op id.
+3. **Reads are local** — `get`/`getAll`/`find` read the local view: confirmed server state with your pending writes layered on top. No network round-trip.
+4. **Bootstrap on connect** — when a session exists, the SDK fetches a snapshot of the account's current state, layers your pending writes on top, then subscribes for live changes.
+5. **The server is the authority** — it orders all ops (last-writer-wins per record; `patch`es merge per field), validates them against your published schema, and echoes them to every connected device. If it rejects a write, the SDK rolls it back locally and surfaces it (see [rejected ops](#rejected-ops)).
+6. **Sign-out is clean** — the user's local data is wiped, the session is revoked server-side, and the app continues in a fresh anonymous workspace. No page reloads.
 
-## API Reference
+## Anonymous & local-first
 
-### `<BasicProvider>`
+Anonymous mode is **on by default**: users can use your app without signing in. Their data lives in a local-only workspace (sync status `local`), fully readable and writable, surviving reloads.
 
-Root provider component. Must wrap your entire app.
+When they sign in, the anonymous workspace **becomes** their account: every anonymous write is already a queued op, so the normal bootstrap-and-push flow merges them into the account — no copy step, no data loss, and live queries keep working through the transition.
 
 ```tsx
-<BasicProvider
-  schema={schema} // Required: Your Basic schema
-  debug={false} // Optional: Enable console logging
-  dbMode="sync" // Optional: "sync" (default) or "remote"
-  devToolbar={false} // Optional: Floating dev status bar (localhost / dev / debug)
-/>
-```
+const { isAnonymous, isSignedIn, signIn, db } = useBasic();
 
-#### Props
+// works signed in or not:
+await db.table("todos").create({ title: "works offline & anonymous" });
 
-| Prop         | Type                 | Default  | Description                                                                                         |
-| ------------ | -------------------- | -------- | --------------------------------------------------------------------------------------------------- |
-| `schema`     | `object`             | required | Schema with `project_id` and `tables`                                                               |
-| `debug`      | `boolean`            | `false`  | Enable debug logging                                                                                |
-| `dbMode`     | `"sync" \| "remote"` | `"sync"` | Database mode                                                                                       |
-| `devToolbar` | `boolean`            | `false`  | Show the Basic dev toolbar (only when `localhost`, `NODE_ENV === "development"`, or `debug={true}`) |
+// prompt when you want the data to start syncing:
+{isAnonymous && <button onClick={() => signIn()}>Sign in to sync</button>}
+```
 
-#### Database Modes
+Safety guarantees:
 
-- **`sync`** - Local-first with IndexedDB + real-time sync via WebSocket
-- **`remote`** - Direct REST API calls (no local storage)
+- A keyspace is **stamped with the account DID** at first bootstrap. Local data from one account can never merge into another — if a different account signs in over it, the local cache is wiped first (it's server-backed; nothing is lost).
+- Signing out wipes that user's local data and drops into a fresh anonymous workspace (nothing readable is left behind on shared machines).
 
----
+Set `anonymous={false}` on the provider to require sign-in before any local data exists (classic behavior).
 
-### `useBasic()`
+## Multiple users
 
-Main hook for accessing auth and database.
+Several local users — anonymous or signed-in — can exist side by side, one active at a time. The active user is **per tab** (two tabs can be on different users); the profiles themselves are shared across tabs. Each user has an isolated keyspace and session.
 
 ```tsx
-const {
-  // Auth state
-  isReady, // boolean - SDK initialized
-  isSignedIn, // boolean - Session is valid
-  user, // { id, email, ... } | null (may be null briefly during profile refresh/recovery)
-
-  // Auth methods
-  signIn, // () => void - Redirect to login
-  signOut, // () => void - Clear session
-  signInWithCode, // (code, state?) => Promise - Manual OAuth
-  getSignInUrl, // (redirectUri?) => string - Get OAuth URL
-  getToken, // () => Promise<string> - Get access token
-
-  // Database
-  db, // Database instance
-  dbStatus, // DBStatus - see below
-  dbMode, // "sync" | "remote"
-
-  // Dev / schema snapshot (for custom tooling)
-  devInfo, // BasicSchemaDevInfo | null — local vs remote schema status
-  refreshSchemaStatus, // () => Promise<void> — re-fetch schema status from API
-} = useBasic();
+const { users, activeUser, switchUser, addUser, removeUser } = useUsers();
+
+<select value={activeUser?.id} onChange={(e) => switchUser(e.target.value)}>
+  {users.map((u) => (
+    <option key={u.id} value={u.id}>
+      {u.kind === "anon" ? "Anonymous" : u.email || u.name || u.did}
+    </option>
+  ))}
+</select>
+<button onClick={() => addUser()}>Add user</button>
 ```
 
-#### `DBStatus` (sync connection state)
+- `switchUser(id)` swaps the active session, database, and sync connection in place. Live queries via `useQuery` re-attach automatically.
+- `addUser()` creates a fresh anonymous user and switches to it (sign in from there to add an account).
+- `removeUser(id)` wipes that user's local data and revokes its session; removing the active user is the same as `signOut()`.
+- `signOut()` removes the active user and falls through to the next one (or a fresh anonymous workspace).
 
-When `dbMode === "sync"`, `dbStatus` is one of:
+## Authentication
 
-| Value              | Description                                                                                                       |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `LOADING`          | SDK initializing                                                                                                  |
-| `OFFLINE`          | Not connected                                                                                                     |
-| `CONNECTING`       | Connecting to sync server                                                                                         |
-| `ONLINE`           | Connected and idle                                                                                                |
-| `SYNCING`          | Syncing data                                                                                                      |
-| `ERROR`            | Sync error                                                                                                        |
-| `ERROR_WILL_RETRY` | Sync error but client will retry (e.g. expired token). Use this to show "Reconnecting…" or trigger token refresh. |
+Basic is the OAuth provider. `signIn()` redirects to the user's Basic sign-in page; after consent the user lands back on your app with a code the SDK exchanges automatically (PKCE, rotating refresh tokens — all handled for you).
 
-Import the enum for comparisons: `import { useBasic, DBStatus } from '@basictech/react'`.
+```tsx
+const auth = useAuth(); // or grab the same fields from useBasic()
+
+auth.status;        // 'bootstrapping' | 'authenticated' | 'recovering' | 'reauth_required' | 'signed_out'
+auth.isSignedIn;    // boolean (stays true during reauth_required so you can show user info)
+auth.user;          // { sub, email, name, picture } | null
+auth.did;           // the user's decentralized id
+auth.scope;         // scopes granted to your app
+
+await auth.signIn();                       // redirect flow (current URL is the redirect URI)
+await auth.signIn("https://app.com/done"); // custom redirect URI
+await auth.signInWithHandle("alice.basic.id"); // federated: resolve the user's own PDS first
+await auth.signOut();                      // revokes server-side + clears local data
+```
 
----
+### Auth status lifecycle
 
-### Development toolbar
+| Status | Meaning | What to render |
+| --- | --- | --- |
+| `bootstrapping` | SDK is initializing | splash / nothing (provider hides children by default) |
+| `authenticated` | Healthy session | your app |
+| `recovering` | Session likely exists but unconfirmed (offline, mid-refresh) | your app (data still works locally) |
+| `reauth_required` | Session definitively invalid — user must sign in again | your app (local reads/writes still work) + a re-sign-in prompt |
+| `signed_out` | No session — anonymous local workspace (default mode) | your app + a "sign in to sync" prompt (`isAnonymous` is true) |
 
-A small floating bar (similar in spirit to Next.js dev indicators) shows **auth**, **database mode**, **sync status**, and **schema vs server** health. It is **opt-in** and only appears in development: `localhost` / `127.0.0.1` / `.local`, `NODE_ENV === "development"`, or when `debug` is `true` on the provider or on the standalone component.
+### Calling your own API
 
-**Option A — provider flag**
+`getToken()` returns a valid access token, refreshing it automatically (tokens are short-lived — never cache them yourself):
 
-```tsx
-<BasicProvider schema={schema} devToolbar debug>
-  <App />
-</BasicProvider>
+```typescript
+const token = await auth.getToken();
+await fetch("https://your-api.example/thing", {
+  headers: { Authorization: `Bearer ${token}` },
+});
+// after a 401 from your API:
+await auth.getToken({ forceRefresh: true });
 ```
 
-**Option B — place the component yourself** (must be under `BasicProvider`; respects the same visibility rules, or pass `debug` to force):
+### Scopes
 
-```tsx
-import { BasicDevToolbar } from "@basictech/react";
+Default requested scopes are `profile,email,app:admin`. Check what was actually granted:
 
-<BasicProvider schema={schema}>
-  <App />
-  <BasicDevToolbar />
-</BasicProvider>;
+```typescript
+auth.hasScope("app:db:read"); // note: app:admin implies all app:db:* scopes
+auth.missingScopes();          // requested but not granted
 ```
 
-The expanded panel includes **Refresh schema** (re-runs the remote schema check) and **Copy debug info** (JSON snapshot **without** raw access tokens). You can also read `devInfo` and call `refreshSchemaStatus()` from `useBasic()` for your own UI.
+## Database
 
----
+`db.table(name)` returns the table API (name must exist in your schema):
 
-### `useQuery()`
+```typescript
+const todos = db.table("todos");
 
-Live query hook - automatically re-renders when data changes.
+const created = await todos.create({ title: "buy milk" });
+// → { id: "0198…", title: "buy milk" } — id minted locally, works offline
 
-```tsx
-import { useQuery } from "@basictech/react";
+await todos.put(id, { title: "replace", completed: false });
+// create-or-replace the WHOLE record with these fields
 
-// Get all items
-const todos = useQuery(() => db.collection("todos").getAll());
+await todos.patch(id, { completed: true });
+// shallow-merge the given fields; returns null if the record doesn't exist
 
-// With type safety
-interface Todo {
-  id: string;
-  title: string;
-  completed: boolean;
-}
-const todos = useQuery(() => db.collection<Todo>("todos").getAll());
-```
+await todos.delete(id);   // idempotent — deleting a missing record is fine
 
-> **Note:** Only works in `sync` mode. In `remote` mode, use manual fetching.
+await todos.get(id);      // record or null
+await todos.getAll();     // all records
+await todos.find((t) => !t.completed);
+```
 
----
+Semantics worth knowing:
 
-### Database Methods
+- **`put` replaces, `patch` merges.** Two devices patching *different* fields of the same record both win; patching the *same* field, the last write wins.
+- **`json` fields are atomic** — patching a `json` field replaces its whole value (no deep merge).
+- Writes are **validated locally** against your schema before queueing (same rules the server enforces), so typos fail fast with a thrown error instead of a round-trip.
+- In sync mode, `create` mints the id client-side — you get the full record back synchronously-ish, even offline.
 
-#### `db.collection(name)`
+## Live queries
 
-Access a collection by name.
+`useQuery` re-runs your query and re-renders whenever the underlying data changes:
 
 ```tsx
-const { db } = useBasic();
-const todos = db.collection("todos");
+const todos = useQuery(() => db.table("todos").getAll());               // undefined while loading
+const open  = useQuery(() => db.table("todos").find((t) => !t.completed));
+const one   = useQuery(() => db.table("todos").get(selectedId), [selectedId]); // deps like useEffect
 ```
 
-#### Collection Methods
+For advanced queries, `table.ref` exposes the underlying [Dexie](https://dexie.org) table over the local view (sync mode only) — indexed fields from your schema are Dexie indexes:
 
-| Method             | Returns              | Description                         |
-| ------------------ | -------------------- | ----------------------------------- |
-| `getAll()`         | `Promise<T[]>`       | Get all records                     |
-| `get(id)`          | `Promise<T \| null>` | Get one record by ID                |
-| `add(data)`        | `Promise<T>`         | Create new record (returns with ID) |
-| `put(data)`        | `Promise<T>`         | Upsert record (requires ID)         |
-| `update(id, data)` | `Promise<T \| null>` | Partial update                      |
-| `delete(id)`       | `Promise<boolean>`   | Delete record                       |
-| `filter(fn)`       | `Promise<T[]>`       | Filter with predicate               |
+```tsx
+const recent = useQuery(() =>
+  db.table("todos").ref!.where("completed").equals(0).limit(10).toArray(),
+);
+```
 
-#### Examples
+## Sync status, offline behavior & errors
 
 ```tsx
-// Create
-const todo = await db.collection("todos").add({
-  title: "Buy milk",
-  completed: false,
-});
-console.log(todo.id); // Auto-generated ID
+const sync = useSyncStatus();
 
-// Read
-const allTodos = await db.collection("todos").getAll();
-const oneTodo = await db.collection("todos").get("some-id");
+sync.status;        // 'idle' | 'local' | 'connecting' | 'online' | 'offline' | 'auth_required' | 'revoked' | 'stopped'
+sync.enabled;       // false when the schema is invalid/unpublished
+sync.pendingCount;  // local writes not yet confirmed by the server
+```
 
-// Update
-await db.collection("todos").update("some-id", { completed: true });
+`local` means the database is working without a connection — an anonymous workspace, an unpublished (version 0) schema during development, or a paused session.
 
-// Delete
-await db.collection("todos").delete("some-id");
+**Offline is not an error.** Writes keep working and queue in IndexedDB; reads serve the local view; everything pushes on reconnect (safe to retry — ops are idempotent). The queue survives page reloads — including offline cold starts: reloading with no network serves all data from the local replica.
 
-// Filter
-const incomplete = await db.collection("todos").filter((t) => !t.completed);
+`revoked` means the user disconnected your app from their account — data access is gone until they sign in and consent again.
+
+### Rejected ops
+
+If the server terminally rejects a write (schema validation, permissions, payload too large), the SDK **rolls the record back**, parks the op in a rejected store, and will never retry it:
+
+```tsx
+const sync = useSyncStatus();
+const rejected = await sync.listRejected();
+// [{ op_id, op: { type, table, record_id, data }, error: 'SCHEMA_VALIDATION_FAILED', message, rejected_at }]
+await sync.clearRejected();
 ```
 
----
+You can also listen live:
 
-## Advanced Usage
+```typescript
+const { client } = useBasic();
+useEffect(() => client.engine?.on("rejected", ({ rejection }) => {
+  toast.error(`write rejected: ${rejection.error}`);
+}), [client]);
+```
 
-### Manual OAuth Flow
+## Shares (multiplayer)
 
-For custom OAuth handling (mobile apps, popups, etc.):
+Users can grant other users access to a slice of their data — a whole table or specific records, read-only or read-write. Grants are created by the user on basic.id (apps can never share a user's data on their own); your app **lists** and **mounts** them:
 
 ```tsx
-const { signInWithCode, getSignInUrl } = useBasic();
+function SharedTodos() {
+  const { received } = useShares();          // shares other users granted to me
+  const share = received[0];
+  const { db: sharedDb, status } = useShare(share?.id); // 'mounting' | 'mounted' | 'error' | 'revoked'
+  const todos = useQuery(() => sharedDb?.table("todos").getAll(), [sharedDb]);
 
-// Get OAuth URL with custom redirect
-const url = getSignInUrl("myapp://callback");
+  if (!share) return <p>nothing shared with you yet</p>;
+  if (status !== "mounted") return <p>{status}…</p>;
 
-// Exchange code for session
-const result = await signInWithCode(code, state);
-if (result.success) {
-  console.log("Signed in!");
+  return (
+    <ul>
+      {todos?.map((t) => (
+        <li key={t.id} onClick={() => sharedDb!.table("todos").patch(t.id, { completed: true })}>
+          {String(t.title)}
+        </li>
+      ))}
+    </ul>
+  );
 }
 ```
 
-### Remote Mode
+Mounted shares live in their **own local keyspace** — separate replica, separate offline queue — and are never merged with the user's own data. Writes work when the share permission is `write` (the owner sees your changes attributed to the guest). When the owner revokes the share, the mount status flips to `revoked` and the local copy is purged.
 
-For server-rendered apps or when you don't need offline support:
+## Typed schemas
 
-```tsx
-<BasicProvider schema={schema} dbMode="remote">
-  <App />
-</BasicProvider>
-```
+`@basictech/schema` (a dependency of this package) can infer record types from your schema:
 
-In remote mode:
+```typescript
+import { defineSchema, type InferRecord } from "@basictech/schema";
 
-- Data is fetched via REST API
-- No IndexedDB storage
-- `useQuery` won't auto-update (use manual refresh)
-- Requires authentication for all operations
-- Auth request failures are surfaced to the caller; recoverable 401s do not automatically sign the user out
+export const schema = defineSchema({
+  project_id: "…",
+  version: 1,
+  tables: {
+    todos: {
+      fields: {
+        title: { type: "string", required: true },
+        completed: { type: "boolean" },
+      },
+    },
+  },
+});
+
+type Todo = InferRecord<typeof schema, "todos">;
+// { id: string; title: string; completed?: boolean }
+
+const todos = db.table<Todo>("todos"); // fully typed CRUD
+```
 
-### Error Handling
+## REST mode
+
+Don't want a local replica? `mode="rest"` makes every table call a direct API request — no IndexedDB, no WebSocket, no offline support:
 
 ```tsx
-import { NotAuthenticatedError } from "@basictech/react";
-
-try {
-  await db.collection("todos").add({ title: "Test" });
-} catch (error) {
-  if (error instanceof NotAuthenticatedError) {
-    // User needs to sign in
-    signIn();
-  }
-}
+<BasicProvider schema={schema} mode="rest">
 ```
 
----
+The table API is identical, with REST semantics: `create` gets its id from the server, `put`/`patch`/`delete` on missing records return null/no-op, reads hit the network. `useQuery` won't live-update in this mode (re-run queries with deps).
 
-## TypeScript
+## API reference
 
-Full TypeScript support with generics:
+### `<BasicProvider>` props
 
-```tsx
-interface Todo {
-  id: string;
-  title: string;
-  completed: boolean;
-  createdAt: number;
-}
+| Prop | Default | Description |
+| --- | --- | --- |
+| `schema` | — | Your Basic schema document (`project_id` is read from it) |
+| `mode` | `"sync"` | `"sync"` (local replica) or `"rest"` (direct API) |
+| `anonymous` | `true` | Local workspace without sign-in; merges into the account on sign-in |
+| `auth.scopes` | `"profile,email,app:admin"` | OAuth scopes to request |
+| `auth.pds_url` | `https://pds.basic.id` | The Basic server (auth + data + sync) |
+| `auth.sync_url` | `wss://<pds>/sync/` | Sync WebSocket URL (rarely needed) |
+| `storage` | `localStorage` | Custom `BasicStorage` adapter for auth state |
+| `debug` | `false` | Verbose console logging |
+| `devToolbar` | `false` | Floating status toolbar (dev environments only) |
+| `renderWhileLoading` | `false` | Render children before auth bootstrap finishes |
 
-// Type-safe collection
-const todos = db.collection<Todo>("todos");
+### Hooks
 
-// All methods are typed
-const todo = await todos.add({
-  title: "Test",
-  completed: false,
-  createdAt: Date.now(),
-});
-// todo is typed as Todo
+| Hook | Returns |
+| --- | --- |
+| `useBasic()` | Everything: auth fields + actions, `db`, `sync`, `users`, `activeUser`, `devInfo`, `client` |
+| `useAuth()` | `{ isReady, isSignedIn, isAnonymous, status, user, did, scope, hasScope, missingScopes, signIn, signInWithHandle, signInWithCode, signOut, getToken, getSignInUrl }` |
+| `useDb()` | The table API for the active user's own data |
+| `useQuery(fn, deps?)` | Live query result (`undefined` while loading); re-attaches automatically on user switch |
+| `useSyncStatus()` | `{ status, enabled, pendingCount, listRejected, clearRejected }` |
+| `useUsers()` | `{ users, activeUser, isAnonymous, switchUser, addUser, removeUser }` |
+| `useShares()` | `{ granted, received, isLoading, error, refresh }` |
+| `useShare(shareId)` | `{ db, status, error }` — a mounted share |
+
+Note on `useQuery` and user switching: the active user's identity is appended to your deps automatically, so queries that read `db` from the current render (via `useBasic()`/`useDb()`) re-attach to the new user's database on switch. If your query closure captures `db` from outside render, pass `[db]` in deps explicitly — or remount the subtree with `key={activeUser?.id}`.
+
+### Table API
+
+| Method | Sync mode | REST mode |
+| --- | --- | --- |
+| `create(data)` | client-minted id, offline-capable | server-minted id |
+| `put(id, data)` | create **or replace** | replace; throws if missing |
+| `patch(id, partial)` | merge; `null` if missing locally | merge; `null` if missing |
+| `delete(id)` | idempotent | no-op if missing |
+| `get(id)` / `getAll()` / `find(fn)` | local view | network |
+| `ref` | Dexie table (live queries, indexes) | `undefined` |
+
+## Advanced usage
+
+### Outside React
+
+Everything is available without React — `BasicClient` is the framework-agnostic core (`AuthManager` + `SyncEngine` + `RestClient`):
+
+```typescript
+import { createBasicClient } from "@basictech/react";
+
+const client = createBasicClient({ schema, debug: true });
+await client.start();
+client.subscribe(() => console.log(client.getSnapshot()));
+await client.db.table("todos").create({ title: "from anywhere" });
 ```
 
+The Sync/2 protocol layer (`SyncEngine`, `SyncConnection`, `SyncStore`, and all wire types) is exported too, for building custom clients or other runtimes — pass a `WebSocketImpl` (e.g. the `ws` package) to run in Node.
+
+### Events
+
+```typescript
+const { client } = useBasic();
+client.engine?.on("status", (s) => {});                       // sync status changes
+client.engine?.on("change", ({ sub, tables }) => {});         // records changed
+client.engine?.on("rejected", ({ sub, rejection }) => {});    // terminal write rejection
+client.engine?.on("revoked", ({ code }) => {});               // app connection revoked
+```
+
+### Custom storage
+
+Auth state lives in `localStorage` by default. Provide any `{ get, set, remove }` async adapter via the `storage` prop (see `BasicStorage`). `STORAGE_KEYS` lists every key the SDK uses.
+
+## Migrating from 0.8
+
+0.9 is a breaking rewrite — the server's legacy sync endpoint was removed, so 0.8 sync no longer functions. Changes you'll make:
+
+| 0.8 | 0.9 |
+| --- | --- |
+| `db.collection("todos")` | `db.table("todos")` |
+| `.add(data)` | `.create(data)` |
+| `.update(id, partial)` | `.patch(id, partial)` |
+| `.put({ id, ...fields })` | `.put(id, fields)` |
+| `dbStatus` / `DBStatus` enum | `useSyncStatus().status` |
+| `dbMode="remote"` | `mode="rest"` |
+| `auth.ws_url` | `auth.sync_url` (you almost never need it) |
+| `signOut()` reloads the page | in-place teardown, no reload |
+
+Local data migrates by re-bootstrap: the old `basicdb` IndexedDB database is deleted automatically and 0.9 builds fresh replicas in `basic-sync:<project_id>` databases from the server (the server is the source of truth, so nothing is lost).
+
 ---
 
 ## License