@basictech/react 0.9.0-beta.1 → 0.11.0-beta.2

package/README.md

@@ -0,0 +1,1111 @@
+# @basictech/react
+
+React and browser integration for [Basic](https://basic.tech): typed data, local-first sync,
+authentication, accounts, files, repos, and sharing.
+
+`@basictech/react` supplies the browser adapters, a React provider, and schema-bound hooks. The
+framework-independent client and protocol types live in `@basictech/core`; schema definition and
+runtime validation live in `@basictech/schema`.
+
+| Package | Role |
+| --- | --- |
+| `@basictech/react` | Browser defaults, React provider, schema-bound factory, and hooks |
+| `@basictech/core` | Framework-neutral client, data model, sync, files, shares, and public types |
+| `@basictech/schema/define` | Dependency-light schema definition and TypeScript inference |
+
+This beta requires React 18 or newer (`useSyncExternalStore`) and declares Node.js 24 or newer in
+its package metadata.
+
+## Install
+
+Install the React SDK and declare the schema package you import directly:
+
+```bash
+npm install @basictech/react @basictech/schema
+```
+
+React is a peer dependency and must already be installed by your application.
+
+## Quick start
+
+Define the schema and create `basic` once at module scope. The returned client, Provider, and hooks
+all carry the schema type.
+
+```tsx
+// file: QuickStart.tsx
+import { createBasic } from '@basictech/react'
+import { defineSchema } from '@basictech/schema/define'
+
+const schema = defineSchema({
+  project_id: 'my-project',
+  version: 1,
+  tables: {
+    todos: {
+      fields: {
+        title: { type: 'string', required: true },
+        done: { type: 'boolean', required: true },
+      },
+    },
+  },
+})
+
+const basic = createBasic({
+  schema,
+  clientId: 'did:web:app.example',
+})
+
+function Todos() {
+  const auth = basic.useAuth()
+  const todos = basic.useCollection('todos')
+  const result = basic.useQuery('todos', { sort: 'title' })
+
+  return (
+    <main>
+      {auth.isAnonymous && (
+        <button onClick={() => void auth.signIn()}>Sign in to sync</button>
+      )}
+      {auth.isSignedIn && (
+        <button onClick={() => void auth.signOut()}>Sign out {auth.user?.email}</button>
+      )}
+
+      <button onClick={() => void todos.create({ title: 'Try Basic', done: false })}>
+        Add todo
+      </button>
+
+      {result.isLoading && <p>Loading…</p>}
+      {result.error && <p>Could not load todos: {result.error.code}</p>}
+      <ul>
+        {result.data.map((todo) => <li key={todo.id}>{todo.value?.title}</li>)}
+      </ul>
+    </main>
+  )
+}
+
+export default function Root() {
+  return <basic.Provider><Todos /></basic.Provider>
+}
+```
+
+With the default sync configuration, a new visitor receives an anonymous local workspace backed
+by IndexedDB. `signIn()` starts redirect-only OAuth with PKCE; after the callback, the SDK replays
+that profile's queued anonymous operations into the account's default repo.
+
+## Define a schema
+
+Use `defineSchema` from the dependency-light `@basictech/schema/define` subpath. It preserves
+literal table and field names so `createBasic` can infer collection names, record values, filters,
+and mutations throughout your app.
+
+```ts
+// file: basic.ts
+import { createBasic } from '@basictech/react'
+import { defineSchema } from '@basictech/schema/define'
+
+export const schema = defineSchema({
+  project_id: 'tasks-web',
+  namespace: 'tasks',
+  version: 1,
+  tables: {
+    todos: {
+      fields: {
+        title: { type: 'string', required: true, indexed: true },
+        done: { type: 'boolean', required: true },
+        rank: { type: 'number' },
+        details: { type: 'json' },
+      },
+    },
+  },
+})
+
+export const basic = createBasic({
+  schema,
+  clientId: 'did:web:app.example',
+  redirectUri: `${location.origin}/oauth/callback`,
+})
+```
+
+A schema has `project_id`, a numeric `version`, optional `namespace`, and a `tables` map. A table
+has a `fields` map and may also define `name`, `type: 'collection'`, or
+`origin: { type: 'reference', project_id, table, version? }`. Field definitions support:
+
+| Option | Type | Effect on inferred values |
+| --- | --- | --- |
+| `type` | `'string' \| 'boolean' \| 'number' \| 'json'` | Required; maps to the corresponding TypeScript type (`json` maps to `unknown`) |
+| `required` | `boolean` | `true` makes the value property required; otherwise it is optional |
+| `indexed` | `boolean` | Declares an indexed schema field; it does not change the TypeScript value type |
+
+Records are lifecycle envelopes: `{ id, value, meta }`. The schema describes `value`; the record
+ID is the envelope's `id`, not a field inside `value`. `InferRecord` from the schema package includes
+an `id` for standalone type use, while the React collection APIs infer the value without that ID.
+
+## Configure `createBasic`
+
+`createBasic(config)` requires a schema and returns one `CreatedBasic<S>`. Its config is the core
+`BasicConfig<S>` plus a required `schema: S`. `BrowserBasicConfig<S>` is an alias of the same core
+config; the React package changes behavior by installing browser defaults before creating the core
+client.
+
+### Configuration reference
+
+| Option | Type | Browser default | When to override |
+| --- | --- | --- | --- |
+| `clientId` | `string` | Required | The application's client DID. Its Basic app metadata must register the redirect URI. |
+| `schema` | `S extends BasicSchema` | Required by `createBasic` | Pass the `defineSchema()` result used by this application. It is optional only in the lower-level `createBasicClient`. |
+| `identityOrigin` | `string` | `'https://basic.id'` | Use another Basic ID web origin for the shares management URL. |
+| `defaultPds` | `string` | `'https://pds.basic.id'` | Change the PDS used for handle resolution and no-argument `signIn()`. `signIn(handleOrDid)` discovers that identity's PDS after resolving handles here. |
+| `redirectUri` | `string` | `location.origin + location.pathname` | Set an explicit OAuth callback route. Outside a browser location, it is required. The URI must appear in the client metadata for `clientId`. |
+| `mode` | `'sync' \| 'rest'` | `'sync'` | Choose direct REST when offline replicas, anonymous mode, multi-account state, and `watch()` are not needed. |
+| `anonymous` | `boolean` | `true` in sync mode | Set `false` to require sign-in. REST mode always disables anonymous workspaces. |
+| `scopes` | `string[]` | `['openid:read']` | Request additional OAuth scopes. `openid:read` is added and duplicates are removed. |
+| `conflictPolicy` | `'keep-mine' \| 'keep-theirs' \| 'event'` | `'keep-mine'` | Keep the local intent, drop it in favor of remote state, or leave conflicts pending for explicit resolution. |
+| `debug` | `boolean` | `false` | Enable selected client lifecycle diagnostics through `console.debug`. |
+| `allowInsecure` | `boolean` | `false` | Allow HTTP identity/PDS endpoints in controlled local development only. HTTPS is otherwise required. |
+| `fetch` | `typeof globalThis.fetch` | `globalThis.fetch` | Inject a fetch implementation, test transport, or instrumented wrapper. |
+| `WebSocketImpl` | `new (url: string \| URL) => WebSocket` | `globalThis.WebSocket` | Inject WebSocket support in a non-browser runtime or tests. |
+| `kv` | `KeyValueStorage` | `localStorage`, then memory | Replace profile registry, cached identity/repo state, and other durable key/value state. |
+| `tokenStore` | `TokenStore` | `BrowserTokenStore` over the default local store | Supply a secure credential facility. See [Token storage](#token-storage-beta-policy). |
+| `sessionStorage` | `KeyValueStorage` | `sessionStorage`, then memory | Replace per-tab active-profile selection and one-time PKCE state storage. |
+| `replicaStore` | `ReplicaStoreFactory` | Dexie/IndexedDB, then memory | Provide another durable replica store or an explicit memory store for tests. |
+| `navigate` | `(url: string) => void \| Promise<void>` | `location.assign(url)` | Integrate OAuth navigation with a browser shell or test harness. |
+| `currentUrl` | `() => string` | `location.href`, or `''` without `location` | Tell auth bootstrap where to read OAuth `code` and `state`. |
+| `replaceUrl` | `(url: string) => void` | `history.replaceState({}, '', url)` | Integrate removal of consumed OAuth query parameters with custom navigation. |
+| `createMessageChannel` | `(name: string) => AuthMessageChannel` | `BroadcastChannel` when available | Replace or disable cross-context auth notifications. The default token adapter also transfers access tokens transiently between tabs. |
+| `reconcileTrigger` | `(listener: () => void) => () => void` | `focus`, `online`, and `visibilitychange` listeners | Subscribe the client to host lifecycle signals so a suspended or backgrounded application reconciles credentials with its owner and mounted Sync sessions on resume. Return a cleanup function; the client calls it on `stop()`. |
+| `ownerCredential` | `OwnerCredentialAdapter` | None | First-party Basic ID/dev tooling can inject owner credentials for `client.drive()`, account-wide `client.storageInfo()`, and `client.shares.leave()`. Normal app credentials should use existing repos and `shares.manageUrl()`. |
+| `uploadTransport` | `UploadTransportAdapter` | Browser XHR, then the core fetch fallback | Supply a multipart transport. XHR is used by default because fetch has no upload-progress events. |
+| `warn` | `(message: string) => void` | `console.warn` for schema checks | Route schema-drift warnings into application logging. |
+
+`KeyValueStorage` and `TokenStore` implement `get(key)`, `set(key, value)`, and `remove(key)`; each
+method may be synchronous or return a Promise.
+
+### Browser persistence and cross-tab behavior
+
+The defaults are selected from browser capabilities at client creation:
+
+- **Replica persistence:** sync replicas, pending operations, rejections, and lifecycle metadata
+  are stored in IndexedDB through Dexie. If IndexedDB is unavailable, replicas are memory-only.
+- **Profile state:** the account registry and per-profile state use `localStorage`; active profile
+  selection and PKCE state use `sessionStorage`. Inaccessible storage falls back to memory.
+- **Single writer:** the persistence adapter uses Web Locks for per-partition leader election and
+  `BroadcastChannel` to forward follower mutations and publish committed replica state. Without
+  both primitives, every tab may write in a degraded version-guarded, last-committed-writer-wins
+  mode; concurrent offline intent can be lost in that fallback.
+- **Auth coordination:** token rotation and sign-out notifications use `BroadcastChannel` when
+  available. Access tokens can cross that channel transiently but are not written by the default
+  token store.
+- **Lifecycle recovery:** when a tab regains focus, comes back online, or becomes visible again,
+  the client reconciles fresh credentials with the owner and mounted Sync sessions. A browser that
+  suspended the page recovers without a reload, and transient refresh failures retry rather than
+  signing the profile out. Override `reconcileTrigger` to supply that signal in another host.
+- **Uploads:** browser multipart uploads use XHR for real `onProgress(loaded, total)` events. The
+  fetch fallback reports only start and completion.
+
+The package also exports the adapters for explicit composition: `BrowserKeyValueStorage`,
+`browserStorage`, `BrowserTokenStore`, `PersistenceStore`, `browserUploadTransport`,
+`createBrowserMessageChannel`, `createBrowserAuthChannelFactory`, `browserNavigate`,
+`browserCurrentUrl`, and `browserReplaceUrl`. Most applications only need `createBasic`, which
+installs them.
+
+### Token storage: beta policy
+
+The default `BrowserTokenStore` stores each profile's refresh token in `localStorage` and keeps its
+access token only in memory. This is the documented **CS-CLIENT-002 beta conformance exception**:
+`localStorage` is not a secure credential facility. Inject `tokenStore` when the host provides a
+secure store. This default is scheduled for reconsideration before GA.
+
+## Provider
+
+`basic.Provider` accepts exactly these props:
+
+| Prop | Type | Default | Behavior |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | Required | The application subtree that can use Basic hooks |
+| `renderWhileLoading` | `boolean` | `false` | Render children before `client.getSnapshot().isReady`; otherwise render nothing until startup settles |
+
+Create `basic` once outside React rendering. On mount the Provider starts that client; on the final
+unmount it stops it. Startup failures are thrown during rendering so a React error boundary can
+handle them. The lifecycle is safe under React StrictMode's effect replay: references are counted,
+duplicate starts share one Promise, and stop is deferred so the replay does not tear down a live
+client.
+
+```tsx
+// file: ProviderExample.tsx
+import { StrictMode, type ReactNode } from 'react'
+import { basic } from './basic'
+
+export function BasicRoot({ children }: { children: ReactNode }) {
+  return (
+    <StrictMode>
+      <basic.Provider renderWhileLoading={false}>{children}</basic.Provider>
+    </StrictMode>
+  )
+}
+```
+
+With the default `renderWhileLoading={false}`, hooks under the Provider first render after the
+client is ready. Setting it to `true` is useful for an application shell that reads `isReady` and
+owns its loading UI.
+
+## Hook reference
+
+The schema-bound factory returns every hook below. Bound hooks are preferred because they reject
+unknown table names and infer fields in reads, writes, and queries.
+
+| Hook | Signature | Purpose |
+| --- | --- | --- |
+| `useAuth` | `useAuth(): UseAuthResult` | Auth state and redirect actions |
+| `useAccounts` | `useAccounts(): UseAccountsResult` | Local profiles and per-tab switching |
+| `useDb` | `useDb(source?: SourceRef): BasicDb` | Database for a default repo, explicit repo, or open mount |
+| `useCollection` | `useCollection(name, { source? }?): Collection` | Typed collection CRUD |
+| `useQuery` | `useQuery(name, query?, { source? }?): UseQueryResult` | Reactive typed query |
+| `useSyncStatus` | `useSyncStatus(source?): UseSyncStatusResult` | Connectivity, pending work, rejections, and conflicts |
+| `useSchemaStatus` | `useSchemaStatus(source?): SchemaStatus` | Local/server schema drift |
+| `useRepos` | `useRepos(): UseReposResult` | Repo catalog operations |
+| `useFiles` | `useFiles(query?, { source? }?): UseFilesResult` | Reactive file listing |
+| `useStorageInfo` | `useStorageInfo(): UseStorageInfoResult` | Default repo storage use and quota |
+| `useMounts` | `useMounts(query?): UseMountsResult` | Incoming mounts and mount opening |
+| `useOutgoingShares` | `useOutgoingShares(): UseOutgoingSharesResult` | Outgoing share lifecycle |
+| `useBasic` | `useBasic(): UseBasicResult` | Auth plus common client, db, account, sync, and repo state |
+
+### `basic.useAuth()`
+
+`useAuth()` returns:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `isReady` | `boolean` | Auth bootstrap has left `bootstrapping` |
+| `isSignedIn` | `boolean` | Status is `authenticated` or `recovering` |
+| `isAnonymous` | `boolean` | The active sync profile is anonymous and not signed in |
+| `status` | `'bootstrapping' \| 'signed_out' \| 'authenticated' \| 'recovering' \| 'reauth_required'` | Current auth lifecycle |
+| `error` | `BasicError \| null` | Stable auth bootstrap/refresh error code when available |
+| `user` | `AuthUser \| null` | OIDC user info (`sub`, `pds_url`, and optional `email`, `name`, `picture`, `handle`) |
+| `did` | `string \| null` | Signed-in account DID |
+| `handle` | `string \| null` | Resolved account handle |
+| `signIn(input?)` | `(input?: string) => Promise<void>` | Begin redirect OAuth. Input may be a handle or DID; omit it to use `defaultPds`. |
+| `signOut()` | `() => Promise<void>` | Best-effort revoke the refresh token, clear the local profile, and activate/create the next profile |
+| `getToken()` | `() => Promise<string>` | Return or refresh an app access token; throws when unauthorized |
+
+```tsx
+// file: AuthPanel.tsx
+import { basic } from './basic'
+
+export function AuthPanel() {
+  const auth = basic.useAuth()
+
+  if (!auth.isReady) return <p>Starting Basic…</p>
+  if (auth.isSignedIn) {
+    return (
+      <p>
+        Signed in as {auth.handle ?? auth.did}
+        <button onClick={() => void auth.signOut()}>Sign out</button>
+      </p>
+    )
+  }
+
+  return (
+    <div>
+      {auth.isAnonymous && <p>Your local work will migrate after sign-in.</p>}
+      <button onClick={() => void auth.signIn()}>Continue with Basic ID</button>
+      <button onClick={() => void auth.signIn('alice.basic.id')}>Sign in as Alice</button>
+      {auth.error && <p>{auth.error.code}</p>}
+    </div>
+  )
+}
+```
+
+Anonymous mode exists only in sync mode. An anonymous profile has its own durable local replica.
+When OAuth completes on that profile, its queued operations are replayed—with their operation IDs—
+into the signed-in account's default repo. Signing out removes the active account profile's local
+replicas and returns to another local profile or a fresh anonymous one when enabled.
+
+### `basic.useAccounts()`
+
+`useAccounts()` returns `{ accounts, active, switchAccount, addAccount, removeAccount }`:
+
+- `accounts: BasicProfile[]` lists local profiles.
+- `active: BasicProfile | null` is this tab's selected profile.
+- `switchAccount(id): Promise<void>` changes the active profile in this tab.
+- `addAccount(): Promise<BasicProfile>` creates and activates a new anonymous profile from which to
+  start another sign-in.
+- `removeAccount(id): Promise<void>` removes that profile and its local credentials/replicas. If it
+  is active, this follows the sign-out path. It does not delete the server account.
+
+`BasicProfile` contains `id`, `kind: 'anon' | 'account'`, `storagePrefix`, `createdAt`,
+`lastActiveAt`, and optional/null `did`, `handle`, `email`, `name`, and `picture`. Multi-account and
+`addAccount()` require sync mode with anonymous profiles enabled.
+
+```tsx
+// file: AccountSwitcher.tsx
+import { basic } from './basic'
+
+export function AccountSwitcher() {
+  const { accounts, active, switchAccount, addAccount, removeAccount } = basic.useAccounts()
+
+  return (
+    <section>
+      <select
+        value={active?.id ?? ''}
+        onChange={(event) => void switchAccount(event.currentTarget.value)}
+      >
+        {accounts.map((account) => (
+          <option key={account.id} value={account.id}>
+            {account.handle ?? account.email ?? `Anonymous ${account.id.slice(0, 8)}`}
+          </option>
+        ))}
+      </select>
+      <button onClick={() => void addAccount()}>Add account</button>
+      {active && <button onClick={() => void removeAccount(active.id)}>Remove local profile</button>}
+    </section>
+  )
+}
+```
+
+### `basic.useDb()` and sources
+
+`SourceRef` is a discriminated union:
+
+| Source | Meaning |
+| --- | --- |
+| `'default'` or omitted | The active account's default repo, or the anonymous local repo |
+| `{ repoId: string }` | A known repo in the active account's catalog |
+| `{ mountId: string }` | An incoming mount already opened with `useMounts().open(mountId)` |
+
+Bare repo/mount strings are not accepted. Unknown catalog entries throw `UNKNOWN_SOURCE`; the SDK
+does not guess. The returned `BasicDb` has `kind: 'sync' | 'rest'`, `source`, `collection(name)`, and
+`files`.
+
+```tsx
+// file: DataSources.tsx
+import { basic } from './basic'
+
+export function DataSources({ repoId, openMountId }: { repoId: string; openMountId: string }) {
+  const defaultDb = basic.useDb()
+  const anotherRepo = basic.useDb({ repoId })
+  const mountedDb = basic.useDb({ mountId: openMountId })
+
+  return (
+    <p>
+      {defaultDb.kind}; {anotherRepo.source === 'default' ? 'default' : 'explicit'};
+      {'files' in mountedDb ? ' mounted' : ''}
+    </p>
+  )
+}
+```
+
+The `{ mountId }` overload exposes `MountViewerFiles`. To obtain editor-only mounted-file methods,
+use the role-discriminated handle returned by `useMounts().open()`.
+
+### `basic.useCollection()` and record lifecycle
+
+`basic.useCollection(table, { source? })` returns a schema-typed `Collection<Value>`. The object is
+an imperative API; use `useQuery` or `watch` when rendering data.
+
+| Method | Signature | Behavior |
+| --- | --- | --- |
+| `create` | `create(value, { id?, idempotencyKey? }?)` | Create with an optional record ID |
+| `put` | `put(id, value, { idempotencyKey? }?)` | Replace the full value; creates when missing |
+| `patch` | `patch(id, partial, { unset?, idempotencyKey? }?)` | Shallow-set fields and optionally remove named fields |
+| `delete` | `delete(id, { idempotencyKey? }?)` | Soft-delete; retains a recoverable value |
+| `restore` | `restore(id, { idempotencyKey? }?)` | Restore a deleted record |
+| `purge` | `purge(id, { idempotencyKey? }?)` | Destructively erase the value and retain a purged shell |
+| `get` | `get(id)` | Return `BasicRecord<Value> \| null` |
+| `list` | `list(query?)` | Return `{ data, nextCursor }`; lifecycle-aware overloads narrow the records |
+| `watch` | `watch(query, listener)` | Publish an initial page and sync updates; returns an unsubscribe function |
+
+Sync mutations use generated durable operation IDs. REST mutations generate UUID idempotency keys;
+if a REST caller supplies one, it must also be a UUID. REST updates use cached ETag preconditions.
+
+Every mutation resolves to `{ record, opId }`. A record is one of:
+
+- live: `{ id, value: V, meta: { state: 'live', ... } }`
+- deleted: `{ id, value: V, meta: { state: 'deleted', ... } }`
+- purged: `{ id, value: null, meta: { state: 'purged', ... } }`
+
+Sync metadata can also include `sync: 'confirmed' | 'pending' | 'conflict' | 'rejected'` and
+`pendingOps: string[]`; REST metadata can include `etag`. Check `meta.state` before using a value
+from an all-state query.
+
+```tsx
+// file: TodoActions.tsx
+import { useState } from 'react'
+import { basic } from './basic'
+
+export function TodoActions({ id }: { id: string }) {
+  const todos = basic.useCollection('todos')
+  const [lastOperation, setLastOperation] = useState<string | null>(null)
+
+  async function complete() {
+    const result = await todos.patch(id, { done: true }, { unset: ['rank'] })
+    setLastOperation(result.opId)
+  }
+
+  async function replace() {
+    await todos.put(id, { title: 'Replaced', done: false })
+  }
+
+  return (
+    <div>
+      <button onClick={() => void complete()}>Complete</button>
+      <button onClick={() => void replace()}>Replace</button>
+      <button onClick={() => void todos.delete(id)}>Delete</button>
+      <button onClick={() => void todos.restore(id)}>Restore</button>
+      <button onClick={() => void todos.purge(id)}>Purge permanently</button>
+      {lastOperation && <small>Queued as {lastOperation}</small>}
+    </div>
+  )
+}
+```
+
+Do not write system collections such as `_files` through the generic collection API.
+
+### `basic.useQuery()`
+
+`basic.useQuery(table, query?, { source? })` returns:
+
+```text
+{
+  data: BasicRecord<Value>[]
+  isLoading: boolean
+  error: BasicError | null
+}
+```
+
+`query` supports:
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `where` | `{ [field]: value \| operators }` | A bare value is equality. Operators are `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `like`, `ilike`, and `isNull`. |
+| `sort` | `string \| string[]` | Prefix a field with `-` for descending order. `id`, `created_at`, `updated_at`, `deleted_at`, and `last_seq` are metadata fields; other names address the record value. |
+| `limit` | `number` | Integer from 1 through 200 |
+| `cursor` | `string` | REST pagination only; local sync queries throw `LOCAL_CURSOR_UNSUPPORTED` |
+| `state` | `'live' \| 'deleted' \| 'all'` | Defaults to `'live'` |
+
+`like` and `ilike` use `*` wildcards. Filters are ANDed. Ordering is deterministic: `id` is added
+as a tie-breaker, and the default local order is `-created_at, id`.
+
+```tsx
+// file: TodoList.tsx
+import { basic } from './basic'
+
+export function TodoList() {
+  const { data, isLoading, error } = basic.useQuery('todos', {
+    where: {
+      done: { eq: false },
+      rank: { gte: 1, lte: 10 },
+      title: { ilike: '*basic*' },
+    },
+    sort: ['rank', '-created_at'],
+    limit: 50,
+  })
+
+  if (isLoading) return <p>Loading todos…</p>
+  if (error) return <p>Query failed: {error.code}</p>
+  return <ul>{data.map((todo) => <li key={todo.id}>{todo.value?.title}</li>)}</ul>
+}
+```
+
+Before the first ready client snapshot, `data` is `[]`, `isLoading` is `true`, and `error` is null.
+When a query invalidates, the previous data remains available while `isLoading` becomes true and
+the old error is cleared. Success replaces `data`; failure retains the previous data and supplies a
+`BasicError` with `isLoading: false`.
+
+In sync mode, the hook subscribes to the local collection and reruns after local or remote replica
+changes. In REST mode there is no server subscription; the hook fetches its first page and reruns
+after a successful collection mutation made through this client. Change the query/options or
+remount to fetch other external changes.
+
+### `basic.useSyncStatus()`
+
+`useSyncStatus(source?)` returns:
+
+- `status: BasicSyncStatus`: `'idle'`, `'bootstrapping'`, `'connecting'`, `'online'`, `'offline'`,
+  `'stopped'`, `'error'`, `'local'`, `'stale'`, or `'ended'`.
+- `pendingCount: number`: queued operations for the selected source, or all open sources when no
+  source is supplied.
+- `rejected: BasicRejection[]`: terminally rejected operations with `source`, `op`, `error`, and
+  optional `message`.
+- `conflicts: BasicConflict[]`: unresolved operations with `source`, `op`, overlapping `fields`,
+  and a `structural` flag.
+- `resolveConflict(opId, 'keep-mine' | 'keep-theirs'): Promise<boolean>`.
+- `discardRejected(opId): Promise<boolean>`.
+
+Connectivity controls and the confirmation barrier live on `basic.client`:
+
+```tsx
+// file: SyncControls.tsx
+import { basic } from './basic'
+
+export function SyncControls() {
+  const sync = basic.useSyncStatus()
+
+  async function waitForServer() {
+    await basic.client.settle({ timeoutMs: 10_000, allowConflicts: false })
+  }
+
+  return (
+    <section>
+      <p>{sync.status}; {sync.pendingCount} pending</p>
+      <button onClick={() => basic.client.goOffline()}>Work offline</button>
+      <button onClick={() => basic.client.goOnline()}>Reconnect</button>
+      <button onClick={() => void waitForServer()}>Wait for sync</button>
+      {sync.conflicts.map((conflict) => (
+        <button
+          key={conflict.op.op_id}
+          onClick={() => void sync.resolveConflict(conflict.op.op_id, 'keep-mine')}
+        >
+          Keep my {conflict.op.record_id}
+        </button>
+      ))}
+      {sync.rejected.map((rejection) => (
+        <button
+          key={rejection.op.op_id}
+          onClick={() => void sync.discardRejected(rejection.op.op_id)}
+        >
+          Dismiss {rejection.error}
+        </button>
+      ))}
+    </section>
+  )
+}
+```
+
+`client.settle({ timeoutMs?, allowConflicts?, cursors? })` waits for pending sync work and optional
+per-subscription minimum numeric cursors. The default timeout is 5 seconds. It throws
+`SETTLE_TIMEOUT` if work remains; in REST mode it is a no-op. `goOffline()` disconnects sync
+sessions without rejecting local writes, and `goOnline()` reconnects them.
+
+The default `conflictPolicy: 'keep-mine'` rebases and retries local intent. `'keep-theirs'` drops a
+conflicting local operation. `'event'` leaves it in `conflicts` until `resolveConflict`; pass
+`allowConflicts: true` only when those unresolved conflicts should not block `settle()`.
+
+### `basic.useSchemaStatus()`
+
+`useSchemaStatus(source?)` returns `{ mode, localVersion?, serverVersion?, drift }`:
+
+- `mode` is `'basic-schema'`, `'dynamic'`, `'freeform'`, or `'unknown'`.
+- `drift` is `'unknown'`, `'match'`, or `'different'`.
+- version fields appear when the corresponding local/server schema is known.
+
+The client checks after opening an account repo. Drift is informational and emits through `warn`;
+it does not replace server-side schema validation.
+
+```tsx
+// file: SchemaNotice.tsx
+import { basic } from './basic'
+
+export function SchemaNotice() {
+  const schema = basic.useSchemaStatus()
+  if (schema.drift !== 'different') return null
+  return <p>App schema v{schema.localVersion} differs from repo schema v{schema.serverVersion}.</p>
+}
+```
+
+### `basic.useRepos()`
+
+`useRepos()` returns:
+
+- `repos: Repo[]` and `defaultRepoId: string | null` from the current catalog.
+- `refresh(): Promise<Repo[]>` to reload active repos.
+- `create({ name, schema_type?, schema? }): Promise<Repo>`. If `schema_type` is omitted, it defaults
+  to `'basic-schema'` when `schema` is supplied and `'freeform'` otherwise.
+- `archive(repoId): Promise<void>` to archive a known repo using its current ETag.
+
+`Repo` includes `id`, `name`, optional `kind`, `schema_type`, `schema_version`, `created_by`,
+lifecycle timestamps, and `access: { is_default, permissions }`.
+
+```tsx
+// file: RepoPicker.tsx
+import { basic } from './basic'
+
+export function RepoPicker() {
+  const repos = basic.useRepos()
+
+  async function createNotesRepo() {
+    await repos.create({ name: 'Notes' })
+    await repos.refresh()
+  }
+
+  return (
+    <section>
+      <p>Default: {repos.defaultRepoId ?? 'none'}</p>
+      <ul>{repos.repos.map((repo) => <li key={repo.id}>{repo.name}</li>)}</ul>
+      <button onClick={() => void createNotesRepo()}>Create repo</button>
+    </section>
+  )
+}
+```
+
+### `basic.useFiles()` and `basic.useStorageInfo()`
+
+Files v2 is capability-gated. `useFiles(query?, { source? })` returns
+`{ data, isLoading, error, refresh }`, where data is `Array<FileRecord | MountFileInfo>`. It
+subscribes to `_files` changes in sync mode.
+
+`FileListQuery` has `prefix?: string`, `state?: 'live' | 'deleted' | 'all'`, `limit?: number`, and
+`cursor?: string`. A sync owner source does not accept a cursor. Mounted-file listing supports
+`prefix`, `limit`, and `cursor`; mount sources do not apply the owner-only `state` filter.
+
+`useStorageInfo()` returns `{ data: StorageInfo | null, isLoading, error, refresh }`. The hook loads
+the signed-in default repo's usage using app credentials. `StorageInfo` contains `usedBytes`,
+`quotaBytes`, `blobCount`, `maxUploadBytes`, and optional `repoId`, `fileCount`, and
+`maxRecordsPerRepo`.
+
+An owner `FileRecord` contains `id`, `state: 'live' | 'deleted' | 'purged'`, nullable `path`,
+`name`, `size`, `sha256`, `contentType`, and `mtime`, plus optional sequence/timestamp/ETag
+metadata. A `MountFileInfo` has the corresponding content fields, `state: 'live' | 'deleted'`, and
+required `lastSeq`, `createdAt`, `updatedAt`, and nullable `deletedAt`.
+
+```tsx
+// file: FilesPanel.tsx
+import { useEffect, useState } from 'react'
+import { basic } from './basic'
+
+export function FilesPanel() {
+  const listing = basic.useFiles({ prefix: '/receipts', state: 'live' })
+  const storage = basic.useStorageInfo()
+  const files = basic.useDb().files
+  const [progress, setProgress] = useState(0)
+
+  useEffect(() => files.watch({ prefix: '/receipts' }, () => listing.refresh()), [files])
+
+  async function upload(file: File) {
+    await files.upload({
+      file,
+      path: `/receipts/${file.name}`,
+      onProgress: (loaded, total) => setProgress(total === 0 ? 0 : loaded / total),
+    })
+    listing.refresh()
+    storage.refresh()
+  }
+
+  async function download(id: string) {
+    const grant = await files.download(id, { disposition: 'inline' })
+    const response = await grant.fetch()
+    const url = URL.createObjectURL(await response.blob())
+    window.open(url, '_blank', 'noopener,noreferrer')
+  }
+
+  return (
+    <section>
+      <input
+        type="file"
+        onChange={(event) => {
+          const file = event.currentTarget.files?.[0]
+          if (file) void upload(file)
+        }}
+      />
+      <progress value={progress} max={1} />
+      <p>{storage.data?.usedBytes ?? 0} / {storage.data?.quotaBytes ?? 0} bytes</p>
+      {listing.isLoading && <p>Loading files…</p>}
+      {listing.error && <p>{listing.error.code}</p>}
+      <ul>
+        {listing.data.map((file) => (
+          <li key={file.id}>
+            {file.path}
+            <button onClick={() => void download(file.id)}>Download</button>
+            <button onClick={() => void files.delete(file.id).then(listing.refresh)}>Delete</button>
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}
+```
+
+Owner files are available at `basic.useDb(source).files`:
+
+| Method | Signature | Notes |
+| --- | --- | --- |
+| `upload` | `upload({ file, path, name?, mtime?, idempotencyKey?, signal?, onProgress? })` | Multipart upload with a shared four-transfer queue |
+| `uploadBlob` | `uploadBlob(bytes, { signal? }?)` | Upload content bytes and return `{ sha256, size, deduplicated }` for a later content-reference update |
+| `list` | `list({ prefix?, state?, limit?, cursor? }?)` | Returns `{ data: FileRecord[], nextCursor }` |
+| `get` | `get(id)` | Returns a `FileRecord` or null |
+| `download` | `download(id, { ttl?, disposition?, signal? }?)` | Returns a temporary grant with metadata and `fetch()`; TTL is capped to server capability |
+| `update` | `update(id, metadataOrContent, { idempotencyKey?, ifMatch? }?)` | Patch `path`, `name`, `contentType`, `mtime`, `unset`, or replace content by `{ sha256, size }` |
+| `delete` | `delete(id, options?)` | Recoverable soft deletion; does not reclaim blob storage |
+| `restore` | `restore(id, options?)` | Restore a soft-deleted file |
+| `purge` | `purge(id, options?)` | Destructive erasure path |
+| `watch` | `watch(query, listener)` | Sync mode only; returns unsubscribe |
+
+`FileRecord` uses camelCase metadata (`contentType`, `lastSeq`, `createdAt`, and so on) and nullable
+content fields for purged shells. `download().fetch()` omits bearer credentials and obtains one
+fresh grant if the provider returns 404. Upload and download retries honor supported server retry
+signals; an `AbortSignal` cancels queue waiting and transfer work.
+
+In REST mode there is no file subscription. Call the hook's `refresh()` after imperative file
+mutations when the UI needs a new listing.
+
+### `basic.useOutgoingShares()`
+
+Shares v2 is capability-gated and requires sign-in. `useOutgoingShares()` returns:
+
+```text
+{
+  data: OutgoingShareInfo[]
+  outgoingShares: OutgoingShareInfo[] // alias of data
+  isLoading: boolean
+  error: BasicError | null
+  refresh(): void
+  create(input: CreateOutgoingShareInput): Promise<OutgoingShareInfo>
+  get(id: string): Promise<OutgoingShareInfo>
+  cancel(id: string): Promise<OutgoingShareInfo>
+  revoke(id: string): Promise<OutgoingShareInfo>
+  getContactHandle(did: string): Promise<string | null>
+  manageUrl(): string
+}
+```
+
+`CreateOutgoingShareInput` has:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `repo` | `'default' \| { repoId: string }` | Origin repo |
+| recipient | Exactly one of `recipientHandle: string` or `recipientDid: string` | A handle is trimmed, lowercased, and resolved through `defaultPds`; a canonical DID skips handle resolution. |
+| `role` | `'viewer' \| 'editor'` | Collaborator role |
+| `scope` | `Array<{ table: string } \| { table: string; recordIds: string[] }>` | Whole-table clauses or static record sets |
+| `acceptBy` | `string` | Optional acceptance deadline passed to Shares v2 |
+| `display` | `{ shareName?: string; repoName?: string }` | Optional recipient-facing labels |
+
+```tsx
+// file: OutgoingShares.tsx
+import { basic } from './basic'
+
+export function OutgoingShares() {
+  const shares = basic.useOutgoingShares()
+
+  async function shareTodos() {
+    await shares.create({
+      repo: 'default',
+      recipientHandle: 'bob.basic.id',
+      role: 'editor',
+      scope: [{ table: 'todos' }],
+      display: { shareName: 'Project todos' },
+    })
+    shares.refresh()
+  }
+
+  return (
+    <section>
+      <button onClick={() => void shareTodos()}>Share todos</button>
+      <button onClick={() => location.assign(shares.manageUrl())}>Manage in Basic ID</button>
+      {shares.error && <p>{shares.error.code}</p>}
+      <ul>
+        {shares.outgoingShares.map((share) => (
+          <li key={share.id}>
+            {share.recipientDid}: {share.effectiveState}
+            {share.state === 'pending' && (
+              <button onClick={() => void shares.cancel(share.id).then(shares.refresh)}>Cancel</button>
+            )}
+            {share.state === 'active' && (
+              <button onClick={() => void shares.revoke(share.id).then(shares.refresh)}>Revoke</button>
+            )}
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}
+```
+
+`OutgoingShareInfo` exposes canonical `recipientDid`, `repoId`, `appId`, `role`, `scope`,
+`staticRecordCount`, `display`, `acceptBy`, `state: 'pending' | 'active' | 'ended'`,
+`effectiveState: 'pending' | 'active' | 'suspended' | 'ended'`, `effectiveStateReason`,
+`deliveryState`, and created, accepted, and ended timestamps/reasons. Revocation prevents future
+access but cannot retract data a recipient already downloaded.
+
+After a handle-based share is created successfully, the SDK stores a profile-local contact entry
+containing `{ did, handle }` in browser local storage. Use `getContactHandle(recipientDid)` to show
+the remembered handle; it returns `null` for DIDs that were shared directly or are not cached.
+
+`manageUrl()` returns the Basic ID `/shares` handoff. Invite acceptance and ordinary mount
+management belong there. `client.shares.leave()` is intentionally owner-only and throws
+`OWNER_CREDENTIAL_REQUIRED` without an explicit owner adapter.
+
+### `basic.useMounts()` and mounted data
+
+`useMounts({ repo? }?)` returns:
+
+```text
+{
+  data: MountInfo[]
+  mounts: MountInfo[] // alias of data
+  isLoading: boolean
+  error: BasicError | null
+  refresh(): void
+  open(mountId: string): Promise<MountHandle<S>>
+  manageUrl(): string
+}
+```
+
+The optional `repo` filter is `'default'` or `{ repoId }`. `open()` completes the share credential
+chain and opens a sync or REST mounted database. Open a mount before passing `{ mountId }` to
+`useDb`, `useCollection`, `useQuery`, or `useFiles`.
+
+Each `MountInfo` contains `id`, `invitationId`, `originOwnerDid`, `originShareId`, `appId`, `repoId`,
+`role`, `scope`, `state: 'active' | 'left'`,
+`originState: 'active' | 'suspended' | 'ended' | 'unavailable' | 'unknown'`,
+`originCheckedAt`, `createdAt`, and `leftAt`.
+
+`MountHandle<S>` is discriminated by `role`:
+
+- A viewer handle has `info`, `db`, and `files` with `list`, `get`, and `download`.
+- An editor handle adds file `update`, `delete`, and `restore`.
+- Collaborators never receive mounted-file `upload`, `uploadBlob`, content replacement, creation,
+  or `purge` methods.
+
+```tsx
+// file: IncomingMounts.tsx
+import { useState } from 'react'
+import type { MountHandle } from '@basictech/core'
+import { basic, schema } from './basic'
+
+export function IncomingMounts() {
+  const mounts = basic.useMounts()
+  const [opened, setOpened] = useState<MountHandle<typeof schema> | null>(null)
+
+  async function open(mountId: string) {
+    const handle = await mounts.open(mountId)
+    setOpened(handle)
+    const page = await handle.files.list({ prefix: '/shared' })
+    if (handle.role === 'editor' && page.data[0]) {
+      await handle.files.update(page.data[0].id, { name: 'Reviewed' })
+    }
+  }
+
+  return (
+    <section>
+      <button onClick={() => location.assign(mounts.manageUrl())}>Manage mounts</button>
+      <ul>
+        {mounts.mounts.map((mount) => (
+          <li key={mount.id}>
+            {mount.role} from {mount.originOwnerDid}
+            <button onClick={() => void open(mount.id)}>Open</button>
+          </li>
+        ))}
+      </ul>
+      {opened && <p>Opened {opened.info.id} as {opened.role}</p>}
+    </section>
+  )
+}
+```
+
+Once opened, records use the same collection/query surface:
+
+```tsx
+// file: MountedTodos.tsx
+import { basic } from './basic'
+
+export function MountedTodos({ mountId }: { mountId: string }) {
+  const result = basic.useQuery('todos', { sort: 'title' }, { source: { mountId } })
+  if (result.isLoading) return <p>Opening shared todos…</p>
+  if (result.error) return <p>{result.error.code}</p>
+  return <ul>{result.data.map((todo) => <li key={todo.id}>{todo.value?.title}</li>)}</ul>
+}
+```
+
+The record collection shape is the same for viewer and editor mounts; the server enforces role and
+scope on attempted record mutations. Mounted-file types are narrower at compile time as described
+above. Terminal ended mounts are removed from the open runtime and their local partition is
+deleted; transient origin outages are not treated as revocation.
+
+### `basic.useBasic()` and `basic.client`
+
+`useBasic()` combines the common state:
+
+```text
+UseAuthResult & {
+  client: BasicClient<S>
+  db: BasicDb<S>
+  accounts: UseAccountsResult
+  sync: UseSyncStatusResult
+  repos: Repo[]
+}
+```
+
+The auth fields (`isReady`, `isSignedIn`, `signIn`, and so on) are at the top level. `accounts` and
+`sync` are the complete corresponding hook results; `repos` is only the repo array, so use
+`useRepos()` for refresh/create/archive actions.
+
+```tsx
+// file: BasicSummary.tsx
+import { basic } from './basic'
+
+export function BasicSummary() {
+  const state = basic.useBasic()
+  return (
+    <p>
+      {state.isAnonymous ? 'anonymous' : state.handle};
+      {' '}{state.sync.pendingCount} pending;
+      {' '}{state.accounts.accounts.length} profiles;
+      {' '}{state.repos.length} repos;
+      {' '}{state.db.kind} mode
+    </p>
+  )
+}
+```
+
+There is no separate `useClient()` hook. The stable client is `basic.client`, and `useBasic()` also
+returns it. Use the client for imperative APIs that are not hook actions, including `settle`,
+`goOffline`, `goOnline`, account-wide owner operations, and lower-level `shares` methods. Provider
+normally owns `client.start()`/`stop()`.
+
+## Unbound hooks and `BasicProvider`
+
+Use the bound `createBasic` API for a fixed application schema. Use the generic exports when table
+names are dynamic, a schema is not known at compile time, or a client is composed outside the
+factory.
+
+`BasicProvider` accepts `children`, optional `renderWhileLoading`, and exactly one client source:
+
+- `{ client: BasicClient<S> }`, or
+- the complete `BrowserBasicConfig<S>` as props (with `client` absent).
+
+When config props are supplied, the Provider creates one browser client on its first render;
+subsequent prop changes do not recreate it. Creating the client explicitly is clearer when other
+code also needs it.
+
+```tsx
+// file: GenericProvider.tsx
+import {
+  BasicProvider,
+  createBasicClient,
+  useCollection,
+  useQuery,
+} from '@basictech/react'
+
+type Note = { body: string; pinned?: boolean }
+
+const client = createBasicClient({
+  clientId: 'did:web:dynamic.example',
+  redirectUri: 'https://dynamic.example/oauth/callback',
+})
+
+function Notes() {
+  const notes = useCollection<Note>('notes')
+  const result = useQuery<Note>('notes', { where: { pinned: true } })
+  return (
+    <section>
+      <button onClick={() => void notes.create({ body: 'Untitled' })}>Add note</button>
+      {result.data.map((note) => <p key={note.id}>{note.value?.body}</p>)}
+    </section>
+  )
+}
+
+export function GenericRoot() {
+  return <BasicProvider client={client}><Notes /></BasicProvider>
+}
+```
+
+The unbound exports mirror the bound hooks:
+
+| Export | Generic behavior |
+| --- | --- |
+| `useBasic<S>()` | Optional explicit schema generic; otherwise `BasicSchema` |
+| `useAuth()` | Same auth result |
+| `useAccounts()` | Same account result |
+| `useDb<S>(source?)` | Optional explicit schema generic; mount overload keeps mounted-file restrictions |
+| `useCollection<V>(name, { source? }?)` | Caller supplies a JSON object value type; name is a string |
+| `useQuery<V>(name, query?, { source? }?)` | Caller supplies a JSON object value type; name is a string |
+| `useSyncStatus(source?)`, `useSchemaStatus(source?)` | Same status results |
+| `useRepos()`, `useFiles()`, `useStorageInfo()` | Same repo/file results |
+| `useMounts()`, `useOutgoingShares()` | Same share results |
+
+Every unbound hook must run below `BasicProvider`; otherwise it throws `Basic hooks must be used
+within a <BasicProvider>`.
+
+## Error handling
+
+Import `BasicError`, `ProblemError`, and `OAuthError` from `@basictech/core`, not from the React
+package. `BasicError` has `code: string` and a message. `ProblemError` adds HTTP `status`, normalized
+Problem Details, and response metadata; `OAuthError` adds the OAuth `error`, optional description,
+and status.
+
+```ts
+// file: errors.ts
+import { BasicError, ProblemError } from '@basictech/core'
+import { basic } from './basic'
+
+export async function renameTodo(id: string) {
+  try {
+    await basic.client.db().collection('todos').patch(id, { title: 'Renamed' })
+  } catch (error) {
+    if (error instanceof ProblemError) {
+      console.error(error.code, error.status, error.problem.request_id)
+      return
+    }
+    if (error instanceof BasicError) {
+      console.error(error.code, error.message)
+      return
+    }
+    throw error
+  }
+}
+```
+
+Common application-facing codes include:
+
+| Code | Typical cause |
+| --- | --- |
+| `AUTHORIZATION_REQUIRED` | A signed-in token/session is required |
+| `UNKNOWN_SOURCE` | The repo is not in the catalog or the mount has not been listed/opened |
+| `RECORD_NOT_FOUND`, `RECORD_EXISTS`, `RECORD_NOT_DELETED` | Record lifecycle precondition failed |
+| `INVALID_PATCH`, `INVALID_RECORD_ID`, `INVALID_IDEMPOTENCY_KEY` | Invalid local mutation input |
+| `INVALID_QUERY_*`, `LOCAL_CURSOR_UNSUPPORTED` | Invalid query, limit/sort/filter, or a REST cursor used locally |
+| `WATCH_REQUIRES_SYNC_MODE`, `SYNC_MODE_REQUIRED` | A sync-only API was called in REST mode |
+| `SETTLE_TIMEOUT` | Pending sync work did not settle before the configured timeout |
+| `CAPABILITY_UNAVAILABLE` | The PDS does not advertise Files v2 |
+| `SHARES_UNSUPPORTED`, `SHARE_ENDED`, `SHARE_SCOPE_DENIED`, `SHARE_ROLE_DENIED` | Shares v2 unavailable or a mount/share lifecycle/permission denied the operation |
+| `OWNER_CREDENTIAL_REQUIRED` | An owner-only operation was called with normal app credentials |
+| `STALE_WRITE`, `SCHEMA_VALIDATION_FAILED` | Server rejected a write; REST errors arrive as `ProblemError`, while sync terminal failures appear in `rejected` |
+| `ACCESS_TOKEN_ADOPTION_TIMEOUT`, `invalid_grant` | Cross-tab token adoption failed or reauthentication is required |
+
+Data hooks (`useQuery`, `useFiles`, `useStorageInfo`, `useMounts`, and `useOutgoingShares`) use the
+same `{ data, isLoading, error }` lifecycle. Files/mounts/outgoing also expose `refresh()`. Disabled
+signed-out storage, mount, and outgoing-share hooks settle after client readiness with empty/null
+data rather than remaining loading. Non-Basic data-hook failures are wrapped as `UNKNOWN_ERROR`;
+query failures use `QUERY_FAILED` as the fallback code. `useAuth().error` reflects auth lifecycle
+errors; imperative methods reject and should be caught at the call site.
+
+## Sync and REST modes
+
+The database and query shapes are shared, but the guarantees differ:
+
+| | `mode: 'sync'` (default) | `mode: 'rest'` |
+| --- | --- | --- |
+| Reads | Local replica after bootstrap | Direct HTTP |
+| Mutations resolve | After the optimistic operation is durably enqueued | After the server response |
+| Offline writes | Persisted and replayed after reconnect | Not queued |
+| React updates | Local writes and incoming Sync/3 changes invalidate queries | Initial fetch and same-client collection mutation invalidation; no server subscription |
+| `watch()` | Supported for records/files | Throws `WATCH_REQUIRES_SYNC_MODE` |
+| Anonymous workspace | Enabled by default | Disabled |
+| Multi-account profiles | Supported; active profile is per tab | Not supported |
+| `settle()` | Waits for server confirmation | No-op |
+| Write concurrency | Sync/3 rebase/conflict policy | ETag/`If-Match`; stale writes surface as `ProblemError` |
+| Pagination cursor | Local queries do not accept cursors | Returns/accepts REST cursors |
+
+Sync mode persists the operation before publishing its optimistic view. `settle()` is the explicit
+barrier when a workflow requires server confirmation. Reconnect drains queued operations; retryable
+failures remain pending, terminal failures move to `rejected`, and stale operations are rebased up
+to the core limit before becoming conflicts/rejections. A conflict policy chooses automatic local
+or remote intent, or leaves the choice to the app.
+
+REST and sync/mount cursors are engine-specific; do not exchange them. REST does not silently
+rebase an ETag failure. See the
+[0.11 migration guide](https://github.com/basicdb/basic-server/blob/dev/docs/MIGRATING_TO_0.11.md)
+and the
+[`@basictech/core` README](https://github.com/basicdb/basic-server/blob/dev/packages/core/README.md)
+for the lower-level model.
+
+## Next.js, migration, and status
+
+- `@basictech/nextjs` is lockstep-versioned but **compile-only and functionally stale in 0.11**.
+  Its old cookie middleware is not a valid authentication boundary for this browser client. New
+  Client Components should import `@basictech/react` directly.
+- Migrating from 0.10 requires deliberate call-site changes; there is no compatibility layer. Read
+  [Migrating to Basic SDK 0.11](https://github.com/basicdb/basic-server/blob/dev/docs/MIGRATING_TO_0.11.md).
+- 0.11 is a beta API, published to npm under the `beta` dist-tag. Check the installed version
+  rather than assuming it matches the repository workspace.
+
+## License
+
+MIT