loro-repo 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,16 +1,58 @@
 import { Flock } from "@loro-dev/flock";
-import { LoroDoc } from "loro-crdt";
 import { FlockAdaptor, LoroAdaptor } from "loro-adaptors";
 import { CrdtType, bytesToHex } from "loro-protocol";
 import { LoroWebsocketClient } from "loro-websocket";
+import { LoroDoc } from "loro-crdt";
+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 = {}) {
 	return new FlockAdaptor(flock, config);
 }
 
+//#endregion
+//#region src/internal/debug.ts
+const getEnv = () => {
+	if (typeof globalThis !== "object" || globalThis === null) return;
+	return globalThis.process?.env;
+};
+const rawNamespaceConfig = (getEnv()?.LORO_REPO_DEBUG ?? "").trim();
+const normalizedNamespaces = rawNamespaceConfig.length > 0 ? rawNamespaceConfig.split(/[\s,]+/).map((token) => token.toLowerCase()).filter(Boolean) : [];
+const wildcardTokens = new Set([
+	"*",
+	"1",
+	"true",
+	"all"
+]);
+const namespaceSet = new Set(normalizedNamespaces);
+const hasWildcard = namespaceSet.size > 0 && normalizedNamespaces.some((token) => wildcardTokens.has(token));
+const isDebugEnabled = (namespace) => {
+	if (!namespaceSet.size) return false;
+	if (!namespace) return hasWildcard;
+	const normalized = namespace.toLowerCase();
+	if (hasWildcard) return true;
+	if (namespaceSet.has(normalized)) return true;
+	const [root] = normalized.split(":");
+	return namespaceSet.has(root);
+};
+const createDebugLogger = (namespace) => {
+	const normalized = namespace.toLowerCase();
+	return (...args) => {
+		if (!isDebugEnabled(normalized)) return;
+		const prefix = `[loro-repo:${namespace}]`;
+		if (args.length === 0) {
+			console.info(prefix);
+			return;
+		}
+		console.info(prefix, ...args);
+	};
+};
+
 //#endregion
 //#region src/transport/websocket.ts
+const debug = createDebugLogger("transport:websocket");
 function withTimeout(promise, timeoutMs) {
 	if (!timeoutMs || timeoutMs <= 0) return promise;
 	return new Promise((resolve, reject) => {
@@ -55,30 +97,51 @@ var WebSocketTransportAdapter = class {
 	}
 	async connect(_options) {
 		const client = this.ensureClient();
-		await client.connect();
-		await client.waitConnected();
+		debug("connect requested", { status: client.getStatus() });
+		try {
+			await client.connect();
+			debug("client.connect resolved");
+			await client.waitConnected();
+			debug("client.waitConnected resolved", { status: client.getStatus() });
+		} catch (error) {
+			debug("connect failed", error);
+			throw error;
+		}
 	}
 	async close() {
+		debug("close requested", {
+			docSessions: this.docSessions.size,
+			metadataSession: Boolean(this.metadataSession)
+		});
 		for (const [docId] of this.docSessions) await this.leaveDocSession(docId).catch(() => {});
 		this.docSessions.clear();
 		await this.teardownMetadataSession().catch(() => {});
 		if (this.client) {
-			this.client.destroy();
+			const client = this.client;
 			this.client = void 0;
+			client.destroy();
+			debug("websocket client destroyed");
 		}
+		debug("close completed");
 	}
 	isConnected() {
 		return this.client?.getStatus() === "connected";
 	}
 	async syncMeta(flock, options) {
-		if (!this.options.metadataRoomId) return { ok: true };
+		if (!this.options.metadataRoomId) {
+			debug("syncMeta skipped; metadata room not configured");
+			return { ok: true };
+		}
+		debug("syncMeta requested", { roomId: this.options.metadataRoomId });
 		try {
 			await withTimeout((await this.ensureMetadataSession(flock, {
 				roomId: this.options.metadataRoomId,
 				auth: this.options.metadataAuth
 			})).firstSynced, options?.timeout);
+			debug("syncMeta completed", { roomId: this.options.metadataRoomId });
 			return { ok: true };
-		} catch {
+		} catch (error) {
+			debug("syncMeta failed", error);
 			return { ok: false };
 		}
 	}
@@ -87,6 +150,10 @@ var WebSocketTransportAdapter = class {
 		const roomId = normalizeRoomId(params?.roomId, fallback);
 		if (!roomId) throw new Error("Metadata room id not configured");
 		const auth = params?.auth ?? this.options.metadataAuth;
+		debug("joinMetaRoom requested", {
+			roomId,
+			hasAuth: Boolean(auth && auth.length)
+		});
 		const ensure = this.ensureMetadataSession(flock, {
 			roomId,
 			auth
@@ -97,7 +164,14 @@ var WebSocketTransportAdapter = class {
 			unsubscribe: () => {
 				ensure.then((session) => {
 					session.refCount = Math.max(0, session.refCount - 1);
-					if (session.refCount === 0) this.teardownMetadataSession(session).catch(() => {});
+					debug("metadata session refCount decremented", {
+						roomId: session.roomId,
+						refCount: session.refCount
+					});
+					if (session.refCount === 0) {
+						debug("tearing down metadata session due to refCount=0", { roomId: session.roomId });
+						this.teardownMetadataSession(session).catch(() => {});
+					}
 				});
 			},
 			firstSyncedWithRemote: firstSynced,
@@ -107,18 +181,37 @@ var WebSocketTransportAdapter = class {
 		};
 		ensure.then((session) => {
 			session.refCount += 1;
+			debug("metadata session refCount incremented", {
+				roomId: session.roomId,
+				refCount: session.refCount
+			});
 		});
 		return subscription;
 	}
 	async syncDoc(docId, doc, options) {
+		debug("syncDoc requested", { docId });
 		try {
-			await withTimeout((await this.ensureDocSession(docId, doc, {})).firstSynced, options?.timeout);
+			const session = await this.ensureDocSession(docId, doc, {});
+			await withTimeout(session.firstSynced, options?.timeout);
+			debug("syncDoc completed", {
+				docId,
+				roomId: session.roomId
+			});
 			return { ok: true };
-		} catch {
+		} catch (error) {
+			debug("syncDoc failed", {
+				docId,
+				error
+			});
 			return { ok: false };
 		}
 	}
 	joinDocRoom(docId, doc, params) {
+		debug("joinDocRoom requested", {
+			docId,
+			roomParamType: params?.roomId ? typeof params.roomId === "string" ? "string" : "uint8array" : void 0,
+			hasAuthOverride: Boolean(params?.auth && params.auth.length)
+		});
 		const ensure = this.ensureDocSession(docId, doc, params ?? {});
 		const firstSynced = ensure.then((session) => session.firstSynced);
 		const getConnected = () => this.isConnected();
@@ -126,6 +219,11 @@ var WebSocketTransportAdapter = class {
 			unsubscribe: () => {
 				ensure.then((session) => {
 					session.refCount = Math.max(0, session.refCount - 1);
+					debug("doc session refCount decremented", {
+						docId,
+						roomId: session.roomId,
+						refCount: session.refCount
+					});
 					if (session.refCount === 0) this.leaveDocSession(docId).catch(() => {});
 				});
 			},
@@ -136,12 +234,24 @@ var WebSocketTransportAdapter = class {
 		};
 		ensure.then((session) => {
 			session.refCount += 1;
+			debug("doc session refCount incremented", {
+				docId,
+				roomId: session.roomId,
+				refCount: session.refCount
+			});
 		});
 		return subscription;
 	}
 	ensureClient() {
-		if (this.client) return this.client;
+		if (this.client) {
+			debug("reusing websocket client", { status: this.client.getStatus() });
+			return this.client;
+		}
 		const { url, client: clientOptions } = this.options;
+		debug("creating websocket client", {
+			url,
+			clientOptionsKeys: clientOptions ? Object.keys(clientOptions) : []
+		});
 		const client = new LoroWebsocketClient({
 			url,
 			...clientOptions
@@ -150,22 +260,49 @@ var WebSocketTransportAdapter = class {
 		return client;
 	}
 	async ensureMetadataSession(flock, params) {
+		debug("ensureMetadataSession invoked", {
+			roomId: params.roomId,
+			hasAuth: Boolean(params.auth && params.auth.length)
+		});
 		const client = this.ensureClient();
 		await client.waitConnected();
-		if (this.metadataSession && this.metadataSession.flock === flock && this.metadataSession.roomId === params.roomId && bytesEqual(this.metadataSession.auth, params.auth)) return this.metadataSession;
-		if (this.metadataSession) await this.teardownMetadataSession(this.metadataSession).catch(() => {});
+		debug("websocket client ready for metadata session", { status: client.getStatus() });
+		if (this.metadataSession && this.metadataSession.flock === flock && this.metadataSession.roomId === params.roomId && bytesEqual(this.metadataSession.auth, params.auth)) {
+			debug("reusing metadata session", {
+				roomId: this.metadataSession.roomId,
+				refCount: this.metadataSession.refCount
+			});
+			return this.metadataSession;
+		}
+		if (this.metadataSession) {
+			debug("tearing down previous metadata session", { roomId: this.metadataSession.roomId });
+			await this.teardownMetadataSession(this.metadataSession).catch(() => {});
+		}
 		const configuredType = this.options.metadataCrdtType;
 		if (configuredType && configuredType !== CrdtType.Flock) throw new Error(`metadataCrdtType must be ${CrdtType.Flock} when syncing Flock metadata`);
 		const adaptor = createRepoFlockAdaptorFromDoc(flock, this.options.metadataAdaptorConfig ?? {});
+		debug("joining metadata room", {
+			roomId: params.roomId,
+			hasAuth: Boolean(params.auth && params.auth.length)
+		});
 		const room = await client.join({
 			roomId: params.roomId,
 			crdtAdaptor: adaptor,
 			auth: params.auth
 		});
+		const firstSynced = room.waitForReachingServerVersion();
+		firstSynced.then(() => {
+			debug("metadata session firstSynced resolved", { roomId: params.roomId });
+		}, (error) => {
+			debug("metadata session firstSynced rejected", {
+				roomId: params.roomId,
+				error
+			});
+		});
 		const session = {
 			adaptor,
 			room,
-			firstSynced: room.waitForReachingServerVersion(),
+			firstSynced,
 			flock,
 			roomId: params.roomId,
 			auth: params.auth,
@@ -177,34 +314,83 @@ var WebSocketTransportAdapter = class {
 	async teardownMetadataSession(session) {
 		const target = session ?? this.metadataSession;
 		if (!target) return;
+		debug("teardownMetadataSession invoked", { roomId: target.roomId });
 		if (this.metadataSession === target) this.metadataSession = void 0;
 		const { adaptor, room } = target;
 		try {
 			await room.leave();
-		} catch {
+			debug("metadata room left", { roomId: target.roomId });
+		} catch (error) {
+			debug("metadata room leave failed; destroying", {
+				roomId: target.roomId,
+				error
+			});
 			await room.destroy().catch(() => {});
 		}
 		adaptor.destroy();
+		debug("metadata session destroyed", { roomId: target.roomId });
 	}
 	async ensureDocSession(docId, doc, params) {
+		debug("ensureDocSession invoked", { docId });
 		const client = this.ensureClient();
 		await client.waitConnected();
+		debug("websocket client ready for doc session", {
+			docId,
+			status: client.getStatus()
+		});
 		const existing = this.docSessions.get(docId);
 		const derivedRoomId = this.options.docRoomId?.(docId) ?? docId;
 		const roomId = normalizeRoomId(params.roomId, derivedRoomId);
 		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(() => {});
+		debug("doc session params resolved", {
+			docId,
+			roomId,
+			hasAuth: Boolean(auth && auth.length)
+		});
+		if (existing && existing.doc === doc && existing.roomId === roomId) {
+			debug("reusing doc session", {
+				docId,
+				roomId,
+				refCount: existing.refCount
+			});
+			return existing;
+		}
+		if (existing) {
+			debug("doc session mismatch; leaving existing session", {
+				docId,
+				previousRoomId: existing.roomId,
+				nextRoomId: roomId
+			});
+			await this.leaveDocSession(docId).catch(() => {});
+		}
 		const adaptor = new LoroAdaptor(doc);
+		debug("joining doc room", {
+			docId,
+			roomId,
+			hasAuth: Boolean(auth && auth.length)
+		});
 		const room = await client.join({
 			roomId,
 			crdtAdaptor: adaptor,
 			auth
 		});
+		const firstSynced = room.waitForReachingServerVersion();
+		firstSynced.then(() => {
+			debug("doc session firstSynced resolved", {
+				docId,
+				roomId
+			});
+		}, (error) => {
+			debug("doc session firstSynced rejected", {
+				docId,
+				roomId,
+				error
+			});
+		});
 		const session = {
 			adaptor,
 			room,
-			firstSynced: room.waitForReachingServerVersion(),
+			firstSynced,
 			doc,
 			roomId,
 			refCount: 0
@@ -214,14 +400,34 @@ var WebSocketTransportAdapter = class {
 	}
 	async leaveDocSession(docId) {
 		const session = this.docSessions.get(docId);
-		if (!session) return;
+		if (!session) {
+			debug("leaveDocSession invoked but no session found", { docId });
+			return;
+		}
 		this.docSessions.delete(docId);
+		debug("leaving doc session", {
+			docId,
+			roomId: session.roomId
+		});
 		try {
 			await session.room.leave();
-		} catch {
+			debug("doc room left", {
+				docId,
+				roomId: session.roomId
+			});
+		} catch (error) {
+			debug("doc room leave failed; destroying", {
+				docId,
+				roomId: session.roomId,
+				error
+			});
 			await session.room.destroy().catch(() => {});
 		}
 		session.adaptor.destroy();
+		debug("doc session destroyed", {
+			docId,
+			roomId: session.roomId
+		});
 	}
 };
 
@@ -483,7 +689,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 +790,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 +934,206 @@ 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/utils.ts
 async function streamToUint8Array(stream) {
 	const reader = stream.getReader();
 	const chunks = [];
@@ -814,12 +1211,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 +1228,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,61 +1294,24 @@ 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 [];
-}
-function getDocFrontiers(doc) {
-	const candidate = doc;
-	if (typeof candidate.frontiers === "function") {
-		const result = candidate.frontiers();
-		if (result) return result;
-	}
-	return emptyFrontiers();
-}
-function versionVectorToJson(vv) {
-	const map = vv.toJSON();
-	const record = {};
-	if (map instanceof Map) {
-		const entries = Array.from(map.entries()).sort(([a], [b]) => String(a).localeCompare(String(b)));
-		for (const [peer, counter] of entries) {
-			if (typeof counter !== "number" || !Number.isFinite(counter)) continue;
-			const key = typeof peer === "string" ? peer : JSON.stringify(peer);
-			record[key] = counter;
-		}
-	}
-	return record;
-}
-function canonicalizeVersionVector(vv) {
-	const json = versionVectorToJson(vv);
+function canonicalizeFrontiers(frontiers) {
+	const json = [...frontiers].sort((a, b) => {
+		if (a.peer < b.peer) return -1;
+		if (a.peer > b.peer) return 1;
+		return a.counter - b.counter;
+	}).map((f) => ({
+		peer: f.peer,
+		counter: f.counter
+	}));
 	return {
 		json,
 		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 includesFrontiers(vv, frontiers) {
+	for (const { peer, counter } of frontiers) if ((vv.get(peer) ?? 0) <= counter) return false;
+	return true;
+}
 function matchesQuery(docId, _metadata, query) {
 	if (!query) return true;
 	if (query.prefix && !docId.startsWith(query.prefix)) return false;
@@ -955,345 +1319,372 @@ 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;
+	get docFrontierKeys() {
+		return this.state.docFrontierKeys;
+	}
 	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;
+		this.storage = options.storage;
+		this.docFrontierDebounceMs = options.docFrontierDebounceMs;
+		this.getMetaFlock = options.getMetaFlock;
+		this.eventBus = options.eventBus;
+		this.persistMeta = options.persistMeta;
+		this.state = options.state;
 	}
-	async ready() {
-		if (!this.readyPromise) this.readyPromise = this.initialize();
-		await this.readyPromise;
+	async openCollaborativeDoc(docId) {
+		return await this.ensureDoc(docId);
 	}
-	async initialize() {
+	async openDetachedDoc(docId) {
+		return await this.materializeDetachedDoc(docId);
+	}
+	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 (this.storage) {
-			const snapshot = await this.storage.loadMeta();
-			if (snapshot) this.metaFlock = snapshot;
+			const stored = await this.storage.loadDoc(docId);
+			if (stored) {
+				this.registerDoc(docId, stored);
+				return stored;
+			}
 		}
-		this.hydrateMetadataFromFlock("sync");
+		const created = new LoroDoc();
+		this.registerDoc(docId, created);
+		return created;
 	}
-	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 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;
 		}
-		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");
-			}
+		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;
 		}
 	}
-	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 updateDocFrontiers(docId, doc, defaultBy) {
+		const frontiers = doc.oplogFrontiers();
+		const { json, key } = canonicalizeFrontiers(frontiers);
+		const existingKeys = this.docFrontierKeys.get(docId) ?? /* @__PURE__ */ new Set();
+		let mutated = false;
+		const metaFlock = this.metaFlock;
+		const vv = doc.version();
+		for (const entry of existingKeys) {
+			if (entry === key) continue;
+			let oldFrontiers;
+			try {
+				oldFrontiers = JSON.parse(entry);
+			} catch {
+				continue;
 			}
-			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
-		});
-	}
-	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
-							});
-						}
-					}
-				}
+			if (includesFrontiers(vv, oldFrontiers)) {
+				metaFlock.delete([
+					"f",
+					docId,
+					entry
+				]);
+				mutated = true;
 			}
-			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",
+		if (!existingKeys.has(key)) {
+			metaFlock.put([
+				"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
-					});
-				}
-			}
+				key
+			], json);
+			mutated = true;
 		}
-		for (const assetId of added) this.emit({
-			kind: "asset-link",
+		if (mutated) {
+			this.refreshDocFrontierKeys(docId);
+			await this.persistMeta();
+		}
+		const by = this.eventBus.resolveEventBy(defaultBy);
+		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 unloadDoc(docId) {
+		const doc = this.docs.get(docId);
+		if (!doc) return;
+		await this.flushScheduledDocFrontierUpdate(docId);
+		await this.persistDocUpdate(docId, doc);
+		await this.updateDocFrontiers(docId, doc, "local");
+		this.docSubscriptions.get(docId)?.();
+		this.docSubscriptions.delete(docId);
+		this.docs.delete(docId);
+		this.docPersistedVersions.delete(docId);
+	}
+	async flush() {
+		const promises$1 = [];
+		for (const [docId, doc] of this.docs) promises$1.push((async () => {
+			await this.persistDocUpdate(docId, doc);
+			await this.flushScheduledDocFrontierUpdate(docId);
+		})());
+		await Promise.all(promises$1);
+	}
+	async close() {
+		await this.flush();
+		for (const unsubscribe of this.docSubscriptions.values()) try {
+			unsubscribe();
+		} catch {}
+		this.docSubscriptions.clear();
+		this.docFrontierUpdates.clear();
+		this.docs.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] });
 		const keys = /* @__PURE__ */ new Set();
 		for (const row of rows) {
 			if (!Array.isArray(row.key) || row.key.length < 3) continue;
+			if (row.value === void 0 || row.value === null) continue;
 			const frontierKey = row.key[2];
 			if (typeof frontierKey === "string") keys.add(frontierKey);
 		}
 		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 materializeDetachedDoc(docId) {
+		const snapshot = await this.exportDocSnapshot(docId);
+		if (snapshot) return LoroDoc.fromSnapshot(snapshot);
+		return new LoroDoc();
 	}
-	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;
+	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.oplogVersion();
+		if (!this.storage) {
+			this.docPersistedVersions.set(docId, nextVersion);
+			return;
 		}
-		const pendingDocIds = Array.from(this.docFrontierUpdates.keys());
-		for (const docId of pendingDocIds) try {
-			await this.flushScheduledDocFrontierUpdate(docId);
+		if (!previousVersion) {
+			await this.persistDoc(docId, doc);
+			this.docPersistedVersions.set(docId, nextVersion);
+			return;
+		}
+		if (previousVersion.compare(nextVersion) === 0) return;
+		const update = doc.export({
+			mode: "update",
+			from: previousVersion
+		});
+		this.docPersistedVersions.set(docId, nextVersion);
+		try {
+			await this.storage.save({
+				type: "doc-update",
+				docId,
+				update
+			});
 		} catch (error) {
-			logAsyncError(`doc ${docId} frontier flush on close`)(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 = (async () => {
+				this.eventBus.pushEventBy(by);
+				try {
+					await this.updateDocFrontiers(docId, doc, by);
+				} finally {
+					this.eventBus.popEventBy();
+				}
+			})();
+			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;
+	}
+	listDoc(query) {
+		if (query?.limit !== void 0 && query.limit <= 0) return [];
+		const { startKey, endKey } = this.computeDocRangeKeys(query);
+		if (startKey && endKey && startKey >= endKey) return [];
+		const scanOptions = { prefix: ["m"] };
+		if (startKey) scanOptions.start = {
+			kind: "inclusive",
+			key: ["m", startKey]
+		};
+		if (endKey) scanOptions.end = {
+			kind: "exclusive",
+			key: ["m", endKey]
+		};
+		const rows = this.metaFlock.scan(scanOptions);
+		const seen = /* @__PURE__ */ new Set();
+		const entries = [];
+		for (const row of rows) {
+			if (query?.limit !== void 0 && entries.length >= query.limit) break;
+			if (!Array.isArray(row.key) || row.key.length < 2) continue;
+			const docId = row.key[1];
+			if (typeof docId !== "string") continue;
+			if (seen.has(docId)) continue;
+			seen.add(docId);
+			const metadata = this.state.metadata.get(docId);
+			if (!metadata) continue;
+			if (!matchesQuery(docId, metadata, query)) continue;
+			entries.push({
+				docId,
+				meta: cloneJsonObject(metadata)
+			});
+			if (query?.limit !== void 0 && entries.length >= query.limit) break;
+		}
+		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 +1709,159 @@ 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
+	computeDocRangeKeys(query) {
+		if (!query) return {};
+		const prefix = query.prefix && query.prefix.length > 0 ? query.prefix : void 0;
+		let startKey = query.start;
+		if (prefix) startKey = !startKey || prefix > startKey ? prefix : startKey;
+		let endKey = query.end;
+		const prefixEnd = this.nextLexicographicString(prefix);
+		if (prefixEnd) endKey = !endKey || prefixEnd < endKey ? prefixEnd : endKey;
+		return {
+			startKey,
+			endKey
 		};
-		this.watchers.add(entry);
-		return { unsubscribe: () => {
-			this.watchers.delete(entry);
-		} };
 	}
-	/**
-	* 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));
+	nextLexicographicString(value) {
+		if (!value) return void 0;
+		for (let i = value.length - 1; i >= 0; i -= 1) {
+			const code = value.charCodeAt(i);
+			if (code < 65535) return `${value.slice(0, i)}${String.fromCharCode(code + 1)}`;
+		}
 	}
-	/**
-	* 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 () => {});
+	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;
+	}
+	get metaFlock() {
+		return this.getMetaFlock();
+	}
+};
+
+//#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 +1898,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 +1931,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 +1995,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 +2028,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 +2044,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 +2082,7 @@ var LoroRepo = class {
 			}
 		}
 		await this.persistMeta();
-		this.emit({
+		this.eventBus.emit({
 			kind: "asset-unlink",
 			docId,
 			assetId,
@@ -1625,7 +2090,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,26 +2097,241 @@ 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()
+	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);
@@ -1712,147 +2391,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 +2487,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;
-		}
+		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);
 	}
-	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
-		});
-	}
-	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 +2523,404 @@ 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
+/**
+* Sync data between storage and transport layer
+*/
+var SyncRunner = class {
+	storage;
+	transport;
+	eventBus;
+	docManager;
+	metadataManager;
+	assetManager;
+	flockHydrator;
+	getMetaFlock;
+	replaceMetaFlock;
+	persistMeta;
+	readyPromise;
+	metaRoomSubscription;
+	unsubscribeMetaFlock;
+	docSubscriptions = /* @__PURE__ */ new Map();
+	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.mergeFlock;
+		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);
+		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");
+			}
 		}
-		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
-				});
+	}
+	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;
 			}
+		};
+		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 existing = this.docSubscriptions.get(docId);
+		if (existing) return existing;
+		const doc = await this.docManager.ensureDoc(docId);
+		const subscription = this.transport.joinDocRoom(docId, doc, params);
+		const wrapped = {
+			unsubscribe: () => {
+				subscription.unsubscribe();
+				if (this.docSubscriptions.get(docId) === wrapped) this.docSubscriptions.delete(docId);
+			},
+			firstSyncedWithRemote: subscription.firstSyncedWithRemote,
+			get connected() {
+				return subscription.connected;
+			}
+		};
+		this.docSubscriptions.set(docId, wrapped);
+		subscription.firstSyncedWithRemote.catch(logAsyncError(`doc ${docId} first sync`));
+		return wrapped;
+	}
+	async destroy() {
+		await this.docManager.close();
+		this.metaRoomSubscription?.unsubscribe();
+		this.metaRoomSubscription = void 0;
+		for (const sub of this.docSubscriptions.values()) sub.unsubscribe();
+		this.docSubscriptions.clear();
+		if (this.unsubscribeMetaFlock) {
+			this.unsubscribeMetaFlock();
+			this.unsubscribeMetaFlock = void 0;
 		}
-		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.eventBus.clear();
+		this.metadataManager.clear();
+		this.assetManager.clear();
+		this.readyPromise = void 0;
+		await this.transport?.close();
+	}
+	async initialize() {
+		if (this.storage) {
+			const snapshot = await this.storage.loadMeta();
+			if (snapshot) this.replaceMetaFlock(snapshot);
 		}
-		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
+		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 LoroRepo {
+	options;
+	_destroyed = false;
+	transport;
+	storage;
+	metaFlock = new Flock();
+	eventBus;
+	docManager;
+	metadataManager;
+	assetManager;
+	assetTransport;
+	flockHydrator;
+	state;
+	syncRunner;
+	constructor(options) {
+		this.options = options;
+		this.transport = options.transportAdapter;
+		this.storage = options.storageAdapter;
+		this.assetTransport = options.assetTransportAdapter;
+		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,
+			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: this.assetTransport,
+			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,
+			mergeFlock: (snapshot) => {
+				this.metaFlock.merge(snapshot);
+			},
+			persistMeta: () => this.persistMeta()
+		});
+	}
+	static async create(options) {
+		const repo = new LoroRepo(options);
+		await repo.storage?.init?.();
+		await repo.ready();
+		return repo;
+	}
+	/**
+	* Load meta from storage.
+	* 
+	* You need to call this before all other operations to make the app functioning correctly.
+	* Though we do that implicitly already
+	*/
+	async ready() {
+		await this.syncRunner.ready();
+	}
+	/**
+	* Sync selected data via the transport adaptor
+	* @param options 
+	*/
+	async sync(options = {}) {
+		await this.syncRunner.sync(options);
+	}
+	/**
+	* Start syncing the metadata (Flock) room. It will establish a realtime connection to the transport adaptor.
+	* All changes on the room will be synced to the Flock, and all changes on the Flock will be synced to the room.
+	* @param params 
+	* @returns 
+	*/
+	async joinMetaRoom(params) {
+		return this.syncRunner.joinMetaRoom(params);
+	}
+	/**
+	* Start syncing the given doc. It will establish a realtime connection to the transport adaptor.
+	* All changes on the doc will be synced to the transport, and all changes on the transport will be synced to the doc.
+	* 
+	* All the changes on the room will be reflected on the same doc you get from `repo.openCollaborativeDoc(docId)`
+	* @param docId 
+	* @param params 
+	* @returns 
+	*/
+	async joinDocRoom(docId, params) {
+		return this.syncRunner.joinDocRoom(docId, params);
+	}
+	/**
+	* Opens a document that is automatically persisted to the configured storage adapter.
+	* 
+	* - Edits are saved to storage (debounced).
+	* - Frontiers are synced to the metadata (Flock).
+	* - Realtime collaboration is NOT enabled by default; use `joinDocRoom` to connect.
+	*/
+	async openPersistedDoc(docId) {
+		return {
+			doc: await this.docManager.openCollaborativeDoc(docId),
+			syncOnce: () => {
+				return this.sync({
+					scope: "doc",
+					docIds: [docId]
 				});
-				continue;
+			},
+			joinRoom: (auth) => {
+				return this.syncRunner.joinDocRoom(docId, { auth });
 			}
-			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
-			});
-		}
+		};
 	}
-	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;
+	async upsertDocMeta(docId, patch) {
+		await this.metadataManager.upsert(docId, patch);
+	}
+	async getDocMeta(docId) {
+		return this.metadataManager.get(docId);
+	}
+	async listDoc(query) {
+		return this.metadataManager.listDoc(query);
+	}
+	getMeta() {
+		return this.metaFlock;
+	}
+	watch(listener, filter = {}) {
+		return this.eventBus.watch(listener, filter);
+	}
+	/**
+	* Opens a detached `LoroDoc` snapshot.
+	* 
+	* - **No Persistence**: Edits to this document are NOT saved to storage.
+	* - **No Sync**: This document does not participate in realtime updates.
+	* - **Use Case**: Ideal for read-only history inspection, temporary drafts, or conflict resolution without affecting the main state.
+	*/
+	async openDetachedDoc(docId) {
+		return this.docManager.openDetachedDoc(docId);
+	}
+	/**
+	* Explicitly unloads a document from memory.
+	* 
+	* - **Persists Immediately**: Forces a save of the document's current state to storage.
+	* - **Frees Memory**: Removes the document from the internal cache.
+	* - **Note**: If the document is currently being synced (via `joinDocRoom`), you should also unsubscribe from the room to fully release resources.
+	*/
+	async unloadDoc(docId) {
+		await this.docManager.unloadDoc(docId);
+	}
+	async flush() {
+		await this.docManager.flush();
+	}
+	async uploadAsset(params) {
+		return this.assetManager.uploadAsset(params);
+	}
+	async linkAsset(docId, params) {
+		return this.assetManager.linkAsset(docId, params);
+	}
+	async fetchAsset(assetId) {
+		return this.assetManager.fetchAsset(assetId);
+	}
+	async unlinkAsset(docId, assetId) {
+		await this.assetManager.unlinkAsset(docId, assetId);
+	}
+	async listAssets(docId) {
+		return this.assetManager.listAssets(docId);
+	}
+	async ensureAsset(assetId) {
+		return this.assetManager.ensureAsset(assetId);
+	}
+	async gcAssets(options = {}) {
+		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
+		});
+	}
+	get destroyed() {
+		return this._destroyed;
+	}
+	async destroy() {
+		if (this._destroyed) return;
+		this._destroyed = true;
+		await this.syncRunner.destroy();
+		this.assetTransport?.close?.();
+		this.storage?.close?.();
+		await this.transport?.close();
 	}
 };
 
 //#endregion
-export { BroadcastChannelTransportAdapter, IndexedDBStorageAdaptor, LoroRepo, WebSocketTransportAdapter };
+export { BroadcastChannelTransportAdapter, FileSystemStorageAdaptor, IndexedDBStorageAdaptor, LoroRepo, WebSocketTransportAdapter };
 //# sourceMappingURL=index.js.map