@basictech/react 0.9.0-beta.0 → 0.9.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basictech/react",
-  "version": "0.9.0-beta.0",
+  "version": "0.9.0-beta.1",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/readme.md

@@ -13,6 +13,8 @@ Basic gives every user their own personal datastore (a PDS). Your app authentica
 - [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)
@@ -110,17 +112,63 @@ function Todos() {
 }
 ```
 
-That's the whole loop: `signIn()` runs the OAuth flow, `db.table(...)` writes apply instantly to the local replica (and queue offline), and `useQuery` re-renders whenever local data changes — whether the change came from this tab, another tab, another device, or another user via a share.
+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. **Bootstrap** — on first run the SDK fetches a snapshot of current state, then subscribes for live changes from that point.
+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. **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)).
-5. **Sign-out is clean** — local data is deleted, the session is revoked server-side, and other tabs update in place. No page reloads.
+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.
+
+## Anonymous & local-first
+
+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.
+
+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
+const { isAnonymous, isSignedIn, signIn, db } = useBasic();
+
+// works signed in or not:
+await db.table("todos").create({ title: "works offline & anonymous" });
+
+// prompt when you want the data to start syncing:
+{isAnonymous && <button onClick={() => signIn()}>Sign in to sync</button>}
+```
+
+Safety guarantees:
+
+- 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).
+
+## Multiple users
+
+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 { 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>
+```
+
+- `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).
 
 ## Authentication
 
@@ -148,8 +196,8 @@ await auth.signOut();                      // revokes server-side + clears local
 | `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 | user info + a sign-in prompt |
-| `signed_out` | No session | sign-in screen |
+| `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) |
 
 ### Calling your own API
 
@@ -226,12 +274,14 @@ const recent = useQuery(() =>
 ```tsx
 const sync = useSyncStatus();
 
-sync.status;        // 'idle' | 'connecting' | 'online' | 'offline' | 'auth_required' | 'revoked' | 'stopped'
+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
 ```
 
-**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.
+`local` means the database is working without a connection — an anonymous workspace, an unpublished (version 0) schema during development, or a paused session.
+
+**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.
 
 `revoked` means the user disconnected your app from their account — data access is gone until they sign in and consent again.
 
@@ -327,6 +377,7 @@ The table API is identical, with REST semantics: `create` gets its id from the s
 | --- | --- | --- |
 | `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) |
@@ -339,14 +390,17 @@ The table API is identical, with REST semantics: `create` gets its id from the s
 
 | Hook | Returns |
 | --- | --- |
-| `useBasic()` | Everything: auth fields + actions, `db`, `sync`, `devInfo`, `client` |
-| `useAuth()` | `{ isReady, isSignedIn, status, user, did, scope, hasScope, missingScopes, signIn, signInWithHandle, signInWithCode, signOut, getToken, getSignInUrl }` |
-| `useDb()` | The table API for the user's own data |
-| `useQuery(fn, deps?)` | Live query result (`undefined` while loading) |
+| `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 |