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

package/dist/index.js

@@ -60,7 +60,7 @@ var init_config = __esm({
 var version;
 var init_package = __esm({
   "package.json"() {
-    version = "0.9.0-beta.0";
+    version = "0.9.0-beta.1";
   }
 });
 
@@ -159,6 +159,22 @@ var init_network = __esm({
 });
 
 // src/react/hooks.ts
+function useQuery(querier, deps = []) {
+  const client = (0, import_react2.useContext)(BasicClientContext);
+  const activeUserId = (0, import_react2.useSyncExternalStore)(
+    client ? client.subscribe : noopSubscribe,
+    () => client?.getSnapshot().activeUser?.id ?? null,
+    () => null
+  );
+  return (0, import_dexie_react_hooks.useLiveQuery)(async () => {
+    try {
+      return await querier();
+    } catch (err) {
+      if (err instanceof Error && err.name === "DatabaseClosedError") return void 0;
+      throw err;
+    }
+  }, [...deps, activeUserId]);
+}
 function useBasicClient() {
   const client = (0, import_react2.useContext)(BasicClientContext);
   if (!client) {
@@ -176,6 +192,7 @@ function useAuth() {
     () => ({
       isReady: snapshot.isReady,
       isSignedIn: snapshot.isSignedIn,
+      isAnonymous: snapshot.isAnonymous,
       status: snapshot.authStatus,
       errorCode: snapshot.authErrorCode,
       user: snapshot.user,
@@ -232,9 +249,11 @@ function useShares() {
     },
     [client]
   );
+  const activeUserId = snapshot.activeUser?.id ?? null;
   (0, import_react2.useEffect)(() => {
     if (isSignedIn) void refresh();
-  }, [isSignedIn, refresh]);
+    else setState({ granted: [], received: [], isLoading: false, error: null });
+  }, [isSignedIn, refresh, activeUserId]);
   return { ...state, refresh };
 }
 function useShare(shareId) {
@@ -244,6 +263,7 @@ function useShare(shareId) {
   const [error, setError] = (0, import_react2.useState)(null);
   const [revoked, setRevoked] = (0, import_react2.useState)(false);
   const canMount = !!shareId && snapshot.isSignedIn && snapshot.authStatus !== "reauth_required";
+  const activeUserId = snapshot.activeUser?.id ?? null;
   (0, import_react2.useEffect)(() => {
     if (!canMount || !shareId) return;
     let cancelled = false;
@@ -267,13 +287,28 @@ function useShare(shareId) {
       void client.unmountShare(shareId).catch(() => {
       });
     };
-  }, [client, shareId, canMount]);
+  }, [client, shareId, canMount, activeUserId]);
   return {
     db: handle?.db ?? null,
     status: revoked ? "revoked" : error ? "error" : handle ? "mounted" : "mounting",
     error
   };
 }
+function useUsers() {
+  const client = useBasicClient();
+  const snapshot = useClientSnapshot(client);
+  return (0, import_react2.useMemo)(
+    () => ({
+      users: snapshot.users,
+      activeUser: snapshot.activeUser,
+      isAnonymous: snapshot.isAnonymous,
+      switchUser: (id) => client.switchUser(id),
+      addUser: () => client.addUser(),
+      removeUser: (id) => client.removeUser(id)
+    }),
+    [client, snapshot]
+  );
+}
 function useBasic() {
   const client = useBasicClient();
   const snapshot = useClientSnapshot(client);
@@ -284,6 +319,8 @@ function useBasic() {
       ...auth,
       db: client.db,
       sync,
+      users: snapshot.users,
+      activeUser: snapshot.activeUser,
       devInfo: snapshot.devInfo,
       refreshSchemaStatus: () => client.refreshSchemaStatus(),
       client
@@ -291,14 +328,15 @@ function useBasic() {
     [client, snapshot, auth, sync]
   );
 }
-var import_react2, import_dexie_react_hooks, useQuery;
+var import_react2, import_dexie_react_hooks, noopSubscribe;
 var init_hooks = __esm({
   "src/react/hooks.ts"() {
     "use strict";
     import_react2 = require("react");
     import_dexie_react_hooks = require("dexie-react-hooks");
     init_context();
-    useQuery = import_dexie_react_hooks.useLiveQuery;
+    noopSubscribe = () => () => {
+    };
   }
 });
 
@@ -316,7 +354,8 @@ function toneForSync(mode, status) {
   if (mode === "rest") return "muted";
   if (status === "online") return "ok";
   if (status === "connecting") return "warn";
-  if (status === "offline" || status === "idle" || status === "stopped") return "muted";
+  if (status === "offline" || status === "idle" || status === "stopped" || status === "local")
+    return "muted";
   return "bad";
 }
 function toneForSchema(info) {
@@ -330,6 +369,8 @@ function syncStatusLabel(status) {
   switch (status) {
     case "idle":
       return "Idle";
+    case "local":
+      return "Local only";
     case "connecting":
       return "Connecting";
     case "online":
@@ -506,18 +547,22 @@ function BasicDevToolbar({ enabled = true, debug }) {
   const {
     isReady,
     isSignedIn,
+    isAnonymous,
     user,
     did,
     scope,
     missingScopes,
     sync,
+    users,
+    activeUser,
     devInfo,
     refreshSchemaStatus,
     client
   } = useBasic();
   const dbMode = client.mode;
   const syncStatus = sync.status;
-  const indexedDbName = dbMode === "sync" && client.projectId ? `basic-sync:${client.projectId}` : null;
+  const indexedDbName = dbMode === "sync" && client.projectId ? `basic-sync:${client.projectId}${activeUser?.keyspace ? `:${activeUser.keyspace}` : ""}` : null;
+  const activeUserLabel = activeUser ? `${isAnonymous ? "anonymous" : activeUser.email || activeUser.name || activeUser.did || "account"} (${activeUser.id.slice(0, 8)}\u2026)${users.length > 1 ? ` \xB7 ${users.length} users` : ""}` : "\u2014";
   const [open, setOpen] = (0, import_react3.useState)(false);
   const [refreshing, setRefreshing] = (0, import_react3.useState)(false);
   const [copied, setCopied] = (0, import_react3.useState)(false);
@@ -554,9 +599,11 @@ function BasicDevToolbar({ enabled = true, debug }) {
       syncStatus,
       pendingOps: sync.pendingCount,
       indexedDbName,
+      activeUser: activeUser ? { id: activeUser.id, kind: activeUser.kind, did: activeUser.did } : null,
+      userCount: users.length,
       schema: devInfo
     };
-  }, [isReady, isSignedIn, did, user, scope, dbMode, syncStatus, sync.pendingCount, indexedDbName, devInfo, missingList]);
+  }, [isReady, isSignedIn, did, user, scope, dbMode, syncStatus, sync.pendingCount, indexedDbName, activeUser, users.length, devInfo, missingList]);
   const handleCopy = (0, import_react3.useCallback)(async () => {
     try {
       await navigator.clipboard.writeText(JSON.stringify(debugPayload, null, 2));
@@ -694,6 +741,17 @@ function BasicDevToolbar({ enabled = true, debug }) {
           children: user ? displayUserLine(user) : "\u2014"
         }
       ),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        CopyableRow,
+        {
+          rowKey: "activeProfile",
+          label: "Profile",
+          copyText: activeUser?.id ?? "",
+          copiedKey: rowCopied,
+          onCopied: onRowCopied,
+          children: activeUserLabel
+        }
+      ),
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
         CopyableRow,
         {
@@ -943,6 +1001,7 @@ __export(index_exports, {
   NotAuthenticatedError: () => NotAuthenticatedError,
   OWN_SUB: () => OWN_SUB,
   PROTOCOL_VERSION: () => PROTOCOL_VERSION,
+  PrefixedStorage: () => PrefixedStorage,
   RestClient: () => RestClient,
   RestDb: () => RestDb,
   RestError: () => RestError,
@@ -951,6 +1010,7 @@ __export(index_exports, {
   SyncDb: () => SyncDb,
   SyncEngine: () => SyncEngine,
   SyncStore: () => SyncStore,
+  UserRegistry: () => UserRegistry,
   applyOpToData: () => applyOpToData,
   createBasicClient: () => createBasicClient,
   isAuthError: () => isAuthError,
@@ -969,7 +1029,8 @@ __export(index_exports, {
   useQuery: () => useQuery,
   useShare: () => useShare,
   useShares: () => useShares,
-  useSyncStatus: () => useSyncStatus
+  useSyncStatus: () => useSyncStatus,
+  useUsers: () => useUsers
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1156,11 +1217,15 @@ var AuthManager = class {
     this.requestedScopes = config.scopes;
     this.initCrossTabSync();
   }
+  get instanceKey() {
+    return this.config.instanceKey ?? "";
+  }
   initCrossTabSync() {
     if (typeof BroadcastChannel === "undefined") return;
     try {
       this.channel = new BroadcastChannel("basic-auth");
       this.channel.onmessage = (event) => {
+        if ((event.data?.userKey ?? "") !== this.instanceKey) return;
         if (event.data?.type === "token_refreshed") {
           log("Received token refresh from another tab");
           void this.handleExternalTokenRefresh(event.data);
@@ -1188,19 +1253,32 @@ var AuthManager = class {
   broadcastTokenRefresh() {
     this.channel?.postMessage({
       type: "token_refreshed",
+      userKey: this.instanceKey,
       accessToken: this.token?.access_token,
       did: this.did,
       tokenScope: this.tokenScope
     });
   }
   broadcastSignIn() {
-    this.channel?.postMessage({ type: "signed_in" });
+    this.channel?.postMessage({ type: "signed_in", userKey: this.instanceKey });
   }
   broadcastSignOut() {
-    this.channel?.postMessage({ type: "signed_out" });
+    this.channel?.postMessage({ type: "signed_out", userKey: this.instanceKey });
   }
   broadcastSessionInvalidated(code) {
-    this.channel?.postMessage({ type: "session_invalidated", code });
+    this.channel?.postMessage({
+      type: "session_invalidated",
+      userKey: this.instanceKey,
+      code
+    });
+  }
+  /** Release resources (cross-tab channel). Used when switching users. */
+  destroy() {
+    try {
+      this.channel?.close();
+    } catch {
+    }
+    this.channel = null;
   }
   // ------------------------------------------------------------------
   // Public API
@@ -2628,6 +2706,7 @@ var SyncConnection = class {
 var import_dexie = __toESM(require("dexie"));
 var META_CURSOR = "cursor";
 var META_CHANNEL = "channel";
+var META_OWNER = "owner_did";
 var SyncStore = class {
   db;
   name;
@@ -2684,6 +2763,32 @@ var SyncStore = class {
     const row = await this.meta.get(META_CHANNEL);
     return typeof row?.value === "string" ? row.value : 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).
+   */
+  async getOwner() {
+    const row = await this.meta.get(META_OWNER);
+    return typeof row?.value === "string" ? row.value : null;
+  }
+  async setOwner(did) {
+    await this.meta.put({ key: META_OWNER, value: did });
+  }
+  /**
+   * Clear everything (views, server state, pending, rejected, meta) without
+   * deleting the database — used when the keyspace changes owners.
+   */
+  async wipeAll() {
+    await this.db.transaction("rw", this.allStores, async () => {
+      await this.server.clear();
+      await this.pending.clear();
+      await this.rejected.clear();
+      await this.meta.clear();
+      for (const tableName of this.tableNames) {
+        await this.view(tableName).clear();
+      }
+    });
+  }
   // -------------------------------------------------------------------
   // Pending / rejected
   // -------------------------------------------------------------------
@@ -2896,7 +3001,11 @@ var SyncEngine = class {
   subs = /* @__PURE__ */ new Map();
   limits = { ...DEFAULT_LIMITS };
   actor = null;
-  started = false;
+  /** Own-sub store is open (local reads/writes work). */
+  storesOpen = false;
+  /** A live connection is wanted (vs. local-only / paused). */
+  connectIntended = false;
+  openingLocal = null;
   revokedInfo = null;
   connectionStatus = "idle";
   _status = "idle";
@@ -2971,26 +3080,76 @@ var SyncEngine = class {
   // -------------------------------------------------------------------
   // Lifecycle
   // -------------------------------------------------------------------
-  /** Open the own-channel keyspace and connect. Idempotent. */
-  async start() {
-    if (this.started) {
-      if (this.connectionStatus === "auth_failed" || this._status === "auth_required") {
-        this.connection.start();
-      }
+  /**
+   * Open the own-channel keyspace for local reads/writes — no connection,
+   * no token needed. This is the anonymous / offline-cold-start entry point.
+   * Idempotent.
+   */
+  async openLocal() {
+    if (this.subs.has(OWN_SUB)) {
+      this.storesOpen = true;
+      this.recomputeStatus();
       return;
     }
-    this.started = true;
-    this.revokedInfo = null;
-    if (!this.subs.has(OWN_SUB)) {
-      const sub = await this.openSub(OWN_SUB, null);
-      this.subs.set(OWN_SUB, sub);
+    if (!this.openingLocal) {
+      this.openingLocal = (async () => {
+        const sub = await this.openSub(OWN_SUB, null);
+        this.subs.set(OWN_SUB, sub);
+        this.storesOpen = true;
+      })().finally(() => {
+        this.openingLocal = null;
+      });
     }
+    await this.openingLocal;
+    this.recomputeStatus();
+  }
+  /**
+   * 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.
+   */
+  async connect() {
+    await this.openLocal();
+    if (this.revokedInfo) {
+      this.log("connect() ignored: app connection is revoked");
+      return;
+    }
+    this.connectIntended = true;
     this.connection.start();
     this.recomputeStatus();
   }
+  /** Clear the revocation latch (after the user re-authorized the app). */
+  clearRevoked() {
+    this.revokedInfo = null;
+    this.recomputeStatus();
+  }
+  /** @deprecated alias of {@link connect} */
+  async start() {
+    return this.connect();
+  }
+  /**
+   * Disconnect but keep stores open: local reads/writes keep working and
+   * ops queue for the next connect. Used on reauth_required.
+   */
+  pause() {
+    this.connectIntended = false;
+    this.connection.stop();
+    for (const t of this.timers) clearTimeout(t);
+    this.timers.clear();
+    for (const sub of this.subs.values()) {
+      sub.active = false;
+      for (const p of sub.pending) {
+        p.sent = false;
+        p.ackedSeq = void 0;
+      }
+    }
+    this.recomputeStatus();
+  }
   /** Close the socket and stores; local data is kept. */
   stop() {
-    this.started = false;
+    this.connectIntended = false;
+    this.storesOpen = false;
     this.connection.stop();
     for (const t of this.timers) clearTimeout(t);
     this.timers.clear();
@@ -3018,10 +3177,10 @@ var SyncEngine = class {
     try {
       const idb = globalThis.indexedDB;
       if (idb && typeof idb.databases === "function") {
-        const prefix = `${this.dbPrefix}:${this.projectId}`;
+        const base = this.baseDbName;
         const dbs = await idb.databases();
         for (const info of dbs) {
-          if (info.name && info.name.startsWith(prefix)) {
+          if (info.name && (info.name === base || info.name.startsWith(`${base}:share:`))) {
             await new Promise((resolve) => {
               const req = idb.deleteDatabase(info.name);
               req.onsuccess = req.onerror = req.onblocked = () => resolve();
@@ -3119,7 +3278,7 @@ var SyncEngine = class {
   // -------------------------------------------------------------------
   handleConnectionStatus(status) {
     this.connectionStatus = status;
-    if (status === "offline" || status === "connecting" || status === "auth_failed") {
+    if (status === "offline" || status === "connecting" || status === "auth_failed" || status === "stopped") {
       for (const sub of this.subs.values()) {
         sub.active = false;
         for (const p of sub.pending) {
@@ -3207,13 +3366,13 @@ var SyncEngine = class {
     switch (msg.code) {
       case "CONNECTION_REVOKED":
         this.revokedInfo = { code: msg.code, message: msg.message };
-        this.started = false;
+        this.connectIntended = false;
         this.connection.stop();
         this.recomputeStatus();
         this.emit("revoked", { code: msg.code, message: msg.message });
         return;
       case "UNSUPPORTED_VERSION":
-        this.started = false;
+        this.connectIntended = false;
         this.connection.stop();
         this.recomputeStatus();
         return;
@@ -3248,7 +3407,7 @@ var SyncEngine = class {
   // Subscription state machine (serialized per sub via `chain`)
   // -------------------------------------------------------------------
   async openSub(key, shareId) {
-    const name = shareId ? `${this.dbPrefix}:${this.projectId}:share:${shareId}` : `${this.dbPrefix}:${this.projectId}`;
+    const name = shareId ? `${this.baseDbName}:share:${shareId}` : this.baseDbName;
     const store = new SyncStore(name, this.schema);
     const [cursor, pendingRows] = await Promise.all([store.getCursor(), store.loadPending()]);
     return {
@@ -3269,6 +3428,16 @@ var SyncEngine = class {
   /** Bootstrap if needed, then bind the stream on the current socket. */
   async activateSub(sub) {
     if (!this.connection.isOnline) return;
+    if (sub.bootstrapped && !sub.shareId && this.opts.getOwnerDid) {
+      try {
+        const did = await this.opts.getOwnerDid() ?? null;
+        if (did) {
+          const stamped = await sub.store.getOwner();
+          if (stamped && stamped !== did) sub.bootstrapped = false;
+        }
+      } catch {
+      }
+    }
     if (!sub.bootstrapped || sub.cursor < 0) {
       try {
         await this.bootstrapSub(sub);
@@ -3287,6 +3456,26 @@ var SyncEngine = class {
   }
   /** Cold start = snapshot + tail; never log replay (§5). Pending survives. */
   async bootstrapSub(sub) {
+    let ownerDid = null;
+    if (!sub.shareId && this.opts.getOwnerDid) {
+      try {
+        ownerDid = await this.opts.getOwnerDid() ?? null;
+      } catch {
+        ownerDid = null;
+      }
+      if (ownerDid) {
+        const stamped = await sub.store.getOwner();
+        if (stamped && stamped !== ownerDid) {
+          this.log(
+            `keyspace owned by ${stamped} but session is ${ownerDid} \u2014 wiping local data before bootstrap`
+          );
+          await sub.store.wipeAll();
+          sub.pending = [];
+          sub.appliedOpIds.clear();
+          sub.cursor = -1;
+        }
+      }
+    }
     const snapshot = await this.opts.fetchSnapshot(
       sub.shareId ? { share: sub.shareId } : void 0
     );
@@ -3295,6 +3484,9 @@ var SyncEngine = class {
       records: snapshot.records ?? {},
       cursor: snapshot.cursor ?? 0
     });
+    if (!sub.shareId && ownerDid) {
+      await sub.store.setOwner(ownerDid);
+    }
     sub.cursor = snapshot.cursor ?? 0;
     sub.bootstrapped = true;
     sub.appliedOpIds.clear();
@@ -3418,6 +3610,11 @@ var SyncEngine = class {
   get dbPrefix() {
     return this.opts.dbNamePrefix ?? "basic-sync";
   }
+  /** Base database name for this keyspace (multi-user: includes the user id). */
+  get baseDbName() {
+    const base = `${this.dbPrefix}:${this.projectId}`;
+    return this.opts.keyspaceId ? `${base}:${this.opts.keyspaceId}` : base;
+  }
   enqueue(sub, task) {
     sub.chain = sub.chain.then(task).catch((err) => {
       this.log(`task failed on '${sub.key}':`, err);
@@ -3435,10 +3632,12 @@ var SyncEngine = class {
     let status;
     if (this.revokedInfo) status = "revoked";
     else if (this.connectionStatus === "auth_failed") status = "auth_required";
-    else if (!this.started) status = this.connectionStatus === "stopped" ? "stopped" : "idle";
+    else if (!this.storesOpen) status = this.connectionStatus === "stopped" ? "stopped" : "idle";
+    else if (!this.connectIntended) status = "local";
     else if (this.connectionStatus === "online") status = "online";
     else if (this.connectionStatus === "connecting") status = "connecting";
     else if (this.connectionStatus === "idle") status = "connecting";
+    else if (this.connectionStatus === "stopped") status = "local";
     else status = "offline";
     if (status !== this._status) {
       this._status = status;
@@ -3464,7 +3663,7 @@ var SyncTable = class {
     const sub = this.engine.getSubscription(this.subKey);
     if (!sub) {
       throw new Error(
-        `subscription '${this.subKey}' is not open \u2014 sign in and wait for the db to be ready`
+        `subscription '${this.subKey}' is not open \u2014 wait for the client to be ready (isReady) before using the db`
       );
     }
     return sub.store;
@@ -3594,6 +3793,171 @@ var RestDb = class {
   }
 };
 
+// src/core/users.ts
+init_config();
+var PrefixedStorage = class {
+  constructor(inner, prefix) {
+    this.inner = inner;
+    this.prefix = prefix;
+  }
+  get(key) {
+    return this.inner.get(this.prefix + key);
+  }
+  set(key, value) {
+    return this.inner.set(this.prefix + key, value);
+  }
+  remove(key) {
+    return this.inner.remove(this.prefix + key);
+  }
+};
+function registryKey(projectId) {
+  return `basic_users:${projectId}`;
+}
+function activeUserSessionKey(projectId) {
+  return `basic_active_user:${projectId}`;
+}
+var UserRegistry = class {
+  constructor(storage, projectId) {
+    this.storage = storage;
+    this.projectId = projectId;
+  }
+  // -------------------------------------------------------------------
+  // Registry CRUD
+  // -------------------------------------------------------------------
+  async list() {
+    const raw = await this.storage.get(registryKey(this.projectId));
+    if (!raw) return [];
+    try {
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+  async save(users) {
+    await this.storage.set(registryKey(this.projectId), JSON.stringify(users));
+  }
+  async get(id) {
+    const users = await this.list();
+    return users.find((u) => u.id === id) ?? null;
+  }
+  async createAnon() {
+    const id = mintOpId();
+    const now = Date.now();
+    const profile = {
+      id,
+      kind: "anon",
+      keyspace: id,
+      storagePrefix: `u:${id}:`,
+      createdAt: now,
+      lastActiveAt: now
+    };
+    const users = await this.list();
+    users.push(profile);
+    await this.save(users);
+    log(`created anonymous user ${id}`);
+    return profile;
+  }
+  async update(id, patch) {
+    const users = await this.list();
+    const idx = users.findIndex((u) => u.id === id);
+    if (idx < 0) return null;
+    users[idx] = { ...users[idx], ...patch };
+    await this.save(users);
+    return users[idx];
+  }
+  async remove(id) {
+    const users = await this.list();
+    await this.save(users.filter((u) => u.id !== id));
+    if (this.getActiveIdRaw() === id) this.clearActiveId();
+  }
+  /** The profile (if any) already bound to an account DID. */
+  async findByDid(did) {
+    const users = await this.list();
+    return users.find((u) => u.did === did) ?? null;
+  }
+  // -------------------------------------------------------------------
+  // Active user (per-tab)
+  // -------------------------------------------------------------------
+  getActiveIdRaw() {
+    try {
+      return sessionStorage.getItem(activeUserSessionKey(this.projectId));
+    } catch {
+      return null;
+    }
+  }
+  setActiveId(id) {
+    try {
+      sessionStorage.setItem(activeUserSessionKey(this.projectId), id);
+    } catch {
+    }
+  }
+  clearActiveId() {
+    try {
+      sessionStorage.removeItem(activeUserSessionKey(this.projectId));
+    } catch {
+    }
+  }
+  /**
+   * Resolve the active profile for this tab: sessionStorage choice if it
+   * still exists, else the most recently active profile, else null.
+   */
+  async resolveActive() {
+    const users = await this.list();
+    const activeId = this.getActiveIdRaw();
+    if (activeId) {
+      const match = users.find((u) => u.id === activeId);
+      if (match) return match;
+    }
+    if (users.length === 0) return null;
+    const recent = [...users].sort((a, b) => b.lastActiveAt - a.lastActiveAt)[0];
+    this.setActiveId(recent.id);
+    return recent;
+  }
+  async touch(id) {
+    await this.update(id, { lastActiveAt: Date.now() });
+  }
+  // -------------------------------------------------------------------
+  // Legacy adoption
+  // -------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async adoptLegacySession() {
+    const users = await this.list();
+    if (users.length > 0) return null;
+    const legacyRefresh = await this.storage.get(STORAGE_KEYS.REFRESH_TOKEN);
+    if (!legacyRefresh) return null;
+    let cachedUser = null;
+    try {
+      const raw = await this.storage.get(STORAGE_KEYS.USER_INFO);
+      if (raw) cachedUser = JSON.parse(raw);
+    } catch {
+    }
+    const now = Date.now();
+    const profile = {
+      id: mintOpId(),
+      kind: "account",
+      did: cachedUser?.sub ?? null,
+      email: cachedUser?.email ?? null,
+      name: cachedUser?.name ?? null,
+      picture: cachedUser?.picture ?? null,
+      keyspace: "",
+      // legacy `basic-sync:{projectId}` database
+      storagePrefix: "",
+      // legacy unprefixed auth keys
+      createdAt: now,
+      lastActiveAt: now
+    };
+    await this.save([profile]);
+    log("adopted legacy single-user session as profile", profile.id);
+    return profile;
+  }
+};
+
 // src/utils/schema.ts
 var import_schema2 = require("@basictech/schema");
 init_config();
@@ -3843,21 +4207,38 @@ var DEFAULTS = {
 function deriveSyncUrl(pdsUrl) {
   return pdsUrl.replace(/^http/, "ws").replace(/\/$/, "") + "/sync/";
 }
+function ephemeralLegacyProfile() {
+  const now = Date.now();
+  return {
+    id: "default",
+    kind: "anon",
+    keyspace: "",
+    storagePrefix: "",
+    createdAt: now,
+    lastActiveAt: now
+  };
+}
 var BasicClient = class {
-  auth;
   rest;
-  engine;
   mode;
   config;
   projectId;
-  syncDb;
+  users;
+  rawStorage;
   restDb;
   debug;
+  anonymousEnabled;
+  authConfig;
+  syncUrl;
+  binding;
+  usersCache = [];
   devInfo = null;
   syncEnabled = false;
   schemaChecked = false;
   started = false;
-  cleanupFns = [];
+  signOutInProgress = false;
+  /** Serializes profile transitions (switch, dispose, sign-out fallthrough). */
+  profileOps = Promise.resolve();
   mounts = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
   snapshot;
@@ -3866,95 +4247,155 @@ var BasicClient = class {
     this.debug = config.debug ?? false;
     this.mode = config.mode ?? "sync";
     this.projectId = config.schema?.project_id || config.project_id;
-    const authConfig = {
+    this.anonymousEnabled = this.mode === "sync" && (config.anonymous ?? true);
+    this.authConfig = {
       scopes: Array.isArray(config.auth?.scopes) ? config.auth.scopes.join(" ") : config.auth?.scopes || DEFAULTS.scopes,
       pds_url: config.auth?.pds_url || DEFAULTS.pds_url,
       admin_url: config.auth?.admin_url || DEFAULTS.admin_url
     };
-    const syncUrl = config.auth?.sync_url || deriveSyncUrl(authConfig.pds_url);
-    const storage = config.storage || new LocalStorageAdapter();
-    this.auth = new AuthManager(
-      {
-        projectId: this.projectId,
-        scopes: authConfig.scopes,
-        pdsUrl: authConfig.pds_url,
-        adminUrl: authConfig.admin_url,
-        debug: this.debug
-      },
-      storage,
-      () => this.handleAuthChange()
-    );
+    this.syncUrl = config.auth?.sync_url || deriveSyncUrl(this.authConfig.pds_url);
+    this.rawStorage = config.storage || new LocalStorageAdapter();
+    this.users = this.mode === "sync" && this.projectId ? new UserRegistry(this.rawStorage, this.projectId) : null;
     this.rest = new RestClient({
-      baseUrl: authConfig.pds_url,
+      baseUrl: this.authConfig.pds_url,
       projectId: this.projectId ?? "",
       getToken: (opts) => this.auth.getToken(opts),
       log: this.debug ? log : void 0
     });
-    if (this.mode === "sync" && this.projectId && this.config.schema?.tables) {
-      this.engine = new SyncEngine({
-        projectId: this.projectId,
-        schema: this.config.schema,
-        wsUrl: syncUrl,
-        getToken: (opts) => this.auth.getToken(opts),
-        fetchSnapshot: (opts) => this.rest.getSnapshot(opts),
-        WebSocketImpl: config.WebSocketImpl,
-        log
-      });
-      this.syncDb = new SyncDb(this.engine, OWN_SUB);
-      this.wireEngineEvents(this.engine);
-    } else {
-      this.engine = null;
-      this.syncDb = null;
-    }
     this.restDb = new RestDb(this.rest, this.config.schema);
+    this.binding = this.createBinding(ephemeralLegacyProfile());
     this.snapshot = this.buildSnapshot();
   }
   // -------------------------------------------------------------------
   // Public surface
   // -------------------------------------------------------------------
-  /** The database handle: offline-first in sync mode, direct API in rest mode. */
+  get auth() {
+    return this.binding.auth;
+  }
+  get engine() {
+    return this.binding.engine;
+  }
+  /** The database handle for the active user. Identity changes on switch. */
   get db() {
-    if (this.mode === "sync" && this.syncDb) return this.syncDb;
+    if (this.mode === "sync" && this.binding.syncDb) return this.binding.syncDb;
     return this.restDb;
   }
-  /** Bootstrap: version migrations, schema check, auth initialization. */
+  get activeUser() {
+    return this.users ? this.binding.profile : null;
+  }
+  /** Bootstrap: version migrations, profile resolution, schema check, auth init. */
   async start() {
     if (this.started) return;
     this.started = true;
     try {
-      const updater = createVersionUpdater(this.auth.storage, version, getMigrations());
+      const updater = createVersionUpdater(this.rawStorage, version, getMigrations());
       const result = await updater.checkAndUpdate();
       if (result.updated) log(`SDK storage migrated ${result.fromVersion} \u2192 ${result.toVersion}`);
     } catch (err) {
       log("version updater failed:", err);
     }
-    void this.checkSchema().then(() => this.maybeStartSync());
-    await this.auth.initialize();
-    const teardownNetwork = this.auth.setupNetworkListeners();
-    this.cleanupFns.push(teardownNetwork);
+    void this.checkSchema().then(() => this.syncLifecycle());
+    await this.queueProfileOp(async () => {
+      let profile = null;
+      if (this.users) {
+        await this.users.adoptLegacySession();
+        profile = await this.users.resolveActive();
+        if (!profile && this.anonymousEnabled) {
+          profile = await this.users.createAnon();
+        }
+        if (profile) this.users.setActiveId(profile.id);
+      }
+      await this.activateProfile(profile ?? ephemeralLegacyProfile(), { initial: true });
+      await this.refreshUsers();
+    });
   }
-  /** Sign out: server-side revoke, local auth clear, sync teardown + purge. */
+  /**
+   * 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.
+   */
   async signOut() {
-    await this.auth.signOut();
-    await this.teardownLocalData();
+    await this.queueProfileOp(async () => {
+      const { profile, auth, engine } = this.binding;
+      this.signOutInProgress = true;
+      try {
+        await auth.signOut();
+      } finally {
+        this.signOutInProgress = false;
+      }
+      this.mounts.clear();
+      try {
+        await engine?.destroyLocal();
+      } catch (err) {
+        log("local data teardown failed:", err);
+      }
+      if (this.users && profile.id !== "default") {
+        await this.users.remove(profile.id);
+      }
+      await this.activateNextProfileLocked();
+      await this.refreshUsers();
+    });
+  }
+  // ---------------- multi-user ----------------
+  /** Switch this tab to another local user. */
+  async switchUser(id) {
+    await this.queueProfileOp(async () => {
+      if (!this.users) throw new Error("multiple users require sync mode with a project id");
+      if (this.binding.profile.id === id) return;
+      const target = await this.users.get(id);
+      if (!target) throw new Error(`unknown user '${id}'`);
+      this.users.setActiveId(id);
+      await this.users.touch(id);
+      await this.activateProfile(target);
+      await this.refreshUsers();
+    });
+  }
+  /** Create a fresh anonymous user and switch to it. */
+  async addUser() {
+    let created = null;
+    await this.queueProfileOp(async () => {
+      if (!this.users) throw new Error("multiple users require sync mode with a project id");
+      created = await this.users.createAnon();
+      this.users.setActiveId(created.id);
+      await this.activateProfile(created);
+      await this.refreshUsers();
+    });
+    return created;
+  }
+  /**
+   * Remove a local user: best-effort server-side revoke, wipe its keyspace
+   * and auth storage, drop the profile. Removing the active user signs out.
+   */
+  async removeUser(id) {
+    if (this.binding.profile.id === id) {
+      return this.signOut();
+    }
+    await this.queueProfileOp(async () => {
+      if (!this.users) return;
+      const profile = await this.users.get(id);
+      if (!profile) return;
+      await this.disposeProfileData(profile);
+      await this.users.remove(id);
+      await this.refreshUsers();
+    });
   }
   /** Stop connections and listeners; local data is kept. */
   stop() {
     this.started = false;
-    this.engine?.stop();
-    for (const fn of this.cleanupFns) {
+    this.binding.engine?.stop();
+    for (const fn of this.binding.sessionCleanup) {
       try {
         fn();
       } catch {
       }
     }
-    this.cleanupFns = [];
+    this.binding.sessionCleanup = [];
   }
   /** Re-run the remote schema status check (dev toolbar). */
   async refreshSchemaStatus() {
     this.schemaChecked = false;
     await this.checkSchema();
-    this.maybeStartSync();
+    this.syncLifecycle();
   }
   async listRejected() {
     return this.engine?.listRejected() ?? [];
@@ -3970,13 +4411,14 @@ var BasicClient = class {
   }
   /** Mount a share: separate local keyspace + subscription. */
   async mountShare(shareId) {
-    if (!this.engine) throw new Error("shares require sync mode");
+    const engine = this.engine;
+    if (!engine) throw new Error("shares require sync mode");
     const existing = this.mounts.get(shareId);
     if (existing) return existing;
-    await this.engine.mountShare(shareId);
+    await engine.mountShare(shareId);
     const handle = {
       shareId,
-      db: new SyncDb(this.engine, shareSubKey(shareId))
+      db: new SyncDb(engine, shareSubKey(shareId))
     };
     this.mounts.set(shareId, handle);
     this.publish();
@@ -4000,50 +4442,260 @@ var BasicClient = class {
     return this.snapshot;
   };
   // -------------------------------------------------------------------
-  // Orchestration
+  // Profile binding & transitions
   // -------------------------------------------------------------------
-  handleAuthChange() {
-    const status = this.auth.authStatus;
-    if (status === "reauth_required") {
-      this.engine?.stop();
-    } else if (status === "signed_out") {
-      void this.teardownLocalData();
+  createBinding(profile) {
+    const storage = profile.storagePrefix ? new PrefixedStorage(this.rawStorage, profile.storagePrefix) : this.rawStorage;
+    const binding = { profile, cleanup: [], sessionCleanup: [] };
+    const auth = new AuthManager(
+      {
+        projectId: this.projectId,
+        scopes: this.authConfig.scopes,
+        pdsUrl: this.authConfig.pds_url,
+        adminUrl: this.authConfig.admin_url,
+        debug: this.debug,
+        instanceKey: profile.storagePrefix
+      },
+      storage,
+      () => {
+        if (this.binding === binding) this.handleAuthChange();
+      }
+    );
+    binding.auth = auth;
+    if (this.mode === "sync" && this.projectId && this.config.schema?.tables) {
+      const engine = new SyncEngine({
+        projectId: this.projectId,
+        schema: this.config.schema,
+        wsUrl: this.syncUrl,
+        getToken: (opts) => auth.getToken(opts),
+        fetchSnapshot: (opts) => this.rest.getSnapshot(opts),
+        WebSocketImpl: this.config.WebSocketImpl,
+        keyspaceId: profile.keyspace,
+        getOwnerDid: () => auth.did,
+        log
+      });
+      binding.engine = engine;
+      binding.syncDb = new SyncDb(engine, OWN_SUB);
+      binding.cleanup.push(
+        engine.on("status", () => this.publish()),
+        engine.on("change", () => this.publish()),
+        engine.on("rejected", ({ rejection }) => {
+          log("op rejected:", rejection.error, rejection.op);
+          this.publish();
+        }),
+        engine.on("revoked", ({ code, message }) => {
+          log("connection revoked:", code, message);
+          void auth.reconcileSession("connection revoked", { forceRefresh: true, throttleMs: 0 }).catch(() => {
+          });
+          this.publish();
+        })
+      );
     } else {
-      this.maybeStartSync();
+      binding.engine = null;
+      binding.syncDb = null;
     }
+    return binding;
+  }
+  /**
+   * 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).
+   */
+  async activateProfile(profile, options) {
+    let old = null;
+    if (options?.initial && this.bindingMatches(profile)) {
+      this.binding.profile = profile;
+    } else {
+      old = this.binding;
+      this.binding = this.createBinding(profile);
+      if (options?.initial) {
+        for (const fn of [...old.cleanup, ...old.sessionCleanup]) fn();
+        old.engine?.stop();
+        old.auth.destroy();
+        old = null;
+      }
+    }
+    await this.binding.auth.initialize();
+    this.binding.sessionCleanup.push(this.binding.auth.setupNetworkListeners());
+    this.mounts.clear();
+    this.syncLifecycle();
     this.publish();
+    if (old) {
+      setTimeout(() => {
+        try {
+          for (const fn of [...old.cleanup, ...old.sessionCleanup]) fn();
+          old.engine?.stop();
+          old.auth.destroy();
+        } catch {
+        }
+      }, 50);
+    }
   }
-  maybeStartSync() {
-    if (!this.engine || !this.started) return;
-    if (!this.syncEnabled) return;
-    if (this.auth.isSignedIn && this.auth.token && this.auth.authStatus !== "reauth_required") {
-      void this.engine.start().catch((err) => log("sync start failed:", err));
+  bindingMatches(profile) {
+    return this.binding.profile.storagePrefix === profile.storagePrefix && this.binding.profile.keyspace === profile.keyspace;
+  }
+  /** After sign-out/disposal: resume on the next profile or a fresh anon one. */
+  async activateNextProfileLocked() {
+    let next = null;
+    if (this.users) {
+      next = await this.users.resolveActive();
+      if (!next && this.anonymousEnabled) {
+        next = await this.users.createAnon();
+      }
+      if (next) this.users.setActiveId(next.id);
     }
+    await this.activateProfile(next ?? ephemeralLegacyProfile());
   }
-  async teardownLocalData() {
-    this.mounts.clear();
-    if (this.engine) {
+  /** Wipe a (non-active) profile's local footprint: keyspace dbs + auth keys. */
+  async disposeProfileData(profile) {
+    const storage = profile.storagePrefix ? new PrefixedStorage(this.rawStorage, profile.storagePrefix) : this.rawStorage;
+    try {
+      const refreshToken = await storage.get(STORAGE_KEYS.REFRESH_TOKEN);
+      if (refreshToken) {
+        await fetch(`${this.authConfig.pds_url}/auth/revoke`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ token: refreshToken, token_type_hint: "refresh_token" })
+        });
+      }
+    } catch {
+    }
+    for (const key of Object.values(STORAGE_KEYS)) {
       try {
-        await this.engine.destroyLocal();
-      } catch (err) {
-        log("local data teardown failed:", err);
+        await storage.remove(key);
+      } catch {
       }
     }
+    await this.deleteKeyspaceDatabases(profile.keyspace);
+  }
+  async deleteKeyspaceDatabases(keyspace) {
+    if (!this.projectId) return;
+    const base = keyspace ? `basic-sync:${this.projectId}:${keyspace}` : `basic-sync:${this.projectId}`;
+    try {
+      const idb = globalThis.indexedDB;
+      if (!idb) return;
+      const names = [base];
+      if (typeof idb.databases === "function") {
+        const dbs = await idb.databases();
+        for (const info of dbs) {
+          if (info.name && info.name.startsWith(`${base}:share:`)) names.push(info.name);
+        }
+      }
+      for (const name of names) {
+        await new Promise((resolve) => {
+          const req = idb.deleteDatabase(name);
+          req.onsuccess = req.onerror = req.onblocked = () => resolve();
+        });
+      }
+    } catch {
+    }
+  }
+  // -------------------------------------------------------------------
+  // Orchestration
+  // -------------------------------------------------------------------
+  /** Previous auth status, for transition detection (revoked-latch clearing). */
+  lastAuthStatus = null;
+  handleAuthChange() {
+    const status = this.auth.authStatus;
+    if (status === "authenticated" && this.lastAuthStatus !== "authenticated" && this.engine?.status === "revoked") {
+      this.engine.clearRevoked();
+    }
+    this.lastAuthStatus = status;
+    if (status === "signed_out" && !this.signOutInProgress && this.started) {
+      const profile = this.binding.profile;
+      if (this.users && profile.kind === "account") {
+        void this.queueProfileOp(async () => {
+          if (this.binding.profile.id !== profile.id) return;
+          if (this.binding.auth.authStatus !== "signed_out") return;
+          this.mounts.clear();
+          try {
+            await this.binding.engine?.destroyLocal();
+          } catch {
+          }
+          await this.users.remove(profile.id);
+          await this.activateNextProfileLocked();
+          await this.refreshUsers();
+        });
+        return;
+      }
+    }
+    this.syncLifecycle();
+    void this.maybeUpgradeProfile();
     this.publish();
   }
-  wireEngineEvents(engine) {
-    engine.on("status", () => this.publish());
-    engine.on("change", () => this.publish());
-    engine.on("rejected", ({ rejection }) => {
-      log("op rejected:", rejection.error, rejection.op);
-      this.publish();
-    });
-    engine.on("revoked", ({ code, message }) => {
-      log("connection revoked:", code, message);
-      void this.auth.reconcileSession("connection revoked", { forceRefresh: true, throttleMs: 0 }).catch(() => {
+  /**
+   * 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
+   */
+  syncLifecycle() {
+    const { engine, auth, profile } = this.binding;
+    if (!engine || !this.started) return;
+    const status = auth.authStatus;
+    if (status === "reauth_required") {
+      engine.pause();
+      return;
+    }
+    const localAllowed = this.anonymousEnabled || auth.isSignedIn || profile.kind === "account";
+    if (!localAllowed) return;
+    const schemaLocallyUsable = this.devInfo === null || this.devInfo.status !== "invalid";
+    if (!schemaLocallyUsable) return;
+    void engine.openLocal().then(() => {
+      if (this.binding.engine !== engine) return;
+      if (this.syncEnabled && auth.isSignedIn && auth.authStatus !== "reauth_required") {
+        return engine.connect();
+      }
+    }).catch((err) => log("sync lifecycle failed:", err));
+  }
+  /**
+   * After sign-in: bind the account identity to the active profile
+   * (anonymous → account upgrade) and dedupe against an existing profile
+   * for the same DID.
+   */
+  async maybeUpgradeProfile() {
+    const { profile, auth } = this.binding;
+    if (!this.users || auth.authStatus !== "authenticated" || !auth.did) return;
+    if (profile.id === "default") return;
+    const did = auth.did;
+    const user = auth.user;
+    const needsUpdate = profile.did !== did || profile.kind !== "account" || profile.email !== (user?.email ?? profile.email) || profile.name !== (user?.name ?? profile.name);
+    if (!needsUpdate) return;
+    await this.queueProfileOp(async () => {
+      if (this.binding.profile.id !== profile.id) return;
+      if (!this.users) return;
+      const existing = await this.users.findByDid(did);
+      if (existing && existing.id !== profile.id) {
+        log(`deduping user profiles for ${did}: dropping ${existing.id}`);
+        await this.disposeProfileData(existing);
+        await this.users.remove(existing.id);
+      }
+      const updated = await this.users.update(profile.id, {
+        kind: "account",
+        did,
+        email: user?.email ?? profile.email ?? null,
+        name: user?.name ?? profile.name ?? null,
+        picture: user?.picture ?? profile.picture ?? null,
+        lastActiveAt: Date.now()
       });
-      this.publish();
+      if (updated) {
+        this.binding.profile = updated;
+      }
+      await this.refreshUsers();
+    });
+  }
+  async refreshUsers() {
+    if (this.users) {
+      this.usersCache = await this.users.list();
+    }
+    this.publish();
+  }
+  queueProfileOp(task) {
+    this.profileOps = this.profileOps.then(task).catch((err) => {
+      log("profile operation failed:", err);
     });
+    return this.profileOps;
   }
   async checkSchema() {
     if (this.schemaChecked) return;
@@ -4087,7 +4739,7 @@ var BasicClient = class {
         this.syncEnabled = result.schemaStatus.valid || remoteCheckInconclusive && locallyPublishable;
         if (!result.schemaStatus.valid) {
           if (status === "unpublished") {
-            log("Schema not published (version 0) \u2014 sync is disabled until you publish.");
+            log("Schema not published (version 0) \u2014 sync is disabled, local-only mode.");
           } else if (remoteCheckInconclusive && locallyPublishable) {
             log("Schema registry check failed \u2014 proceeding with the local schema (offline-first).");
           }
@@ -4108,19 +4760,23 @@ var BasicClient = class {
     this.publish();
   }
   buildSnapshot() {
+    const { auth, engine, profile } = this.binding;
     return {
-      isReady: this.auth.isAuthReady,
-      isSignedIn: this.auth.isSignedIn,
-      authStatus: this.auth.authStatus,
-      authErrorCode: this.auth.authErrorCode,
-      user: this.auth.user,
-      did: this.auth.did,
-      scope: this.auth.tokenScope,
-      syncStatus: this.engine?.status ?? "idle",
-      pendingCount: this.engine?.pendingCount ?? 0,
+      isReady: auth.isAuthReady,
+      isSignedIn: auth.isSignedIn,
+      authStatus: auth.authStatus,
+      authErrorCode: auth.authErrorCode,
+      user: auth.user,
+      did: auth.did,
+      scope: auth.tokenScope,
+      syncStatus: engine?.status ?? "idle",
+      pendingCount: engine?.pendingCount ?? 0,
       syncEnabled: this.syncEnabled,
       devInfo: this.devInfo,
-      mode: this.mode
+      mode: this.mode,
+      users: this.usersCache,
+      activeUser: this.users ? profile : null,
+      isAnonymous: this.users ? profile.kind === "anon" && !auth.isSignedIn : false
     };
   }
   publish() {
@@ -4151,6 +4807,7 @@ function BasicProvider({
   storage,
   debug = false,
   mode = "sync",
+  anonymous = true,
   devToolbar = false,
   renderWhileLoading = false
 }) {
@@ -4162,7 +4819,8 @@ function BasicProvider({
       auth,
       storage,
       debug,
-      mode
+      mode,
+      anonymous
     });
   }
   const client = clientRef.current;
@@ -4194,6 +4852,7 @@ init_BasicDevToolbar();
   NotAuthenticatedError,
   OWN_SUB,
   PROTOCOL_VERSION,
+  PrefixedStorage,
   RestClient,
   RestDb,
   RestError,
@@ -4202,6 +4861,7 @@ init_BasicDevToolbar();
   SyncDb,
   SyncEngine,
   SyncStore,
+  UserRegistry,
   applyOpToData,
   createBasicClient,
   isAuthError,
@@ -4220,6 +4880,7 @@ init_BasicDevToolbar();
   useQuery,
   useShare,
   useShares,
-  useSyncStatus
+  useSyncStatus,
+  useUsers
 });
 //# sourceMappingURL=index.js.map