loro-repo 0.0.0 → 0.2.0

package/dist/index.js

@@ -1,8 +1,11 @@
 import { Flock } from "@loro-dev/flock";
 import { LoroDoc } from "loro-crdt";
-import { FlockAdaptor, createLoroAdaptorFromDoc } from "loro-adaptors";
+import { FlockAdaptor, LoroAdaptor } from "loro-adaptors";
 import { CrdtType, bytesToHex } from "loro-protocol";
 import { LoroWebsocketClient } from "loro-websocket";
+import { promises } from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
 
 //#region src/loro-adaptor.ts
 function createRepoFlockAdaptorFromDoc(flock, config = {}) {
@@ -195,7 +198,7 @@ var WebSocketTransportAdapter = class {
 		const auth = params.auth ?? this.options.docAuth?.(docId);
 		if (existing && existing.doc === doc && existing.roomId === roomId) return existing;
 		if (existing) await this.leaveDocSession(docId).catch(() => {});
-		const adaptor = createLoroAdaptorFromDoc(doc);
+		const adaptor = new LoroAdaptor(doc);
 		const room = await client.join({
 			roomId,
 			crdtAdaptor: adaptor,
@@ -483,7 +486,7 @@ const DEFAULT_META_STORE = "meta";
 const DEFAULT_ASSET_STORE = "assets";
 const DEFAULT_DOC_UPDATE_STORE = "doc-updates";
 const DEFAULT_META_KEY = "snapshot";
-const textDecoder = new TextDecoder();
+const textDecoder$1 = new TextDecoder();
 function describeUnknown(cause) {
 	if (typeof cause === "string") return cause;
 	if (typeof cause === "number" || typeof cause === "boolean") return String(cause);
@@ -584,7 +587,7 @@ var IndexedDBStorageAdaptor = class {
 		const bytes = await this.getBinary(this.metaStore, this.metaKey);
 		if (!bytes) return void 0;
 		try {
-			const json = textDecoder.decode(bytes);
+			const json = textDecoder$1.decode(bytes);
 			const bundle = JSON.parse(json);
 			const flock = new Flock();
 			flock.importJson(bundle);
@@ -728,15 +731,224 @@ var IndexedDBStorageAdaptor = class {
 };
 
 //#endregion
-//#region src/index.ts
-const textEncoder = new TextEncoder();
-const DEFAULT_DOC_FRONTIER_DEBOUNCE_MS = 1e3;
-function logAsyncError(context) {
-	return (error) => {
-		if (error instanceof Error) console.error(`[loro-repo] ${context} failed: ${error.message}`, error);
-		else console.error(`[loro-repo] ${context} failed with non-error reason:`, error);
-	};
+//#region src/storage/filesystem.ts
+const textDecoder = new TextDecoder();
+var FileSystemStorageAdaptor = class {
+	baseDir;
+	docsDir;
+	assetsDir;
+	metaPath;
+	initPromise;
+	updateCounter = 0;
+	constructor(options = {}) {
+		this.baseDir = path.resolve(options.baseDir ?? path.join(process.cwd(), ".loro-repo"));
+		this.docsDir = path.join(this.baseDir, options.docsDirName ?? "docs");
+		this.assetsDir = path.join(this.baseDir, options.assetsDirName ?? "assets");
+		this.metaPath = path.join(this.baseDir, options.metaFileName ?? "meta.json");
+		this.initPromise = this.ensureLayout();
+	}
+	async save(payload) {
+		await this.initPromise;
+		switch (payload.type) {
+			case "doc-snapshot":
+				await this.writeDocSnapshot(payload.docId, payload.snapshot);
+				return;
+			case "doc-update":
+				await this.enqueueDocUpdate(payload.docId, payload.update);
+				return;
+			case "asset":
+				await this.writeAsset(payload.assetId, payload.data);
+				return;
+			case "meta":
+				await writeFileAtomic(this.metaPath, payload.update);
+				return;
+			default: throw new Error(`Unsupported payload type: ${payload.type}`);
+		}
+	}
+	async deleteAsset(assetId) {
+		await this.initPromise;
+		await removeIfExists(this.assetPath(assetId));
+	}
+	async loadDoc(docId) {
+		await this.initPromise;
+		const snapshotBytes = await readFileIfExists(this.docSnapshotPath(docId));
+		const updateDir = this.docUpdatesDir(docId);
+		const updateFiles = await listFiles(updateDir);
+		if (!snapshotBytes && updateFiles.length === 0) return;
+		const doc = snapshotBytes ? LoroDoc.fromSnapshot(snapshotBytes) : new LoroDoc();
+		if (updateFiles.length === 0) return doc;
+		const updatePaths = updateFiles.map((file) => path.join(updateDir, file));
+		for (const updatePath of updatePaths) {
+			const update = await readFileIfExists(updatePath);
+			if (!update) continue;
+			doc.import(update);
+		}
+		await Promise.all(updatePaths.map((filePath) => removeIfExists(filePath)));
+		const consolidated = doc.export({ mode: "snapshot" });
+		await this.writeDocSnapshot(docId, consolidated);
+		return doc;
+	}
+	async loadMeta() {
+		await this.initPromise;
+		const bytes = await readFileIfExists(this.metaPath);
+		if (!bytes) return void 0;
+		try {
+			const bundle = JSON.parse(textDecoder.decode(bytes));
+			const flock = new Flock();
+			flock.importJson(bundle);
+			return flock;
+		} catch (error) {
+			throw new Error("Failed to hydrate metadata snapshot", { cause: error });
+		}
+	}
+	async loadAsset(assetId) {
+		await this.initPromise;
+		return readFileIfExists(this.assetPath(assetId));
+	}
+	async ensureLayout() {
+		await Promise.all([
+			ensureDir(this.baseDir),
+			ensureDir(this.docsDir),
+			ensureDir(this.assetsDir)
+		]);
+	}
+	async writeDocSnapshot(docId, snapshot) {
+		await ensureDir(this.docDir(docId));
+		await writeFileAtomic(this.docSnapshotPath(docId), snapshot);
+	}
+	async enqueueDocUpdate(docId, update) {
+		const dir = this.docUpdatesDir(docId);
+		await ensureDir(dir);
+		const counter = this.updateCounter = (this.updateCounter + 1) % 1e6;
+		const fileName = `${Date.now().toString().padStart(13, "0")}-${counter.toString().padStart(6, "0")}.bin`;
+		await writeFileAtomic(path.join(dir, fileName), update);
+	}
+	async writeAsset(assetId, data) {
+		const filePath = this.assetPath(assetId);
+		await ensureDir(path.dirname(filePath));
+		await writeFileAtomic(filePath, data);
+	}
+	docDir(docId) {
+		return path.join(this.docsDir, encodeComponent(docId));
+	}
+	docSnapshotPath(docId) {
+		return path.join(this.docDir(docId), "snapshot.bin");
+	}
+	docUpdatesDir(docId) {
+		return path.join(this.docDir(docId), "updates");
+	}
+	assetPath(assetId) {
+		return path.join(this.assetsDir, encodeComponent(assetId));
+	}
+};
+function encodeComponent(value) {
+	return Buffer.from(value, "utf8").toString("base64url");
+}
+async function ensureDir(dir) {
+	await promises.mkdir(dir, { recursive: true });
 }
+async function readFileIfExists(filePath) {
+	try {
+		const data = await promises.readFile(filePath);
+		return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+async function removeIfExists(filePath) {
+	try {
+		await promises.rm(filePath);
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+async function listFiles(dir) {
+	try {
+		return (await promises.readdir(dir)).sort();
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+async function writeFileAtomic(targetPath, data) {
+	const dir = path.dirname(targetPath);
+	await ensureDir(dir);
+	const tempPath = path.join(dir, `.tmp-${randomUUID()}`);
+	await promises.writeFile(tempPath, data);
+	await promises.rename(tempPath, targetPath);
+}
+
+//#endregion
+//#region src/internal/event-bus.ts
+var RepoEventBus = class {
+	watchers = /* @__PURE__ */ new Set();
+	eventByStack = [];
+	watch(listener, filter = {}) {
+		const entry = {
+			listener,
+			filter
+		};
+		this.watchers.add(entry);
+		return { unsubscribe: () => {
+			this.watchers.delete(entry);
+		} };
+	}
+	emit(event) {
+		for (const entry of this.watchers) if (this.shouldNotify(entry.filter, event)) entry.listener(event);
+	}
+	clear() {
+		this.watchers.clear();
+		this.eventByStack.length = 0;
+	}
+	pushEventBy(by) {
+		this.eventByStack.push(by);
+	}
+	popEventBy() {
+		this.eventByStack.pop();
+	}
+	resolveEventBy(defaultBy) {
+		const index = this.eventByStack.length - 1;
+		return index >= 0 ? this.eventByStack[index] : defaultBy;
+	}
+	shouldNotify(filter, event) {
+		if (!filter.docIds && !filter.kinds && !filter.metadataFields && !filter.by) return true;
+		if (filter.kinds && !filter.kinds.includes(event.kind)) return false;
+		if (filter.by && !filter.by.includes(event.by)) return false;
+		const docId = (() => {
+			if (event.kind === "doc-metadata" || event.kind === "doc-frontiers") return event.docId;
+			if (event.kind === "asset-link" || event.kind === "asset-unlink") return event.docId;
+		})();
+		if (filter.docIds && docId && !filter.docIds.includes(docId)) return false;
+		if (filter.docIds && !docId) return false;
+		if (filter.metadataFields && event.kind === "doc-metadata") {
+			if (!Object.keys(event.patch).some((key) => filter.metadataFields?.includes(key))) return false;
+		}
+		return true;
+	}
+};
+
+//#endregion
+//#region src/internal/doc-handle.ts
+var RepoDocHandleImpl = class {
+	doc;
+	whenSyncedWithRemote;
+	docId;
+	onClose;
+	constructor(docId, doc, whenSyncedWithRemote, onClose) {
+		this.docId = docId;
+		this.doc = doc;
+		this.whenSyncedWithRemote = whenSyncedWithRemote;
+		this.onClose = onClose;
+	}
+	async close() {
+		await this.onClose(this.docId, this.doc);
+	}
+};
+
+//#endregion
+//#region src/utils.ts
 async function streamToUint8Array(stream) {
 	const reader = stream.getReader();
 	const chunks = [];
@@ -814,12 +1026,14 @@ function asJsonObject(value) {
 	if (cloned && typeof cloned === "object" && !Array.isArray(cloned)) return cloned;
 }
 function isJsonObjectValue(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+	return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function stableStringify(value) {
-	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (value === null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
 	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-	if (!isJsonObjectValue(value)) return JSON.stringify(value);
+	if (!isJsonObjectValue(value)) return "null";
 	return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
 }
 function jsonEquals(a, b) {
@@ -829,15 +1043,17 @@ function jsonEquals(a, b) {
 }
 function diffJsonObjects(previous, next) {
 	const patch = {};
-	const keys = new Set([...Object.keys(next), ...previous ? Object.keys(previous) : []]);
+	const keys = /* @__PURE__ */ new Set();
+	if (previous) for (const key of Object.keys(previous)) keys.add(key);
+	for (const key of Object.keys(next)) keys.add(key);
 	for (const key of keys) {
 		const prevValue = previous ? previous[key] : void 0;
-		if (!Object.prototype.hasOwnProperty.call(next, key)) {
-			patch[key] = null;
-			continue;
-		}
 		const nextValue = next[key];
 		if (!jsonEquals(prevValue, nextValue)) {
+			if (nextValue === void 0 && previous && key in previous) {
+				patch[key] = null;
+				continue;
+			}
 			const cloned = cloneJsonValue(nextValue);
 			if (cloned !== void 0) patch[key] = cloned;
 		}
@@ -893,15 +1109,6 @@ function toReadableStream(bytes) {
 		controller.close();
 	} });
 }
-function computeVersionVector(doc) {
-	const candidate = doc;
-	if (typeof candidate.frontiers === "function" && typeof candidate.frontiersToVV === "function") {
-		const frontiers = candidate.frontiers();
-		return candidate.frontiersToVV(frontiers);
-	}
-	if (typeof candidate.version === "function") return candidate.version();
-	return {};
-}
 function emptyFrontiers() {
 	return [];
 }
@@ -933,21 +1140,6 @@ function canonicalizeVersionVector(vv) {
 		key: stableStringify(json)
 	};
 }
-var RepoDocHandleImpl = class {
-	doc;
-	whenSyncedWithRemote;
-	docId;
-	onClose;
-	constructor(docId, doc, whenSyncedWithRemote, onClose) {
-		this.docId = docId;
-		this.doc = doc;
-		this.whenSyncedWithRemote = whenSyncedWithRemote;
-		this.onClose = onClose;
-	}
-	async close() {
-		await this.onClose(this.docId, this.doc);
-	}
-};
 function matchesQuery(docId, _metadata, query) {
 	if (!query) return true;
 	if (query.prefix && !docId.startsWith(query.prefix)) return false;
@@ -955,185 +1147,164 @@ function matchesQuery(docId, _metadata, query) {
 	if (query.end && docId > query.end) return false;
 	return true;
 }
-var LoroRepo = class {
-	options;
-	transport;
+
+//#endregion
+//#region src/internal/logging.ts
+function logAsyncError(context) {
+	return (error) => {
+		if (error instanceof Error) console.error(`[loro-repo] ${context} failed: ${error.message}`, error);
+		else console.error(`[loro-repo] ${context} failed with non-error reason:`, error);
+	};
+}
+
+//#endregion
+//#region src/internal/doc-manager.ts
+var DocManager = class {
 	storage;
-	assetTransport;
 	docFactory;
-	metaFlock = new Flock();
-	metadata = /* @__PURE__ */ new Map();
+	docFrontierDebounceMs;
+	getMetaFlock;
+	eventBus;
+	persistMeta;
+	state;
 	docs = /* @__PURE__ */ new Map();
 	docRefs = /* @__PURE__ */ new Map();
 	docSubscriptions = /* @__PURE__ */ new Map();
-	docAssets = /* @__PURE__ */ new Map();
-	assets = /* @__PURE__ */ new Map();
-	orphanedAssets = /* @__PURE__ */ new Map();
-	assetToDocRefs = /* @__PURE__ */ new Map();
-	docFrontierKeys = /* @__PURE__ */ new Map();
 	docFrontierUpdates = /* @__PURE__ */ new Map();
 	docPersistedVersions = /* @__PURE__ */ new Map();
-	docFrontierDebounceMs;
-	watchers = /* @__PURE__ */ new Set();
-	eventByStack = [];
-	metaRoomSubscription;
-	unsubscribeMetaFlock;
-	readyPromise;
-	constructor(options) {
-		this.options = options;
-		this.transport = options.transportAdapter;
-		this.storage = options.storageAdapter;
-		this.assetTransport = options.assetTransportAdapter;
-		this.docFactory = options.docFactory ?? (async () => new LoroDoc());
-		const configuredDebounce = options.docFrontierDebounceMs;
-		this.docFrontierDebounceMs = typeof configuredDebounce === "number" && Number.isFinite(configuredDebounce) && configuredDebounce >= 0 ? configuredDebounce : DEFAULT_DOC_FRONTIER_DEBOUNCE_MS;
+	get docFrontierKeys() {
+		return this.state.docFrontierKeys;
 	}
-	async ready() {
-		if (!this.readyPromise) this.readyPromise = this.initialize();
-		await this.readyPromise;
+	constructor(options) {
+		this.storage = options.storage;
+		this.docFactory = options.docFactory;
+		this.docFrontierDebounceMs = options.docFrontierDebounceMs;
+		this.getMetaFlock = options.getMetaFlock;
+		this.eventBus = options.eventBus;
+		this.persistMeta = options.persistMeta;
+		this.state = options.state;
+	}
+	async openCollaborativeDoc(docId, whenSyncedWithRemote) {
+		const doc = await this.ensureDoc(docId);
+		const refs = this.docRefs.get(docId) ?? 0;
+		this.docRefs.set(docId, refs + 1);
+		return new RepoDocHandleImpl(docId, doc, whenSyncedWithRemote, async () => this.onDocHandleClose(docId, doc));
 	}
-	async initialize() {
-		if (this.storage) {
-			const snapshot = await this.storage.loadMeta();
-			if (snapshot) this.metaFlock = snapshot;
-		}
-		this.hydrateMetadataFromFlock("sync");
+	async openDetachedDoc(docId) {
+		return new RepoDocHandleImpl(docId, await this.materializeDetachedDoc(docId), Promise.resolve(), async () => {});
 	}
-	async sync(options = {}) {
-		await this.ready();
-		const { scope = "full", docIds } = options;
-		if (!this.transport) return;
-		if (!this.transport.isConnected()) await this.transport.connect();
-		if (scope === "meta" || scope === "full") {
-			this.pushEventBy("sync");
-			const recordedEvents = [];
-			const unsubscribe = this.metaFlock.subscribe((batch) => {
-				if (batch.source === "local") return;
-				recordedEvents.push(...batch.events);
-			});
-			try {
-				if (!(await this.transport.syncMeta(this.metaFlock)).ok) throw new Error("Metadata sync failed");
-				if (recordedEvents.length > 0) this.applyMetaFlockEvents(recordedEvents, "sync");
-				else this.hydrateMetadataFromFlock("sync");
-				await this.persistMeta();
-			} finally {
-				unsubscribe();
-				this.popEventBy();
-			}
+	async ensureDoc(docId) {
+		const cached = this.docs.get(docId);
+		if (cached) {
+			this.ensureDocSubscription(docId, cached);
+			if (!this.docPersistedVersions.has(docId)) this.docPersistedVersions.set(docId, cached.version());
+			return cached;
 		}
-		if (scope === "doc" || scope === "full") {
-			const targets = docIds ?? Array.from(this.metadata.keys());
-			for (const docId of targets) {
-				const doc = await this.ensureDoc(docId);
-				this.pushEventBy("sync");
-				try {
-					if (!(await this.transport.syncDoc(docId, doc)).ok) throw new Error(`Document sync failed for ${docId}`);
-				} finally {
-					this.popEventBy();
-				}
-				await this.persistDoc(docId, doc);
-				await this.updateDocFrontiers(docId, doc, "sync");
+		if (this.storage) {
+			const stored = await this.storage.loadDoc(docId);
+			if (stored) {
+				this.registerDoc(docId, stored);
+				return stored;
 			}
 		}
+		const created = await this.docFactory(docId);
+		this.registerDoc(docId, created);
+		return created;
 	}
-	refreshDocMetadataEntry(docId, by) {
-		const previous = this.metadata.get(docId);
-		const next = this.readDocMetadataFromFlock(docId);
-		if (!next) {
-			if (previous) {
-				this.metadata.delete(docId);
-				this.emit({
-					kind: "doc-metadata",
-					docId,
-					patch: {},
-					by
-				});
-			}
+	async persistDoc(docId, doc) {
+		const previousVersion = this.docPersistedVersions.get(docId);
+		const snapshot = doc.export({ mode: "snapshot" });
+		const nextVersion = doc.version();
+		if (!this.storage) {
+			this.docPersistedVersions.set(docId, nextVersion);
 			return;
 		}
-		this.metadata.set(docId, next);
-		const patch = diffJsonObjects(previous, next);
-		if (!previous || Object.keys(patch).length > 0) this.emit({
-			kind: "doc-metadata",
-			docId,
-			patch,
-			by
-		});
+		this.docPersistedVersions.set(docId, nextVersion);
+		try {
+			await this.storage.save({
+				type: "doc-snapshot",
+				docId,
+				snapshot
+			});
+		} catch (error) {
+			if (previousVersion) this.docPersistedVersions.set(docId, previousVersion);
+			else this.docPersistedVersions.delete(docId);
+			throw error;
+		}
 	}
-	refreshDocAssetsEntry(docId, by) {
-		const mapping = this.readDocAssetsFromFlock(docId);
-		const previous = this.docAssets.get(docId);
-		if (!mapping.size) {
-			if (previous?.size) {
-				this.docAssets.delete(docId);
-				for (const assetId of previous.keys()) {
-					this.emit({
-						kind: "asset-unlink",
-						docId,
-						assetId,
-						by
-					});
-					if (!Array.from(this.docAssets.values()).some((assets) => assets.has(assetId))) {
-						const record = this.assets.get(assetId);
-						if (record) {
-							const deletedAt = this.orphanedAssets.get(assetId)?.deletedAt ?? Date.now();
-							this.orphanedAssets.set(assetId, {
-								metadata: record.metadata,
-								deletedAt
-							});
-						}
-					}
-				}
-			}
-			return;
-		}
-		this.docAssets.set(docId, mapping);
-		const added = [];
-		const removed = [];
-		if (previous) {
-			for (const assetId of previous.keys()) if (!mapping.has(assetId)) removed.push(assetId);
-		}
-		for (const assetId of mapping.keys()) if (!previous || !previous.has(assetId)) added.push(assetId);
-		for (const assetId of removed) {
-			this.emit({
-				kind: "asset-unlink",
+	async updateDocFrontiers(docId, doc, defaultBy) {
+		const { json, key } = canonicalizeVersionVector(doc.version());
+		const existingKeys = this.docFrontierKeys.get(docId) ?? /* @__PURE__ */ new Set();
+		let mutated = false;
+		if (existingKeys.size !== 1 || !existingKeys.has(key)) {
+			const metaFlock = this.metaFlock;
+			for (const entry of existingKeys) metaFlock.delete([
+				"f",
 				docId,
-				assetId,
-				by
-			});
-			if (!Array.from(this.docAssets.values()).some((assets) => assets.has(assetId))) {
-				const record = this.assets.get(assetId);
-				if (record) {
-					const deletedAt = this.orphanedAssets.get(assetId)?.deletedAt ?? Date.now();
-					this.orphanedAssets.set(assetId, {
-						metadata: record.metadata,
-						deletedAt
-					});
-				}
-			}
+				entry
+			]);
+			metaFlock.put([
+				"f",
+				docId,
+				key
+			], json);
+			this.docFrontierKeys.set(docId, new Set([key]));
+			mutated = true;
 		}
-		for (const assetId of added) this.emit({
-			kind: "asset-link",
+		if (mutated) await this.persistMeta();
+		const by = this.eventBus.resolveEventBy(defaultBy);
+		const frontiers = getDocFrontiers(doc);
+		this.eventBus.emit({
+			kind: "doc-frontiers",
 			docId,
-			assetId,
+			frontiers,
 			by
 		});
 	}
-	refreshAssetMetadataEntry(assetId, by) {
-		const previous = this.assets.get(assetId);
-		const metadata = assetMetaFromJson(this.metaFlock.get(["a", assetId]));
-		if (!metadata) {
-			this.handleAssetRemoval(assetId, by);
-			return;
+	async flushScheduledDocFrontierUpdate(docId) {
+		const pending = this.docFrontierUpdates.get(docId);
+		if (!pending) return false;
+		clearTimeout(pending.timeout);
+		this.docFrontierUpdates.delete(docId);
+		this.eventBus.pushEventBy(pending.by);
+		try {
+			await this.updateDocFrontiers(docId, pending.doc, pending.by);
+		} finally {
+			this.eventBus.popEventBy();
 		}
-		const existingData = previous?.data;
-		this.rememberAsset(metadata, existingData);
-		for (const assets of this.docAssets.values()) if (assets.has(assetId)) assets.set(assetId, cloneRepoAssetMetadata(metadata));
-		if (!previous || !assetMetadataEqual(previous.metadata, metadata)) this.emit({
-			kind: "asset-metadata",
-			asset: this.createAssetDownload(assetId, metadata, existingData),
-			by
-		});
+		return true;
+	}
+	async close() {
+		for (const unsubscribe of this.docSubscriptions.values()) try {
+			unsubscribe();
+		} catch {}
+		this.docSubscriptions.clear();
+		const pendingDocIds = Array.from(this.docFrontierUpdates.keys());
+		for (const docId of pendingDocIds) try {
+			await this.flushScheduledDocFrontierUpdate(docId);
+		} catch (error) {
+			logAsyncError(`doc ${docId} frontier flush on close`)(error);
+		}
+		this.docFrontierUpdates.clear();
+		this.docs.clear();
+		this.docRefs.clear();
+		this.docPersistedVersions.clear();
+		this.docFrontierKeys.clear();
+	}
+	hydrateFrontierKeys() {
+		const nextFrontierKeys = /* @__PURE__ */ new Map();
+		const frontierRows = this.metaFlock.scan({ prefix: ["f"] });
+		for (const row of frontierRows) {
+			if (!Array.isArray(row.key) || row.key.length < 3) continue;
+			const docId = row.key[1];
+			const frontierKey = row.key[2];
+			if (typeof docId !== "string" || typeof frontierKey !== "string") continue;
+			const set = nextFrontierKeys.get(docId) ?? /* @__PURE__ */ new Set();
+			set.add(frontierKey);
+			nextFrontierKeys.set(docId, set);
+		}
+		this.docFrontierKeys.clear();
+		for (const [docId, keys] of nextFrontierKeys) this.docFrontierKeys.set(docId, keys);
 	}
 	refreshDocFrontierKeys(docId) {
 		const rows = this.metaFlock.scan({ prefix: ["f", docId] });
@@ -1146,154 +1317,166 @@ var LoroRepo = class {
 		if (keys.size > 0) this.docFrontierKeys.set(docId, keys);
 		else this.docFrontierKeys.delete(docId);
 	}
-	readDocMetadataFromFlock(docId) {
-		const rows = this.metaFlock.scan({ prefix: ["m", docId] });
-		if (!rows.length) return void 0;
-		const docMeta = {};
-		let populated = false;
-		for (const row of rows) {
-			if (!Array.isArray(row.key) || row.key.length < 2) continue;
-			if (row.key.length === 2) {
-				const obj = asJsonObject(row.value);
-				if (!obj) continue;
-				for (const [field, value] of Object.entries(obj)) {
-					const cloned = cloneJsonValue(value);
-					if (cloned !== void 0) {
-						docMeta[field] = cloned;
-						populated = true;
-					}
-				}
-				continue;
-			}
-			const fieldKey = row.key[2];
-			if (typeof fieldKey !== "string") continue;
-			if (fieldKey === "$tombstone") {
-				docMeta.tombstone = Boolean(row.value);
-				populated = true;
-				continue;
-			}
-			const jsonValue = cloneJsonValue(row.value);
-			if (jsonValue === void 0) continue;
-			docMeta[fieldKey] = jsonValue;
-			populated = true;
-		}
-		return populated ? docMeta : void 0;
-	}
-	readDocAssetsFromFlock(docId) {
-		const rows = this.metaFlock.scan({ prefix: ["ld", docId] });
-		const mapping = /* @__PURE__ */ new Map();
-		for (const row of rows) {
-			if (!Array.isArray(row.key) || row.key.length < 3) continue;
-			const assetId = row.key[2];
-			if (typeof assetId !== "string") continue;
-			if (!(row.value !== void 0 && row.value !== null && row.value !== false)) continue;
-			let metadata = this.assets.get(assetId)?.metadata;
-			if (!metadata) {
-				metadata = this.readAssetMetadataFromFlock(assetId);
-				if (!metadata) continue;
-				this.rememberAsset(metadata);
-			}
-			mapping.set(assetId, cloneRepoAssetMetadata(metadata));
-		}
-		return mapping;
+	get metaFlock() {
+		return this.getMetaFlock();
 	}
-	readAssetMetadataFromFlock(assetId) {
-		return assetMetaFromJson(this.metaFlock.get(["a", assetId]));
+	registerDoc(docId, doc) {
+		this.docs.set(docId, doc);
+		this.docPersistedVersions.set(docId, doc.version());
+		this.ensureDocSubscription(docId, doc);
 	}
-	handleAssetRemoval(assetId, by) {
-		const record = this.assets.get(assetId);
-		if (!record) return;
-		this.assets.delete(assetId);
-		const deletedAt = this.orphanedAssets.get(assetId)?.deletedAt ?? Date.now();
-		this.orphanedAssets.set(assetId, {
-			metadata: record.metadata,
-			deletedAt
+	ensureDocSubscription(docId, doc) {
+		if (this.docSubscriptions.has(docId)) return;
+		const unsubscribe = doc.subscribe((batch) => {
+			const stackBy = this.eventBus.resolveEventBy("local");
+			const by = stackBy === "local" && batch.by === "import" ? "live" : stackBy;
+			this.onDocEvent(docId, doc, batch, by);
 		});
-		const affectedDocs = [];
-		for (const [docId, assets] of this.docAssets) if (assets.delete(assetId)) {
-			if (assets.size === 0) this.docAssets.delete(docId);
-			affectedDocs.push(docId);
-		}
-		for (const docId of affectedDocs) this.emit({
-			kind: "asset-unlink",
-			docId,
-			assetId,
-			by
+		if (typeof unsubscribe === "function") this.docSubscriptions.set(docId, unsubscribe);
+	}
+	scheduleDocFrontierUpdate(docId, doc, by) {
+		const existing = this.docFrontierUpdates.get(docId);
+		const effectiveBy = existing ? this.mergeRepoEventBy(existing.by, by) : by;
+		if (existing) clearTimeout(existing.timeout);
+		const delay = this.docFrontierDebounceMs > 0 ? this.docFrontierDebounceMs : 0;
+		const timeout = setTimeout(() => this.runScheduledDocFrontierUpdate(docId), delay);
+		this.docFrontierUpdates.set(docId, {
+			timeout,
+			doc,
+			by: effectiveBy
 		});
 	}
-	emit(event) {
-		for (const entry of this.watchers) if (this.shouldNotify(entry.filter, event)) entry.listener(event);
+	mergeRepoEventBy(current, next) {
+		if (current === next) return current;
+		if (current === "live" || next === "live") return "live";
+		if (current === "sync" || next === "sync") return "sync";
+		return "local";
 	}
-	async joinMetaRoom(params) {
-		await this.ready();
-		if (!this.transport) throw new Error("Transport adapter not configured");
-		if (!this.transport.isConnected()) await this.transport.connect();
-		if (this.metaRoomSubscription) return this.metaRoomSubscription;
-		this.ensureMetaLiveMonitor();
-		const subscription = this.transport.joinMetaRoom(this.metaFlock, params);
-		const wrapped = {
-			unsubscribe: () => {
-				subscription.unsubscribe();
-				if (this.metaRoomSubscription === wrapped) this.metaRoomSubscription = void 0;
-				if (this.unsubscribeMetaFlock) {
-					this.unsubscribeMetaFlock();
-					this.unsubscribeMetaFlock = void 0;
-				}
-			},
-			firstSyncedWithRemote: subscription.firstSyncedWithRemote,
-			get connected() {
-				return subscription.connected;
+	runScheduledDocFrontierUpdate(docId) {
+		const pending = this.docFrontierUpdates.get(docId);
+		if (!pending) return;
+		this.docFrontierUpdates.delete(docId);
+		this.eventBus.pushEventBy(pending.by);
+		(async () => {
+			try {
+				await this.updateDocFrontiers(docId, pending.doc, pending.by);
+			} finally {
+				this.eventBus.popEventBy();
 			}
-		};
-		this.metaRoomSubscription = wrapped;
-		subscription.firstSyncedWithRemote.then(async () => {
-			const by = this.resolveEventBy("live");
-			this.hydrateMetadataFromFlock(by);
-			await this.persistMeta();
-		}).catch(logAsyncError("meta room first sync"));
-		return wrapped;
+		})().catch(logAsyncError(`doc ${docId} frontier debounce`));
 	}
-	async joinDocRoom(docId, params) {
-		await this.ready();
-		if (!this.transport) throw new Error("Transport adapter not configured");
-		if (!this.transport.isConnected()) await this.transport.connect();
-		const doc = await this.ensureDoc(docId);
-		const subscription = this.transport.joinDocRoom(docId, doc, params);
-		subscription.firstSyncedWithRemote.catch(logAsyncError(`doc ${docId} first sync`));
-		return subscription;
+	async onDocHandleClose(docId, doc) {
+		const refs = this.docRefs.get(docId) ?? 0;
+		if (refs <= 1) {
+			this.docRefs.delete(docId);
+			this.docSubscriptions.get(docId)?.();
+			this.docSubscriptions.delete(docId);
+			this.docs.delete(docId);
+			this.docPersistedVersions.delete(docId);
+		} else this.docRefs.set(docId, refs - 1);
+		await this.persistDocUpdate(docId, doc);
+		if (!await this.flushScheduledDocFrontierUpdate(docId)) await this.updateDocFrontiers(docId, doc, "local");
 	}
-	async close() {
-		for (const unsubscribe of this.docSubscriptions.values()) try {
-			unsubscribe();
-		} catch {}
-		this.docSubscriptions.clear();
-		this.metaRoomSubscription?.unsubscribe();
-		this.metaRoomSubscription = void 0;
-		if (this.unsubscribeMetaFlock) {
-			this.unsubscribeMetaFlock();
-			this.unsubscribeMetaFlock = void 0;
-		}
-		const pendingDocIds = Array.from(this.docFrontierUpdates.keys());
-		for (const docId of pendingDocIds) try {
-			await this.flushScheduledDocFrontierUpdate(docId);
-		} catch (error) {
-			logAsyncError(`doc ${docId} frontier flush on close`)(error);
+	async materializeDetachedDoc(docId) {
+		const snapshot = await this.exportDocSnapshot(docId);
+		if (snapshot) return LoroDoc.fromSnapshot(snapshot);
+		return this.docFactory(docId);
+	}
+	async exportDocSnapshot(docId) {
+		const cached = this.docs.get(docId);
+		if (cached) return cached.export({ mode: "snapshot" });
+		if (!this.storage) return;
+		return (await this.storage.loadDoc(docId))?.export({ mode: "snapshot" });
+	}
+	async persistDocUpdate(docId, doc) {
+		const previousVersion = this.docPersistedVersions.get(docId);
+		const nextVersion = doc.version();
+		if (!this.storage) {
+			this.docPersistedVersions.set(docId, nextVersion);
+			return;
+		}
+		if (!previousVersion) {
+			await this.persistDoc(docId, doc);
+			this.docPersistedVersions.set(docId, nextVersion);
+			return;
+		}
+		const update = doc.export({
+			mode: "update",
+			from: previousVersion
+		});
+		if (!update.length) {
+			this.docPersistedVersions.set(docId, nextVersion);
+			return;
+		}
+		this.docPersistedVersions.set(docId, nextVersion);
+		try {
+			await this.storage.save({
+				type: "doc-update",
+				docId,
+				update
+			});
+		} catch (error) {
+			this.docPersistedVersions.set(docId, previousVersion);
+			throw error;
 		}
-		this.docFrontierUpdates.clear();
-		this.watchers.clear();
-		this.docs.clear();
-		this.docRefs.clear();
-		this.metadata.clear();
-		this.docAssets.clear();
-		this.assets.clear();
-		this.docFrontierKeys.clear();
-		this.docPersistedVersions.clear();
-		this.readyPromise = void 0;
-		await this.transport?.close();
 	}
-	async upsertDocMeta(docId, patch, _options = {}) {
-		await this.ready();
-		const base = this.metadata.get(docId);
+	onDocEvent(docId, doc, _batch, by) {
+		(async () => {
+			const persist = this.persistDocUpdate(docId, doc);
+			if (by === "local") {
+				this.scheduleDocFrontierUpdate(docId, doc, by);
+				await persist;
+				return;
+			}
+			const flushed = this.flushScheduledDocFrontierUpdate(docId);
+			const updated = this.updateDocFrontiers(docId, doc, by);
+			await Promise.all([
+				persist,
+				flushed,
+				updated
+			]);
+		})().catch(logAsyncError(`doc ${docId} event processing`));
+	}
+};
+
+//#endregion
+//#region src/internal/metadata-manager.ts
+var MetadataManager = class {
+	getMetaFlock;
+	eventBus;
+	persistMeta;
+	state;
+	constructor(options) {
+		this.getMetaFlock = options.getMetaFlock;
+		this.eventBus = options.eventBus;
+		this.persistMeta = options.persistMeta;
+		this.state = options.state;
+	}
+	getDocIds() {
+		return Array.from(this.state.metadata.keys());
+	}
+	entries() {
+		return this.state.metadata.entries();
+	}
+	get(docId) {
+		const metadata = this.state.metadata.get(docId);
+		return metadata ? cloneJsonObject(metadata) : void 0;
+	}
+	list(query) {
+		const entries = [];
+		for (const [docId, metadata] of this.state.metadata.entries()) {
+			if (!matchesQuery(docId, metadata, query)) continue;
+			entries.push({
+				docId,
+				meta: cloneJsonObject(metadata)
+			});
+		}
+		entries.sort((a, b) => a.docId < b.docId ? -1 : a.docId > b.docId ? 1 : 0);
+		if (query?.limit !== void 0) return entries.slice(0, query.limit);
+		return entries;
+	}
+	async upsert(docId, patch) {
+		const base = this.state.metadata.get(docId);
 		const next = base ? cloneJsonObject(base) : {};
 		const outPatch = {};
 		let changed = false;
@@ -1318,70 +1501,139 @@ var LoroRepo = class {
 			changed = true;
 		}
 		if (!changed) {
-			if (!this.metadata.has(docId)) this.metadata.set(docId, next);
+			if (!this.state.metadata.has(docId)) this.state.metadata.set(docId, next);
 			return;
 		}
-		this.metadata.set(docId, next);
+		this.state.metadata.set(docId, next);
 		await this.persistMeta();
-		this.emit({
+		this.eventBus.emit({
 			kind: "doc-metadata",
 			docId,
 			patch: cloneJsonObject(outPatch),
 			by: "local"
 		});
 	}
-	async getDocMeta(docId) {
-		await this.ready();
-		const metadata = this.metadata.get(docId);
-		return metadata ? cloneJsonObject(metadata) : void 0;
+	refreshFromFlock(docId, by) {
+		const previous = this.state.metadata.get(docId);
+		const next = this.readDocMetadataFromFlock(docId);
+		if (!next) {
+			if (previous) {
+				this.state.metadata.delete(docId);
+				this.eventBus.emit({
+					kind: "doc-metadata",
+					docId,
+					patch: {},
+					by
+				});
+			}
+			return;
+		}
+		this.state.metadata.set(docId, next);
+		const patch = diffJsonObjects(previous, next);
+		if (!previous || Object.keys(patch).length > 0) this.eventBus.emit({
+			kind: "doc-metadata",
+			docId,
+			patch,
+			by
+		});
 	}
-	async listDoc(query) {
-		await this.ready();
-		const entries = [];
-		for (const [docId, metadata] of this.metadata.entries()) {
-			if (!matchesQuery(docId, metadata, query)) continue;
-			entries.push({
+	replaceAll(nextMetadata, by) {
+		const prevMetadata = new Map(this.state.metadata);
+		this.state.metadata.clear();
+		for (const [docId, meta] of nextMetadata) this.state.metadata.set(docId, meta);
+		const docIds = new Set([...prevMetadata.keys(), ...nextMetadata.keys()]);
+		for (const docId of docIds) {
+			const previous = prevMetadata.get(docId);
+			const current = nextMetadata.get(docId);
+			if (!current) {
+				if (previous) this.eventBus.emit({
+					kind: "doc-metadata",
+					docId,
+					patch: {},
+					by
+				});
+				continue;
+			}
+			const patch = diffJsonObjects(previous, current);
+			if (!previous || Object.keys(patch).length > 0) this.eventBus.emit({
+				kind: "doc-metadata",
 				docId,
-				meta: cloneJsonObject(metadata)
+				patch,
+				by
 			});
 		}
-		entries.sort((a, b) => a.docId < b.docId ? -1 : a.docId > b.docId ? 1 : 0);
-		if (query?.limit !== void 0) return entries.slice(0, query.limit);
-		return entries;
 	}
-	getMetaReplica() {
-		return this.metaFlock;
+	clear() {
+		this.state.metadata.clear();
 	}
-	watch(listener, filter = {}) {
-		const entry = {
-			listener,
-			filter
-		};
-		this.watchers.add(entry);
-		return { unsubscribe: () => {
-			this.watchers.delete(entry);
-		} };
+	readDocMetadataFromFlock(docId) {
+		const rows = this.metaFlock.scan({ prefix: ["m", docId] });
+		if (!rows.length) return void 0;
+		const docMeta = {};
+		let populated = false;
+		for (const row of rows) {
+			if (!Array.isArray(row.key) || row.key.length < 2) continue;
+			if (row.key.length === 2) {
+				const obj = asJsonObject(row.value);
+				if (!obj) continue;
+				for (const [field, value] of Object.entries(obj)) {
+					const cloned = cloneJsonValue(value);
+					if (cloned !== void 0) {
+						docMeta[field] = cloned;
+						populated = true;
+					}
+				}
+				continue;
+			}
+			const fieldKey = row.key[2];
+			if (typeof fieldKey !== "string") continue;
+			if (fieldKey === "$tombstone") {
+				docMeta.tombstone = Boolean(row.value);
+				populated = true;
+				continue;
+			}
+			const jsonValue = cloneJsonValue(row.value);
+			if (jsonValue === void 0) continue;
+			docMeta[fieldKey] = jsonValue;
+			populated = true;
+		}
+		return populated ? docMeta : void 0;
 	}
-	/**
-	* Opens the repo-managed collaborative document, registers it for persistence,
-	* and schedules a doc-level sync so `whenSyncedWithRemote` resolves after remote backfills.
-	*/
-	async openCollaborativeDoc(docId) {
-		const doc = await this.ensureDoc(docId);
-		const refs = this.docRefs.get(docId) ?? 0;
-		this.docRefs.set(docId, refs + 1);
-		return new RepoDocHandleImpl(docId, doc, this.whenDocInSyncWithRemote(docId), async (id, instance) => this.onDocHandleClose(id, instance));
+	get metaFlock() {
+		return this.getMetaFlock();
 	}
-	/**
-	* Opens a detached `LoroDoc` snapshot that never registers with the repo, meaning
-	* it neither participates in remote subscriptions nor persists edits back to storage.
-	*/
-	async openDetachedDoc(docId) {
-		await this.ready();
-		return new RepoDocHandleImpl(docId, await this.materializeDetachedDoc(docId), Promise.resolve(), async () => {});
+};
+
+//#endregion
+//#region src/internal/asset-manager.ts
+var AssetManager = class {
+	storage;
+	assetTransport;
+	getMetaFlock;
+	eventBus;
+	persistMeta;
+	state;
+	get docAssets() {
+		return this.state.docAssets;
+	}
+	get assets() {
+		return this.state.assets;
+	}
+	get orphanedAssets() {
+		return this.state.orphanedAssets;
+	}
+	get assetToDocRefs() {
+		return this.state.assetToDocRefs;
+	}
+	constructor(options) {
+		this.storage = options.storage;
+		this.assetTransport = options.assetTransport;
+		this.getMetaFlock = options.getMetaFlock;
+		this.eventBus = options.eventBus;
+		this.persistMeta = options.persistMeta;
+		this.state = options.state;
 	}
 	async uploadAsset(params) {
-		await this.ready();
 		const bytes = await assetContentToUint8Array(params.content);
 		const assetId = await computeSha256(bytes);
 		if (params.assetId && params.assetId !== assetId) throw new Error("Provided assetId does not match content digest");
@@ -1418,7 +1670,7 @@ var LoroRepo = class {
 				existing.metadata = metadata$1;
 				this.metaFlock.put(["a", assetId], assetMetaToJson(metadata$1));
 				await this.persistMeta();
-				this.emit({
+				this.eventBus.emit({
 					kind: "asset-metadata",
 					asset: this.createAssetDownload(assetId, metadata$1, existing.data),
 					by: "local"
@@ -1451,26 +1703,17 @@ var LoroRepo = class {
 			data: storedBytes.slice()
 		});
 		this.rememberAsset(metadata, storedBytes);
-		for (const assets of this.docAssets.values()) if (assets.has(assetId)) assets.set(assetId, metadata);
+		this.updateDocAssetMetadata(assetId, metadata);
 		this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
 		await this.persistMeta();
-		this.emit({
+		this.eventBus.emit({
 			kind: "asset-metadata",
 			asset: this.createAssetDownload(assetId, metadata, storedBytes),
 			by: "local"
 		});
 		return assetId;
 	}
-	async whenDocInSyncWithRemote(docId) {
-		await this.ready();
-		await this.ensureDoc(docId);
-		await this.sync({
-			scope: "doc",
-			docIds: [docId]
-		});
-	}
 	async linkAsset(docId, params) {
-		await this.ready();
 		const bytes = await assetContentToUint8Array(params.content);
 		const assetId = await computeSha256(bytes);
 		if (params.assetId && params.assetId !== assetId) throw new Error("Provided assetId does not match content digest");
@@ -1524,7 +1767,7 @@ var LoroRepo = class {
 				metadata = nextMetadata;
 				this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
 				await this.persistMeta();
-				this.emit({
+				this.eventBus.emit({
 					kind: "asset-metadata",
 					asset: this.createAssetDownload(assetId, metadata, existing.data),
 					by: "local"
@@ -1557,7 +1800,7 @@ var LoroRepo = class {
 				data: storedBytes.slice()
 			});
 			this.rememberAsset(metadata, storedBytes);
-			for (const assets of this.docAssets.values()) if (assets.has(assetId)) assets.set(assetId, metadata);
+			this.updateDocAssetMetadata(assetId, metadata);
 			this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
 			created = true;
 		}
@@ -1573,26 +1816,20 @@ var LoroRepo = class {
 			assetId
 		], true);
 		await this.persistMeta();
-		this.emit({
+		this.eventBus.emit({
 			kind: "asset-link",
 			docId,
 			assetId,
 			by: "local"
 		});
-		if (created) this.emit({
+		if (created) this.eventBus.emit({
 			kind: "asset-metadata",
 			asset: this.createAssetDownload(assetId, metadata, storedBytes ?? bytes),
 			by: "local"
 		});
 		return assetId;
 	}
-	async fetchAsset(assetId) {
-		await this.ready();
-		const { metadata, bytes } = await this.materializeAsset(assetId);
-		return this.createAssetDownload(assetId, metadata, bytes);
-	}
 	async unlinkAsset(docId, assetId) {
-		await this.ready();
 		const mapping = this.docAssets.get(docId);
 		if (!mapping || !mapping.has(assetId)) return;
 		mapping.delete(assetId);
@@ -1617,7 +1854,7 @@ var LoroRepo = class {
 			}
 		}
 		await this.persistMeta();
-		this.emit({
+		this.eventBus.emit({
 			kind: "asset-unlink",
 			docId,
 			assetId,
@@ -1625,7 +1862,6 @@ var LoroRepo = class {
 		});
 	}
 	async listAssets(docId) {
-		await this.ready();
 		const mapping = this.docAssets.get(docId);
 		if (!mapping) return [];
 		return Array.from(mapping.values()).map((asset) => ({ ...asset }));
@@ -1633,36 +1869,251 @@ var LoroRepo = class {
 	async ensureAsset(assetId) {
 		return this.fetchAsset(assetId);
 	}
-	createAssetDownload(assetId, metadata, initialBytes) {
-		let cached = initialBytes ? initialBytes.slice() : void 0;
-		return {
-			assetId,
-			size: metadata.size,
-			createdAt: metadata.createdAt,
-			mime: metadata.mime,
-			policy: metadata.policy,
-			tag: metadata.tag,
-			content: async () => {
-				if (!cached) cached = (await this.materializeAsset(assetId)).bytes.slice();
-				return toReadableStream(cached.slice());
-			}
-		};
+	async fetchAsset(assetId) {
+		const { metadata, bytes } = await this.materializeAsset(assetId);
+		return this.createAssetDownload(assetId, metadata, bytes);
 	}
-	async materializeAsset(assetId) {
-		let record = this.assets.get(assetId);
-		if (record?.data) return {
-			metadata: record.metadata,
-			bytes: record.data.slice()
-		};
-		if (record && this.storage) {
-			const stored = await this.storage.loadAsset(assetId);
-			if (stored) {
-				const clone = stored.slice();
-				record.data = clone.slice();
-				return {
-					metadata: record.metadata,
-					bytes: clone
-				};
+	async gcAssets(options = {}) {
+		const { minKeepMs = 0 } = options;
+		const now = Date.now();
+		let removed = 0;
+		for (const [assetId, orphan] of Array.from(this.orphanedAssets.entries())) {
+			if (now - orphan.deletedAt < minKeepMs) continue;
+			this.orphanedAssets.delete(assetId);
+			if (this.storage?.deleteAsset) try {
+				await this.storage.deleteAsset(assetId);
+			} catch (error) {
+				logAsyncError(`asset ${assetId} delete`)(error);
+			}
+			removed += 1;
+		}
+		return removed;
+	}
+	refreshDocAssetsEntry(docId, by) {
+		const mapping = this.readDocAssetsFromFlock(docId);
+		const previous = this.docAssets.get(docId);
+		if (!mapping.size) {
+			if (previous?.size) {
+				this.docAssets.delete(docId);
+				for (const assetId of previous.keys()) {
+					this.removeDocAssetReference(assetId, docId);
+					this.eventBus.emit({
+						kind: "asset-unlink",
+						docId,
+						assetId,
+						by
+					});
+				}
+			}
+			return;
+		}
+		this.docAssets.set(docId, mapping);
+		const removed = [];
+		if (previous) {
+			for (const assetId of previous.keys()) if (!mapping.has(assetId)) removed.push(assetId);
+		}
+		for (const assetId of removed) {
+			this.removeDocAssetReference(assetId, docId);
+			this.eventBus.emit({
+				kind: "asset-unlink",
+				docId,
+				assetId,
+				by
+			});
+		}
+		for (const assetId of mapping.keys()) {
+			const isNew = !previous || !previous.has(assetId);
+			this.addDocReference(assetId, docId);
+			if (isNew) this.eventBus.emit({
+				kind: "asset-link",
+				docId,
+				assetId,
+				by
+			});
+		}
+	}
+	refreshAssetMetadataEntry(assetId, by) {
+		const previous = this.assets.get(assetId);
+		const metadata = assetMetaFromJson(this.metaFlock.get(["a", assetId]));
+		if (!metadata) {
+			this.handleAssetRemoval(assetId, by);
+			return;
+		}
+		const existingData = previous?.data;
+		this.rememberAsset(metadata, existingData);
+		this.updateDocAssetMetadata(assetId, cloneRepoAssetMetadata(metadata));
+		if (!previous || !assetMetadataEqual(previous.metadata, metadata)) this.eventBus.emit({
+			kind: "asset-metadata",
+			asset: this.createAssetDownload(assetId, metadata, existingData),
+			by
+		});
+	}
+	hydrateFromFlock(by) {
+		const prevDocAssets = new Map(this.docAssets);
+		const prevAssets = new Map(this.assets);
+		const nextAssets = /* @__PURE__ */ new Map();
+		const assetRows = this.metaFlock.scan({ prefix: ["a"] });
+		for (const row of assetRows) {
+			if (!Array.isArray(row.key) || row.key.length < 2) continue;
+			const assetId = row.key[1];
+			if (typeof assetId !== "string") continue;
+			const metadata = assetMetaFromJson(row.value);
+			if (!metadata) continue;
+			const existing = this.assets.get(assetId);
+			nextAssets.set(assetId, {
+				metadata,
+				data: existing?.data
+			});
+		}
+		const nextDocAssets = /* @__PURE__ */ new Map();
+		const linkRows = this.metaFlock.scan({ prefix: ["ld"] });
+		for (const row of linkRows) {
+			if (!Array.isArray(row.key) || row.key.length < 3) continue;
+			const docId = row.key[1];
+			const assetId = row.key[2];
+			if (typeof docId !== "string" || typeof assetId !== "string") continue;
+			const metadata = nextAssets.get(assetId)?.metadata;
+			if (!metadata) continue;
+			const mapping = nextDocAssets.get(docId) ?? /* @__PURE__ */ new Map();
+			mapping.set(assetId, metadata);
+			nextDocAssets.set(docId, mapping);
+		}
+		const removedAssets = [];
+		for (const [assetId, record] of prevAssets) if (!nextAssets.has(assetId)) removedAssets.push([assetId, record]);
+		if (removedAssets.length > 0) {
+			const now = Date.now();
+			for (const [assetId, record] of removedAssets) {
+				const deletedAt = this.orphanedAssets.get(assetId)?.deletedAt ?? now;
+				this.orphanedAssets.set(assetId, {
+					metadata: record.metadata,
+					deletedAt
+				});
+			}
+		}
+		this.docAssets.clear();
+		for (const [docId, assets] of nextDocAssets) this.docAssets.set(docId, assets);
+		this.assetToDocRefs.clear();
+		for (const [docId, assets] of nextDocAssets) for (const assetId of assets.keys()) {
+			const refs = this.assetToDocRefs.get(assetId) ?? /* @__PURE__ */ new Set();
+			refs.add(docId);
+			this.assetToDocRefs.set(assetId, refs);
+		}
+		this.assets.clear();
+		for (const record of nextAssets.values()) this.rememberAsset(record.metadata, record.data);
+		for (const [assetId, record] of nextAssets) {
+			const previous = prevAssets.get(assetId)?.metadata;
+			if (!assetMetadataEqual(previous, record.metadata)) this.eventBus.emit({
+				kind: "asset-metadata",
+				asset: this.createAssetDownload(assetId, record.metadata, record.data),
+				by
+			});
+		}
+		for (const [docId, assets] of nextDocAssets) {
+			const previous = prevDocAssets.get(docId);
+			for (const assetId of assets.keys()) if (!previous || !previous.has(assetId)) this.eventBus.emit({
+				kind: "asset-link",
+				docId,
+				assetId,
+				by
+			});
+		}
+		for (const [docId, assets] of prevDocAssets) {
+			const current = nextDocAssets.get(docId);
+			for (const assetId of assets.keys()) if (!current || !current.has(assetId)) this.eventBus.emit({
+				kind: "asset-unlink",
+				docId,
+				assetId,
+				by
+			});
+		}
+	}
+	clear() {
+		this.docAssets.clear();
+		this.assets.clear();
+		this.orphanedAssets.clear();
+		this.assetToDocRefs.clear();
+	}
+	readDocAssetsFromFlock(docId) {
+		const rows = this.metaFlock.scan({ prefix: ["ld", docId] });
+		const mapping = /* @__PURE__ */ new Map();
+		for (const row of rows) {
+			if (!Array.isArray(row.key) || row.key.length < 3) continue;
+			const assetId = row.key[2];
+			if (typeof assetId !== "string") continue;
+			if (!(row.value !== void 0 && row.value !== null && row.value !== false)) continue;
+			let metadata = this.assets.get(assetId)?.metadata;
+			if (!metadata) {
+				metadata = this.readAssetMetadataFromFlock(assetId);
+				if (!metadata) continue;
+				this.rememberAsset(metadata);
+			}
+			mapping.set(assetId, cloneRepoAssetMetadata(metadata));
+		}
+		return mapping;
+	}
+	readAssetMetadataFromFlock(assetId) {
+		return assetMetaFromJson(this.metaFlock.get(["a", assetId]));
+	}
+	handleAssetRemoval(assetId, by) {
+		const record = this.assets.get(assetId);
+		if (!record) return;
+		this.assets.delete(assetId);
+		this.markAssetAsOrphan(assetId, record.metadata);
+		const refs = this.assetToDocRefs.get(assetId);
+		if (refs) {
+			this.assetToDocRefs.delete(assetId);
+			for (const docId of refs) {
+				const assets = this.docAssets.get(docId);
+				if (assets?.delete(assetId) && assets.size === 0) this.docAssets.delete(docId);
+				this.eventBus.emit({
+					kind: "asset-unlink",
+					docId,
+					assetId,
+					by
+				});
+			}
+			return;
+		}
+		for (const [docId, assets] of this.docAssets) if (assets.delete(assetId)) {
+			if (assets.size === 0) this.docAssets.delete(docId);
+			this.eventBus.emit({
+				kind: "asset-unlink",
+				docId,
+				assetId,
+				by
+			});
+		}
+	}
+	createAssetDownload(assetId, metadata, initialBytes) {
+		let cached = initialBytes ? initialBytes.slice() : void 0;
+		return {
+			assetId,
+			size: metadata.size,
+			createdAt: metadata.createdAt,
+			mime: metadata.mime,
+			policy: metadata.policy,
+			tag: metadata.tag,
+			content: async () => {
+				if (!cached) cached = (await this.materializeAsset(assetId)).bytes.slice();
+				return toReadableStream(cached.slice());
+			}
+		};
+	}
+	async materializeAsset(assetId) {
+		let record = this.assets.get(assetId);
+		if (record?.data) return {
+			metadata: record.metadata,
+			bytes: record.data.slice()
+		};
+		if (record && this.storage) {
+			const stored = await this.storage.loadAsset(assetId);
+			if (stored) {
+				const clone = stored.slice();
+				record.data = clone.slice();
+				return {
+					metadata: record.metadata,
+					bytes: clone
+				};
 			}
 		}
 		if (!record && this.storage) {
@@ -1712,147 +2163,77 @@ var LoroRepo = class {
 		};
 	}
 	updateDocAssetMetadata(assetId, metadata) {
-		for (const assets of this.docAssets.values()) if (assets.has(assetId)) assets.set(assetId, metadata);
-	}
-	async gcAssets(options = {}) {
-		await this.ready();
-		const { minKeepMs = 0 } = options;
-		const now = Date.now();
-		let removed = 0;
-		for (const [assetId, orphan] of Array.from(this.orphanedAssets.entries())) {
-			if (now - orphan.deletedAt < minKeepMs) continue;
-			this.orphanedAssets.delete(assetId);
-			if (this.storage?.deleteAsset) try {
-				await this.storage.deleteAsset(assetId);
-			} catch (error) {
-				logAsyncError(`asset ${assetId} delete`)(error);
-			}
-			removed += 1;
+		const refs = this.assetToDocRefs.get(assetId);
+		if (!refs) return;
+		for (const docId of refs) {
+			const assets = this.docAssets.get(docId);
+			if (assets) assets.set(assetId, metadata);
 		}
-		return removed;
 	}
-	async onDocHandleClose(docId, doc) {
-		const refs = this.docRefs.get(docId) ?? 0;
-		if (refs <= 1) this.docRefs.delete(docId);
-		else this.docRefs.set(docId, refs - 1);
-		await this.persistDocUpdate(docId, doc);
-		if (!await this.flushScheduledDocFrontierUpdate(docId)) await this.updateDocFrontiers(docId, doc, "local");
+	rememberAsset(metadata, bytes) {
+		const data = bytes ? bytes.slice() : this.assets.get(metadata.assetId)?.data;
+		this.assets.set(metadata.assetId, {
+			metadata,
+			data
+		});
+		this.orphanedAssets.delete(metadata.assetId);
 	}
-	async ensureDoc(docId) {
-		await this.ready();
-		const cached = this.docs.get(docId);
-		if (cached) {
-			this.ensureDocSubscription(docId, cached);
-			if (!this.docPersistedVersions.has(docId)) this.docPersistedVersions.set(docId, cached.version());
-			return cached;
-		}
-		if (this.storage) {
-			const stored = await this.storage.loadDoc(docId);
-			if (stored) {
-				this.registerDoc(docId, stored);
-				return stored;
-			}
+	addDocReference(assetId, docId) {
+		const refs = this.assetToDocRefs.get(assetId) ?? /* @__PURE__ */ new Set();
+		refs.add(docId);
+		this.assetToDocRefs.set(assetId, refs);
+	}
+	removeDocAssetReference(assetId, docId) {
+		const refs = this.assetToDocRefs.get(assetId);
+		if (!refs) return;
+		refs.delete(docId);
+		if (refs.size === 0) {
+			this.assetToDocRefs.delete(assetId);
+			this.markAssetAsOrphan(assetId);
 		}
-		const created = await this.docFactory(docId);
-		this.registerDoc(docId, created);
-		return created;
 	}
-	async materializeDetachedDoc(docId) {
-		const doc = await this.docFactory(docId);
-		const snapshot = await this.exportDocSnapshot(docId);
-		if (snapshot) doc.import(snapshot);
-		return doc;
-	}
-	async exportDocSnapshot(docId) {
-		const cached = this.docs.get(docId);
-		if (cached) return cached.export({ mode: "snapshot" });
-		if (!this.storage) return;
-		return (await this.storage.loadDoc(docId))?.export({ mode: "snapshot" });
-	}
-	async persistMeta() {
-		if (!this.storage) return;
-		const bundle = this.metaFlock.exportJson();
-		const encoded = textEncoder.encode(JSON.stringify(bundle));
-		await this.storage.save({
-			type: "meta",
-			update: encoded
+	markAssetAsOrphan(assetId, metadataOverride) {
+		const metadata = metadataOverride ?? this.assets.get(assetId)?.metadata;
+		if (!metadata) return;
+		const deletedAt = this.orphanedAssets.get(assetId)?.deletedAt ?? Date.now();
+		this.orphanedAssets.set(assetId, {
+			metadata,
+			deletedAt
 		});
 	}
-	async persistDoc(docId, doc) {
-		const previousVersion = this.docPersistedVersions.get(docId);
-		const nextVersion = doc.version();
-		if (!this.storage) {
-			this.docPersistedVersions.set(docId, nextVersion);
-			return;
-		}
-		const snapshot = doc.export({ mode: "snapshot" });
-		this.docPersistedVersions.set(docId, nextVersion);
-		try {
-			await this.storage.save({
-				type: "doc-snapshot",
-				docId,
-				snapshot
-			});
-		} catch (error) {
-			if (previousVersion) this.docPersistedVersions.set(docId, previousVersion);
-			else this.docPersistedVersions.delete(docId);
-			throw error;
-		}
-	}
-	async persistDocUpdate(docId, doc) {
-		const previousVersion = this.docPersistedVersions.get(docId);
-		const nextVersion = doc.version();
-		if (!this.storage) {
-			this.docPersistedVersions.set(docId, nextVersion);
-			return;
-		}
-		if (!previousVersion) {
-			await this.persistDoc(docId, doc);
-			this.docPersistedVersions.set(docId, nextVersion);
-			return;
-		}
-		const update = doc.export({
-			mode: "update",
-			from: previousVersion
-		});
-		if (!update.length) {
-			this.docPersistedVersions.set(docId, nextVersion);
-			return;
-		}
-		this.docPersistedVersions.set(docId, nextVersion);
-		try {
-			await this.storage.save({
-				type: "doc-update",
-				docId,
-				update
-			});
-		} catch (error) {
-			this.docPersistedVersions.set(docId, previousVersion);
-			throw error;
+	getAssetMetadata(assetId) {
+		const record = this.assets.get(assetId);
+		if (record) return record.metadata;
+		for (const assets of this.docAssets.values()) {
+			const metadata = assets.get(assetId);
+			if (metadata) return metadata;
 		}
 	}
-	pushEventBy(by) {
-		this.eventByStack.push(by);
-	}
-	popEventBy() {
-		this.eventByStack.pop();
-	}
-	resolveEventBy(defaultBy) {
-		const index = this.eventByStack.length - 1;
-		return index >= 0 ? this.eventByStack[index] : defaultBy;
-	}
-	ensureMetaLiveMonitor() {
-		if (this.unsubscribeMetaFlock) return;
-		this.unsubscribeMetaFlock = this.metaFlock.subscribe((batch) => {
-			if (batch.source === "local") return;
-			const by = this.resolveEventBy("live");
-			(async () => {
-				this.applyMetaFlockEvents(batch.events, by);
-				await this.persistMeta();
-			})().catch(logAsyncError("meta live monitor sync"));
-		});
+	get metaFlock() {
+		return this.getMetaFlock();
 	}
-	applyMetaFlockEvents(events, by) {
+};
+
+//#endregion
+//#region src/internal/flock-hydrator.ts
+var FlockHydrator = class {
+	getMetaFlock;
+	metadataManager;
+	assetManager;
+	docManager;
+	constructor(options) {
+		this.getMetaFlock = options.getMetaFlock;
+		this.metadataManager = options.metadataManager;
+		this.assetManager = options.assetManager;
+		this.docManager = options.docManager;
+	}
+	hydrateAll(by) {
+		const nextMetadata = this.readAllDocMetadata();
+		this.metadataManager.replaceAll(nextMetadata, by);
+		this.assetManager.hydrateFromFlock(by);
+		this.docManager.hydrateFrontierKeys();
+	}
+	applyEvents(events, by) {
 		if (!events.length) return;
 		const docMetadataIds = /* @__PURE__ */ new Set();
 		const docAssetIds = /* @__PURE__ */ new Set();
@@ -1878,134 +2259,12 @@ var LoroRepo = class {
 				if (typeof docId === "string") docFrontiersIds.add(docId);
 			}
 		}
-		for (const assetId of assetIds) this.refreshAssetMetadataEntry(assetId, by);
-		for (const docId of docMetadataIds) this.refreshDocMetadataEntry(docId, by);
-		for (const docId of docAssetIds) this.refreshDocAssetsEntry(docId, by);
-		for (const docId of docFrontiersIds) this.refreshDocFrontierKeys(docId);
-	}
-	registerDoc(docId, doc) {
-		this.docs.set(docId, doc);
-		this.docPersistedVersions.set(docId, doc.version());
-		this.ensureDocSubscription(docId, doc);
-	}
-	ensureDocSubscription(docId, doc) {
-		if (this.docSubscriptions.has(docId)) return;
-		const unsubscribe = doc.subscribe((batch) => {
-			const stackBy = this.resolveEventBy("local");
-			const by = stackBy === "local" && batch.by === "import" ? "live" : stackBy;
-			this.onDocEvent(docId, doc, batch, by);
-		});
-		if (typeof unsubscribe === "function") this.docSubscriptions.set(docId, unsubscribe);
-	}
-	rememberAsset(metadata, bytes) {
-		const data = bytes ? bytes.slice() : this.assets.get(metadata.assetId)?.data;
-		this.assets.set(metadata.assetId, {
-			metadata,
-			data
-		});
-		this.orphanedAssets.delete(metadata.assetId);
-	}
-	scheduleDocFrontierUpdate(docId, doc, by) {
-		const existing = this.docFrontierUpdates.get(docId);
-		const effectiveBy = existing ? this.mergeRepoEventBy(existing.by, by) : by;
-		if (existing) clearTimeout(existing.timeout);
-		const delay = this.docFrontierDebounceMs > 0 ? this.docFrontierDebounceMs : 0;
-		const timeout = setTimeout(() => this.runScheduledDocFrontierUpdate(docId), delay);
-		this.docFrontierUpdates.set(docId, {
-			timeout,
-			doc,
-			by: effectiveBy
-		});
-	}
-	mergeRepoEventBy(current, next) {
-		if (current === next) return current;
-		if (current === "live" || next === "live") return "live";
-		if (current === "sync" || next === "sync") return "sync";
-		return "local";
-	}
-	runScheduledDocFrontierUpdate(docId) {
-		const pending = this.docFrontierUpdates.get(docId);
-		if (!pending) return;
-		this.docFrontierUpdates.delete(docId);
-		this.pushEventBy(pending.by);
-		(async () => {
-			try {
-				await this.updateDocFrontiers(docId, pending.doc, pending.by);
-			} finally {
-				this.popEventBy();
-			}
-		})().catch(logAsyncError(`doc ${docId} frontier debounce`));
-	}
-	async flushScheduledDocFrontierUpdate(docId) {
-		const pending = this.docFrontierUpdates.get(docId);
-		if (!pending) return false;
-		clearTimeout(pending.timeout);
-		this.docFrontierUpdates.delete(docId);
-		this.pushEventBy(pending.by);
-		try {
-			await this.updateDocFrontiers(docId, pending.doc, pending.by);
-		} finally {
-			this.popEventBy();
-		}
-		return true;
-	}
-	onDocEvent(docId, doc, _batch, by) {
-		(async () => {
-			const a = this.persistDocUpdate(docId, doc);
-			if (by === "local") {
-				this.scheduleDocFrontierUpdate(docId, doc, by);
-				await a;
-				return;
-			}
-			const b = this.flushScheduledDocFrontierUpdate(docId);
-			const c = this.updateDocFrontiers(docId, doc, by);
-			await Promise.all([
-				a,
-				b,
-				c
-			]);
-		})().catch(logAsyncError(`doc ${docId} event processing`));
-	}
-	getAssetMetadata(assetId) {
-		const record = this.assets.get(assetId);
-		if (record) return record.metadata;
-		for (const assets of this.docAssets.values()) {
-			const metadata = assets.get(assetId);
-			if (metadata) return metadata;
-		}
-	}
-	async updateDocFrontiers(docId, doc, defaultBy = "local") {
-		const { json, key } = canonicalizeVersionVector(computeVersionVector(doc));
-		const existingKeys = this.docFrontierKeys.get(docId) ?? /* @__PURE__ */ new Set();
-		let mutated = false;
-		if (existingKeys.size !== 1 || !existingKeys.has(key)) {
-			for (const entry of existingKeys) this.metaFlock.delete([
-				"f",
-				docId,
-				entry
-			]);
-			this.metaFlock.put([
-				"f",
-				docId,
-				key
-			], json);
-			this.docFrontierKeys.set(docId, new Set([key]));
-			mutated = true;
-		}
-		if (mutated) await this.persistMeta();
-		const by = this.resolveEventBy(defaultBy);
-		const frontiers = getDocFrontiers(doc);
-		this.emit({
-			kind: "doc-frontiers",
-			docId,
-			frontiers,
-			by
-		});
+		for (const assetId of assetIds) this.assetManager.refreshAssetMetadataEntry(assetId, by);
+		for (const docId of docMetadataIds) this.metadataManager.refreshFromFlock(docId, by);
+		for (const docId of docAssetIds) this.assetManager.refreshDocAssetsEntry(docId, by);
+		for (const docId of docFrontiersIds) this.docManager.refreshDocFrontierKeys(docId);
 	}
-	hydrateMetadataFromFlock(by) {
-		const prevMetadata = new Map(this.metadata);
-		const prevDocAssets = new Map(this.docAssets);
-		const prevAssets = new Map(this.assets);
+	readAllDocMetadata() {
 		const nextMetadata = /* @__PURE__ */ new Map();
 		const metadataRows = this.metaFlock.scan({ prefix: ["m"] });
 		for (const row of metadataRows) {
@@ -2036,135 +2295,337 @@ var LoroRepo = class {
 			if (jsonValue === void 0) continue;
 			docMeta[fieldKey] = jsonValue;
 		}
-		const nextAssets = /* @__PURE__ */ new Map();
-		const assetRows = this.metaFlock.scan({ prefix: ["a"] });
-		for (const row of assetRows) {
-			if (!Array.isArray(row.key) || row.key.length < 2) continue;
-			const assetId = row.key[1];
-			if (typeof assetId !== "string") continue;
-			const metadata = assetMetaFromJson(row.value);
-			if (!metadata) continue;
-			const existing = this.assets.get(assetId);
-			nextAssets.set(assetId, {
-				metadata,
-				data: existing?.data
+		return nextMetadata;
+	}
+	get metaFlock() {
+		return this.getMetaFlock();
+	}
+};
+
+//#endregion
+//#region src/internal/sync-runner.ts
+var SyncRunner = class {
+	storage;
+	transport;
+	eventBus;
+	docManager;
+	metadataManager;
+	assetManager;
+	flockHydrator;
+	getMetaFlock;
+	replaceMetaFlock;
+	persistMeta;
+	readyPromise;
+	metaRoomSubscription;
+	unsubscribeMetaFlock;
+	constructor(options) {
+		this.storage = options.storage;
+		this.transport = options.transport;
+		this.eventBus = options.eventBus;
+		this.docManager = options.docManager;
+		this.metadataManager = options.metadataManager;
+		this.assetManager = options.assetManager;
+		this.flockHydrator = options.flockHydrator;
+		this.getMetaFlock = options.getMetaFlock;
+		this.replaceMetaFlock = options.replaceMetaFlock;
+		this.persistMeta = options.persistMeta;
+	}
+	async ready() {
+		if (!this.readyPromise) this.readyPromise = this.initialize();
+		await this.readyPromise;
+	}
+	async sync(options = {}) {
+		await this.ready();
+		const { scope = "full", docIds } = options;
+		if (!this.transport) return;
+		if (!this.transport.isConnected()) await this.transport.connect();
+		if (scope === "meta" || scope === "full") {
+			this.eventBus.pushEventBy("sync");
+			const recordedEvents = [];
+			const unsubscribe = this.metaFlock.subscribe((batch) => {
+				if (batch.source === "local") return;
+				recordedEvents.push(...batch.events);
 			});
+			try {
+				if (!(await this.transport.syncMeta(this.metaFlock)).ok) throw new Error("Metadata sync failed");
+				if (recordedEvents.length > 0) this.flockHydrator.applyEvents(recordedEvents, "sync");
+				else this.flockHydrator.hydrateAll("sync");
+				await this.persistMeta();
+			} finally {
+				unsubscribe();
+				this.eventBus.popEventBy();
+			}
 		}
-		const nextDocAssets = /* @__PURE__ */ new Map();
-		const linkRows = this.metaFlock.scan({ prefix: ["ld"] });
-		for (const row of linkRows) {
-			if (!Array.isArray(row.key) || row.key.length < 3) continue;
-			const docId = row.key[1];
-			const assetId = row.key[2];
-			if (typeof docId !== "string" || typeof assetId !== "string") continue;
-			const metadata = nextAssets.get(assetId)?.metadata;
-			if (!metadata) continue;
-			const mapping = nextDocAssets.get(docId) ?? /* @__PURE__ */ new Map();
-			mapping.set(assetId, metadata);
-			nextDocAssets.set(docId, mapping);
-		}
-		const nextFrontierKeys = /* @__PURE__ */ new Map();
-		const frontierRows = this.metaFlock.scan({ prefix: ["f"] });
-		for (const row of frontierRows) {
-			if (!Array.isArray(row.key) || row.key.length < 3) continue;
-			const docId = row.key[1];
-			const frontierKey = row.key[2];
-			if (typeof docId !== "string" || typeof frontierKey !== "string") continue;
-			const set = nextFrontierKeys.get(docId) ?? /* @__PURE__ */ new Set();
-			set.add(frontierKey);
-			nextFrontierKeys.set(docId, set);
-		}
-		const removedAssets = [];
-		for (const [assetId, record] of prevAssets) if (!nextAssets.has(assetId)) removedAssets.push([assetId, record]);
-		if (removedAssets.length > 0) {
-			const now = Date.now();
-			for (const [assetId, record] of removedAssets) {
-				const deletedAt = this.orphanedAssets.get(assetId)?.deletedAt ?? now;
-				this.orphanedAssets.set(assetId, {
-					metadata: record.metadata,
-					deletedAt
-				});
+		if (scope === "doc" || scope === "full") {
+			const targets = docIds ?? this.metadataManager.getDocIds();
+			for (const docId of targets) {
+				const doc = await this.docManager.ensureDoc(docId);
+				this.eventBus.pushEventBy("sync");
+				try {
+					if (!(await this.transport.syncDoc(docId, doc)).ok) throw new Error(`Document sync failed for ${docId}`);
+				} finally {
+					this.eventBus.popEventBy();
+				}
+				await this.docManager.persistDoc(docId, doc);
+				await this.docManager.updateDocFrontiers(docId, doc, "sync");
 			}
 		}
-		this.metadata.clear();
-		for (const [docId, meta] of nextMetadata) this.metadata.set(docId, meta);
-		this.docAssets.clear();
-		for (const [docId, assets] of nextDocAssets) this.docAssets.set(docId, assets);
-		this.assetToDocRefs.clear();
-		for (const [docId, assets] of nextDocAssets) for (const assetId of assets.keys()) {
-			const refs = this.assetToDocRefs.get(assetId) ?? /* @__PURE__ */ new Set();
-			refs.add(docId);
-			this.assetToDocRefs.set(assetId, refs);
-		}
-		this.assets.clear();
-		for (const record of nextAssets.values()) this.rememberAsset(record.metadata, record.data);
-		this.docFrontierKeys.clear();
-		for (const [docId, keys] of nextFrontierKeys) this.docFrontierKeys.set(docId, keys);
-		const docIds = new Set([...prevMetadata.keys(), ...nextMetadata.keys()]);
-		for (const docId of docIds) {
-			const previous = prevMetadata.get(docId);
-			const current = nextMetadata.get(docId);
-			if (!current) {
-				if (previous) this.emit({
-					kind: "doc-metadata",
-					docId,
-					patch: {},
-					by
-				});
-				continue;
+	}
+	async joinMetaRoom(params) {
+		await this.ready();
+		if (!this.transport) throw new Error("Transport adapter not configured");
+		if (!this.transport.isConnected()) await this.transport.connect();
+		if (this.metaRoomSubscription) return this.metaRoomSubscription;
+		this.ensureMetaLiveMonitor();
+		const subscription = this.transport.joinMetaRoom(this.metaFlock, params);
+		const wrapped = {
+			unsubscribe: () => {
+				subscription.unsubscribe();
+				if (this.metaRoomSubscription === wrapped) this.metaRoomSubscription = void 0;
+				if (this.unsubscribeMetaFlock) {
+					this.unsubscribeMetaFlock();
+					this.unsubscribeMetaFlock = void 0;
+				}
+			},
+			firstSyncedWithRemote: subscription.firstSyncedWithRemote,
+			get connected() {
+				return subscription.connected;
 			}
-			const patch = diffJsonObjects(previous, current);
-			if (Object.keys(patch).length > 0) this.emit({
-				kind: "doc-metadata",
-				docId,
-				patch,
-				by
-			});
-		}
-		for (const [assetId, record] of nextAssets) {
-			const previous = prevAssets.get(assetId)?.metadata;
-			if (!assetMetadataEqual(previous, record.metadata)) this.emit({
-				kind: "asset-metadata",
-				asset: this.createAssetDownload(assetId, record.metadata, record.data),
-				by
-			});
-		}
-		for (const [docId, assets] of nextDocAssets) {
-			const previous = prevDocAssets.get(docId);
-			for (const assetId of assets.keys()) if (!previous || !previous.has(assetId)) this.emit({
-				kind: "asset-link",
-				docId,
-				assetId,
-				by
-			});
-		}
-		for (const [docId, assets] of prevDocAssets) {
-			const current = nextDocAssets.get(docId);
-			for (const assetId of assets.keys()) if (!current || !current.has(assetId)) this.emit({
-				kind: "asset-unlink",
-				docId,
-				assetId,
-				by
-			});
+		};
+		this.metaRoomSubscription = wrapped;
+		subscription.firstSyncedWithRemote.then(async () => {
+			const by = this.eventBus.resolveEventBy("live");
+			this.flockHydrator.hydrateAll(by);
+			await this.persistMeta();
+		}).catch(logAsyncError("meta room first sync"));
+		return wrapped;
+	}
+	async joinDocRoom(docId, params) {
+		await this.ready();
+		if (!this.transport) throw new Error("Transport adapter not configured");
+		if (!this.transport.isConnected()) await this.transport.connect();
+		const doc = await this.docManager.ensureDoc(docId);
+		const subscription = this.transport.joinDocRoom(docId, doc, params);
+		subscription.firstSyncedWithRemote.catch(logAsyncError(`doc ${docId} first sync`));
+		return subscription;
+	}
+	async close() {
+		await this.docManager.close();
+		this.metaRoomSubscription?.unsubscribe();
+		this.metaRoomSubscription = void 0;
+		if (this.unsubscribeMetaFlock) {
+			this.unsubscribeMetaFlock();
+			this.unsubscribeMetaFlock = void 0;
 		}
+		this.eventBus.clear();
+		this.metadataManager.clear();
+		this.assetManager.clear();
+		this.readyPromise = void 0;
+		await this.transport?.close();
 	}
-	shouldNotify(filter, event) {
-		if (!filter.docIds && !filter.kinds && !filter.metadataFields && !filter.by) return true;
-		if (filter.kinds && !filter.kinds.includes(event.kind)) return false;
-		if (filter.by && !filter.by.includes(event.by)) return false;
-		const docId = (() => {
-			if (event.kind === "doc-metadata" || event.kind === "doc-frontiers") return event.docId;
-			if (event.kind === "asset-link" || event.kind === "asset-unlink") return event.docId;
-		})();
-		if (filter.docIds && docId && !filter.docIds.includes(docId)) return false;
-		if (filter.docIds && !docId) return false;
-		if (filter.metadataFields && event.kind === "doc-metadata") {
-			if (!Object.keys(event.patch).some((key) => filter.metadataFields?.includes(key))) return false;
+	async initialize() {
+		if (this.storage) {
+			const snapshot = await this.storage.loadMeta();
+			if (snapshot) this.replaceMetaFlock(snapshot);
 		}
-		return true;
+		this.flockHydrator.hydrateAll("sync");
+	}
+	ensureMetaLiveMonitor() {
+		if (this.unsubscribeMetaFlock) return;
+		this.unsubscribeMetaFlock = this.metaFlock.subscribe((batch) => {
+			if (batch.source === "local") return;
+			const by = this.eventBus.resolveEventBy("live");
+			(async () => {
+				this.flockHydrator.applyEvents(batch.events, by);
+				await this.persistMeta();
+			})().catch(logAsyncError("meta live monitor sync"));
+		});
+	}
+	get metaFlock() {
+		return this.getMetaFlock();
+	}
+};
+
+//#endregion
+//#region src/internal/repo-state.ts
+function createRepoState() {
+	return {
+		metadata: /* @__PURE__ */ new Map(),
+		docAssets: /* @__PURE__ */ new Map(),
+		assets: /* @__PURE__ */ new Map(),
+		orphanedAssets: /* @__PURE__ */ new Map(),
+		assetToDocRefs: /* @__PURE__ */ new Map(),
+		docFrontierKeys: /* @__PURE__ */ new Map()
+	};
+}
+
+//#endregion
+//#region src/index.ts
+const textEncoder = new TextEncoder();
+const DEFAULT_DOC_FRONTIER_DEBOUNCE_MS = 1e3;
+var LoroRepo = class {
+	options;
+	transport;
+	storage;
+	docFactory;
+	metaFlock = new Flock();
+	eventBus;
+	docManager;
+	metadataManager;
+	assetManager;
+	flockHydrator;
+	state;
+	syncRunner;
+	constructor(options) {
+		this.options = options;
+		this.transport = options.transportAdapter;
+		this.storage = options.storageAdapter;
+		this.docFactory = options.docFactory ?? (async () => new LoroDoc());
+		this.eventBus = new RepoEventBus();
+		this.state = createRepoState();
+		const configuredDebounce = options.docFrontierDebounceMs;
+		const docFrontierDebounceMs = typeof configuredDebounce === "number" && Number.isFinite(configuredDebounce) && configuredDebounce >= 0 ? configuredDebounce : DEFAULT_DOC_FRONTIER_DEBOUNCE_MS;
+		this.docManager = new DocManager({
+			storage: this.storage,
+			docFactory: this.docFactory,
+			docFrontierDebounceMs,
+			getMetaFlock: () => this.metaFlock,
+			eventBus: this.eventBus,
+			persistMeta: () => this.persistMeta(),
+			state: this.state
+		});
+		this.metadataManager = new MetadataManager({
+			getMetaFlock: () => this.metaFlock,
+			eventBus: this.eventBus,
+			persistMeta: () => this.persistMeta(),
+			state: this.state
+		});
+		this.assetManager = new AssetManager({
+			storage: this.storage,
+			assetTransport: options.assetTransportAdapter,
+			getMetaFlock: () => this.metaFlock,
+			eventBus: this.eventBus,
+			persistMeta: () => this.persistMeta(),
+			state: this.state
+		});
+		this.flockHydrator = new FlockHydrator({
+			getMetaFlock: () => this.metaFlock,
+			metadataManager: this.metadataManager,
+			assetManager: this.assetManager,
+			docManager: this.docManager
+		});
+		this.syncRunner = new SyncRunner({
+			storage: this.storage,
+			transport: this.transport,
+			eventBus: this.eventBus,
+			docManager: this.docManager,
+			metadataManager: this.metadataManager,
+			assetManager: this.assetManager,
+			flockHydrator: this.flockHydrator,
+			getMetaFlock: () => this.metaFlock,
+			replaceMetaFlock: (snapshot) => {
+				this.metaFlock = snapshot;
+			},
+			persistMeta: () => this.persistMeta()
+		});
+	}
+	async ready() {
+		await this.syncRunner.ready();
+	}
+	async sync(options = {}) {
+		await this.syncRunner.sync(options);
+	}
+	async joinMetaRoom(params) {
+		return this.syncRunner.joinMetaRoom(params);
+	}
+	async joinDocRoom(docId, params) {
+		return this.syncRunner.joinDocRoom(docId, params);
+	}
+	async close() {
+		await this.syncRunner.close();
+	}
+	async upsertDocMeta(docId, patch, _options = {}) {
+		await this.ready();
+		await this.metadataManager.upsert(docId, patch);
+	}
+	async getDocMeta(docId) {
+		await this.ready();
+		return this.metadataManager.get(docId);
+	}
+	async listDoc(query) {
+		await this.ready();
+		return this.metadataManager.list(query);
+	}
+	getMetaReplica() {
+		return this.metaFlock;
+	}
+	watch(listener, filter = {}) {
+		return this.eventBus.watch(listener, filter);
+	}
+	/**
+	* Opens the repo-managed collaborative document, registers it for persistence,
+	* and schedules a doc-level sync so `whenSyncedWithRemote` resolves after remote backfills.
+	*/
+	async openCollaborativeDoc(docId) {
+		await this.ready();
+		const whenSyncedWithRemote = this.whenDocInSyncWithRemote(docId);
+		return this.docManager.openCollaborativeDoc(docId, whenSyncedWithRemote);
+	}
+	/**
+	* Opens a detached `LoroDoc` snapshot that never registers with the repo, meaning
+	* it neither participates in remote subscriptions nor persists edits back to storage.
+	*/
+	async openDetachedDoc(docId) {
+		await this.ready();
+		return this.docManager.openDetachedDoc(docId);
+	}
+	async uploadAsset(params) {
+		await this.ready();
+		return this.assetManager.uploadAsset(params);
+	}
+	async whenDocInSyncWithRemote(docId) {
+		await this.ready();
+		await this.docManager.ensureDoc(docId);
+		await this.sync({
+			scope: "doc",
+			docIds: [docId]
+		});
+	}
+	async linkAsset(docId, params) {
+		await this.ready();
+		return this.assetManager.linkAsset(docId, params);
+	}
+	async fetchAsset(assetId) {
+		await this.ready();
+		return this.assetManager.fetchAsset(assetId);
+	}
+	async unlinkAsset(docId, assetId) {
+		await this.ready();
+		await this.assetManager.unlinkAsset(docId, assetId);
+	}
+	async listAssets(docId) {
+		await this.ready();
+		return this.assetManager.listAssets(docId);
+	}
+	async ensureAsset(assetId) {
+		await this.ready();
+		return this.assetManager.ensureAsset(assetId);
+	}
+	async gcAssets(options = {}) {
+		await this.ready();
+		return this.assetManager.gcAssets(options);
+	}
+	async persistMeta() {
+		if (!this.storage) return;
+		const bundle = this.metaFlock.exportJson();
+		const encoded = textEncoder.encode(JSON.stringify(bundle));
+		await this.storage.save({
+			type: "meta",
+			update: encoded
+		});
 	}
 };
 
 //#endregion
-export { BroadcastChannelTransportAdapter, IndexedDBStorageAdaptor, LoroRepo, WebSocketTransportAdapter };
+export { BroadcastChannelTransportAdapter, FileSystemStorageAdaptor, IndexedDBStorageAdaptor, LoroRepo, WebSocketTransportAdapter };
 //# sourceMappingURL=index.js.map