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

package/dist/index.d.ts

@@ -1,395 +1,1115 @@
-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';
+import { useLiveQuery } from 'dexie-react-hooks';
 
+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;
+};
 /**
- * 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 initCrossTabSync;
+    private broadcastTokenRefresh;
+    private broadcastSignIn;
+    private broadcastSignOut;
+    private broadcastSessionInvalidated;
     /**
-     * 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;
-    /**
-     * Optional callback when authentication fails (401 error after retry)
-     * Use this to show login UI or redirect to sign-in
-     */
-    onAuthError?: (error: AuthError) => void;
+    getToken: (options?: GetTokenOptions) => Promise<string>;
+    log?: (...args: unknown[]) => void;
 }
-
-/**
- * RemoteDB - REST API based implementation of BasicDB
- * Creates RemoteCollection instances for each table
- */
-declare class RemoteDB implements BasicDB {
-    private config;
-    private collections;
-    constructor(config: RemoteDBConfig);
+/** 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>;
     /**
-     * Get a collection by name
-     * Collections are cached for reuse
+     * Shares granted by and received by the caller. App tokens see only
+     * shares involving their own app (the ones they can mount).
      */
-    collection<T extends {
-        id: string;
-    } = Record<string, any> & {
-        id: string;
-    }>(name: string): Collection<T>;
+    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;
 }
 
 /**
- * Error thrown when user is not authenticated
+ * 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 NotAuthenticatedError extends Error {
-    constructor(message?: string);
+
+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;
 }
-/**
- * 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;
+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>;
+    /** 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>;
     /**
-     * Check if an error is a "not authenticated" error
+     * Enqueue a local op and apply it optimistically to the view.
+     * Returns the resulting view record (null when the op deletes it).
      */
-    private isNotAuthenticatedError;
+    addPending(op: OpEnvelope): Promise<Record<string, unknown> | null>;
     /**
-     * Helper to make authenticated API requests
-     * Automatically retries once on 401 (token expired) by refreshing the token
+     * 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.
      */
-    private request;
+    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>;
     /**
-     * Validate data against schema if available
+     * Terminal rejection: remove from pending, park in the rejected store,
+     * roll the view record back to server state + remaining pending ops.
      */
-    private validateData;
+    rejectPending(opId: string, error: SyncErrorCode | string, message?: string): Promise<RejectedRow | null>;
     /**
-     * Get the base path for this collection
+     * 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.
      */
-    private get basePath();
+    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;
     /**
-     * Add a new record to the collection
-     * The server generates the ID
-     * Requires authentication - throws NotAuthenticatedError if not signed in
+     * Rebase one record: view = server data + pending ops for that record in
+     * creation order. Must run inside a transaction covering all stores.
      */
-    add(data: Omit<T, 'id'>): Promise<T>;
-    /**
-     * Put (upsert) a record - requires id
-     * Requires authentication - throws NotAuthenticatedError if not signed in
-     */
-    put(data: T): Promise<T>;
+    private recomputeViewRecord;
+}
+
+type SyncStatus = 'idle' | '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;
+}
+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;
     /**
-     * Update an existing record by id
-     * Requires authentication - throws NotAuthenticatedError if not signed in
+     * 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.
      */
-    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<T | null>;
+    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;
+    private started;
+    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>;
+    /** Open the own-channel keyspace and connect. Idempotent. */
+    start(): Promise<void>;
+    /** Close the socket and stores; local data is kept. */
+    stop(): void;
     /**
-     * Delete a record by 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.
      */
-    delete(id: string): Promise<boolean>;
+    destroyLocal(): Promise<void>;
     /**
-     * Get a single record by id
-     * Returns null if not authenticated (graceful degradation for read operations)
+     * Mount a share: separate keyspace `(project, share)` with its own cursor
+     * and pending queue. Bootstraps + subscribes when the socket is online.
      */
-    get(id: string): 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>;
     /**
-     * Get all records in the collection
-     * Returns empty array if not authenticated (graceful degradation for read operations)
+     * 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).
      */
-    getAll(): Promise<T[]>;
+    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;
     /**
-     * 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)
+     * Responsibilities 3+4+5: ordered apply, cursor advance, dedupe/confirm.
+     * Runs inside the sub's serial chain.
      */
-    filter(fn: (item: T) => boolean): Promise<T[]>;
+    private processOps;
     /**
-     * ref is not available for remote collections
+     * 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.
      */
-    ref: undefined;
+    private processPushed;
+    /** Push unsent pending ops, chunked to `limits.max_ops_per_push`. */
+    private flush;
+    private get dbPrefix();
+    private enqueue;
+    private timer;
+    private recomputeStatus;
+    private log;
 }
 
-interface BasicStorage {
-    get(key: string): Promise<string | null>;
-    set(key: string, value: string): Promise<void>;
-    remove(key: string): Promise<void>;
+/**
+ * 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>;
 }
-declare class LocalStorageAdapter implements BasicStorage {
-    get(key: string): Promise<string | null>;
-    set(key: string, value: string): Promise<void>;
-    remove(key: string): Promise<void>;
+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>;
 }
-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.
- *
- * - `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.
+ * BasicClient — the framework-agnostic SDK core. Owns:
+ * - AuthManager (OAuth/PKCE, tokens, cross-tab session)
+ * - SyncEngine  (Sync/2 client: local store, pending queue, WS connection)
+ * - RestClient  (REST v2: snapshot/changes bootstrap, shares, CRUD)
  *
- * 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.
+ * and orchestrates them: sync connects when a healthy session exists, stops
+ * on reauth_required, and tears down local data on sign-out (no page reload).
+ * The React layer (`BasicProvider` + hooks) is a thin subscriber.
  */
-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"
+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;
+    /** Node/testing: pass the `ws` constructor. */
+    WebSocketImpl?: typeof WebSocket;
 }
-/** Snapshot of local schema vs server (for dev toolbar and debugging). */
-type BasicSchemaDevInfo = {
+/** 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;
+    mode: BasicMode;
+}
+interface ShareMountHandle {
+    shareId: string;
+    db: BasicDb;
+}
+declare class BasicClient {
+    readonly auth: AuthManager;
+    readonly rest: RestClient;
+    readonly engine: SyncEngine | null;
+    readonly mode: BasicMode;
+    readonly config: BasicClientConfig;
+    readonly projectId: string | undefined;
+    private readonly syncDb;
+    private readonly restDb;
+    private readonly debug;
+    private devInfo;
+    private syncEnabled;
+    private schemaChecked;
+    private started;
+    private cleanupFns;
+    private mounts;
+    private listeners;
+    private snapshot;
+    constructor(config: BasicClientConfig);
+    /** The database handle: offline-first in sync mode, direct API in rest mode. */
+    get db(): BasicDb;
+    /** Bootstrap: version migrations, schema check, auth initialization. */
+    start(): Promise<void>;
+    /** Sign out: server-side revoke, local auth clear, sync teardown + purge. */
+    signOut(): 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 handleAuthChange;
+    private maybeStartSync;
+    private teardownLocalData;
+    private wireEngineEvents;
+    private checkSchema;
+    private buildSnapshot;
+    private publish;
+}
+declare function createBasicClient(config: BasicClientConfig): BasicClient;
 
-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;
-    /**
-     * @deprecated Project ID is now extracted from schema.project_id.
-     * This prop is kept for backward compatibility but can be omitted.
-     */
+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;
     /**
-     * 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' (default): offline-first local replica synced over Sync/2
+     * - 'rest': direct REST calls, no local persistence
      */
-    dbMode?: DBMode;
-    /** Show floating dev toolbar (localhost, NODE_ENV=development, or debug=true). */
+    mode?: BasicMode;
+    /** 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, 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).
+ * Re-export of dexie-react-hooks' `useLiveQuery` — any read through
+ * `db.table(...)` (or its `ref` Dexie table) is observable.
+ *
+ * ```tsx
+ * const todos = useQuery(() => db.table('todos').getAll())
+ * ```
+ */
+declare const useQuery: typeof useLiveQuery;
+/** 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;
+    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 UseBasicResult extends UseAuthResult {
+    db: BasicDb;
+    sync: UseSyncStatusResult;
+    /** 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. */
+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`.
  */
-declare function BasicDevToolbar({ enabled, debug }: BasicDevToolbarProps): react_jsx_runtime.JSX.Element | null;
+
+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 +1138,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 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, 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 User, applyOpToData, createBasicClient, isAuthError, isRebootstrapError, isRevocationError, isTerminalOpError, mintOpId, resolveDid, resolveDidWebUrl, resolveHandle, shareSubKey, useAuth, useBasic, useBasicClient, useDb, useQuery, useShare, useShares, useSyncStatus };