@abraca/dabra 1.5.0 → 1.8.0

package/dist/index.d.ts

@@ -811,6 +811,12 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   private childProviders;
   private pendingLoads;
   private subdocLoading;
+  /** LRU tracking: childId → last access timestamp */
+  private childAccessTimes;
+  /** Pinned children that must not be evicted (e.g. actively viewed docs) */
+  private pinnedChildren;
+  /** Max simultaneously cached child providers before LRU eviction kicks in */
+  private static readonly MAX_CHILDREN;
   private abracadabraConfig;
   private readonly boundHandleYSubdocsChange;
   /**
@@ -884,6 +890,20 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   loadChild(childId: string): Promise<AbracadabraProvider>;
   private _doLoadChild;
   unloadChild(childId: string): void;
+  /**
+   * Mark a child as pinned so LRU eviction will not remove it.
+   * Use this when a document is actively being viewed by the user.
+   */
+  pinChild(childId: string): void;
+  /**
+   * Unpin a child, allowing LRU eviction to reclaim it when capacity is exceeded.
+   */
+  unpinChild(childId: string): void;
+  /**
+   * Evict least-recently-used unpinned child providers until the cache is
+   * at or below MAX_CHILDREN.
+   */
+  private evictLRU;
   /** Return all currently-loaded child providers. */
   get children(): Map<string, AbracadabraProvider>;
   /**
@@ -1133,6 +1153,11 @@ type onAwarenessChangeParameters = {
 type onStatelessParameters = {
   payload: string;
 };
+type onServerErrorParameters = {
+  source: string;
+  code: string;
+  message: string;
+};
 type StatesArray = {
   clientId: number;
   [key: string | number]: any;
@@ -1319,6 +1344,77 @@ interface DocEncryptionInfo {
   effective_mode: "none" | "cse" | "e2e";
   inherited_from?: string;
 }
+interface ChatMessage {
+  id: string;
+  channel: string;
+  sender_id: string;
+  sender_name?: string | null;
+  content: string;
+  created_at: number;
+}
+interface ChatChannel {
+  channel: string;
+  label?: string | null;
+  last_message: ChatMessage;
+  unread_count: number;
+}
+interface ChatTypingEvent {
+  channel: string;
+  sender_id: string;
+  sender_name?: string | null;
+}
+interface ChatReadReceipt {
+  channel: string;
+  user_id: string;
+  last_read_at: number;
+}
+interface ChatReadCursor {
+  user_id: string;
+  last_read_at: number;
+}
+interface SendChatMessageInput {
+  channel: string;
+  content: string;
+  sender_name?: string;
+}
+interface GetChatHistoryInput {
+  channel: string;
+  before?: number;
+  limit?: number;
+}
+interface NotificationRecord {
+  id: string;
+  recipient_id: string;
+  notification_type: string;
+  title: string;
+  body: string;
+  icon?: string | null;
+  link?: string | null;
+  source_id?: string | null;
+  read: boolean;
+  created_at: number;
+}
+interface NotificationReadUpdate {
+  /** Present when a specific set of notifications was marked read. */
+  ids?: string[];
+  /** Present when mark_all_read was called. */
+  all?: boolean;
+  recipient_id: string;
+}
+interface CreateNotificationInput {
+  recipient_id: string;
+  notification_type?: string;
+  title: string;
+  body?: string;
+  icon?: string;
+  link?: string;
+  source_id?: string;
+}
+interface FetchNotificationsInput {
+  before?: number;
+  limit?: number;
+  unread_only?: boolean;
+}
 //#endregion
 //#region packages/provider/src/AbracadabraWS.d.ts
 type AbracadabraWebSocketConn = WebSocket & {
@@ -1499,6 +1595,7 @@ interface CompleteAbracadabraBaseProviderConfiguration {
   onAwarenessUpdate: (data: onAwarenessUpdateParameters) => void;
   onAwarenessChange: (data: onAwarenessChangeParameters) => void;
   onStateless: (data: onStatelessParameters) => void;
+  onServerError: (data: onServerErrorParameters) => void;
   onUnsyncedChanges: (data: onUnsyncedChangesParameters) => void;
 }
 /** @deprecated Use CompleteAbracadabraBaseProviderConfiguration */
@@ -1812,19 +1909,26 @@ declare function makeEncryptedYText(ydoc: Y.Doc, fieldName: string, docKey: Cryp
 //#endregion
 //#region packages/provider/src/TreeTimestamps.d.ts
 /**
- * Attach an observer that writes `updatedAt: Date.now()` to the root
- * doc-tree entry for `childDocId` whenever the child doc receives a
- * non-offline update.
+ * Attach an observer that writes `updatedAt` to the root doc-tree entry for
+ * `childDocId` whenever the child doc receives a non-offline update.
  *
- * @param treeMap     The root doc's "doc-tree" Y.Map.
- * @param childDocId  The child document's UUID (key in treeMap).
- * @param childDoc    The child Y.Doc to observe.
+ * Writes are throttled: the first qualifying update records the timestamp;
+ * a trailing-edge timer flushes it to the tree map after `throttleMs`.
+ *
+ * @param treeMap       The root doc's "doc-tree" Y.Map.
+ * @param childDocId    The child document's UUID (key in treeMap).
+ * @param childDoc      The child Y.Doc to observe.
  * @param offlineStore  The child provider's OfflineStore (used to detect
  *                      offline-replay origins and skip them). Pass null when
  *                      the offline store is disabled.
- * @returns           Cleanup function — call on provider destroy.
+ * @param options       Optional config. `throttleMs` controls the write
+ *                      interval (default 5000).
+ * @returns             Cleanup function — call on provider destroy.  Flushes
+ *                      any pending write before detaching.
  */
-declare function attachUpdatedAtObserver(treeMap: Y.Map<any>, childDocId: string, childDoc: Y.Doc, offlineStore: OfflineStore | null): () => void;
+declare function attachUpdatedAtObserver(treeMap: Y.Map<any>, childDocId: string, childDoc: Y.Doc, offlineStore: OfflineStore | null, options?: {
+  throttleMs?: number;
+}): () => void;
 //#endregion
 //#region packages/provider/src/BackgroundSyncPersistence.d.ts
 /**
@@ -2501,14 +2605,22 @@ declare class DevicePairingChannel extends EventEmitter {
   /**
    * Approve the pending pairing request. Calls `client.addKey()` to
    * register Device B's public key, then notifies Device B.
+   *
+   * @param client Authenticated REST client.
+   * @param masterPublicKey Approver's account-level Ed25519 public key (base64url).
+   *   Sent to Device B so it can adopt the master's identity doc.
    */
-  approve(client: AbracadabraClient): Promise<PairingResult>;
+  approve(client: AbracadabraClient, masterPublicKey?: string): Promise<PairingResult>;
   /**
    * Approve via server-side device invite. Creates a single-use invite code
    * and sends it to Device B over the E2EE channel. Device B redeems it
    * independently via HTTP — Device A can go offline after this.
+   *
+   * @param client Authenticated REST client.
+   * @param masterPublicKey Approver's account-level Ed25519 public key (base64url).
+   *   Sent to Device B so it can adopt the master's identity doc.
    */
-  approveWithInvite(client: AbracadabraClient): Promise<PairingResult>;
+  approveWithInvite(client: AbracadabraClient, masterPublicKey?: string): Promise<PairingResult>;
   /**
    * Reject the pending pairing request.
    */
@@ -2728,6 +2840,12 @@ declare class IdentityDocProvider extends EventEmitter {
    * Call this to decide whether to run migration from localStorage.
    */
   isEmpty(): boolean;
+  /**
+   * Enable WebRTC P2P sync at runtime.
+   * Use this for claimed/passkey users where E2EE identity derivation
+   * was deferred to avoid biometric prompts on page load.
+   */
+  enableWebRTC(webrtcConfig: NonNullable<IdentityDocConfiguration["webrtc"]>): void;
   /**
    * Update the sync server URL at runtime (e.g. when user changes their
    * designated sync server in settings).
@@ -2793,6 +2911,111 @@ declare class DeviceRegistrationService {
   }): Promise<void>;
 }
 //#endregion
+//#region packages/provider/src/ChatClient.d.ts
+/**
+ * Minimal provider surface ChatClient needs. Matches `AbracadabraBaseProvider`.
+ * Kept as an interface so consumers can pass any compatible transport.
+ */
+interface ChatClientTransport {
+  sendStateless(payload: string): void;
+  on(event: string, fn: Function): unknown;
+  off(event: string, fn?: Function): unknown;
+}
+/**
+ * Typed client for the Abracadabra chat feature.
+ *
+ * Wraps a connected provider (or base provider) and translates JSON envelopes
+ * on the stateless channel into typed method calls and events.
+ *
+ * Events emitted:
+ *   - `message`      → ChatMessage       (new message broadcast)
+ *   - `typing`       → ChatTypingEvent   (typing indicator broadcast)
+ *   - `readReceipt`  → ChatReadReceipt   (mark_read broadcast)
+ */
+declare class ChatClient extends EventEmitter {
+  private readonly provider;
+  private readonly responseTimeoutMs;
+  private readonly pending;
+  private readonly boundOnStateless;
+  constructor(provider: ChatClientTransport, options?: {
+    responseTimeoutMs?: number;
+  });
+  /** Stop listening for chat messages. Does not disconnect the underlying provider. */
+  destroy(): void;
+  /** Send a chat message on a channel. Fire-and-forget (the server broadcasts). */
+  sendMessage(input: SendChatMessageInput): void;
+  /** Fetch historical messages for a channel. Resolves with the server response. */
+  getHistory(input: GetChatHistoryInput): Promise<{
+    channel: string;
+    messages: ChatMessage[];
+  }>;
+  /** Broadcast a typing indicator on a channel. */
+  sendTyping(channel: string): void;
+  /** List the current user's channels (ordered by last activity). */
+  listChannels(): Promise<{
+    channels: ChatChannel[];
+  }>;
+  /** Mark a channel read up to `timestamp` (unix ms). */
+  markRead(channel: string, timestamp: number): void;
+  /** Fetch per-user read cursors for a channel. */
+  getReadCursors(channel: string): Promise<{
+    channel: string;
+    cursors: ChatReadCursor[];
+  }>;
+  onMessage(fn: (m: ChatMessage) => void): this;
+  onTyping(fn: (e: ChatTypingEvent) => void): this;
+  onReadReceipt(fn: (e: ChatReadReceipt) => void): this;
+  private enqueue;
+  private removePending;
+  private resolveNext;
+  private handleStateless;
+}
+//#endregion
+//#region packages/provider/src/NotificationsClient.d.ts
+/**
+ * Typed client for the Abracadabra notifications feature.
+ *
+ * Emits:
+ *   - `new`        → NotificationRecord      (incoming notify:new broadcast)
+ *   - `readUpdate` → NotificationReadUpdate  (broadcast after mark_read / mark_all_read)
+ */
+declare class NotificationsClient extends EventEmitter {
+  private readonly provider;
+  private readonly responseTimeoutMs;
+  private readonly pending;
+  private readonly boundOnStateless;
+  constructor(provider: ChatClientTransport, options?: {
+    responseTimeoutMs?: number;
+  });
+  destroy(): void;
+  /**
+   * Create a notification targeting a specific recipient. Requires elevated role
+   * (service or admin); a `server:error` event with code `forbidden` is emitted
+   * by the underlying provider if the caller lacks permission.
+   */
+  create(input: CreateNotificationInput): void;
+  /** Fetch notification history for the current user. */
+  fetch(input?: FetchNotificationsInput): Promise<{
+    notifications: NotificationRecord[];
+  }>;
+  /** Mark a single notification, or a batch, as read. */
+  markRead(target: {
+    id: string;
+  } | {
+    ids: string[];
+  }): void;
+  /** Mark every notification for the current user as read. */
+  markAllRead(): void;
+  /** Mark all notifications generated by the given source (e.g. a chat channel) as read. */
+  markReadBySource(sourceId: string): void;
+  onNew(fn: (n: NotificationRecord) => void): this;
+  onReadUpdate(fn: (u: NotificationReadUpdate) => void): this;
+  private enqueue;
+  private removePending;
+  private resolveNext;
+  private handleStateless;
+}
+//#endregion
 //#region node_modules/@scure/bip39/esm/wordlists/english.d.ts
 declare const wordlist: string[];
 //#endregion
@@ -2860,4 +3083,4 @@ declare function wrapSeed(seed: Uint8Array, wrappingKeyBytes: Uint8Array): Promi
  */
 declare function unwrapSeed(ciphertext: ArrayBuffer, iv: Uint8Array, wrappingKeyBytes: Uint8Array): Promise<Uint8Array>;
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptField, generateMnemonic, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, unwrapSeed, validateMnemonic, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, type ChatChannel, ChatClient, type ChatClientTransport, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceTier, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedYMap, EncryptedYText, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, InviteRow, KEY_EXCHANGE_CHANNEL, ManualSignaling, type ManualSignalingBlob, MessageTooBig, MessageType, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, type SendChatMessageInput, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptField, generateMnemonic, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, unwrapSeed, validateMnemonic, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.5.0",
+  "version": "1.8.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraBaseProvider.ts

@@ -25,6 +25,7 @@ import type {
   onMessageParameters,
   onOpenParameters,
   onOutgoingMessageParameters,
+  onServerErrorParameters,
   onStatelessParameters,
   onStatusParameters,
   onSyncedParameters,
@@ -95,6 +96,7 @@ export interface CompleteAbracadabraBaseProviderConfiguration {
   onAwarenessUpdate: (data: onAwarenessUpdateParameters) => void;
   onAwarenessChange: (data: onAwarenessChangeParameters) => void;
   onStateless: (data: onStatelessParameters) => void;
+  onServerError: (data: onServerErrorParameters) => void;
   onUnsyncedChanges: (data: onUnsyncedChangesParameters) => void;
 }
 
@@ -129,6 +131,7 @@ export class AbracadabraBaseProvider extends EventEmitter {
     onAwarenessUpdate: () => null,
     onAwarenessChange: () => null,
     onStateless: () => null,
+    onServerError: () => null,
     onUnsyncedChanges: () => null,
   };
 
@@ -172,6 +175,7 @@ export class AbracadabraBaseProvider extends EventEmitter {
     this.on("awarenessUpdate", this.configuration.onAwarenessUpdate);
     this.on("awarenessChange", this.configuration.onAwarenessChange);
     this.on("stateless", this.configuration.onStateless);
+    this.on("serverError", this.configuration.onServerError);
     this.on("unsyncedChanges", this.configuration.onUnsyncedChanges);
 
     this.on("authenticated", this.configuration.onAuthenticated);
@@ -368,6 +372,17 @@ export class AbracadabraBaseProvider extends EventEmitter {
   }
 
   receiveStateless(payload: string) {
+    try {
+      const parsed = JSON.parse(payload);
+      if (parsed?.type === "error" && parsed.source && parsed.code) {
+        const { source, code, message } = parsed;
+        console.warn(`[Abracadabra] Server error: ${source} (${code}) — ${message}`);
+        this.emit("serverError", { source, code, message: message ?? "" });
+        return;
+      }
+    } catch {
+      // not JSON — fall through to generic stateless event
+    }
     this.emit("stateless", { payload });
   }
 

package/src/AbracadabraProvider.ts

@@ -110,6 +110,13 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	private pendingLoads = new Map<string, Promise<AbracadabraProvider>>();
 	private subdocLoading: "lazy" | "eager";
 
+	/** LRU tracking: childId → last access timestamp */
+	private childAccessTimes = new Map<string, number>();
+	/** Pinned children that must not be evicted (e.g. actively viewed docs) */
+	private pinnedChildren = new Set<string>();
+	/** Max simultaneously cached child providers before LRU eviction kicks in */
+	private static readonly MAX_CHILDREN = 20;
+
 	private abracadabraConfig: AbracadabraProviderConfiguration;
 
 	private readonly boundHandleYSubdocsChange = this.handleYSubdocsChange.bind(this);
@@ -454,6 +461,7 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		}
 
 		if (this.childProviders.has(childId)) {
+			this.childAccessTimes.set(childId, Date.now());
 			return Promise.resolve(this.childProviders.get(childId)!);
 		}
 
@@ -500,6 +508,10 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		childProvider.attach();
 
 		this.childProviders.set(childId, childProvider);
+		this.childAccessTimes.set(childId, Date.now());
+
+		// Evict least-recently-used children if over capacity
+		this.evictLRU();
 
 		this.emit("subdocLoaded", { childId, provider: childProvider });
 
@@ -511,6 +523,48 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		if (provider) {
 			provider.destroy();
 			this.childProviders.delete(childId);
+			this.childAccessTimes.delete(childId);
+			this.pinnedChildren.delete(childId);
+		}
+	}
+
+	/**
+	 * Mark a child as pinned so LRU eviction will not remove it.
+	 * Use this when a document is actively being viewed by the user.
+	 */
+	pinChild(childId: string) {
+		this.pinnedChildren.add(childId);
+	}
+
+	/**
+	 * Unpin a child, allowing LRU eviction to reclaim it when capacity is exceeded.
+	 */
+	unpinChild(childId: string) {
+		this.pinnedChildren.delete(childId);
+		// Run eviction now in case we're over capacity
+		this.evictLRU();
+	}
+
+	/**
+	 * Evict least-recently-used unpinned child providers until the cache is
+	 * at or below MAX_CHILDREN.
+	 */
+	private evictLRU() {
+		if (this.childProviders.size <= AbracadabraProvider.MAX_CHILDREN) return;
+
+		// Build a list of evictable children sorted by last access (oldest first)
+		const evictable: Array<{ id: string; accessTime: number }> = [];
+		for (const [id] of this.childProviders) {
+			if (this.pinnedChildren.has(id)) continue;
+			evictable.push({ id, accessTime: this.childAccessTimes.get(id) ?? 0 });
+		}
+		evictable.sort((a, b) => a.accessTime - b.accessTime);
+
+		let toEvict = this.childProviders.size - AbracadabraProvider.MAX_CHILDREN;
+		for (const entry of evictable) {
+			if (toEvict <= 0) break;
+			this.unloadChild(entry.id);
+			toEvict--;
 		}
 	}
 
@@ -605,6 +659,8 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			provider.destroy();
 		}
 		this.childProviders.clear();
+		this.childAccessTimes.clear();
+		this.pinnedChildren.clear();
 
 		// Force-clear any stale providerMap entries for our children.
 		// detach() only removes if current === provider, so orphans can remain

package/src/BackgroundSyncManager.ts

@@ -328,13 +328,15 @@ export class BackgroundSyncManager extends EventEmitter {
 	): Promise<boolean> {
 		if (this._destroyed) return true;
 
-		// Skip if already synced and doc hasn't changed since last sync
+		// Skip if already synced and doc hasn't changed since last sync.
+		// The 200ms grace margin handles edge cases where the updatedAt
+		// observer writes a timestamp milliseconds after lastSynced was recorded.
 		const existing = this.syncStates.get(docId);
 		if (
 			existing &&
 			existing.status === "synced" &&
 			existing.lastSynced !== null &&
-			existing.lastSynced >= updatedAt
+			existing.lastSynced + 200 >= updatedAt
 		) {
 			this.emit("stateChanged", { docId, state: existing });
 			return true;
@@ -391,6 +393,8 @@ export class BackgroundSyncManager extends EventEmitter {
 	}
 
 	private async _syncNonE2EDoc(docId: string): Promise<DocSyncState> {
+		const treeMap = this.rootProvider.document.getMap("doc-tree") as Y.Map<any>;
+
 		// Check if the provider already exists (user is viewing it) before loading.
 		const alreadyCached = this.rootProvider.children.has(docId);
 
@@ -415,39 +419,46 @@ export class BackgroundSyncManager extends EventEmitter {
 
 		const childProvider = await this.rootProvider.loadChild(docId);
 
-		// Wait for ready (offline snapshot loaded) then synced (server sync done)
-		await childProvider.ready;
-		await this._waitForSynced(childProvider);
+		try {
+			// Wait for ready (offline snapshot loaded) then synced (server sync done)
+			await childProvider.ready;
+			await this._waitForSynced(childProvider);
 
-		// Emit docSynced while the child is still loaded so listeners can
-		// extract data (search text, file refs) without opening a new IDB.
-		{
-			const treeMap = this.rootProvider.document.getMap("doc-tree") as Y.Map<any>;
-			const treeEntry = treeMap.get(docId);
-			this.emit("docSynced", {
-				docId,
-				document: childProvider.document,
-				label: treeEntry?.label ?? "",
-				meta: treeEntry?.meta,
-			});
-		}
+			// Emit docSynced while the child is still loaded so listeners can
+			// extract data (search text, file refs) without opening a new IDB.
+			{
+				const treeEntry = treeMap.get(docId);
+				this.emit("docSynced", {
+					docId,
+					document: childProvider.document,
+					label: treeEntry?.label ?? "",
+					meta: treeEntry?.meta,
+				});
+			}
 
-		// Prefetch file blobs
-		if (this.opts.prefetchFiles && this.fileBlobStore) {
-			this._prefetchDocFiles(docId, childProvider.document).catch(() => null);
-		}
+			// Prefetch file blobs
+			if (this.opts.prefetchFiles && this.fileBlobStore) {
+				this._prefetchDocFiles(docId, childProvider.document).catch(() => null);
+			}
 
-		// Release provider if it was created solely for background sync.
-		// This closes its IDB database, freeing the file descriptor.
-		// Providers that were already cached (user is viewing them) are kept alive.
-		if (!alreadyCached) {
-			this.rootProvider.unloadChild(docId);
+			// Use the tree's updatedAt so lastSynced >= updatedAt, preventing
+			// the observer's timestamp write from triggering a spurious re-sync.
+			const treeEntry = treeMap.get(docId);
+			const treeUpdatedAt = treeEntry?.updatedAt ?? treeEntry?.createdAt ?? 0;
+			return { docId, status: "synced", lastSynced: Math.max(Date.now(), treeUpdatedAt), isE2E: false };
+		} finally {
+			// Always release the provider if it was created solely for background sync.
+			// This closes its IDB database, freeing the file descriptor.
+			// Providers that were already cached (user is viewing them) are kept alive.
+			if (!alreadyCached) {
+				this.rootProvider.unloadChild(docId);
+			}
 		}
-
-		return { docId, status: "synced", lastSynced: Date.now(), isE2E: false };
 	}
 
 	private async _syncE2EDoc(docId: string): Promise<DocSyncState> {
+		const treeMap = this.rootProvider.document.getMap("doc-tree") as Y.Map<any>;
+
 		// Attempt E2E sync only when docKeyManager and keystore are available
 		const docKeyManager = (this.rootProvider as any).abracadabraConfig
 			?.docKeyManager;
@@ -474,7 +485,6 @@ export class BackgroundSyncManager extends EventEmitter {
 			// Emit docSynced while the child is still alive so listeners can
 			// extract data without opening a new IDB connection.
 			{
-				const treeMap = this.rootProvider.document.getMap("doc-tree") as Y.Map<any>;
 				const treeEntry = treeMap.get(docId);
 				this.emit("docSynced", {
 					docId,
@@ -488,7 +498,11 @@ export class BackgroundSyncManager extends EventEmitter {
 				this._prefetchDocFiles(docId, childDoc).catch(() => null);
 			}
 
-			return { docId, status: "synced", lastSynced: Date.now(), isE2E: true };
+			// Use the tree's updatedAt so lastSynced >= updatedAt, preventing
+			// the observer's timestamp write from triggering a spurious re-sync.
+			const treeEntry = treeMap.get(docId);
+			const treeUpdatedAt = treeEntry?.updatedAt ?? treeEntry?.createdAt ?? 0;
+			return { docId, status: "synced", lastSynced: Math.max(Date.now(), treeUpdatedAt), isE2E: true };
 		} finally {
 			childProvider.destroy();
 		}