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

package/dist/index.d.ts

@@ -1,395 +1,1357 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import react from 'react';
-export { useLiveQuery as useQuery } from 'dexie-react-hooks';
+import React from 'react';
+import Dexie, { Table } from 'dexie';
 
+interface BasicStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+declare class LocalStorageAdapter implements BasicStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+declare const STORAGE_KEYS: {
+    readonly REFRESH_TOKEN: "basic_refresh_token";
+    readonly USER_INFO: "basic_user_info";
+    readonly AUTH_STATE: "basic_auth_state";
+    readonly REDIRECT_URI: "basic_redirect_uri";
+    readonly SERVER_URL: "basic_server_url";
+    readonly PDS_ENDPOINTS: "basic_pds_endpoints";
+    readonly LAST_CONNECT_REPORT: "basic_last_connect_report";
+    readonly DEBUG: "basic_debug";
+    readonly CODE_VERIFIER: "basic_code_verifier";
+};
+
+type Token = {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token: string;
+};
+type User = {
+    sub?: string;
+    name?: string;
+    email?: string;
+    picture?: string;
+};
 /**
- * Core DB types for Basic SDK
- * These interfaces are implemented by both SyncDB (Dexie-based) and RemoteDB (REST-based)
+ * High-level auth lifecycle state.
+ *
+ * - `bootstrapping` — SDK is initializing; not yet determined if a session exists.
+ * - `authenticated` — User has a valid access token and active session.
+ * - `recovering`    — A session likely exists (refresh token / cached user) but
+ *                     the SDK hasn't confirmed it yet (e.g. offline, mid-refresh).
+ * - `reauth_required` — The session is definitively invalid (revoked, expired
+ *                     refresh token, etc.). The user must sign in again.
+ *                     NOTE: `isSignedIn` remains `true` in this state so the UI
+ *                     can display user info while prompting re-authentication.
+ *                     Use `authStatus === 'reauth_required'` to distinguish
+ *                     this from a healthy signed-in state.
+ * - `signed_out`    — No session. User is not authenticated.
+ *
+ * TODO: revisit naming and ergonomics — consider adding a `needsReauth` or
+ * `shouldPromptSignIn` convenience getter so consumers don't need to inspect
+ * the raw status to decide between "sign in" vs "sign out" UI.
  */
+type AuthStatus = 'bootstrapping' | 'authenticated' | 'recovering' | 'reauth_required' | 'signed_out';
+type AuthResult = {
+    success: boolean;
+    error?: string;
+    code?: string;
+};
+type GetTokenOptions$1 = {
+    forceRefresh?: boolean;
+};
+type PdsEndpoints = {
+    pds_url: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+};
+type AuthManagerConfig = {
+    projectId: string | undefined;
+    scopes: string;
+    pdsUrl: string;
+    adminUrl: string;
+    debug: boolean;
+    /**
+     * Identifies which local user profile this manager belongs to (multi-user).
+     * Cross-tab events are scoped to it so a tab active on another profile
+     * ignores them. Defaults to '' (single-user / legacy profile).
+     */
+    instanceKey?: string;
+};
 /**
- * Collection interface for CRUD operations on a table
- * All write operations return the full object (not just the id)
+ * Framework-agnostic auth manager. Holds token state, handles OAuth flow,
+ * token refresh (with mutex), and user info fetching.
+ *
+ * React integration: pass a state-setter as `notify` so the component
+ * re-renders whenever auth state changes.
  */
-interface Collection<T extends {
-    id: string;
-} = Record<string, any> & {
-    id: string;
-}> {
+declare class AuthManager {
+    token: Token | null;
+    user: User | null;
+    isSignedIn: boolean;
+    isAuthReady: boolean;
+    authStatus: AuthStatus;
+    authErrorCode: string | null;
+    did: string | null;
+    /** Space-separated scopes granted in the current access token */
+    tokenScope: string | null;
+    /** Space-separated scopes originally requested in the auth config */
+    requestedScopes: string;
+    readonly config: AuthManagerConfig;
+    readonly storage: BasicStorage;
+    /** True only during a user-initiated OAuth code exchange (not session restore) */
+    private freshSignIn;
+    private notify;
+    private refreshPromise;
+    private codeExchangePromise;
+    private pendingRefresh;
+    private isOnline;
+    private channel;
+    private nextUserRecoveryAt;
+    private sessionCheckPromise;
+    private lastSessionCheckAt;
+    constructor(config: AuthManagerConfig, storage: BasicStorage, notify: () => void);
+    private get instanceKey();
+    private initCrossTabSync;
+    private broadcastTokenRefresh;
+    private broadcastSignIn;
+    private broadcastSignOut;
+    private broadcastSessionInvalidated;
+    /** Release resources (cross-tab channel). Used when switching users. */
+    destroy(): void;
     /**
-     * Add a new record to the collection
-     * @param data - The data to add (without id, which will be generated)
-     * @returns The created object with its generated id
+     * Bootstrap auth: handle OAuth callback (?code=), restore session
+     * from refresh token, or load cached user for offline mode.
      */
-    add(data: Omit<T, 'id'>): Promise<T>;
+    initialize(): Promise<void>;
     /**
-     * Put (upsert) a record - requires id
-     * @param data - The full object including id
-     * @returns The upserted object
+     * Get a valid access token string. Refreshes proactively (5s buffer)
+     * or on demand (forceRefresh). Mutex prevents concurrent refreshes.
      */
-    put(data: T): Promise<T>;
+    getToken(options?: GetTokenOptions$1): Promise<string>;
+    getSignInUrl(redirectUri?: string, endpoints?: PdsEndpoints): Promise<string>;
+    signIn(redirectUri?: string): Promise<void>;
+    signInWithHandle(handle: string): Promise<void>;
+    signInWithCode(code: string, state?: string): Promise<AuthResult>;
     /**
-     * Update an existing record by id
-     * @param id - The record id to update
-     * @param data - Partial data to merge
-     * @returns The updated object, or null if not found
+     * Sign out: revoke the session server-side (`POST /auth/logout`, best
+     * effort), then clear auth state and storage. Does NOT handle sync/DB
+     * cleanup — the client layer wraps this to add sync teardown.
      */
-    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>;
+    signOut(): Promise<void>;
     /**
-     * Delete a record by id
-     * @param id - The record id to delete
-     * @returns true if deleted, false if not found
+     * Best-effort server-side revocation of the current device/session and
+     * its refresh chain (Step 2 auth: logout is finally server-side).
+     * Never blocks or fails the local sign-out.
      */
-    delete(id: string): Promise<boolean>;
+    private revokeSessionOnServer;
+    reconcileSession(reason?: string, options?: {
+        forceRefresh?: boolean;
+        throttleMs?: number;
+    }): Promise<void>;
+    hasScope(scope: string): boolean;
     /**
-     * Get a single record by id
-     * @param id - The record id to fetch
-     * @returns The object or null if not found
+     * Returns scopes that were requested but not granted in the current token.
+     * Useful after login or when a 403 is returned.
      */
-    get(id: string): Promise<T | null>;
+    missingScopes(): string[];
     /**
-     * Get all records in the collection
-     * @returns Array of all objects
+     * Register online/offline and visibility handlers that retry pending
+     * refreshes and proactively refresh tokens when the app resumes from
+     * background (critical for PWAs and mobile browsers where timers are
+     * frozen while backgrounded).
+     * Returns a cleanup function for useEffect teardown.
      */
-    getAll(): Promise<T[]>;
+    setupNetworkListeners(): () => void;
+    private get adminHostname();
+    private defaultPdsEndpoints;
+    private getActivePdsEndpoints;
+    private reportConnection;
     /**
-     * Filter records using a predicate function
-     * @param fn - Filter function that returns true for matches
-     * @returns Array of matching objects
+     * After a new token is stored, decode JWT claims and fetch user info.
      */
-    filter(fn: (item: T) => boolean): Promise<T[]>;
+    private processNewToken;
+    private restoreCachedUser;
+    private fetchUser;
     /**
-     * Direct access to underlying storage (optional)
-     * For sync mode: Dexie table reference
-     * For remote mode: undefined
+     * Exchange an auth code or refresh token for an access token.
+     * Handles mutex (one in-flight refresh), token validation, and
+     * triggers processNewToken on success.
      */
-    ref?: any;
-}
-/**
- * BasicDB interface - factory for creating collections
- */
-interface BasicDB {
+    private exchangeToken;
+    private resetAuthState;
+    private clearStoredAuth;
+    private isNetworkError;
+    private getRefreshToken;
+    private syncRefreshTokenFromStorage;
+    private applyTokenClaims;
+    private broadcastSessionUpdate;
+    private handleUserFetchFailure;
+    private isCompatibleUser;
+    private recoverMissingUserProfile;
+    private isDefinitiveTokenErrorCode;
+    private isDefinitiveAuthFailure;
     /**
-     * Get a collection by name
-     * @param name - The table/collection name (must match schema)
-     * @returns A Collection instance for CRUD operations
+     * Centralised auth status setter. Derives `isSignedIn` and `isAuthReady`
+     * from the status so they stay consistent.
+     *
+     * `isSignedIn` is intentionally `true` during `reauth_required` so the
+     * UI layer can still display user info while prompting re-authentication.
+     * Consumers should check `authStatus` (or a future convenience getter)
+     * when they need to distinguish "healthy session" from "needs re-auth".
      */
-    collection<T extends {
-        id: string;
-    } = Record<string, any> & {
-        id: string;
-    }>(name: string): Collection<T>;
+    private updateAuthStatus;
+    private clearStoredSessionTokens;
+    private restoreStoredSession;
+    private handleExternalTokenRefresh;
+    private fetchCurrentSession;
+    private markReauthRequired;
 }
+
 /**
- * Database mode - determines which implementation is used
- * - 'sync': Uses Dexie + WebSocket for local-first sync (default)
- * - 'remote': Uses REST API calls directly to server
+ * Sync/2 wire protocol types — the client side of basic-server's
+ * `docs/SYNC_V2.md` contract (protocol version 1).
+ *
+ * WebSocket endpoint: `wss://<pds>/sync/`
+ * HTTP bootstrap:     `GET /account/:project_id/db/snapshot`
+ * HTTP pull:          `GET /account/:project_id/db/changes`
  */
-type DBMode = 'sync' | 'remote';
+declare const PROTOCOL_VERSION = 1;
+type OpType = 'put' | 'patch' | 'delete';
+/** An op as pushed by the client. `op_id` is the client-minted idempotency key. */
+interface OpEnvelope {
+    op_id: string;
+    type: OpType;
+    table: string;
+    record_id: string;
+    data?: Record<string, unknown> | null;
+    /** What the writer had seen when creating the op. Recorded, never enforced (v1). */
+    base_seq?: number | null;
+}
+/** An op as delivered by the server (`ops` message / `changes` endpoint). */
+interface LoggedOp extends OpEnvelope {
+    seq: number;
+    /** Server-stamped writer identity — never sent by the client. */
+    actor: string;
+    server_ts: string | number;
+}
+type SyncErrorCode = 'SCHEMA_VALIDATION_FAILED' | 'UNKNOWN_TABLE' | 'RECORD_NOT_FOUND' | 'PERMISSION_DENIED' | 'PAYLOAD_TOO_LARGE' | 'CHANNEL_FULL' | 'TOO_MANY_OPS' | 'RATE_LIMITED' | 'TRY_AGAIN' | 'SNAPSHOT_REQUIRED' | 'RESET_REQUIRED' | 'UNAUTHORIZED' | 'TOKEN_EXPIRED' | 'SHARE_REVOKED' | 'CONNECTION_REVOKED' | 'UNSUPPORTED_VERSION' | 'BAD_MESSAGE';
+/** Terminal = poison-op rule applies: park in rejected store, never re-push. */
+declare function isTerminalOpError(code: string | undefined, terminalFlag?: boolean): boolean;
+/** Errors that mean "discard channel state, re-bootstrap from snapshot, resubscribe". */
+declare function isRebootstrapError(code: string): boolean;
+/** Errors that mean the subscription is gone and must not be retried. */
+declare function isRevocationError(code: string): boolean;
+/** Errors that mean the token was rejected; reauth then reconnect. */
+declare function isAuthError(code: string): boolean;
+interface SyncLimits {
+    max_ops_per_push: number;
+    max_op_bytes: number;
+    replay_limit: number;
+}
+declare const DEFAULT_LIMITS: SyncLimits;
 /**
- * Auth error information passed to onAuthError callback
+ * First message on the socket. Sending only `{version, token}` opens a
+ * multiplexed session (auth-only welcome); streams are then bound with
+ * explicit `subscribe` messages. (The legacy single-subscription handshake
+ * with `cursor`/`share` on the hello is not used by this client.)
  */
-interface AuthError {
-    status: number;
-    message: string;
-    response?: any;
-    /** Classifies the error for UI display (e.g. "session expired" vs "forbidden") */
-    errorType: 'expired' | 'forbidden' | 'revoked' | 'network' | 'unknown';
-    /** True if this error occurred after a retry with a refreshed token */
-    afterRetry: boolean;
+interface HelloMsg {
+    type: 'hello';
+    version: number;
+    token: string;
+}
+interface SubscribeFilter {
+    table: string;
+    record_ids?: string[];
 }
+interface SubscribeMsg {
+    type: 'subscribe';
+    sub: string;
+    /** Last seq seen. Required — a null/absent cursor gets SNAPSHOT_REQUIRED. */
+    cursor: number;
+    /** Mount a share instead of the token's own channel. */
+    share?: string;
+    /** Narrow an own-channel subscription (partial sync). */
+    filter?: SubscribeFilter;
+}
+interface UnsubscribeMsg {
+    type: 'unsubscribe';
+    sub: string;
+}
+interface PushMsg {
+    type: 'push';
+    sub: string;
+    ops: OpEnvelope[];
+}
+interface PingMsg {
+    type: 'ping';
+    cursor?: number;
+}
+/** Refresh auth on a live socket without reconnecting. */
+interface TokenMsg {
+    type: 'token';
+    token: string;
+}
+type ClientMsg = HelloMsg | SubscribeMsg | UnsubscribeMsg | PushMsg | PingMsg | TokenMsg;
+/** Multiplexed handshake: auth-only welcome (`channel`/`cursor` absent). */
+interface WelcomeMsg {
+    type: 'welcome';
+    actor: string;
+    limits: SyncLimits;
+    channel?: string;
+    cursor?: number;
+    head?: number;
+    schema_version?: string | number | null;
+}
+interface SubscribedMsg {
+    type: 'subscribed';
+    sub: string;
+    channel: string;
+    cursor: number;
+    head: number;
+    schema_version: string | number | null;
+}
+interface UnsubscribedMsg {
+    type: 'unsubscribed';
+    sub: string;
+}
+interface OpsMsg {
+    type: 'ops';
+    sub: string;
+    /** May be empty — a filtered tail still advances `cursor`; always adopt it. */
+    ops: LoggedOp[];
+    cursor: number;
+}
+type PushResult = {
+    op_id: string;
+    seq: number;
+} | {
+    op_id: string;
+    error: SyncErrorCode;
+    terminal?: boolean;
+    message?: string;
+};
+interface PushedMsg {
+    type: 'pushed';
+    sub: string;
+    results: PushResult[];
+    /** Channel head after commit. Absent when nothing was committed. */
+    cursor?: number;
+}
+interface PongMsg {
+    type: 'pong';
+    head: number;
+    heads?: Record<string, number>;
+}
+interface TokenOkMsg {
+    type: 'token_ok';
+}
+interface ErrorMsg {
+    type: 'error';
+    code: SyncErrorCode;
+    message?: string;
+    terminal?: boolean;
+    /** Present when the error concerns one subscription on a multiplexed socket. */
+    sub?: string;
+}
+type ServerMsg = WelcomeMsg | SubscribedMsg | UnsubscribedMsg | OpsMsg | PushedMsg | PongMsg | TokenOkMsg | ErrorMsg;
+/** `GET /account/:project_id/db/snapshot` → `{ data: Snapshot }` */
+interface Snapshot {
+    channel: string;
+    /** table → record_id → field values (tombstones excluded, no `id` field). */
+    records: Record<string, Record<string, Record<string, unknown>>>;
+    /** Head seq the snapshot is consistent with. */
+    cursor: number;
+}
+/** `GET /account/:project_id/db/changes` → `{ data: ChangesPage }` */
+interface ChangesPage {
+    ops: LoggedOp[];
+    cursor: number;
+    more: boolean;
+}
+type SharePermission = 'read' | 'write';
+interface ShareSelector {
+    table: string;
+    record_ids?: string[] | null;
+}
+/** A share row as returned by `GET /account/shares`. */
+interface Share {
+    id: string;
+    account_id: string;
+    channel_id: string;
+    grantee: string;
+    selector: ShareSelector;
+    permission: SharePermission;
+    created_at: string;
+    expires_at: string | null;
+    revoked_at: string | null;
+}
+/** Client-minted op id (idempotency key). */
+declare function mintOpId(): string;
 /**
- * Custom error class for Remote DB API errors
- * Includes HTTP status code for reliable error handling
+ * Apply one op to a record's field data. Returns the new data, or `undefined`
+ * when the record does not exist (deleted / never created).
+ *
+ * - `put`: create or replace the whole record
+ * - `patch`: shallow-merge top-level fields; no effect on a missing record
+ * - `delete`: tombstone (idempotent)
  */
-declare class RemoteDBError extends Error {
-    status: number;
-    response?: any;
-    constructor(message: string, status: number, response?: any);
-}
+declare function applyOpToData(existing: Record<string, unknown> | undefined, op: OpEnvelope): Record<string, unknown> | undefined;
+
 /**
- * Options for getToken (e.g. force refresh after 401)
+ * RestClient — the REST v2 surface under `/account/:project_id/db/...`.
+ *
+ * Used by the sync engine for bootstrap (`snapshot`) and pull sync
+ * (`changes`), by the shares API, and by the REST-mode table API (CRUD on
+ * materialized state). All writes go through the same server-side sync
+ * engine as WebSocket pushes — one write path.
  */
-interface GetTokenOptions$1 {
-    /** When true, refresh the access token before returning (e.g. after server returned 401) */
+
+interface GetTokenOptions {
     forceRefresh?: boolean;
 }
-/**
- * Configuration for RemoteDB
- */
-interface RemoteDBConfig {
-    serverUrl: string;
+declare class RestError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly response?: unknown;
+    constructor(message: string, status: number, code?: string, response?: unknown);
+}
+declare class NotAuthenticatedError extends Error {
+    constructor(message?: string);
+}
+interface RestClientOptions {
+    /** PDS base URL, e.g. `https://pds.basic.id` */
+    baseUrl: string;
+    /** Project id (UUID or DID) — used in `/account/:project_id/...` paths. */
     projectId: string;
-    getToken: (options?: GetTokenOptions$1) => Promise<string>;
-    schema?: any;
-    /** Enable debug logging (default: false) */
-    debug?: boolean;
+    getToken: (options?: GetTokenOptions) => Promise<string>;
+    log?: (...args: unknown[]) => void;
+}
+/** A record as returned by REST reads: flattened `{ id, ...fields }`. */
+type RestRecord = {
+    id: string;
+} & Record<string, unknown>;
+declare class RestClient {
+    private readonly opts;
+    constructor(opts: RestClientOptions);
+    get projectId(): string;
+    /** `GET /account/:project_id/db` — tables, enforced schema version, channel head. */
+    getDbInfo(): Promise<{
+        tables: string[];
+        schema_version: string | number | null;
+        channel: {
+            id: string;
+            head_seq: number;
+            compacted_to_seq: number;
+        };
+    }>;
+    /** Bootstrap snapshot (SPEC §5). `share` bootstraps a mount; `table` filters. */
+    getSnapshot(options?: {
+        share?: string;
+        table?: string;
+    }): Promise<Snapshot>;
+    /** Pull ordered ops after a cursor — the non-WebSocket sync path. */
+    getChanges(options: {
+        cursor: number;
+        limit?: number;
+        share?: string;
+        table?: string;
+    }): Promise<ChangesPage>;
     /**
-     * Optional callback when authentication fails (401 error after retry)
-     * Use this to show login UI or redirect to sign-in
+     * Shares granted by and received by the caller. App tokens see only
+     * shares involving their own app (the ones they can mount).
      */
-    onAuthError?: (error: AuthError) => void;
+    listShares(): Promise<{
+        granted: Share[];
+        received: Share[];
+    }>;
+    list(table: string, query?: Record<string, string>): Promise<RestRecord[]>;
+    getRecord(table: string, id: string): Promise<RestRecord | null>;
+    /** `POST` — server mints the record id. */
+    createRecord(table: string, value: Record<string, unknown>): Promise<RestRecord>;
+    /** `PUT` — full replace. REST semantics: 404 for missing records. */
+    putRecord(table: string, id: string, value: Record<string, unknown>): Promise<RestRecord | null>;
+    /** `PATCH` — partial merge. 404 → null. */
+    patchRecord(table: string, id: string, value: Record<string, unknown>): Promise<RestRecord | null>;
+    /** `DELETE`. Returns false when the record did not exist. */
+    deleteRecord(table: string, id: string): Promise<boolean>;
+    private get dbPath();
+    /** Authenticated request; retries once with a force-refreshed token on 401. */
+    private request;
 }
 
 /**
- * RemoteDB - REST API based implementation of BasicDB
- * Creates RemoteCollection instances for each table
+ * SyncStore — persistent local state for one sync keyspace (an own channel or
+ * a mounted share), backed by plain Dexie/IndexedDB.
+ *
+ * Layout (one Dexie database per keyspace):
+ * - one **view** store per app table: `{ id, ...fields }` — what the app
+ *   reads (server state + pending ops rebased). `useQuery`/liveQuery reads
+ *   these stores directly.
+ * - `_server`: confirmed records only, keyed `[table+record_id]`.
+ * - `_pending`: queued local ops (survive restarts), insertion-ordered.
+ * - `_rejected`: terminally rejected ops (poison-op rule — never re-pushed).
+ * - `_meta`: cursor, channel id, limits, schema version.
+ *
+ * The app-visible view is always `serverState + pending applied in order`
+ * (client responsibility #6). Rebasing is done per affected record inside
+ * the same transaction as the change that triggered it.
  */
-declare class RemoteDB implements BasicDB {
-    private config;
-    private collections;
-    constructor(config: RemoteDBConfig);
+
+interface PendingRow {
+    /** Auto-increment — preserves creation order across restarts. */
+    idx?: number;
+    op_id: string;
+    op: OpEnvelope;
+    /** Set when the server acked the op (`pushed` seq) but the echo hasn't arrived yet. */
+    acked_seq?: number;
+}
+interface RejectedRow {
+    idx?: number;
+    op_id: string;
+    op: OpEnvelope;
+    error: SyncErrorCode | string;
+    message?: string;
+    rejected_at: number;
+}
+interface SyncStoreSchema {
+    version?: number;
+    tables: Record<string, {
+        fields: Record<string, {
+            indexed?: boolean;
+        }>;
+    }>;
+}
+declare class SyncStore {
+    readonly db: Dexie;
+    readonly name: string;
+    private readonly tableNames;
+    constructor(name: string, schema: SyncStoreSchema);
+    /** The Dexie view table for an app table (what liveQuery reads). */
+    view(table: string): Table<Record<string, unknown>, string>;
+    hasTable(table: string): boolean;
+    get tables(): string[];
+    private get server();
+    private get pending();
+    private get rejected();
+    private get meta();
+    private get allStores();
+    getCursor(): Promise<number | null>;
+    getChannel(): Promise<string | null>;
+    /**
+     * The account DID this keyspace's confirmed data belongs to. Absent for
+     * anonymous-era data (which may be merged into whichever account signs in).
+     */
+    getOwner(): Promise<string | null>;
+    setOwner(did: string): Promise<void>;
+    /**
+     * Clear everything (views, server state, pending, rejected, meta) without
+     * deleting the database — used when the keyspace changes owners.
+     */
+    wipeAll(): Promise<void>;
+    /** All pending ops in creation order (used to warm the in-memory queue). */
+    loadPending(): Promise<PendingRow[]>;
+    listRejected(): Promise<RejectedRow[]>;
+    clearRejected(): Promise<void>;
+    /** Record a server ack for a pending op (echo not yet seen). */
+    markAcked(opId: string, seq: number): Promise<void>;
     /**
-     * Get a collection by name
-     * Collections are cached for reuse
+     * Enqueue a local op and apply it optimistically to the view.
+     * Returns the resulting view record (null when the op deletes it).
      */
-    collection<T extends {
-        id: string;
-    } = Record<string, any> & {
-        id: string;
-    }>(name: string): Collection<T>;
+    addPending(op: OpEnvelope): Promise<Record<string, unknown> | null>;
+    /**
+     * Commit a batch of incoming server ops (already filtered/deduped by the
+     * engine): update `_server`, drop confirmed pending ops, advance the
+     * cursor, and rebase every affected view record — in one transaction.
+     */
+    commitIncoming(params: {
+        applyOps: LoggedOp[];
+        confirmedOpIds: string[];
+        cursor: number;
+    }): Promise<void>;
+    /** Persist a cursor advance with no ops (empty `ops` message / pushed cursor). */
+    setCursor(cursor: number): Promise<void>;
+    /**
+     * Terminal rejection: remove from pending, park in the rejected store,
+     * roll the view record back to server state + remaining pending ops.
+     */
+    rejectPending(opId: string, error: SyncErrorCode | string, message?: string): Promise<RejectedRow | null>;
+    /**
+     * Replace all server state from a snapshot (cold start or
+     * SNAPSHOT_REQUIRED/RESET_REQUIRED recovery). Pending ops survive and are
+     * re-applied on top of the fresh state.
+     */
+    replaceFromSnapshot(params: {
+        channel: string;
+        records: Record<string, Record<string, Record<string, unknown>>>;
+        cursor: number;
+    }): Promise<void>;
+    getViewRecord(table: string, id: string): Promise<Record<string, unknown> | null>;
+    getViewRecords(table: string): Promise<Record<string, unknown>[]>;
+    close(): void;
+    /** Delete the underlying IndexedDB database (sign-out / revoked mount). */
+    destroy(): Promise<void>;
+    private applyToServer;
+    /**
+     * Rebase one record: view = server data + pending ops for that record in
+     * creation order. Must run inside a transaction covering all stores.
+     */
+    private recomputeViewRecord;
 }
 
-/**
- * Error thrown when user is not authenticated
- */
-declare class NotAuthenticatedError extends Error {
-    constructor(message?: string);
+type SyncStatus = 'idle' | 'local' | 'connecting' | 'online' | 'offline' | 'auth_required' | 'revoked' | 'stopped';
+declare const OWN_SUB = "own";
+declare function shareSubKey(shareId: string): string;
+interface PendingEntry {
+    op: OpEnvelope;
+    sent: boolean;
+    ackedSeq?: number;
 }
-/**
- * RemoteCollection - REST API based implementation of the Collection interface
- * All operations make HTTP calls to the Basic API server
- */
-declare class RemoteCollection<T extends {
-    id: string;
-} = Record<string, any> & {
-    id: string;
-}> implements Collection<T> {
-    private tableName;
-    private config;
-    constructor(tableName: string, config: RemoteDBConfig);
-    private log;
+type SubStatus = 'initializing' | 'live' | 'revoked' | 'error';
+declare class BoundedSet {
+    private readonly cap;
+    private set;
+    private order;
+    constructor(cap?: number);
+    has(value: string): boolean;
+    add(value: string): void;
+    clear(): void;
+}
+interface SubscriptionState {
+    key: string;
+    shareId: string | null;
+    store: SyncStore;
+    cursor: number;
+    pending: PendingEntry[];
+    /** Bound on the current socket (subscribed ack received). */
+    active: boolean;
+    bootstrapped: boolean;
+    status: SubStatus;
+    revokedCode?: string;
+    appliedOpIds: BoundedSet;
+    /** Serializes ops/pushed/bootstrap handling per subscription. */
+    chain: Promise<void>;
+    schemaVersion: string | number | null;
+}
+interface SyncEngineEvents {
+    status: SyncStatus;
+    /** Records changed in a subscription's view (local write or server ops). */
+    change: {
+        sub: string;
+        tables: string[];
+    };
+    rejected: {
+        sub: string;
+        rejection: RejectedRow;
+    };
+    /** Sub-level protocol errors (share revoked, re-bootstrapping, ...). */
+    suberror: {
+        sub: string;
+        code: string;
+        message?: string;
+    };
+    /** Connection-level revocation — the app connection is gone. */
+    revoked: {
+        code: string;
+        message?: string;
+    };
+}
+interface EngineSchema {
+    project_id?: string;
+    version?: number;
+    tables: Record<string, {
+        fields: Record<string, {
+            type: string;
+            required?: boolean;
+            indexed?: boolean;
+        }>;
+    }>;
+}
+interface SyncEngineOptions {
+    projectId: string;
+    schema: EngineSchema;
+    /** e.g. `wss://pds.basic.id/sync/` */
+    wsUrl: string;
+    getToken: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string>;
+    /** Bootstrap fetch (REST snapshot). Injected so the engine stays transport-thin. */
+    fetchSnapshot: (options?: {
+        share?: string;
+    }) => Promise<Snapshot>;
+    /** Prefix for IndexedDB database names. Default `basic-sync`. */
+    dbNamePrefix?: string;
     /**
-     * Check if an error is a "not authenticated" error
+     * Keyspace segment appended to database names (multi-user: the local user
+     * id). `''`/unset = the legacy single-user keyspace.
      */
-    private isNotAuthenticatedError;
+    keyspaceId?: string;
     /**
-     * Helper to make authenticated API requests
-     * Automatically retries once on 401 (token expired) by refreshing the token
+     * The account DID the current session belongs to, consulted at bootstrap
+     * for the owner guard: a keyspace stamped with a different DID is wiped
+     * before bootstrapping (never merge one account's local data into
+     * another); an unstamped keyspace (anonymous-era data) keeps its pending
+     * ops — that is the anonymous → signed-in migration path.
      */
-    private request;
+    getOwnerDid?: () => string | null | Promise<string | null>;
+    /**
+     * App name included in `subscribe` messages. Production derives the channel
+     * from the token and ignores this; the sync-playground conformance server
+     * requires it. Leave unset against production.
+     */
+    appName?: string;
+    WebSocketImpl?: typeof WebSocket;
+    heartbeatMs?: number;
+    /** Validate writes locally before queueing (mirrors server). Default true. */
+    validateWrites?: boolean;
+    log?: (...args: unknown[]) => void;
+}
+declare class SyncEngine {
+    readonly projectId: string;
+    readonly schema: EngineSchema;
+    private readonly opts;
+    private readonly connection;
+    private readonly subs;
+    private limits;
+    private actor;
+    /** Own-sub store is open (local reads/writes work). */
+    private storesOpen;
+    /** A live connection is wanted (vs. local-only / paused). */
+    private connectIntended;
+    private openingLocal;
+    private revokedInfo;
+    private connectionStatus;
+    private _status;
+    private listeners;
+    private timers;
+    constructor(opts: SyncEngineOptions);
+    on<E extends keyof SyncEngineEvents>(event: E, fn: (data: SyncEngineEvents[E]) => void): () => void;
+    private emit;
+    get status(): SyncStatus;
+    get syncLimits(): SyncLimits;
+    get serverActor(): string | null;
+    getSubscription(key: string): SubscriptionState | undefined;
+    get own(): SubscriptionState | undefined;
+    get pendingCount(): number;
+    listRejected(subKey?: string): Promise<RejectedRow[]>;
+    clearRejected(subKey?: string): Promise<void>;
     /**
-     * Validate data against schema if available
+     * Open the own-channel keyspace for local reads/writes — no connection,
+     * no token needed. This is the anonymous / offline-cold-start entry point.
+     * Idempotent.
      */
-    private validateData;
+    openLocal(): Promise<void>;
     /**
-     * Get the base path for this collection
+     * Open the keyspace (if needed) and start syncing. Idempotent.
+     * Note: a `CONNECTION_REVOKED` latch is NOT cleared here — reconnecting a
+     * revoked app connection requires a fresh consent flow. Call
+     * {@link clearRevoked} (or rebind the engine) after re-authorization.
      */
-    private get basePath();
+    connect(): Promise<void>;
+    /** Clear the revocation latch (after the user re-authorized the app). */
+    clearRevoked(): void;
+    /** @deprecated alias of {@link connect} */
+    start(): Promise<void>;
     /**
-     * Add a new record to the collection
-     * The server generates the ID
-     * Requires authentication - throws NotAuthenticatedError if not signed in
+     * Disconnect but keep stores open: local reads/writes keep working and
+     * ops queue for the next connect. Used on reauth_required.
      */
-    add(data: Omit<T, 'id'>): Promise<T>;
+    pause(): void;
+    /** Close the socket and stores; local data is kept. */
+    stop(): void;
     /**
-     * Put (upsert) a record - requires id
-     * Requires authentication - throws NotAuthenticatedError if not signed in
+     * Stop and delete every local database for this project (sign-out).
+     * Best-effort discovery of mount keyspaces from previous sessions.
      */
-    put(data: T): Promise<T>;
+    destroyLocal(): Promise<void>;
     /**
-     * Update an existing record by id
-     * Requires authentication - throws NotAuthenticatedError if not signed in
+     * Mount a share: separate keyspace `(project, share)` with its own cursor
+     * and pending queue. Bootstraps + subscribes when the socket is online.
      */
-    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>;
+    mountShare(shareId: string): Promise<SubscriptionState>;
+    /** Unsubscribe a mount. Local cache is kept unless `purge` is set. */
+    unmountShare(shareId: string, options?: {
+        purge?: boolean;
+    }): Promise<void>;
     /**
-     * Delete a record by id
-     * Requires authentication - throws NotAuthenticatedError if not signed in
+     * Queue a local op, apply it optimistically, and push when online.
+     * Returns the resulting view record (null when deleted).
+     * Throws on local validation failure (fail fast — the server would
+     * terminally reject it anyway).
      */
-    delete(id: string): Promise<boolean>;
+    apply(subKey: string, partial: {
+        type: OpType;
+        table: string;
+        record_id: string;
+        data?: Record<string, unknown>;
+    }): Promise<Record<string, unknown> | null>;
+    private handleConnectionStatus;
+    private handleWelcome;
+    private handleMessage;
+    private handleSubscribed;
+    private handleError;
+    private openSub;
+    /** Bootstrap if needed, then bind the stream on the current socket. */
+    private activateSub;
+    /** Cold start = snapshot + tail; never log replay (§5). Pending survives. */
+    private bootstrapSub;
     /**
-     * Get a single record by id
-     * Returns null if not authenticated (graceful degradation for read operations)
+     * Responsibilities 3+4+5: ordered apply, cursor advance, dedupe/confirm.
+     * Runs inside the sub's serial chain.
      */
-    get(id: string): Promise<T | null>;
+    private processOps;
     /**
-     * Get all records in the collection
-     * Returns empty array if not authenticated (graceful degradation for read operations)
+     * Push verdicts (§6.5, §8, §9). Success acks are recorded but the op stays
+     * pending until its echo arrives in seq order — this preserves strict
+     * ordered apply even when `pushed` races ahead of intermediate remote ops.
+     * Terminal errors apply the poison-op rule; retryables back off.
      */
+    private processPushed;
+    /** Push unsent pending ops, chunked to `limits.max_ops_per_push`. */
+    private flush;
+    private get dbPrefix();
+    /** Base database name for this keyspace (multi-user: includes the user id). */
+    private get baseDbName();
+    private enqueue;
+    private timer;
+    private recomputeStatus;
+    private log;
+}
+
+/**
+ * The table API — the app-facing database surface, shaped around Sync/2 ops.
+ *
+ * Two implementations of the same interface:
+ * - `SyncDb`  — offline-first over a SyncEngine subscription (own channel or
+ *   a mounted share). Writes queue ops and apply optimistically; reads hit
+ *   the local Dexie view stores (which `useQuery`/liveQuery observe).
+ * - `RestDb`  — direct REST calls, no local persistence (for server-ish
+ *   contexts or apps that don't want a local replica).
+ */
+
+type BasicRecord = {
+    id: string;
+} & Record<string, unknown>;
+interface BasicTable<T extends BasicRecord = BasicRecord> {
+    /** Create a record. Sync mode mints the id locally; REST mode server-side. */
+    create(data: Omit<T, 'id'>): Promise<T>;
+    /** Create or replace the whole record (Sync/2 `put` op). */
+    put(id: string, data: Omit<T, 'id'>): Promise<T>;
+    /** Shallow-merge top-level fields (`patch` op). Returns null when missing. */
+    patch(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>;
+    /** Delete (tombstone). Idempotent. */
+    delete(id: string): Promise<void>;
+    get(id: string): Promise<T | null>;
     getAll(): Promise<T[]>;
+    find(predicate: (record: T) => boolean): Promise<T[]>;
+    /** Sync mode: the Dexie view table (for liveQuery / advanced queries). */
+    ref?: Table<T, string>;
+}
+interface BasicDb {
+    readonly kind: 'sync' | 'rest';
+    table<T extends BasicRecord = BasicRecord>(name: string): BasicTable<T>;
+}
+declare class SyncDb implements BasicDb {
+    private readonly engine;
+    private readonly subKey;
+    readonly kind: "sync";
+    private readonly tables;
+    constructor(engine: SyncEngine, subKey?: string);
+    table<T extends BasicRecord = BasicRecord>(name: string): BasicTable<T>;
+}
+declare class RestDb implements BasicDb {
+    private readonly rest;
+    private readonly schema?;
+    readonly kind: "rest";
+    private readonly tables;
+    constructor(rest: RestClient, schema?: {
+        tables?: Record<string, unknown>;
+    } | undefined);
+    table<T extends BasicRecord = BasicRecord>(name: string): BasicTable<T>;
+}
+
+/**
+ * User registry — multiple local users per project (anonymous or signed-in),
+ * one active at a time, switchable.
+ *
+ * - Profiles live in localStorage under `basic_users:{projectId}` and are
+ *   shared across tabs.
+ * - The *active* user id is per-tab (sessionStorage) so different tabs can be
+ *   on different users; it survives the OAuth redirect, so a sign-in resumes
+ *   on the profile that initiated it. Falls back to the most recently active
+ *   profile.
+ * - Each profile owns an isolated sync keyspace and a namespaced slice of
+ *   auth storage (refresh token, cached userinfo, PKCE state, ...) via
+ *   `PrefixedStorage`.
+ * - A pre-multi-user session (0.9.0-beta.0: bare `basic_refresh_token` +
+ *   `basic-sync:{projectId}` keyspace) is adopted as the first profile with
+ *   empty prefix/keyspace — no key or IndexedDB renames.
+ */
+
+type BasicUserKind = 'anon' | 'account';
+interface BasicUserProfile {
+    /** Local profile id (uuid). Stable across sign-in upgrades. */
+    id: string;
+    kind: BasicUserKind;
+    /** Account identity, set once signed in. */
+    did?: string | null;
+    handle?: string | null;
+    email?: string | null;
+    name?: string | null;
+    picture?: string | null;
     /**
-     * Filter records using a predicate function
-     * Note: This fetches all records and filters client-side
-     * Returns empty array if not authenticated (graceful degradation for read operations)
+     * Keyspace segment for sync data. `''` = the legacy pre-multi-user
+     * keyspace (`basic-sync:{projectId}`); otherwise db names append it.
      */
-    filter(fn: (item: T) => boolean): Promise<T[]>;
+    keyspace: string;
     /**
-     * ref is not available for remote collections
+     * Prefix for this profile's auth storage keys. `''` = legacy unprefixed
+     * keys; otherwise `u:{id}:`.
      */
-    ref: undefined;
+    storagePrefix: string;
+    createdAt: number;
+    lastActiveAt: number;
 }
-
-interface BasicStorage {
+/** Namespaces every key of an underlying BasicStorage adapter. */
+declare class PrefixedStorage implements BasicStorage {
+    private readonly inner;
+    readonly prefix: string;
+    constructor(inner: BasicStorage, prefix: string);
     get(key: string): Promise<string | null>;
     set(key: string, value: string): Promise<void>;
     remove(key: string): Promise<void>;
 }
-declare class LocalStorageAdapter implements BasicStorage {
-    get(key: string): Promise<string | null>;
-    set(key: string, value: string): Promise<void>;
-    remove(key: string): Promise<void>;
+declare class UserRegistry {
+    private readonly storage;
+    private readonly projectId;
+    constructor(storage: BasicStorage, projectId: string);
+    list(): Promise<BasicUserProfile[]>;
+    private save;
+    get(id: string): Promise<BasicUserProfile | null>;
+    createAnon(): Promise<BasicUserProfile>;
+    update(id: string, patch: Partial<Omit<BasicUserProfile, 'id' | 'keyspace' | 'storagePrefix'>>): Promise<BasicUserProfile | null>;
+    remove(id: string): Promise<void>;
+    /** The profile (if any) already bound to an account DID. */
+    findByDid(did: string): Promise<BasicUserProfile | null>;
+    private getActiveIdRaw;
+    setActiveId(id: string): void;
+    private clearActiveId;
+    /**
+     * Resolve the active profile for this tab: sessionStorage choice if it
+     * still exists, else the most recently active profile, else null.
+     */
+    resolveActive(): Promise<BasicUserProfile | null>;
+    touch(id: string): Promise<void>;
+    /**
+     * Adopt a pre-multi-user session as the first profile. Idempotent: runs
+     * only when the registry is empty and a bare refresh token exists. The
+     * adopted profile keeps the unprefixed storage keys and the legacy
+     * keyspace name, so nothing needs to move.
+     */
+    adoptLegacySession(): Promise<BasicUserProfile | null>;
 }
-declare const STORAGE_KEYS: {
-    readonly REFRESH_TOKEN: "basic_refresh_token";
-    readonly USER_INFO: "basic_user_info";
-    readonly AUTH_STATE: "basic_auth_state";
-    readonly REDIRECT_URI: "basic_redirect_uri";
-    readonly SERVER_URL: "basic_server_url";
-    readonly PDS_ENDPOINTS: "basic_pds_endpoints";
-    readonly LAST_CONNECT_REPORT: "basic_last_connect_report";
-    readonly DEBUG: "basic_debug";
-    readonly CODE_VERIFIER: "basic_code_verifier";
-};
 
-type User = {
-    sub?: string;
-    name?: string;
-    email?: string;
-    picture?: string;
-};
 /**
- * High-level auth lifecycle state.
+ * BasicClient — the framework-agnostic SDK core. Owns, per active user:
+ * - AuthManager (OAuth/PKCE, tokens, cross-tab session; storage namespaced
+ *   per local user profile)
+ * - SyncEngine  (Sync/2 client on the profile's own keyspace)
+ * - RestClient  (REST v2: snapshot/changes bootstrap, shares, CRUD)
  *
- * - `bootstrapping` — SDK is initializing; not yet determined if a session exists.
- * - `authenticated` — User has a valid access token and active session.
- * - `recovering`    — A session likely exists (refresh token / cached user) but
- *                     the SDK hasn't confirmed it yet (e.g. offline, mid-refresh).
- * - `reauth_required` — The session is definitively invalid (revoked, expired
- *                     refresh token, etc.). The user must sign in again.
- *                     NOTE: `isSignedIn` remains `true` in this state so the UI
- *                     can display user info while prompting re-authentication.
- *                     Use `authStatus === 'reauth_required'` to distinguish
- *                     this from a healthy signed-in state.
- * - `signed_out`    — No session. User is not authenticated.
+ * plus the multi-user registry: several local users (anonymous or signed-in)
+ * exist side by side, one active at a time per tab, switchable.
  *
- * TODO: revisit naming and ergonomics — consider adding a `needsReauth` or
- * `shouldPromptSignIn` convenience getter so consumers don't need to inspect
- * the raw status to decide between "sign in" vs "sign out" UI.
+ * Local-first rules:
+ * - The local keyspace opens with no token and no network (anonymous mode is
+ *   on by default; offline cold start works).
+ * - Anonymous writes are pending ops; sign-in upgrades the profile in place
+ *   and the normal bootstrap+flush merges them into the account.
+ * - `reauth_required` pauses the connection but keeps local reads/writes.
+ * - Sign-out wipes the profile's local data and falls through to the next
+ *   (or a fresh anonymous) user. No page reloads.
  */
-type AuthStatus = 'bootstrapping' | 'authenticated' | 'recovering' | 'reauth_required' | 'signed_out';
-type AuthResult = {
-    success: boolean;
-    error?: string;
-    code?: string;
-};
-type GetTokenOptions = {
-    forceRefresh?: boolean;
-};
 
-declare enum DBStatus {
-    LOADING = "LOADING",
-    OFFLINE = "OFFLINE",
-    CONNECTING = "CONNECTING",
-    ONLINE = "ONLINE",
-    SYNCING = "SYNCING",
-    ERROR = "ERROR",
-    /** Sync-layer error with automatic retry (maps from dexie-syncable status 4). */
-    ERROR_WILL_RETRY = "ERROR_WILL_RETRY",
-    /**
-     * Auth-driven status: set by the provider when `authStatus` transitions to
-     * `reauth_required`, causing sync to disconnect. Unlike the other statuses
-     * this is NOT mapped from a dexie-syncable status code — it is set
-     * programmatically by `BasicProvider` to signal that the token is
-     * definitively invalid and the user must re-authenticate before sync can
-     * resume.
-     */
-    ERROR_TOKEN_EXPIRED = "ERROR_TOKEN_EXPIRED"
-}
-/** Snapshot of local schema vs server (for dev toolbar and debugging). */
-type BasicSchemaDevInfo = {
+type BasicMode = 'sync' | 'rest';
+interface BasicAuthConfig {
+    scopes?: string | string[];
+    /** PDS URL for auth, data, and sync (default https://pds.basic.id) */
+    pds_url?: string;
+    /** Admin server URL for connect reporting + schema status (default https://api.basic.tech) */
+    admin_url?: string;
+    /** Sync WebSocket URL. Default: pds_url with ws(s) scheme + `/sync/`. */
+    sync_url?: string;
+}
+interface BasicClientConfig {
+    /** The Basic schema document (`{ project_id, version, tables }`). */
+    schema?: Record<string, unknown> & {
+        project_id?: string;
+        version?: number;
+        tables?: Record<string, unknown>;
+    };
+    /** Project id override; normally taken from `schema.project_id`. */
+    project_id?: string;
+    auth?: BasicAuthConfig;
+    storage?: BasicStorage;
+    debug?: boolean;
+    /** 'sync' (offline-first local replica, default) or 'rest' (direct API). */
+    mode?: BasicMode;
+    /**
+     * Anonymous/local-first usage (sync mode only, default true): the local db
+     * works without a session; data merges into the account on sign-in.
+     */
+    anonymous?: boolean;
+    /** Node/testing: pass the `ws` constructor. */
+    WebSocketImpl?: typeof WebSocket;
+}
+/** Local schema vs server status (dev toolbar and debugging). */
+interface BasicSchemaDevInfo {
     projectId: string | null;
     localVersion: number | undefined;
     status: string;
     valid: boolean;
     lastCheckedAt: number;
     error?: string;
-};
-/**
- * Context type for useBasic hook
- */
-type BasicContextType = {
+}
+interface BasicClientSnapshot {
+    /** Auth bootstrap finished and (in sync mode) the local db is decided. */
     isReady: boolean;
     isSignedIn: boolean;
     authStatus: AuthStatus;
     authErrorCode: string | null;
     user: User | null;
     did: string | null;
+    /** Space-separated scopes granted in the current access token. */
     scope: string | null;
-    hasScope: (scope: string) => boolean;
-    missingScopes: () => string[];
-    signIn: () => Promise<void>;
-    signInWithHandle: (handle: string) => Promise<void>;
-    signOut: () => Promise<void>;
-    signInWithCode: (code: string, state?: string) => Promise<AuthResult>;
-    getToken: (options?: GetTokenOptions) => Promise<string>;
-    getSignInUrl: (redirectUri?: string) => Promise<string>;
-    db: BasicDB;
-    dbStatus: DBStatus;
-    dbMode: DBMode;
-    /** Local schema vs server status; null if no schema on the provider. */
+    syncStatus: SyncStatus;
+    pendingCount: number;
+    /** True when the schema allows sync (valid + published + matching server). */
+    syncEnabled: boolean;
     devInfo: BasicSchemaDevInfo | null;
-    /** Re-run remote schema check (dev toolbar). */
-    refreshSchemaStatus: () => Promise<void>;
-    isAuthReady: boolean;
-    signin: () => Promise<void>;
-    signout: () => Promise<void>;
-    signinWithCode: (code: string, state?: string) => Promise<AuthResult>;
-    getSignInLink: (redirectUri?: string) => Promise<string>;
-};
-declare function useBasic(): BasicContextType;
-
-type AuthConfig = {
-    scopes?: string | string[];
-    /** @deprecated Use pds_url instead */
-    server_url?: string;
-    /** PDS URL for auth and data (default: https://pds.basic.id) */
-    pds_url?: string;
-    /** Admin server URL for connect reporting (default: https://api.basic.tech) */
-    admin_url?: string;
-    ws_url?: string;
-};
-type BasicProviderProps = {
-    children: react.ReactNode;
+    mode: BasicMode;
+    /** All local user profiles (anonymous and signed-in). */
+    users: BasicUserProfile[];
+    /** The profile active in this tab. */
+    activeUser: BasicUserProfile | null;
+    /** Active profile has no account yet (local-only workspace). */
+    isAnonymous: boolean;
+}
+interface ShareMountHandle {
+    shareId: string;
+    db: BasicDb;
+}
+declare class BasicClient {
+    readonly rest: RestClient;
+    readonly mode: BasicMode;
+    readonly config: BasicClientConfig;
+    readonly projectId: string | undefined;
+    readonly users: UserRegistry | null;
+    private readonly rawStorage;
+    private readonly restDb;
+    private readonly debug;
+    private readonly anonymousEnabled;
+    private readonly authConfig;
+    private readonly syncUrl;
+    private binding;
+    private usersCache;
+    private devInfo;
+    private syncEnabled;
+    private schemaChecked;
+    private started;
+    private signOutInProgress;
+    /** Serializes profile transitions (switch, dispose, sign-out fallthrough). */
+    private profileOps;
+    private mounts;
+    private listeners;
+    private snapshot;
+    constructor(config: BasicClientConfig);
+    get auth(): AuthManager;
+    get engine(): SyncEngine | null;
+    /** The database handle for the active user. Identity changes on switch. */
+    get db(): BasicDb;
+    get activeUser(): BasicUserProfile | null;
+    /** Bootstrap: version migrations, profile resolution, schema check, auth init. */
+    start(): Promise<void>;
+    /**
+     * Sign out the active user: server-side revoke, wipe the profile's local
+     * data, drop the profile, and fall through to the next (or a fresh
+     * anonymous) user.
+     */
+    signOut(): Promise<void>;
+    /** Switch this tab to another local user. */
+    switchUser(id: string): Promise<void>;
+    /** Create a fresh anonymous user and switch to it. */
+    addUser(): Promise<BasicUserProfile>;
+    /**
+     * Remove a local user: best-effort server-side revoke, wipe its keyspace
+     * and auth storage, drop the profile. Removing the active user signs out.
+     */
+    removeUser(id: string): Promise<void>;
+    /** Stop connections and listeners; local data is kept. */
+    stop(): void;
+    /** Re-run the remote schema status check (dev toolbar). */
+    refreshSchemaStatus(): Promise<void>;
+    listRejected(): Promise<RejectedRow[]>;
+    clearRejected(): Promise<void>;
+    /** Shares granted by / received by this user for this app. */
+    listShares(): Promise<{
+        granted: Share[];
+        received: Share[];
+    }>;
+    /** Mount a share: separate local keyspace + subscription. */
+    mountShare(shareId: string): Promise<ShareMountHandle>;
+    unmountShare(shareId: string, options?: {
+        purge?: boolean;
+    }): Promise<void>;
+    getMountedShare(shareId: string): ShareMountHandle | undefined;
+    subscribe: (listener: () => void) => (() => void);
+    getSnapshot: () => BasicClientSnapshot;
+    private createBinding;
     /**
-     * @deprecated Project ID is now extracted from schema.project_id.
-     * This prop is kept for backward compatibility but can be omitted.
+     * Bind and boot a profile. Publishes the new binding first so React
+     * subscriptions re-attach to the new db, then tears the old binding down
+     * on the next tick (avoids in-flight live queries hitting a closed store).
      */
+    private activateProfile;
+    private bindingMatches;
+    /** After sign-out/disposal: resume on the next profile or a fresh anon one. */
+    private activateNextProfileLocked;
+    /** Wipe a (non-active) profile's local footprint: keyspace dbs + auth keys. */
+    private disposeProfileData;
+    private deleteKeyspaceDatabases;
+    /** Previous auth status, for transition detection (revoked-latch clearing). */
+    private lastAuthStatus;
+    private handleAuthChange;
+    /**
+     * Drive the engine from auth + schema state:
+     * - local keyspace opens with no token (anonymous mode / offline cold start)
+     * - connect when a session exists (recovering counts — the connection
+     *   retries token acquisition itself)
+     * - reauth_required pauses the connection, keeps local data usable
+     */
+    private syncLifecycle;
+    /**
+     * After sign-in: bind the account identity to the active profile
+     * (anonymous → account upgrade) and dedupe against an existing profile
+     * for the same DID.
+     */
+    private maybeUpgradeProfile;
+    private refreshUsers;
+    private queueProfileOp;
+    private checkSchema;
+    private buildSnapshot;
+    private publish;
+}
+declare function createBasicClient(config: BasicClientConfig): BasicClient;
+
+interface BasicProviderProps {
+    children: React.ReactNode;
+    /** The Basic schema object containing project_id and table definitions. */
+    schema?: Record<string, unknown>;
+    /** Project id override; normally taken from `schema.project_id`. */
     project_id?: string;
-    /** The Basic schema object containing project_id and table definitions */
-    schema?: any;
-    debug?: boolean;
+    auth?: BasicAuthConfig;
     storage?: BasicStorage;
-    auth?: AuthConfig;
+    debug?: boolean;
+    /**
+     * - 'sync' (default): offline-first local replica synced over Sync/2
+     * - 'rest': direct REST calls, no local persistence
+     */
+    mode?: BasicMode;
     /**
-     * Database mode - determines which implementation is used
-     * - 'sync': Uses Dexie + WebSocket for local-first sync (default)
-     * - 'remote': Uses REST API calls directly to server
+     * Anonymous/local-first usage (sync mode only, default true): the db works
+     * without a session and local data merges into the account on sign-in.
+     * Set false to require sign-in before any local data exists.
      */
-    dbMode?: DBMode;
-    /** Show floating dev toolbar (localhost, NODE_ENV=development, or debug=true). */
+    anonymous?: boolean;
+    /** Show the floating dev toolbar (localhost / NODE_ENV=development / debug). */
     devToolbar?: boolean;
-};
-declare function BasicProvider({ children, project_id: project_id_prop, schema, debug, storage, auth, dbMode, devToolbar, }: BasicProviderProps): react_jsx_runtime.JSX.Element;
+    /**
+     * Render children before auth/db are ready (default false: children render
+     * once the client finished bootstrapping, like previous versions).
+     */
+    renderWhileLoading?: boolean;
+}
+declare function BasicProvider({ children, schema, project_id, auth, storage, debug, mode, anonymous, devToolbar, renderWhileLoading, }: BasicProviderProps): React.JSX.Element;
 
-type BasicDevToolbarProps = {
-    /** When false, toolbar does not render. Defaults to true when used standalone. */
-    enabled?: boolean;
-    /** Same as BasicProvider `debug` — when true, toolbar shows even off localhost. */
-    debug?: boolean;
-};
 /**
- * Floating dev-only toolbar: auth, DB/sync, and schema status. Requires `BasicProvider` with `debug` or localhost / NODE_ENV=development for visibility unless `enabled` is forced.
+ * Reactive live queries against the local database (sync mode), built on
+ * dexie-react-hooks' `useLiveQuery`. Any read through `db.table(...)` (or
+ * its `ref` Dexie table) is observable.
+ *
+ * ```tsx
+ * const todos = useQuery(() => db.table('todos').getAll())
+ * ```
+ *
+ * User-aware: the active user's id is appended to `deps` automatically, so
+ * queries re-subscribe against the new user's database on `switchUser` /
+ * sign-in / sign-out — provided the query reads `db` from the current render
+ * (e.g. from `useBasic()`/`useDb()`). For closures created outside render,
+ * pass `[db]` in deps explicitly.
  */
-declare function BasicDevToolbar({ enabled, debug }: BasicDevToolbarProps): react_jsx_runtime.JSX.Element | null;
+declare function useQuery<T>(querier: () => T | Promise<T | undefined> | undefined, deps?: unknown[]): T | undefined;
+/** The BasicClient instance from the nearest provider. */
+declare function useBasicClient(): BasicClient;
+interface UseAuthResult {
+    /** Auth bootstrap finished (a session may or may not exist). */
+    isReady: boolean;
+    isSignedIn: boolean;
+    /** Active user is a local-only (anonymous) workspace with no account. */
+    isAnonymous: boolean;
+    status: AuthStatus;
+    errorCode: string | null;
+    user: User | null;
+    did: string | null;
+    /** Space-separated scopes granted in the current access token. */
+    scope: string | null;
+    hasScope: (scope: string) => boolean;
+    missingScopes: () => string[];
+    signIn: (redirectUri?: string) => Promise<void>;
+    signInWithHandle: (handle: string) => Promise<void>;
+    signInWithCode: (code: string, state?: string) => Promise<AuthResult>;
+    signOut: () => Promise<void>;
+    getToken: (options?: GetTokenOptions$1) => Promise<string>;
+    getSignInUrl: (redirectUri?: string) => Promise<string>;
+}
+/** Auth state + actions. */
+declare function useAuth(): UseAuthResult;
+/** The database handle (own channel). Offline-first in sync mode. */
+declare function useDb(): BasicDb;
+interface UseSyncStatusResult {
+    /** Engine status: idle | connecting | online | offline | auth_required | revoked | stopped */
+    status: SyncStatus;
+    /** True when the schema is valid + published and sync can run. */
+    enabled: boolean;
+    /** Locally queued ops not yet confirmed by the server. */
+    pendingCount: number;
+    /** Terminally rejected ops (poison-op rule — never re-pushed). */
+    listRejected: () => Promise<RejectedRow[]>;
+    clearRejected: () => Promise<void>;
+}
+/** Sync engine state: connection status, pending queue depth, rejected ops. */
+declare function useSyncStatus(): UseSyncStatusResult;
+interface UseSharesResult {
+    /** Shares this user granted to others (for this app). */
+    granted: Share[];
+    /** Shares others granted to this user (mountable). */
+    received: Share[];
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+/** List shares granted by / received by the signed-in user for this app. */
+declare function useShares(): UseSharesResult;
+interface UseShareResult {
+    /** Table API over the mounted share's keyspace; null until mounted. */
+    db: BasicDb | null;
+    status: 'mounting' | 'mounted' | 'error' | 'revoked';
+    error: Error | null;
+}
+/**
+ * Mount a share (data another user granted to you) and get a db handle for
+ * it. The mount lives in its own local keyspace with its own cursor and
+ * pending queue — never merged with your own data.
+ */
+declare function useShare(shareId: string | null | undefined): UseShareResult;
+interface UseUsersResult {
+    /** All local user profiles (anonymous and signed-in), shared across tabs. */
+    users: BasicUserProfile[];
+    /** The profile active in this tab. */
+    activeUser: BasicUserProfile | null;
+    isAnonymous: boolean;
+    /** Switch this tab to another local user. */
+    switchUser: (id: string) => Promise<void>;
+    /** Create a fresh anonymous user and switch to it. */
+    addUser: () => Promise<BasicUserProfile>;
+    /** Remove a local user (wipes its local data; active user = sign out). */
+    removeUser: (id: string) => Promise<void>;
+}
+/** Multiple local users (anonymous or signed-in) with per-tab switching. */
+declare function useUsers(): UseUsersResult;
+interface UseBasicResult extends UseAuthResult {
+    db: BasicDb;
+    sync: UseSyncStatusResult;
+    /** All local user profiles. */
+    users: BasicUserProfile[];
+    /** The profile active in this tab. */
+    activeUser: BasicUserProfile | null;
+    /** Local schema vs server status; null if no schema on the provider. */
+    devInfo: BasicClientSnapshot['devInfo'];
+    refreshSchemaStatus: () => Promise<void>;
+    client: BasicClient;
+}
+/** Umbrella hook: auth + db + sync status + users. */
+declare function useBasic(): UseBasicResult;
+
+/**
+ * SyncConnection — one multiplexed WebSocket to `wss://<pds>/sync/`
+ * (SYNC_V2.md §6.9: one socket, many streams).
+ *
+ * Owns the transport only: hello handshake, heartbeat ping, exponential
+ * backoff reconnect, and token refresh on auth rejection. Everything above
+ * the socket (subscriptions, cursors, pending queues) belongs to SyncEngine,
+ * which receives every parsed server message via `onMessage`.
+ */
+
+type ConnectionStatus = 'idle' | 'connecting' | 'online' | 'offline' | 'auth_failed' | 'stopped';
+interface SyncConnectionOptions {
+    /** e.g. `wss://pds.basic.id/sync/` */
+    wsUrl: string;
+    getToken: (options?: {
+        forceRefresh?: boolean;
+    }) => Promise<string>;
+    /** Pass the `ws` constructor in Node; defaults to global WebSocket. */
+    WebSocketImpl?: typeof WebSocket;
+    /** Heartbeat interval (default 30s per spec). */
+    heartbeatMs?: number;
+    onWelcome: (msg: WelcomeMsg) => void;
+    onMessage: (msg: ServerMsg) => void;
+    onStatus: (status: ConnectionStatus) => void;
+    log?: (...args: unknown[]) => void;
+}
+declare class SyncConnection {
+    private readonly opts;
+    private readonly WS;
+    private readonly heartbeatMs;
+    private ws;
+    private _status;
+    private stopped;
+    private reconnectDelay;
+    private timers;
+    private heartbeatTimer;
+    /** One forced-refresh reconnect attempt per auth rejection. */
+    private authRetryUsed;
+    private removeOnlineListener;
+    constructor(opts: SyncConnectionOptions);
+    get status(): ConnectionStatus;
+    get isOnline(): boolean;
+    start(): void;
+    stop(): void;
+    /** Send a message; returns false when the socket is not open. */
+    send(msg: ClientMsg): boolean;
+    /** Refresh auth on the live socket (no reconnect). */
+    sendToken(): Promise<void>;
+    /**
+     * The server rejected our token (`UNAUTHORIZED` / `TOKEN_EXPIRED` + close).
+     * Retry once with a force-refreshed token; give up (status `auth_failed`)
+     * when the refresh itself fails or a fresh token is rejected again.
+     */
+    handleAuthRejection(): void;
+    private open;
+    private handleMessage;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private listenForNetwork;
+    private clearTimers;
+    private setStatus;
+    private log;
+}
 
 type ResolvedDid = {
     did: string;
@@ -418,4 +1380,15 @@ declare function resolveDid(did: string): Promise<ResolvedDid>;
  */
 declare function resolveHandle(handle: string): Promise<ResolvedDid>;
 
-export { type AuthConfig, type AuthError, type AuthResult, type BasicContextType, type BasicDB, BasicDevToolbar, type BasicDevToolbarProps, BasicProvider, type BasicProviderProps, type BasicSchemaDevInfo, type BasicStorage, type Collection, type DBMode, DBStatus, type GetTokenOptions$1 as GetTokenOptions, LocalStorageAdapter, NotAuthenticatedError, RemoteCollection, RemoteDB, type RemoteDBConfig, RemoteDBError, type ResolvedDid, STORAGE_KEYS, resolveDid, resolveDidWebUrl, resolveHandle, useBasic };
+type BasicDevToolbarProps = {
+    /** When false, toolbar does not render. Defaults to true when used standalone. */
+    enabled?: boolean;
+    /** Same as BasicProvider `debug` — when true, toolbar shows even off localhost. */
+    debug?: boolean;
+};
+/**
+ * Floating dev-only toolbar: auth, DB/sync, and schema status. Requires `BasicProvider` with `debug` or localhost / NODE_ENV=development for visibility unless `enabled` is forced.
+ */
+declare function BasicDevToolbar({ enabled, debug }: BasicDevToolbarProps): React.JSX.Element | null;
+
+export { AuthManager, type AuthResult, type AuthStatus, type BasicAuthConfig, BasicClient, type BasicClientConfig, type BasicClientSnapshot, type BasicDb, BasicDevToolbar, type BasicDevToolbarProps, type BasicMode, BasicProvider, type BasicProviderProps, type BasicRecord, type BasicSchemaDevInfo, type BasicStorage, type BasicTable, type BasicUserKind, type BasicUserProfile, type ChangesPage, type ConnectionStatus, DEFAULT_LIMITS, type GetTokenOptions$1 as GetTokenOptions, LocalStorageAdapter, type LoggedOp, NotAuthenticatedError, OWN_SUB, type OpEnvelope, type OpType, PROTOCOL_VERSION, type PdsEndpoints, type PendingRow, PrefixedStorage, type PushResult, type RejectedRow, type ResolvedDid, RestClient, type RestClientOptions, RestDb, RestError, type RestRecord, STORAGE_KEYS, type Share, type ShareMountHandle, type SharePermission, type ShareSelector, type Snapshot, type SubscriptionState, SyncConnection, SyncDb, SyncEngine, type SyncEngineEvents, type SyncEngineOptions, type SyncErrorCode, type SyncLimits, type SyncStatus, SyncStore, type SyncStoreSchema, type Token, type UseAuthResult, type UseBasicResult, type UseShareResult, type UseSharesResult, type UseSyncStatusResult, type UseUsersResult, type User, UserRegistry, applyOpToData, createBasicClient, isAuthError, isRebootstrapError, isRevocationError, isTerminalOpError, mintOpId, resolveDid, resolveDidWebUrl, resolveHandle, shareSubKey, useAuth, useBasic, useBasicClient, useDb, useQuery, useShare, useShares, useSyncStatus, useUsers };