@abraca/dabra 1.3.4 → 1.6.0

package/dist/abracadabra-provider.cjs

@@ -2317,6 +2317,7 @@ var AbracadabraBaseProvider = class extends EventEmitter {
 			onAwarenessUpdate: () => null,
 			onAwarenessChange: () => null,
 			onStateless: () => null,
+			onServerError: () => null,
 			onUnsyncedChanges: () => null
 		};
 		this.isSynced = false;
@@ -2348,6 +2349,7 @@ var AbracadabraBaseProvider = class 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);
 		this.on("authenticationFailed", this.configuration.onAuthenticationFailed);
@@ -2463,6 +2465,19 @@ var AbracadabraBaseProvider = class extends EventEmitter {
 		if (state) this.emit("synced", { state });
 	}
 	receiveStateless(payload) {
+		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 {}
 		this.emit("stateless", { payload });
 	}
 	async connect() {
@@ -2808,6 +2823,9 @@ function isValidDocId(id) {
 *     refreshed from the server on every reconnect.
 */
 var AbracadabraProvider = class AbracadabraProvider extends AbracadabraBaseProvider {
+	static {
+		this.MAX_CHILDREN = 20;
+	}
 	constructor(configuration) {
 		const resolved = { ...configuration };
 		const client = configuration.client ?? null;
@@ -2819,6 +2837,8 @@ var AbracadabraProvider = class AbracadabraProvider extends AbracadabraBaseProvi
 		this.effectiveRole = null;
 		this.childProviders = /* @__PURE__ */ new Map();
 		this.pendingLoads = /* @__PURE__ */ new Map();
+		this.childAccessTimes = /* @__PURE__ */ new Map();
+		this.pinnedChildren = /* @__PURE__ */ new Set();
 		this.boundHandleYSubdocsChange = this.handleYSubdocsChange.bind(this);
 		this._client = client;
 		this.abracadabraConfig = configuration;
@@ -3013,7 +3033,10 @@ var AbracadabraProvider = class AbracadabraProvider extends AbracadabraBaseProvi
 	*/
 	loadChild(childId) {
 		if (!isValidDocId(childId)) return Promise.reject(/* @__PURE__ */ new Error(`loadChild: "${childId}" is not a valid document ID (must be a UUID). If this node was created with an older version of the app, delete it and recreate it.`));
-		if (this.childProviders.has(childId)) return Promise.resolve(this.childProviders.get(childId));
+		if (this.childProviders.has(childId)) {
+			this.childAccessTimes.set(childId, Date.now());
+			return Promise.resolve(this.childProviders.get(childId));
+		}
 		if (this.pendingLoads.has(childId)) return this.pendingLoads.get(childId);
 		const load = this._doLoadChild(childId);
 		this.pendingLoads.set(childId, load);
@@ -3038,6 +3061,8 @@ var AbracadabraProvider = class AbracadabraProvider extends AbracadabraBaseProvi
 		});
 		childProvider.attach();
 		this.childProviders.set(childId, childProvider);
+		this.childAccessTimes.set(childId, Date.now());
+		this.evictLRU();
 		this.emit("subdocLoaded", {
 			childId,
 			provider: childProvider
@@ -3049,6 +3074,44 @@ var AbracadabraProvider = class AbracadabraProvider extends AbracadabraBaseProvi
 		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) {
+		this.pinnedChildren.add(childId);
+	}
+	/**
+	* Unpin a child, allowing LRU eviction to reclaim it when capacity is exceeded.
+	*/
+	unpinChild(childId) {
+		this.pinnedChildren.delete(childId);
+		this.evictLRU();
+	}
+	/**
+	* Evict least-recently-used unpinned child providers until the cache is
+	* at or below MAX_CHILDREN.
+	*/
+	evictLRU() {
+		if (this.childProviders.size <= AbracadabraProvider.MAX_CHILDREN) return;
+		const evictable = [];
+		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--;
 		}
 	}
 	/** Return all currently-loaded child providers. */
@@ -3108,6 +3171,8 @@ var AbracadabraProvider = class AbracadabraProvider extends AbracadabraBaseProvi
 		const childIds = [...this.childProviders.keys()];
 		for (const provider of this.childProviders.values()) provider.destroy();
 		this.childProviders.clear();
+		this.childAccessTimes.clear();
+		this.pinnedChildren.clear();
 		const wsProviderMap = this.configuration.websocketProvider?.configuration?.providerMap;
 		if (wsProviderMap) for (const childId of childIds) wsProviderMap.delete(childId);
 		this.offlineStore?.destroy();
@@ -3550,6 +3615,34 @@ var AbracadabraClient = class {
 	async adminStorageRepair() {
 		return this.request("POST", "/admin/storage/repair");
 	}
+	/** List snapshot metadata for a document. */
+	async listSnapshots(docId, opts) {
+		const params = new URLSearchParams();
+		if (opts?.limit != null) params.set("limit", String(opts.limit));
+		if (opts?.offset != null) params.set("offset", String(opts.offset));
+		const qs = params.toString();
+		return (await this.request("GET", `/docs/${encodeURIComponent(docId)}/snapshots${qs ? `?${qs}` : ""}`)).snapshots;
+	}
+	/** Fetch a single snapshot including its base64-encoded data blob. */
+	async getSnapshot(docId, version) {
+		return this.request("GET", `/docs/${encodeURIComponent(docId)}/snapshots/${version}`);
+	}
+	/** Create a manual snapshot of the current document state. */
+	async createSnapshot(docId, opts) {
+		return this.request("POST", `/docs/${encodeURIComponent(docId)}/snapshots`, { body: opts ?? {} });
+	}
+	/** Delete a specific snapshot version. Requires manage permission. */
+	async deleteSnapshot(docId, version) {
+		await this.request("DELETE", `/docs/${encodeURIComponent(docId)}/snapshots/${version}`);
+	}
+	/** Restore a snapshot by merging it forward into the current document state. */
+	async restoreSnapshot(docId, version) {
+		return this.request("POST", `/docs/${encodeURIComponent(docId)}/snapshots/${version}/restore`, { body: {} });
+	}
+	/** Fork a snapshot into a new document. */
+	async forkSnapshot(docId, version) {
+		return this.request("POST", `/docs/${encodeURIComponent(docId)}/snapshots/${version}/fork`, { body: {} });
+	}
 	/** Health check — no auth required. */
 	async health() {
 		return this.request("GET", "/health", { auth: false });
@@ -10878,35 +10971,57 @@ var E2EAbracadabraProvider = class E2EAbracadabraProvider extends AbracadabraPro
 * 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.
 */
 /**
-* 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.
+*
+* 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 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.
-*/
-function attachUpdatedAtObserver(treeMap, childDocId, childDoc, offlineStore) {
-	function handler(update, origin) {
-		if (offlineStore !== null && origin === offlineStore) return;
+* @param options       Optional config. `throttleMs` controls the write
+*                      interval (default 5000).
+* @returns             Cleanup function — call on provider destroy.  Flushes
+*                      any pending write before detaching.
+*/
+function attachUpdatedAtObserver(treeMap, childDocId, childDoc, offlineStore, options) {
+	const throttleMs = options?.throttleMs ?? 5e3;
+	let latestTs = 0;
+	let timer = null;
+	function flush() {
+		if (latestTs === 0) return;
+		const ts = latestTs;
+		latestTs = 0;
+		timer = null;
 		const raw = treeMap.get(childDocId);
 		if (!raw) return;
 		const entry = raw instanceof yjs.Map ? raw.toJSON() : raw;
 		treeMap.set(childDocId, {
 			...entry,
-			updatedAt: Date.now()
+			updatedAt: ts
 		});
 	}
+	function handler(_update, origin) {
+		if (offlineStore !== null && origin === offlineStore) return;
+		latestTs = Date.now();
+		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();
+		}
+	};
 }
 
 //#endregion
@@ -11176,7 +11291,7 @@ var BackgroundSyncManager = class extends EventEmitter {
 	async _syncWithSemaphore(docId, updatedAt) {
 		if (this._destroyed) return true;
 		const existing = this.syncStates.get(docId);
-		if (existing && existing.status === "synced" && existing.lastSynced !== null && existing.lastSynced >= updatedAt) {
+		if (existing && existing.status === "synced" && existing.lastSynced !== null && existing.lastSynced + 200 >= updatedAt) {
 			this.emit("stateChanged", {
 				docId,
 				state: existing
@@ -11228,6 +11343,7 @@ var BackgroundSyncManager = class extends EventEmitter {
 		}
 	}
 	async _syncNonE2EDoc(docId) {
+		const treeMap = this.rootProvider.document.getMap("doc-tree");
 		const alreadyCached = this.rootProvider.children.has(docId);
 		if (!alreadyCached) {
 			if ((this.rootProvider.configuration?.websocketProvider?.configuration?.providerMap)?.has(docId)) return {
@@ -11238,27 +11354,33 @@ var BackgroundSyncManager = class extends EventEmitter {
 			};
 		}
 		const childProvider = await this.rootProvider.loadChild(docId);
-		await childProvider.ready;
-		await this._waitForSynced(childProvider);
-		{
-			const treeEntry = this.rootProvider.document.getMap("doc-tree").get(docId);
-			this.emit("docSynced", {
+		try {
+			await childProvider.ready;
+			await this._waitForSynced(childProvider);
+			{
+				const treeEntry = treeMap.get(docId);
+				this.emit("docSynced", {
+					docId,
+					document: childProvider.document,
+					label: treeEntry?.label ?? "",
+					meta: treeEntry?.meta
+				});
+			}
+			if (this.opts.prefetchFiles && this.fileBlobStore) this._prefetchDocFiles(docId, childProvider.document).catch(() => null);
+			const treeEntry = treeMap.get(docId);
+			const treeUpdatedAt = treeEntry?.updatedAt ?? treeEntry?.createdAt ?? 0;
+			return {
 				docId,
-				document: childProvider.document,
-				label: treeEntry?.label ?? "",
-				meta: treeEntry?.meta
-			});
+				status: "synced",
+				lastSynced: Math.max(Date.now(), treeUpdatedAt),
+				isE2E: false
+			};
+		} finally {
+			if (!alreadyCached) this.rootProvider.unloadChild(docId);
 		}
-		if (this.opts.prefetchFiles && this.fileBlobStore) this._prefetchDocFiles(docId, childProvider.document).catch(() => null);
-		if (!alreadyCached) this.rootProvider.unloadChild(docId);
-		return {
-			docId,
-			status: "synced",
-			lastSynced: Date.now(),
-			isE2E: false
-		};
 	}
 	async _syncE2EDoc(docId) {
+		const treeMap = this.rootProvider.document.getMap("doc-tree");
 		const docKeyManager = this.rootProvider.abracadabraConfig?.docKeyManager;
 		const keystore = this.rootProvider.abracadabraConfig?.keystore;
 		if (!docKeyManager || !keystore) return {
@@ -11279,7 +11401,7 @@ var BackgroundSyncManager = class extends EventEmitter {
 			await childProvider.ready;
 			await this._waitForSynced(childProvider);
 			{
-				const treeEntry = this.rootProvider.document.getMap("doc-tree").get(docId);
+				const treeEntry = treeMap.get(docId);
 				this.emit("docSynced", {
 					docId,
 					document: childDoc,
@@ -11288,10 +11410,12 @@ var BackgroundSyncManager = class extends EventEmitter {
 				});
 			}
 			if (this.opts.prefetchFiles && this.fileBlobStore) this._prefetchDocFiles(docId, childDoc).catch(() => null);
+			const treeEntry = treeMap.get(docId);
+			const treeUpdatedAt = treeEntry?.updatedAt ?? treeEntry?.createdAt ?? 0;
 			return {
 				docId,
 				status: "synced",
-				lastSynced: Date.now(),
+				lastSynced: Math.max(Date.now(), treeUpdatedAt),
 				isE2E: true
 			};
 		} finally {