@abraca/dabra 2.4.0 → 2.6.0

package/dist/abracadabra-provider.esm.js

@@ -3251,22 +3251,23 @@ var AbracadabraProvider = class AbracadabraProvider extends AbracadabraBaseProvi
 	* errors across async await boundaries.
 	*/
 	async flushPendingUpdates() {
-		if (!this.canWrite) return;
 		const store = this.offlineStore;
 		if (!store) return;
-		const updates = await store.getPendingUpdates();
-		if (updates.length > 0) {
-			for (const update of updates) this.send(UpdateMessage, {
-				update,
-				documentName: this.configuration.name
+		if (this.canWrite) {
+			const updates = await store.getPendingUpdates();
+			if (updates.length > 0) {
+				for (const update of updates) this.send(UpdateMessage, {
+					update,
+					documentName: this.configuration.name
+				});
+				await store.clearPendingUpdates();
+			}
+			const pendingSubdocs = await store.getPendingSubdocs();
+			for (const { childId } of pendingSubdocs) this.send(SubdocMessage, {
+				documentName: this.configuration.name,
+				childDocumentName: childId
 			});
-			await store.clearPendingUpdates();
 		}
-		const pendingSubdocs = await store.getPendingSubdocs();
-		for (const { childId } of pendingSubdocs) this.send(SubdocMessage, {
-			documentName: this.configuration.name,
-			childDocumentName: childId
-		});
 		const snapshot = Y.encodeStateAsUpdate(this.document);
 		await store.saveDocSnapshot(snapshot).catch(() => null);
 	}
@@ -10336,6 +10337,7 @@ function fromBase64$3(b64) {
 }
 var AbracadabraClient = class {
 	constructor(config) {
+		this.rootListInflight = /* @__PURE__ */ new Map();
 		this.baseUrl = config.url.replace(/\/+$/, "");
 		this.persistAuth = config.persistAuth ?? typeof localStorage !== "undefined";
 		this.storageKey = config.storageKey ?? "abracadabra:auth";
@@ -10739,11 +10741,21 @@ var AbracadabraClient = class {
 	* recursive tree walks; callers that need it can read `meta.id` from
 	* the returned metas.
 	*/
-	async listChildren(parentId) {
-		const path = parentId ? `/docs/${encodeURIComponent(parentId)}/children` : "/docs?root=true";
-		const res = await this.request("GET", path);
-		if (this.cache && parentId && res.children) await this.cache.setChildren(parentId, res.children).catch(() => null);
-		return res.documents;
+	async listChildren(parentId, opts) {
+		const kind = opts?.kind;
+		if (parentId) {
+			const res = await this.request("GET", `/docs/${encodeURIComponent(parentId)}/children`);
+			if (this.cache && res.children) await this.cache.setChildren(parentId, res.children).catch(() => null);
+			return kind ? res.documents.filter((d) => d.kind === kind) : res.documents;
+		}
+		const key = kind ?? "";
+		const existing = this.rootListInflight.get(key);
+		const docs = existing ? await existing : await (() => {
+			const p = this.request("GET", kind ? `/docs?root=true&kind=${encodeURIComponent(kind)}` : "/docs?root=true").then((res) => res.documents).finally(() => this.rootListInflight.delete(key));
+			this.rootListInflight.set(key, p);
+			return p;
+		})();
+		return kind ? docs.filter((d) => d.kind === kind) : docs;
 	}
 	/**
 	* Create a child document under a parent (requires write permission).
@@ -10872,7 +10884,7 @@ var AbracadabraClient = class {
 	* spaces resolving to any role; anonymous users see public ones.
 	*/
 	async listSpaces() {
-		return (await this.listChildren()).filter((d) => d.kind === Kind.Space);
+		return this.listChildren(void 0, { kind: Kind.Space });
 	}
 	/**
 	* Create a new top-level Space. Equivalent to a `POST /docs` with
@@ -10990,6 +11002,46 @@ var AbracadabraClient = class {
 		return this.request("POST", "/admin/storage/repair");
 	}
 	/**
+	* Admin one-shot: populate the `snapshot_files` table for snapshots
+	* created before that migration ran, so `SnapshotMeta.file_count` and
+	* upload-ref tracking become accurate. Idempotent (insert-or-ignore).
+	* Requires elevated role.
+	*/
+	async adminSnapshotsBackfillRefs() {
+		return this.request("POST", "/admin/snapshots/backfill-refs");
+	}
+	/**
+	* Admin one-shot: migrate pre-dedup inline snapshot data into the
+	* content-addressed `snapshot_blobs` store. Idempotent (only migrates
+	* rows with `data_hash IS NULL`). Requires elevated role.
+	*/
+	async adminSnapshotsBackfillBlobs() {
+		return this.request("POST", "/admin/snapshots/backfill-blobs");
+	}
+	/**
+	* Admin: server-wide upload listing, joined with the owning document
+	* (label is best-effort — labels live in the CRDT, not the SQL row)
+	* and the content-addressed blob (`ref_count` exposes dedup).
+	* Server-side paginated + filtered. Requires elevated role.
+	*/
+	async adminListUploads(opts = {}) {
+		const p = new URLSearchParams();
+		if (opts.q) p.set("q", opts.q);
+		if (opts.docId) p.set("doc_id", opts.docId);
+		if (opts.limit != null) p.set("limit", String(opts.limit));
+		if (opts.offset != null) p.set("offset", String(opts.offset));
+		const qs = p.toString();
+		return this.request("GET", `/admin/uploads${qs ? `?${qs}` : ""}`);
+	}
+	/**
+	* Admin: aggregate storage figures. `logicalBytes` is what users
+	* uploaded; `physicalBytes` is on-disk after content-addressed dedup;
+	* `dedupSaved` is the difference. Requires elevated role.
+	*/
+	async adminStorageStats() {
+		return this.request("GET", "/admin/storage/stats");
+	}
+	/**
 	* Clear the lockout state on a user account: zeroes the failed-login
 	* counter and `locked_until`. Requires elevated role (Admin or
 	* Service). The action is recorded in the audit log under
@@ -10999,6 +11051,60 @@ var AbracadabraClient = class {
 		await this.request("POST", `/admin/users/${encodeURIComponent(userId)}/unlock`);
 	}
 	/**
+	* Admin: every non-deleted document the user owns (`source: "owner"`)
+	* or has an explicit permission grant on (`source: "grant"`, with
+	* `role`). Answers "what does this identity touch" without an N+1
+	* client tree walk. Labels are best-effort (they live in the CRDT).
+	* Requires elevated role.
+	*/
+	async adminUserDocs(userId, opts = {}) {
+		const qs = opts.limit != null ? `?limit=${opts.limit}` : "";
+		return this.request("GET", `/admin/users/${encodeURIComponent(userId)}/docs${qs}`);
+	}
+	/**
+	* List `service`-role users (runners, demo seeders, automation
+	* identities). Requires Service role. Admins can see service users via
+	* `/admin/users` too but cannot mint or rotate them.
+	*/
+	async adminListServiceAccounts() {
+		return this.request("GET", "/admin/service-accounts");
+	}
+	/**
+	* Create a new `service`-role user. When `public_key` is omitted the
+	* server generates a keypair and returns the private half in the
+	* response — show it to the operator **once** and discard; the server
+	* never persists it. Requires Service role.
+	*/
+	async adminCreateServiceAccount(body) {
+		return this.request("POST", "/admin/service-accounts", { body });
+	}
+	/**
+	* Rotate the active keypair on a service account. Old JWTs are
+	* invalidated; old device keys are marked revoked; the canonical
+	* `users.public_key` swaps to the new value. `users.id` stays put so
+	* existing permission rows keep matching. Returns the new pubkey (and
+	* private half when the server generated it). Requires Service role.
+	*/
+	async adminRotateServiceAccountKey(userId, body = {}) {
+		return this.request("POST", `/admin/service-accounts/${encodeURIComponent(userId)}/rotate-key`, { body });
+	}
+	/**
+	* Lock a service account and revoke all of its device keys. Idempotent.
+	* Refuses targets whose `users.role` isn't `"service"`. Requires
+	* Service role.
+	*/
+	async adminRevokeServiceAccount(userId) {
+		await this.request("DELETE", `/admin/service-accounts/${encodeURIComponent(userId)}`);
+	}
+	/**
+	* Revoke a single device key on a user (any role). Bumps
+	* `tokens_invalid_before` so open WS sessions tied to the key must
+	* re-auth. Requires elevated role (Service or Admin@root).
+	*/
+	async adminRevokeDeviceKey(userId, keyId) {
+		await this.request("POST", `/admin/users/${encodeURIComponent(userId)}/device-keys/${encodeURIComponent(keyId)}/revoke`);
+	}
+	/**
 	* Page through the audit log. Filters AND-combine; `limit` defaults to
 	* 100 server-side. Requires elevated role.
 	*/
@@ -11119,6 +11225,30 @@ var AbracadabraClient = class {
 	async adminConfigEnvSnapshot() {
 		return this.request("GET", "/admin/config/env-snapshot");
 	}
+	/**
+	* List every route pattern that currently has at least one per-route
+	* config override. Use {@link adminConfigGetRoute} to read individual
+	* fields. Requires elevated role.
+	*/
+	async adminConfigListRoutes() {
+		return (await this.request("GET", "/admin/config/routes")).routes;
+	}
+	/**
+	* Read a field's effective value scoped to `route`, falling back to
+	* the global value when no per-route override exists. `origin_kind`
+	* is `"route_override"` only when an override is actually set.
+	*/
+	async adminConfigGetRoute(route, path) {
+		return this.request("GET", `/admin/config/routes/${encodeURIComponent(route)}/fields/${encodeURIComponent(path)}`);
+	}
+	/** Set or replace a per-route override. Mirrors {@link adminConfigSet}. */
+	async adminConfigSetRoute(route, path, value) {
+		return this.request("PUT", `/admin/config/routes/${encodeURIComponent(route)}/fields/${encodeURIComponent(path)}`, { body: { value } });
+	}
+	/** Clear a per-route override (falls back to global). True if one existed. */
+	async adminConfigUnsetRoute(route, path) {
+		return (await this.request("DELETE", `/admin/config/routes/${encodeURIComponent(route)}/fields/${encodeURIComponent(path)}`)).existed;
+	}
 	/** List snapshot metadata for a document. */
 	async listSnapshots(docId, opts) {
 		const params = new URLSearchParams();
@@ -14630,6 +14760,10 @@ var FileBlobStore = class FileBlobStore extends EventEmitter {
 		if (!idbAvailable$1()) return Promise.resolve(null);
 		if (!this.dbPromise) this.dbPromise = openDb$1(this.origin).catch(() => null).then((db) => {
 			this.db = db;
+			if (db) db.onclose = () => {
+				if (this.db === db) this.db = null;
+				this.dbPromise = null;
+			};
 			return db;
 		});
 		return this.dbPromise;
@@ -14648,10 +14782,23 @@ var FileBlobStore = class FileBlobStore extends EventEmitter {
 		const key = this.blobKey(docId, uploadId);
 		const existing = this.objectUrls.get(key);
 		if (existing) return existing;
-		const db = await this.getDb();
+		let db = await this.getDb();
 		if (db) {
-			const tx = db.transaction("blobs", "readonly");
-			const entry = await txPromise(tx.objectStore("blobs"), tx.objectStore("blobs").get(key));
+			let entry;
+			try {
+				const tx = db.transaction("blobs", "readonly");
+				entry = await txPromise(tx.objectStore("blobs"), tx.objectStore("blobs").get(key));
+			} catch (err) {
+				if (err?.name === "InvalidStateError") {
+					if (this.db === db) this.db = null;
+					this.dbPromise = null;
+					db = await this.getDb();
+					if (db) {
+						const tx = db.transaction("blobs", "readonly");
+						entry = await txPromise(tx.objectStore("blobs"), tx.objectStore("blobs").get(key));
+					}
+				} else throw err;
+			}
 			if (entry) {
 				const url = URL.createObjectURL(entry.blob);
 				this.objectUrls.set(key, url);
@@ -14902,6 +15049,7 @@ var FileBlobStore = class FileBlobStore extends EventEmitter {
 		this.objectUrls.clear();
 		this.db?.close();
 		this.db = null;
+		this.dbPromise = null;
 		this.removeAllListeners();
 	}
 };
@@ -15444,21 +15592,113 @@ var E2EAbracadabraProvider = class E2EAbracadabraProvider extends AbracadabraPro
 };
 
 //#endregion
-//#region packages/provider/src/TreeTimestamps.ts
+//#region packages/provider/src/DocUtils.ts
 /**
-* TreeTimestamps
+* Shared utilities for the DocumentManager ORM layer.
 *
-* Attaches an afterUpdate observer on a child Y.Doc so that whenever a
-* non-offline update is applied, the `updatedAt` timestamp on the
-* corresponding entry in the root doc's `doc-tree` map is written.
+* These functions were previously duplicated across `mcp/src/utils.ts`,
+* `mcp/src/server.ts`, `cli/src/connection.ts`, and `mcp/src/tools/tree.ts`.
+*/
+/**
+* Wait for a provider's `synced` event with a timeout.
+* Resolves immediately if the provider is already synced.
+*/
+function waitForSync(provider, timeoutMs = 15e3) {
+	if (provider.isSynced) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			provider.off("synced", handler);
+			reject(/* @__PURE__ */ new Error(`Sync timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		function handler() {
+			clearTimeout(timer);
+			resolve();
+		}
+		provider.on("synced", handler);
+	});
+}
+/**
+* Wrap a promise with a timeout.
+*/
+function withTimeout(promise, timeoutMs, message) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(message ?? `Operation timed out after ${timeoutMs}ms`)), timeoutMs);
+		promise.then((val) => {
+			clearTimeout(timer);
+			resolve(val);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err);
+		});
+	});
+}
+/**
+* Normalize a document ID so the hub/root doc ID is treated as the tree root
+* (null). This lets callers pass the hub doc_id from list_spaces as
+* parentId/rootId and get the expected root-level results instead of an empty
+* set.
+*/
+function normalizeRootId(id, rootDocId) {
+	if (id == null) return null;
+	return id === rootDocId ? null : id;
+}
+/**
+* Safely read a tree map value, converting Y.Map to plain object if needed.
+*/
+function toPlain(val) {
+	return val instanceof Y.Map ? val.toJSON() : val;
+}
+/**
+* Build a tree/trash entry as a nested `Y.Map`. Use for a brand-new or
+* re-created key (create / duplicate / restore) where no concurrent
+* writer exists, so a whole-value write is safe. `undefined` fields are
+* omitted; `null` is kept (a real value, e.g. top-level `parentId`).
+*/
+function makeEntryMap(fields) {
+	const m = new Y.Map();
+	for (const [k, v] of Object.entries(fields)) if (v !== void 0) m.set(k, v);
+	return m;
+}
+/**
+* Patch an EXISTING entry's fields per-key on its nested `Y.Map`, so a
+* concurrent edit to a *different* field by a peer is preserved instead
+* of being clobbered by a whole-entry write — the whole-entry-LWW fix
+* (audit ⑦), the mirror of the Rust provider's `with_entry_mut`.
 *
-* This propagates "last edited" timestamps to all peers via the root CRDT,
-* without requiring any server-side changes.
+* - nested `Y.Map` entry → set/delete only the touched keys in place;
+* - legacy opaque (plain-object) entry → migrated once to a `Y.Map`;
+* - missing entry → created from the patch (lenient; matches the prior
+*   call-site behaviour of spreading `undefined`).
 *
-* Leading-edge + trailing-edge throttle (default 5 s window): the first
-* update flushes immediately so the "last edited" badge updates instantly;
-* follow-up updates within the window are coalesced into one trailing flush.
+* A patch value of `undefined` deletes the key; `null` is written.
+* Self-transacting: it batches its writes in one `Y.Doc` transaction
+* (a safe reentrant no-op join when already inside one), so callers
+* don't need to pass or own a transaction.
 */
+function patchEntry(treeMap, id, patch, removeKeys = []) {
+	const apply = () => {
+		const raw = treeMap.get(id);
+		if (raw instanceof Y.Map) {
+			for (const [k, v] of Object.entries(patch)) if (v === void 0) raw.delete(k);
+			else raw.set(k, v);
+			for (const k of removeKeys) raw.delete(k);
+			return;
+		}
+		const merged = {
+			...raw == null ? {} : toPlain(raw),
+			...patch
+		};
+		for (const [k, v] of Object.entries(patch)) if (v === void 0) delete merged[k];
+		for (const k of removeKeys) delete merged[k];
+		treeMap.set(id, makeEntryMap(merged));
+	};
+	const doc = treeMap.doc;
+	if (doc) doc.transact(apply);
+	else apply();
+}
+
+//#endregion
+//#region packages/provider/src/TreeTimestamps.ts
 /**
 * Attach an observer that writes `updatedAt` to the root doc-tree entry for
 * `childDocId` whenever the child doc receives a non-offline update.
@@ -15480,13 +15720,8 @@ function attachUpdatedAtObserver(treeMap, childDocId, childDoc, offlineStore, op
 	let pendingTs = 0;
 	let timer = null;
 	function writeTs(ts) {
-		const raw = treeMap.get(childDocId);
-		if (!raw) return;
-		const entry = raw instanceof Y.Map ? raw.toJSON() : raw;
-		treeMap.set(childDocId, {
-			...entry,
-			updatedAt: ts
-		});
+		if (!treeMap.get(childDocId)) return;
+		patchEntry(treeMap, childDocId, { updatedAt: ts });
 		lastFlushedAt = ts;
 	}
 	function flushPending() {
@@ -18113,64 +18348,6 @@ function resolvePageType(key) {
 	return PAGE_TYPES[TYPE_ALIASES[key] ?? key];
 }
 
-//#endregion
-//#region packages/provider/src/DocUtils.ts
-/**
-* Shared utilities for the DocumentManager ORM layer.
-*
-* These functions were previously duplicated across `mcp/src/utils.ts`,
-* `mcp/src/server.ts`, `cli/src/connection.ts`, and `mcp/src/tools/tree.ts`.
-*/
-/**
-* Wait for a provider's `synced` event with a timeout.
-* Resolves immediately if the provider is already synced.
-*/
-function waitForSync(provider, timeoutMs = 15e3) {
-	if (provider.isSynced) return Promise.resolve();
-	return new Promise((resolve, reject) => {
-		const timer = setTimeout(() => {
-			provider.off("synced", handler);
-			reject(/* @__PURE__ */ new Error(`Sync timed out after ${timeoutMs}ms`));
-		}, timeoutMs);
-		function handler() {
-			clearTimeout(timer);
-			resolve();
-		}
-		provider.on("synced", handler);
-	});
-}
-/**
-* Wrap a promise with a timeout.
-*/
-function withTimeout(promise, timeoutMs, message) {
-	return new Promise((resolve, reject) => {
-		const timer = setTimeout(() => reject(new Error(message ?? `Operation timed out after ${timeoutMs}ms`)), timeoutMs);
-		promise.then((val) => {
-			clearTimeout(timer);
-			resolve(val);
-		}, (err) => {
-			clearTimeout(timer);
-			reject(err);
-		});
-	});
-}
-/**
-* Normalize a document ID so the hub/root doc ID is treated as the tree root
-* (null). This lets callers pass the hub doc_id from list_spaces as
-* parentId/rootId and get the expected root-level results instead of an empty
-* set.
-*/
-function normalizeRootId(id, rootDocId) {
-	if (id == null) return null;
-	return id === rootDocId ? null : id;
-}
-/**
-* Safely read a tree map value, converting Y.Map to plain object if needed.
-*/
-function toPlain(val) {
-	return val instanceof Y.Map ? val.toJSON() : val;
-}
-
 //#endregion
 //#region packages/provider/src/SchemaTypes.ts
 /**
@@ -18209,9 +18386,112 @@ function projectTreeEntry(entry, expectedType) {
 
 //#endregion
 //#region packages/provider/src/TreeManager.ts
+/**
+* Stable total order over tree siblings: `order` ascending, then `id`
+* ascending as a deterministic tiebreak. The legacy scan sorted by
+* `order` alone and left ties to insertion/iteration order — a superset
+* change that makes cursor pagination well-defined.
+*/
+function cmpKey(oa, ia, ob, ib) {
+	if (oa !== ob) return oa < ob ? -1 : 1;
+	return ia < ib ? -1 : ia > ib ? 1 : 0;
+}
+function cmpEntry(a, b) {
+	return cmpKey(a.order ?? 0, a.id, b.order ?? 0, b.id);
+}
+/** Opaque, dependency-free cursor over the (order,id) sibling order. */
+function encodeCursor(order, id) {
+	return encodeURIComponent(JSON.stringify([order ?? 0, id]));
+}
+function decodeCursor(c) {
+	try {
+		const v = JSON.parse(decodeURIComponent(c));
+		if (Array.isArray(v) && typeof v[0] === "number" && typeof v[1] === "string") return {
+			order: v[0],
+			id: v[1]
+		};
+	} catch {}
+	return null;
+}
 var TreeManager = class {
 	constructor(dm) {
 		this.dm = dm;
+		this._idxMap = null;
+		this._idxObserver = null;
+		this._idxDirty = true;
+		this._byId = /* @__PURE__ */ new Map();
+		this._childrenByParent = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Ensure the index is enabled, bound to the current root doc's tree
+	* map, and fresh. Returns `false` when the index is disabled or there
+	* is no tree map yet — callers then use the legacy scan path.
+	*/
+	ensureIndex() {
+		if (!this.dm.treeIndexEnabled) return false;
+		const treeMap = this.dm.getTreeMap();
+		if (!treeMap) {
+			this.unbindIndex();
+			return false;
+		}
+		if (treeMap !== this._idxMap) {
+			this.unbindIndex();
+			const obs = () => {
+				this._idxDirty = true;
+			};
+			treeMap.observeDeep(obs);
+			this._idxMap = treeMap;
+			this._idxObserver = obs;
+			this._idxDirty = true;
+		}
+		if (this._idxDirty) this.rebuildIndex(treeMap);
+		return true;
+	}
+	unbindIndex() {
+		if (this._idxMap && this._idxObserver) this._idxMap.unobserveDeep(this._idxObserver);
+		this._idxMap = null;
+		this._idxObserver = null;
+		this._byId = /* @__PURE__ */ new Map();
+		this._childrenByParent = /* @__PURE__ */ new Map();
+		this._idxDirty = true;
+	}
+	rebuildIndex(treeMap) {
+		const root = this.dm.rootDocId;
+		const byId = /* @__PURE__ */ new Map();
+		const childrenByParent = /* @__PURE__ */ new Map();
+		treeMap.forEach((raw, id) => {
+			const value = toPlain(raw);
+			if (typeof value !== "object" || value === null) return;
+			const entry = {
+				id,
+				label: value.label || "Untitled",
+				parentId: normalizeRootId(value.parentId ?? null, root),
+				order: value.order ?? 0,
+				type: value.type,
+				meta: value.meta,
+				createdAt: value.createdAt,
+				updatedAt: value.updatedAt
+			};
+			byId.set(id, entry);
+			let bucket = childrenByParent.get(entry.parentId);
+			if (!bucket) {
+				bucket = [];
+				childrenByParent.set(entry.parentId, bucket);
+			}
+			bucket.push(entry);
+		});
+		for (const bucket of childrenByParent.values()) bucket.sort(cmpEntry);
+		this._byId = byId;
+		this._childrenByParent = childrenByParent;
+		this._idxDirty = false;
+	}
+	/**
+	* Release the deep observer. Optional — the observer is auto-rebound
+	* on space switch and becomes moot when the root Y.Doc is GC'd — but
+	* available for consumers that want deterministic teardown.
+	*/
+	dispose() {
+		this.unbindIndex();
 	}
 	/** Read all tree entries as plain objects. */
 	readEntries() {
@@ -18234,15 +18514,83 @@ var TreeManager = class {
 		});
 		return entries;
 	}
+	/**
+	* Like {@link readEntries} but with every entry's *stored* parentId
+	* run through {@link normalizeRootId} (parentId === rootDocId → null),
+	* so a cou-sh / orphan-rescue top-level doc (parentId === spaceRoot)
+	* resolves to top-level identically to a provider-created one
+	* (parentId: null). Without this, the raw `parentId === spaceRoot`
+	* form never matches the normalized `null` query and such docs are
+	* silently invisible cross-client. Mirrors the Rust provider's
+	* `normalized_entries`. readEntries/get keep raw values for
+	* round-trip consumers; only tree-walk reads use this.
+	*/
+	normalizedEntries() {
+		if (this.ensureIndex()) return Array.from(this._byId.values());
+		const root = this.dm.rootDocId;
+		return this.readEntries().map((e) => ({
+			...e,
+			parentId: normalizeRootId(e.parentId, root)
+		}));
+	}
 	/** Get immediate children of a parent (sorted by order). */
 	childrenOf(parentId) {
 		const normalized = normalizeRootId(parentId, this.dm.rootDocId);
-		return this.readEntries().filter((e) => e.parentId === normalized).sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+		if (this.ensureIndex()) {
+			const bucket = this._childrenByParent.get(normalized);
+			return bucket ? bucket.slice() : [];
+		}
+		return this.normalizedEntries().filter((e) => e.parentId === normalized).sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+	}
+	/**
+	* Paginated immediate children — the Path-1 surface for large fan-out
+	* parents. Walks the same stable (order,id) sibling order as
+	* {@link childrenOf}; `cursor` is opaque (round-trip `nextCursor`).
+	* `limit` defaults to 100. A stale/garbage cursor restarts from the
+	* head rather than throwing. Cursor stability is exact when the index
+	* is enabled; on the legacy scan path siblings with equal `order`
+	* may shift between calls.
+	*/
+	childrenOfPage(parentId, opts = {}) {
+		const all = this.childrenOf(parentId);
+		const limit = opts.limit != null && opts.limit > 0 ? Math.floor(opts.limit) : 100;
+		let start = 0;
+		if (opts.cursor) {
+			const dec = decodeCursor(opts.cursor);
+			if (dec) {
+				const at = all.findIndex((e) => cmpKey(e.order ?? 0, e.id, dec.order, dec.id) > 0);
+				start = at < 0 ? all.length : at;
+			}
+		}
+		const entries = all.slice(start, start + limit);
+		const last = entries[entries.length - 1];
+		return {
+			entries,
+			nextCursor: last && start + limit < all.length ? encodeCursor(last.order ?? 0, last.id) : null
+		};
 	}
 	/** Get all descendants recursively. */
 	descendantsOf(parentId) {
 		const normalized = normalizeRootId(parentId, this.dm.rootDocId);
-		const entries = this.readEntries();
+		if (this.ensureIndex()) {
+			const result = [];
+			const visited = /* @__PURE__ */ new Set();
+			const walk = (pid) => {
+				if (pid !== null) {
+					if (visited.has(pid)) return;
+					visited.add(pid);
+				}
+				const bucket = this._childrenByParent.get(pid);
+				if (!bucket) return;
+				for (const child of bucket) {
+					result.push(child);
+					walk(child.id);
+				}
+			};
+			walk(normalized);
+			return result;
+		}
+		const entries = this.normalizedEntries();
 		const result = [];
 		const visited = /* @__PURE__ */ new Set();
 		const collect = (pid) => {
@@ -18259,9 +18607,25 @@ var TreeManager = class {
 	/** Build nested tree JSON. */
 	buildTree(rootId, maxDepth = 3) {
 		const normalized = normalizeRootId(rootId ?? null, this.dm.rootDocId);
-		const entries = this.readEntries();
+		if (this.ensureIndex()) return this._buildTreeIndexed(normalized, maxDepth, 0, /* @__PURE__ */ new Set());
+		const entries = this.normalizedEntries();
 		return this._buildTree(entries, normalized, maxDepth, 0, /* @__PURE__ */ new Set());
 	}
+	_buildTreeIndexed(rootId, maxDepth, currentDepth, visited) {
+		if (maxDepth >= 0 && currentDepth >= maxDepth) return [];
+		return (this._childrenByParent.get(rootId) ?? []).filter((e) => !visited.has(e.id)).map((entry) => {
+			const next = new Set(visited);
+			next.add(entry.id);
+			return {
+				id: entry.id,
+				label: entry.label,
+				type: entry.type,
+				meta: entry.meta,
+				order: entry.order,
+				children: this._buildTreeIndexed(entry.id, maxDepth, currentDepth + 1, next)
+			};
+		});
+	}
 	_buildTree(entries, rootId, maxDepth, currentDepth, visited) {
 		if (maxDepth >= 0 && currentDepth >= maxDepth) return [];
 		return entries.filter((e) => e.parentId === rootId).sort((a, b) => (a.order ?? 0) - (b.order ?? 0)).filter((e) => !visited.has(e.id)).map((entry) => {
@@ -18312,7 +18676,7 @@ var TreeManager = class {
 	}
 	/** Search by label (case-insensitive substring match). */
 	find(query, rootId) {
-		const entries = this.readEntries();
+		const entries = this.normalizedEntries();
 		const lowerQuery = query.toLowerCase();
 		const normalized = normalizeRootId(rootId ?? null, this.dm.rootDocId);
 		const matches = (normalized ? this.descendantsOf(normalized) : entries).filter((e) => e.label.toLowerCase().includes(lowerQuery));
@@ -18346,7 +18710,7 @@ var TreeManager = class {
 		const normalizedParent = normalizeRootId(opts.parentId ?? null, this.dm.rootDocId);
 		const now = Date.now();
 		rootDoc.transact(() => {
-			treeMap.set(id, {
+			treeMap.set(id, makeEntryMap({
 				label: opts.label,
 				parentId: normalizedParent,
 				order: now,
@@ -18354,7 +18718,7 @@ var TreeManager = class {
 				meta: opts.meta,
 				createdAt: now,
 				updatedAt: now
-			});
+			}));
 		});
 		return {
 			id,
@@ -18393,12 +18757,9 @@ var TreeManager = class {
 		const treeMap = this.dm.getTreeMap();
 		const rootDoc = this.dm.rootDocument;
 		if (!treeMap || !rootDoc) throw new Error("Not connected");
-		const raw = treeMap.get(docId);
-		if (!raw) throw new Error(`Document ${docId} not found`);
-		const entry = toPlain(raw);
+		if (!treeMap.get(docId)) throw new Error(`Document ${docId} not found`);
 		rootDoc.transact(() => {
-			treeMap.set(docId, {
-				...entry,
+			patchEntry(treeMap, docId, {
 				label,
 				updatedAt: Date.now()
 			});
@@ -18409,12 +18770,9 @@ var TreeManager = class {
 		const treeMap = this.dm.getTreeMap();
 		const rootDoc = this.dm.rootDocument;
 		if (!treeMap || !rootDoc) throw new Error("Not connected");
-		const raw = treeMap.get(docId);
-		if (!raw) throw new Error(`Document ${docId} not found`);
-		const entry = toPlain(raw);
+		if (!treeMap.get(docId)) throw new Error(`Document ${docId} not found`);
 		rootDoc.transact(() => {
-			treeMap.set(docId, {
-				...entry,
+			patchEntry(treeMap, docId, {
 				parentId: normalizeRootId(newParentId ?? null, this.dm.rootDocId),
 				order: order ?? Date.now(),
 				updatedAt: Date.now()
@@ -18426,12 +18784,9 @@ var TreeManager = class {
 		const treeMap = this.dm.getTreeMap();
 		const rootDoc = this.dm.rootDocument;
 		if (!treeMap || !rootDoc) throw new Error("Not connected");
-		const raw = treeMap.get(docId);
-		if (!raw) throw new Error(`Document ${docId} not found`);
-		const entry = toPlain(raw);
+		if (!treeMap.get(docId)) throw new Error(`Document ${docId} not found`);
 		rootDoc.transact(() => {
-			treeMap.set(docId, {
-				...entry,
+			patchEntry(treeMap, docId, {
 				type,
 				updatedAt: Date.now()
 			});
@@ -18446,10 +18801,12 @@ var TreeManager = class {
 		const trashMap = this.dm.getTrashMap();
 		const rootDoc = this.dm.rootDocument;
 		if (!treeMap || !trashMap || !rootDoc) throw new Error("Not connected");
-		const entries = this.readEntries();
-		const toDelete = [docId, ...this._descendantIds(entries, docId)];
 		const now = Date.now();
+		let deletedCount = 0;
 		rootDoc.transact(() => {
+			const entries = this.readEntries();
+			const toDelete = [docId, ...this._descendantIds(entries, docId)];
+			deletedCount = toDelete.length;
 			for (const nid of toDelete) {
 				const raw = treeMap.get(nid);
 				if (!raw) continue;
@@ -18465,7 +18822,7 @@ var TreeManager = class {
 				treeMap.delete(nid);
 			}
 		});
-		return toDelete.length;
+		return deletedCount;
 	}
 	/** Duplicate a document (shallow clone). Returns the new entry. */
 	duplicate(docId) {
@@ -18477,13 +18834,13 @@ var TreeManager = class {
 		const newId = crypto.randomUUID();
 		const now = Date.now();
 		const newLabel = (entry.label || "Untitled") + " (copy)";
-		treeMap.set(newId, {
+		treeMap.set(newId, makeEntryMap({
 			...entry,
 			label: newLabel,
 			order: now,
 			createdAt: now,
 			updatedAt: now
-		});
+		}));
 		return {
 			id: newId,
 			label: newLabel,
@@ -18501,21 +18858,37 @@ var TreeManager = class {
 		const trashMap = this.dm.getTrashMap();
 		const rootDoc = this.dm.rootDocument;
 		if (!treeMap || !trashMap || !rootDoc) throw new Error("Not connected");
-		const raw = trashMap.get(docId);
-		if (!raw) throw new Error(`Document ${docId} not found in trash`);
-		const entry = toPlain(raw);
+		if (!trashMap.get(docId)) throw new Error(`Document ${docId} not found in trash`);
 		const now = Date.now();
 		rootDoc.transact(() => {
-			treeMap.set(docId, {
-				label: entry.label || "Untitled",
-				parentId: entry.parentId ?? null,
-				order: entry.order ?? now,
-				type: entry.type,
-				meta: entry.meta,
-				createdAt: entry.createdAt ?? now,
-				updatedAt: now
+			const trashed = /* @__PURE__ */ new Map();
+			trashMap.forEach((raw, id) => {
+				const v = toPlain(raw);
+				if (typeof v === "object" && v !== null) trashed.set(id, v);
 			});
-			trashMap.delete(docId);
+			const toRestore = [];
+			const visited = /* @__PURE__ */ new Set();
+			const collect = (id) => {
+				if (visited.has(id)) return;
+				visited.add(id);
+				if (!trashed.has(id)) return;
+				toRestore.push(id);
+				for (const [cid, v] of trashed) if ((v.parentId ?? null) === id) collect(cid);
+			};
+			collect(docId);
+			for (const id of toRestore) {
+				const entry = trashed.get(id);
+				treeMap.set(id, makeEntryMap({
+					label: entry.label || "Untitled",
+					parentId: entry.parentId ?? null,
+					order: entry.order ?? now,
+					type: entry.type,
+					meta: entry.meta,
+					createdAt: entry.createdAt ?? now,
+					updatedAt: now
+				}));
+				trashMap.delete(id);
+			}
 		});
 	}
 	/** List trashed documents. */
@@ -19886,9 +20259,9 @@ var ContentManager = class {
 	* body, tree metadata, and immediate children.
 	*/
 	async read(docId) {
-		const { title, markdown } = yjsToMarkdown((await this.dm.getChildProvider(docId)).document.getXmlFragment("default"));
+		const fragment = (await this.dm.getChildProvider(docId)).document.getXmlFragment("default");
 		const treeMap = this.dm.getTreeMap();
-		let label = title;
+		let label = "Untitled";
 		let type;
 		let meta;
 		const childrenWithOrder = [];
@@ -19896,7 +20269,7 @@ var ContentManager = class {
 			const raw = treeMap.get(docId);
 			if (raw) {
 				const entry = toPlain(raw);
-				label = entry.label || title;
+				label = entry.label || label;
 				type = entry.type;
 				meta = entry.meta;
 			}
@@ -19918,11 +20291,12 @@ var ContentManager = class {
 			type,
 			meta
 		}));
+		const markdown = yjsToMarkdown(fragment, label, meta, type);
 		return {
 			label,
 			type,
 			meta,
-			title,
+			title: label,
 			markdown,
 			children
 		};
@@ -19944,16 +20318,14 @@ var ContentManager = class {
 			if (treeMap && rootDoc) {
 				const entry = treeMap.get(docId);
 				if (entry) rootDoc.transact(() => {
-					const updates = {
-						...entry,
-						updatedAt: Date.now()
-					};
-					if (title) updates.label = title;
-					if (Object.keys(meta).length > 0) updates.meta = {
-						...entry.meta ?? {},
+					const cur = toPlain(entry);
+					const patch = { updatedAt: Date.now() };
+					if (title) patch.label = title;
+					if (Object.keys(meta).length > 0) patch.meta = {
+						...cur.meta ?? {},
 						...meta
 					};
-					treeMap.set(docId, updates);
+					patchEntry(treeMap, docId, patch);
 				});
 			}
 		}
@@ -20072,8 +20444,7 @@ var MetaManager = class {
 			...meta
 		};
 		this.validateOrThrow(docId, entry, mergedMeta);
-		treeMap.set(docId, {
-			...entry,
+		patchEntry(treeMap, docId, {
 			meta: mergedMeta,
 			updatedAt: Date.now()
 		});
@@ -20092,8 +20463,7 @@ var MetaManager = class {
 		if (!raw) throw new Error(`Document ${docId} not found`);
 		const entry = toPlain(raw);
 		this.validateOrThrow(docId, entry, meta);
-		treeMap.set(docId, {
-			...entry,
+		patchEntry(treeMap, docId, {
 			meta,
 			updatedAt: Date.now()
 		});
@@ -20110,8 +20480,7 @@ var MetaManager = class {
 		const updated = { ...entry.meta ?? {} };
 		for (const key of keys) delete updated[key];
 		this.validateOrThrow(docId, entry, updated);
-		treeMap.set(docId, {
-			...entry,
+		patchEntry(treeMap, docId, {
 			meta: updated,
 			updatedAt: Date.now()
 		});
@@ -20218,6 +20587,13 @@ var DocumentManager = class {
 	get rootDocId() {
 		return this._rootDocId;
 	}
+	/**
+	* Whether the TreeManager in-memory index is enabled (Path-1 prototype).
+	* Off by default — see {@link DocumentManagerConfig.treeIndex}.
+	*/
+	get treeIndexEnabled() {
+		return this._config.treeIndex ?? false;
+	}
 	get rootDocument() {
 		return this._rootDoc;
 	}
@@ -20347,5 +20723,5 @@ var DocumentManager = class {
 };
 
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraClient, AbracadabraProvider, AbracadabraWS, AbracadabraWebRTC, AuthMessageType, AwarenessError, BackgroundSyncManager, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, ChatClient, ConnectionTimeout, ContentManager, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, DeviceRegistrationService, DocKeyManager, DocumentCache, DocumentManager, E2EAbracadabraProvider, E2EEChannel, E2EOfflineStore, EncryptedChatClient, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, Forbidden, GEO_TYPE_META_SCHEMAS, HocuspocusProvider, HocuspocusProviderWebsocket, IdentityDocProvider, KEY_EXCHANGE_CHANNEL, Kind, LocalStorageDeviceSessionStorage, ManualSignaling, MessageTooBig, MessageType, MetaManager, MetaValidationError, NotificationsClient, OfflineStore, PAGE_TYPES, PeerConnection, QUERY_PREFIX, QueryClient, QueryError, RPC_PREFIX, ResetConnection, RpcClient, RpcError, SERVER_ROOT_ID, SearchIndex, SignalingSocket, SubdocMessage, TYPE_ALIASES, TokenManager, TreeManager, TypedDocTypeMismatchError, Unauthorized, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, makeEncryptedYMap, makeEncryptedYText, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, parseFrontmatter, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };
+export { AbracadabraBaseProvider, AbracadabraClient, AbracadabraProvider, AbracadabraWS, AbracadabraWebRTC, AuthMessageType, AwarenessError, BackgroundSyncManager, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, ChatClient, ConnectionTimeout, ContentManager, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, DevicePairingChannel, DeviceRegistrationService, DocKeyManager, DocumentCache, DocumentManager, E2EAbracadabraProvider, E2EEChannel, E2EOfflineStore, EncryptedChatClient, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, Forbidden, GEO_TYPE_META_SCHEMAS, HocuspocusProvider, HocuspocusProviderWebsocket, IdentityDocProvider, KEY_EXCHANGE_CHANNEL, Kind, LocalStorageDeviceSessionStorage, ManualSignaling, MessageTooBig, MessageType, MetaManager, MetaValidationError, NotificationsClient, OfflineStore, PAGE_TYPES, PeerConnection, QUERY_PREFIX, QueryClient, QueryError, RPC_PREFIX, ResetConnection, RpcClient, RpcError, SERVER_ROOT_ID, SearchIndex, SignalingSocket, SubdocMessage, TYPE_ALIASES, TokenManager, TreeManager, TypedDocTypeMismatchError, Unauthorized, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, makeEncryptedYMap, makeEncryptedYText, makeEntryMap, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, parseFrontmatter, patchEntry, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };
 //# sourceMappingURL=abracadabra-provider.esm.js.map