@abraca/dabra 1.5.0 → 1.6.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;
@@ -1499,6 +1524,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 +1838,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
 /**
@@ -2860,4 +2893,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, 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, 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.6.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();
 		}

package/src/TreeTimestamps.ts

@@ -8,47 +8,78 @@
  * This propagates "last edited" timestamps to all peers via the root CRDT,
  * without requiring any server-side changes.
  *
- * Limitation: at least one client must have the child doc open after an edit
- * for the timestamp to propagate (eventually consistent).
+ * A trailing-edge throttle (default 5 s) limits writes to avoid CRDT bloat
+ * on the root doc during rapid typing.
  */
 
 import * as Y from "yjs";
 import type { OfflineStore } from "./OfflineStore.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.
  */
 export function attachUpdatedAtObserver(
 	treeMap: Y.Map<any>,
 	childDocId: string,
 	childDoc: Y.Doc,
 	offlineStore: OfflineStore | null,
+	options?: { throttleMs?: number },
 ): () => void {
-	function handler(update: Uint8Array, origin: unknown): void {
-		// Skip updates replayed from the local offline store — they represent
-		// content that was already "seen" and shouldn't advance updatedAt.
-		if (offlineStore !== null && origin === offlineStore) return;
+	const throttleMs = options?.throttleMs ?? 5000;
+
+	let latestTs = 0;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+
+	function flush(): void {
+		if (latestTs === 0) return;
+		const ts = latestTs;
+		latestTs = 0;
+		timer = null;
 
-		// Update the root tree entry (no-op if the entry doesn't exist).
 		const raw = treeMap.get(childDocId);
 		if (!raw) return;
 
 		// Guard: if the entry is a nested Y.Map (possible after Yrs
 		// document compaction), convert to plain object so spread works.
 		const entry = raw instanceof Y.Map ? (raw as any).toJSON() : raw;
-		treeMap.set(childDocId, { ...entry, updatedAt: Date.now() });
+		treeMap.set(childDocId, { ...entry, updatedAt: ts });
+	}
+
+	function handler(_update: Uint8Array, origin: unknown): void {
+		// Skip updates replayed from the local offline store — they represent
+		// content that was already "seen" and shouldn't advance updatedAt.
+		if (offlineStore !== null && origin === offlineStore) return;
+
+		latestTs = Date.now();
+
+		// Schedule a trailing-edge flush if none is pending.
+		if (timer === null) {
+			timer = setTimeout(flush, throttleMs);
+		}
 	}
 
 	childDoc.on("update", handler);
-	return () => childDoc.off("update", handler);
+
+	return () => {
+		childDoc.off("update", handler);
+		if (timer !== null) {
+			clearTimeout(timer);
+			flush(); // persist the last pending timestamp
+		}
+	};
 }

package/src/types.ts

@@ -124,6 +124,12 @@ export type onStatelessParameters = {
   payload: string;
 };
 
+export type onServerErrorParameters = {
+  source: string;
+  code: string;
+  message: string;
+};
+
 export type StatesArray = { clientId: number; [key: string | number]: any }[];
 
 // ── Abracadabra extensions ────────────────────────────────────────────────────