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

package/dist/index.d.mts

@@ -1,1394 +1,270 @@
-import React from 'react';
-import Dexie, { Table } from 'dexie';
+import * as react from 'react';
+import { ReactNode, ReactElement } from 'react';
+import { BasicSchema, BasicConfig, BasicClient, BasicProfile, AuthStatus, BasicError, AuthUser, BasicSyncStatus, BasicRejection, BasicConflict, SourceRef, SchemaStatus, BasicDb, Repo, FileRecord, MountFileInfo, StorageInfo, FileListQuery, MountInfo, MountHandle, OutgoingShareInfo, CreateOutgoingShareInput, MountsQuery, JsonObject, BasicRecord, Query, MountViewerFiles, OwnerFiles, TableNames, Collection, InferValue, KeyValueStorage, TokenStore, AuthMessageChannel, ReplicaStoreFactory, StoragePartition, ReplicaStore, UploadTransportAdapter } from '@basictech/core';
 
-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 BrowserBasicConfig<S extends BasicSchema = BasicSchema> = BasicConfig<S>;
+/** Create a core client with the complete browser adapter set installed. */
+declare function createBasicClient<S extends BasicSchema>(config: BrowserBasicConfig<S>): BasicClient<S>;
 
-type Token = {
-    access_token: string;
-    token_type: string;
-    expires_in: number;
-    refresh_token: string;
-};
-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.
- *
- * 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;
-};
-/**
- * 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.
- */
-declare class AuthManager {
-    token: Token | null;
-    user: User | null;
+interface UseAccountsResult {
+    accounts: BasicProfile[];
+    active: BasicProfile | null;
+    switchAccount(id: string): Promise<void>;
+    addAccount(): Promise<BasicProfile>;
+    removeAccount(id: string): Promise<void>;
+}
+declare function useAccounts(): UseAccountsResult;
+
+interface UseAuthResult {
+    isReady: boolean;
     isSignedIn: boolean;
-    isAuthReady: boolean;
-    authStatus: AuthStatus;
-    authErrorCode: string | null;
+    isAnonymous: boolean;
+    status: AuthStatus;
+    error: BasicError | null;
+    user: AuthUser | 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;
-    /**
-     * Bootstrap auth: handle OAuth callback (?code=), restore session
-     * from refresh token, or load cached user for offline mode.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Get a valid access token string. Refreshes proactively (5s buffer)
-     * or on demand (forceRefresh). Mutex prevents concurrent refreshes.
-     */
-    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>;
-    /**
-     * 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.
-     */
+    handle: string | null;
+    signIn(input?: string): Promise<void>;
     signOut(): Promise<void>;
-    /**
-     * 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.
-     */
-    private revokeSessionOnServer;
-    reconcileSession(reason?: string, options?: {
-        forceRefresh?: boolean;
-        throttleMs?: number;
-    }): Promise<void>;
-    hasScope(scope: string): boolean;
-    /**
-     * Returns scopes that were requested but not granted in the current token.
-     * Useful after login or when a 403 is returned.
-     */
-    missingScopes(): string[];
-    /**
-     * 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.
-     */
-    setupNetworkListeners(): () => void;
-    private get adminHostname();
-    private defaultPdsEndpoints;
-    private getActivePdsEndpoints;
-    private reportConnection;
-    /**
-     * After a new token is stored, decode JWT claims and fetch user info.
-     */
-    private processNewToken;
-    private restoreCachedUser;
-    private fetchUser;
-    /**
-     * Exchange an auth code or refresh token for an access token.
-     * Handles mutex (one in-flight refresh), token validation, and
-     * triggers processNewToken on success.
-     */
-    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;
-    /**
-     * 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".
-     */
-    private updateAuthStatus;
-    private clearStoredSessionTokens;
-    private restoreStoredSession;
-    private handleExternalTokenRefresh;
-    private fetchCurrentSession;
-    private markReauthRequired;
+    getToken(): Promise<string>;
 }
+declare function useAuth(): UseAuthResult;
 
-/**
- * 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`
- */
-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;
-/**
- * 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 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;
+interface UseSyncStatusResult {
+    status: BasicSyncStatus;
+    pendingCount: number;
+    rejected: BasicRejection[];
+    conflicts: BasicConflict[];
+    resolveConflict(opId: string, choice: 'keep-mine' | 'keep-theirs'): Promise<boolean>;
+    discardRejected(opId: string): Promise<boolean>;
 }
-type SharePermission = 'read' | 'write';
-interface ShareSelector {
-    table: string;
-    record_ids?: string[] | null;
+declare function useSyncStatus(source?: SourceRef): UseSyncStatusResult;
+declare function useSchemaStatus(source?: SourceRef): SchemaStatus;
+
+interface UseBasicResult<S extends BasicSchema = BasicSchema> extends UseAuthResult {
+    client: BasicClient<S>;
+    db: BasicDb<S>;
+    accounts: UseAccountsResult;
+    sync: UseSyncStatusResult;
+    repos: Repo[];
 }
-/** 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;
+declare function useBasic<S extends BasicSchema = BasicSchema>(): UseBasicResult<S>;
+
+interface UseFilesResult {
+    data: Array<FileRecord | MountFileInfo>;
+    isLoading: boolean;
+    error: BasicError | null;
+    refresh(): void;
+}
+declare function useFiles(query?: FileListQuery, options?: {
+    source?: SourceRef;
+}): UseFilesResult;
+interface UseStorageInfoResult {
+    data: StorageInfo | null;
+    isLoading: boolean;
+    error: BasicError | null;
+    refresh(): void;
 }
-/** Client-minted op id (idempotency key). */
-declare function mintOpId(): string;
-/**
- * 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 function applyOpToData(existing: Record<string, unknown> | undefined, op: OpEnvelope): Record<string, unknown> | undefined;
+declare function useStorageInfo(): UseStorageInfoResult;
 
-/**
- * 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 UseMountsResult<S extends BasicSchema = BasicSchema> {
+    data: MountInfo[];
+    mounts: MountInfo[];
+    isLoading: boolean;
+    error: BasicError | null;
+    refresh(): void;
+    open(mountId: string): Promise<MountHandle<S>>;
+    manageUrl(): string;
+}
+declare function useMounts(query?: MountsQuery): UseMountsResult;
+interface UseOutgoingSharesResult {
+    data: OutgoingShareInfo[];
+    outgoingShares: OutgoingShareInfo[];
+    isLoading: boolean;
+    error: BasicError | null;
+    refresh(): void;
+    create(input: CreateOutgoingShareInput): Promise<OutgoingShareInfo>;
+    get(id: string): Promise<OutgoingShareInfo>;
+    cancel(id: string): Promise<OutgoingShareInfo>;
+    revoke(id: string): Promise<OutgoingShareInfo>;
+    getContactHandle(did: string): Promise<string | null>;
+    manageUrl(): string;
+}
+declare function useOutgoingShares(): UseOutgoingSharesResult;
 
-interface GetTokenOptions {
-    forceRefresh?: boolean;
-}
-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) => 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>;
-    /**
-     * Shares granted by and received by the caller. App tokens see only
-     * shares involving their own app (the ones they can mount).
-     */
-    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;
+interface UseQueryResult<V extends JsonObject> {
+    data: BasicRecord<V>[];
+    isLoading: boolean;
+    error: BasicError | null;
 }
+declare function useQuery<V extends JsonObject = JsonObject>(collection: string, query?: Query<V>, options?: {
+    source?: SourceRef;
+}): UseQueryResult<V>;
 
-/**
- * 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.
- */
+interface UseReposResult {
+    repos: Repo[];
+    defaultRepoId: string | null;
+    refresh(): Promise<Repo[]>;
+    create(input: {
+        name: string;
+        schema_type?: Repo['schema_type'];
+        schema?: JsonObject;
+    }): Promise<Repo>;
+    archive(repoId: string): Promise<void>;
+}
+declare function useRepos(): UseReposResult;
 
-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>;
-    /**
-     * Enqueue a local op and apply it optimistically to the view.
-     * Returns the resulting view record (null when the op deletes it).
-     */
-    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;
+type CreateBasicConfig<S extends BasicSchema> = BrowserBasicConfig<S> & {
+    schema: S;
+};
+interface BoundBasicProviderProps {
+    children: ReactNode;
+    renderWhileLoading?: boolean;
 }
+interface CreatedBasic<S extends BasicSchema> {
+    client: BasicClient<S>;
+    Provider(props: BoundBasicProviderProps): ReactElement;
+    useBasic(): UseBasicResult<S>;
+    useAuth(): UseAuthResult;
+    useAccounts(): UseAccountsResult;
+    useDb(source: {
+        mountId: string;
+    }): BasicDb<S, MountViewerFiles>;
+    useDb(source?: 'default' | {
+        repoId: string;
+    }): BasicDb<S, OwnerFiles>;
+    useDb(source: SourceRef): BasicDb<S, OwnerFiles | MountViewerFiles>;
+    useCollection<T extends TableNames<S>>(name: T, options?: {
+        source?: SourceRef;
+    }): Collection<InferValue<S, T> & JsonObject>;
+    useQuery<T extends TableNames<S>>(collection: T, query?: Query<InferValue<S, T> & JsonObject>, options?: {
+        source?: SourceRef;
+    }): UseQueryResult<InferValue<S, T> & JsonObject>;
+    useSyncStatus(source?: SourceRef): UseSyncStatusResult;
+    useSchemaStatus(source?: SourceRef): SchemaStatus;
+    useRepos(): UseReposResult;
+    useFiles(query?: FileListQuery, options?: {
+        source?: SourceRef;
+    }): UseFilesResult;
+    useStorageInfo(): UseStorageInfoResult;
+    useMounts(query?: MountsQuery): UseMountsResult<S>;
+    useOutgoingShares(): UseOutgoingSharesResult;
+}
+/** Create one browser client and a complete hook surface bound to its schema. */
+declare function createBasic<const S extends BasicSchema>(config: CreateBasicConfig<S>): CreatedBasic<S>;
 
-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;
-}
-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;
-    /**
-     * Keyspace segment appended to database names (multi-user: the local user
-     * id). `''`/unset = the legacy single-user keyspace.
-     */
-    keyspaceId?: string;
-    /**
-     * 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.
-     */
-    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>;
-    /**
-     * Open the own-channel keyspace for local reads/writes — no connection,
-     * no token needed. This is the anonymous / offline-cold-start entry point.
-     * Idempotent.
-     */
-    openLocal(): Promise<void>;
-    /**
-     * 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.
-     */
-    connect(): Promise<void>;
-    /** Clear the revocation latch (after the user re-authorized the app). */
-    clearRevoked(): void;
-    /** @deprecated alias of {@link connect} */
-    start(): Promise<void>;
-    /**
-     * Disconnect but keep stores open: local reads/writes keep working and
-     * ops queue for the next connect. Used on reauth_required.
-     */
-    pause(): void;
-    /** Close the socket and stores; local data is kept. */
-    stop(): void;
-    /**
-     * Stop and delete every local database for this project (sign-out).
-     * Best-effort discovery of mount keyspaces from previous sessions.
-     */
-    destroyLocal(): Promise<void>;
-    /**
-     * Mount a share: separate keyspace `(project, share)` with its own cursor
-     * and pending queue. Bootstraps + subscribes when the socket is online.
-     */
-    mountShare(shareId: string): Promise<SubscriptionState>;
-    /** Unsubscribe a mount. Local cache is kept unless `purge` is set. */
-    unmountShare(shareId: string, options?: {
-        purge?: boolean;
-    }): Promise<void>;
-    /**
-     * 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).
-     */
-    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;
-    /**
-     * Responsibilities 3+4+5: ordered apply, cursor advance, dedupe/confirm.
-     * Runs inside the sub's serial chain.
-     */
-    private processOps;
-    /**
-     * 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;
+interface ProviderChildrenProps {
+    children: ReactNode;
+    renderWhileLoading?: boolean;
 }
+type BasicProviderProps<S extends BasicSchema = BasicSchema> = ProviderChildrenProps & ({
+    client: BasicClient<S>;
+} | (BrowserBasicConfig<S> & {
+    client?: never;
+}));
+/** Generic provider for schema-less or explicitly generic applications. */
+declare function BasicProvider<S extends BasicSchema = BasicSchema>(props: BasicProviderProps<S>): react.JSX.Element;
 
-/**
- * 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).
- */
+declare function useDb<S extends BasicSchema = BasicSchema>(source: {
+    mountId: string;
+}): BasicDb<S, MountViewerFiles>;
+declare function useDb<S extends BasicSchema = BasicSchema>(source?: 'default' | {
+    repoId: string;
+}): BasicDb<S, OwnerFiles>;
+declare function useDb<S extends BasicSchema = BasicSchema>(source: SourceRef): BasicDb<S, OwnerFiles | MountViewerFiles>;
+declare function useCollection<V extends JsonObject = JsonObject>(name: string, options?: {
+    source?: SourceRef;
+}): Collection<V>;
 
-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>;
+/** Synchronous browser Storage adapted to core's key-value contract. */
+declare class BrowserKeyValueStorage implements KeyValueStorage {
+    private readonly storage;
+    constructor(storage: Storage);
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
 }
+declare function browserStorage(name: 'localStorage' | 'sessionStorage'): BrowserKeyValueStorage | null;
 
+interface MemoryAccessToken {
+    value: string;
+    expiresAt: number;
+    refreshToken: string;
+}
 /**
- * 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.
+ * Browser token policy: refresh tokens survive reloads in the supplied
+ * persistent store; access tokens exist only in this JavaScript realm.
  */
-
-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;
-    /**
-     * Keyspace segment for sync data. `''` = the legacy pre-multi-user
-     * keyspace (`basic-sync:{projectId}`); otherwise db names append it.
-     */
-    keyspace: string;
-    /**
-     * Prefix for this profile's auth storage keys. `''` = legacy unprefixed
-     * keys; otherwise `u:{id}:`.
-     */
-    storagePrefix: string;
-    createdAt: number;
-    lastActiveAt: number;
-}
-/** Namespaces every key of an underlying BasicStorage adapter. */
-declare class PrefixedStorage implements BasicStorage {
-    private readonly inner;
-    readonly prefix: string;
-    constructor(inner: BasicStorage, prefix: string);
+declare class BrowserTokenStore implements TokenStore {
+    private readonly persistent;
+    private readonly accessTokens;
+    private readonly accessWaiters;
+    constructor(persistent: KeyValueStorage);
     get(key: string): Promise<string | null>;
     set(key: string, value: string): Promise<void>;
     remove(key: string): Promise<void>;
+    accessToken(key: string): MemoryAccessToken | null;
+    adoptAccessToken(key: string, value: string, expiresAt: number, refreshToken: string): Promise<void>;
+    private resolveAccessWaiters;
+    private waitForAccessToken;
 }
-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>;
-}
-
-/**
- * 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)
- *
- * plus the multi-user registry: several local users (anonymous or signed-in)
- * exist side by side, one active at a time per tab, switchable.
- *
- * 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 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;
-}
-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;
-    syncStatus: SyncStatus;
-    pendingCount: number;
-    /** True when the schema allows sync (valid + published + matching server). */
-    syncEnabled: boolean;
-    devInfo: BasicSchemaDevInfo | null;
-    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;
-    /**
-     * 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;
-    auth?: BasicAuthConfig;
-    storage?: BasicStorage;
-    debug?: boolean;
-    /**
-     * - 'sync' (default): offline-first local replica synced over Sync/2
-     * - 'rest': direct REST calls, no local persistence
-     */
-    mode?: BasicMode;
-    /**
-     * 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.
-     */
-    anonymous?: boolean;
-    /** Show the floating dev toolbar (localhost / NODE_ENV=development / debug). */
-    devToolbar?: boolean;
-    /**
-     * 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;
 
-/**
- * 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 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;
+interface BrowserMessageChannel {
+    postMessage(message: unknown): void;
+    close(): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
 }
+/** Core message-channel adapter backed by the browser BroadcastChannel API. */
+declare function createBrowserMessageChannel(name: string): BrowserMessageChannel;
 /**
- * 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.
+ * Access tokens may cross tabs transiently but are never written to browser
+ * storage. The receiving adapter adopts the token before core handles the
+ * ordinary token-rotation notification.
  */
-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;
+declare function createBrowserAuthChannelFactory(clientId: string, tokenStore: BrowserTokenStore): (name: string) => AuthMessageChannel;
 
-/**
- * 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 browserNavigate(url: string): void;
+declare function browserCurrentUrl(): string;
+declare function browserReplaceUrl(url: string): void;
 
-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;
+interface ReplicaMessageChannel {
+    postMessage(message: unknown): void;
+    close(): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+}
+interface AvailableLock {
+    name: string;
+}
+interface BrowserLockManager {
+    request<T>(name: string, options: {
+        mode?: 'exclusive';
+        ifAvailable?: true;
+    }, callback: (lock: AvailableLock | null) => T | Promise<T>): Promise<T>;
+}
+interface PersistenceStoreOptions {
+    locks?: BrowserLockManager | null;
+    createChannel?: ((name: string) => ReplicaMessageChannel) | null;
+}
+/** Dexie adapter for core's six-field, version-guarded replica store. */
+declare class PersistenceStore implements ReplicaStoreFactory {
+    private readonly db;
+    private readonly stores;
+    private readonly locks;
+    private readonly createChannel;
+    private opened;
+    constructor(appKey: string, options?: PersistenceStoreOptions);
+    private get partitions();
+    open(): Promise<void>;
+    forPartition(partition: StoragePartition): ReplicaStore;
+    deleteProfile(profileId: string): Promise<void>;
+    close(): void;
 }
 
-type ResolvedDid = {
-    did: string;
-    handle?: string;
-    didDocument: Record<string, unknown>;
-    pdsUrl: string;
-    authorization_endpoint: string;
-    token_endpoint: string;
-    userinfo_endpoint: string;
-};
-/**
- * Convert a did:web DID to the HTTPS URL where its DID document lives.
- *
- * did:web:pds.basic.id:did:abc123 -> https://pds.basic.id/did/abc123/did.json
- * did:web:example.com             -> https://example.com/.well-known/did.json
- */
-declare function resolveDidWebUrl(did: string): string | null;
-/**
- * Fetch a DID document by DID, extract the PDS URL, and discover OAuth endpoints.
- */
-declare function resolveDid(did: string): Promise<ResolvedDid>;
-/**
- * Resolve a handle (e.g. "alice.basic.id") to a DID and discover PDS + OAuth endpoints.
- *
- * Fetches https://{handle}/.well-known/did.json per the did:web spec.
- */
-declare function resolveHandle(handle: string): Promise<ResolvedDid>;
-
-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;
+/** Browser multipart transport with upload progress, adapted from the Drive UI. */
+declare const browserUploadTransport: UploadTransportAdapter;
 
-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 };
+export { BasicProvider, type BasicProviderProps, type BoundBasicProviderProps, type BrowserBasicConfig, BrowserKeyValueStorage, type BrowserLockManager, type BrowserMessageChannel, BrowserTokenStore, type CreateBasicConfig, type CreatedBasic, PersistenceStore, type PersistenceStoreOptions, type UseAccountsResult, type UseAuthResult, type UseBasicResult, type UseFilesResult, type UseMountsResult, type UseOutgoingSharesResult, type UseQueryResult, type UseReposResult, type UseStorageInfoResult, type UseSyncStatusResult, browserCurrentUrl, browserNavigate, browserReplaceUrl, browserStorage, browserUploadTransport, createBasic, createBasicClient, createBrowserAuthChannelFactory, createBrowserMessageChannel, useAccounts, useAuth, useBasic, useCollection, useDb, useFiles, useMounts, useOutgoingShares, useQuery, useRepos, useSchemaStatus, useStorageInfo, useSyncStatus };