@abraca/dabra 2.4.0 → 2.6.0

package/dist/abracadabra-provider.cjs

@@ -3281,22 +3281,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 = yjs.encodeStateAsUpdate(this.document);
 		await store.saveDocSnapshot(snapshot).catch(() => null);
 	}
@@ -10366,6 +10367,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";
@@ -10769,11 +10771,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).
@@ -10902,7 +10914,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
@@ -11020,6 +11032,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
@@ -11029,6 +11081,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.
 	*/
@@ -11149,6 +11255,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();
@@ -14660,6 +14790,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;
@@ -14678,10 +14812,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);
@@ -14932,6 +15079,7 @@ var FileBlobStore = class FileBlobStore extends EventEmitter {
 		this.objectUrls.clear();
 		this.db?.close();
 		this.db = null;
+		this.dbPromise = null;
 		this.removeAllListeners();
 	}
 };
@@ -15482,6 +15630,112 @@ var E2EAbracadabraProvider = class E2EAbracadabraProvider extends AbracadabraPro
 	}
 };
 
+//#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 yjs.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 yjs.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`.
+*
+* - 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`).
+*
+* 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 yjs.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
 /**
@@ -15519,13 +15773,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 yjs.Map ? raw.toJSON() : raw;
-		treeMap.set(childDocId, {
-			...entry,
-			updatedAt: ts
-		});
+		if (!treeMap.get(childDocId)) return;
+		patchEntry(treeMap, childDocId, { updatedAt: ts });
 		lastFlushedAt = ts;
 	}
 	function flushPending() {
@@ -18152,64 +18401,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 yjs.Map ? val.toJSON() : val;
-}
-
 //#endregion
 //#region packages/provider/src/SchemaTypes.ts
 /**
@@ -18255,9 +18446,112 @@ function projectTreeEntry(entry, expectedType) {
 * Extracted from `mcp/tools/tree.ts` and `cli/commands/documents.ts` logic.
 * All tree CRUD operations go through this class.
 */
+/**
+* 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() {
@@ -18280,15 +18574,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) => {
@@ -18305,9 +18667,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) => {
@@ -18358,7 +18736,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));
@@ -18392,7 +18770,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,
@@ -18400,7 +18778,7 @@ var TreeManager = class {
 				meta: opts.meta,
 				createdAt: now,
 				updatedAt: now
-			});
+			}));
 		});
 		return {
 			id,
@@ -18439,12 +18817,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()
 			});
@@ -18455,12 +18830,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()
@@ -18472,12 +18844,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()
 			});
@@ -18492,10 +18861,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;
@@ -18511,7 +18882,7 @@ var TreeManager = class {
 				treeMap.delete(nid);
 			}
 		});
-		return toDelete.length;
+		return deletedCount;
 	}
 	/** Duplicate a document (shallow clone). Returns the new entry. */
 	duplicate(docId) {
@@ -18523,13 +18894,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,
@@ -18547,21 +18918,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. */
@@ -19937,9 +20324,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 = [];
@@ -19947,7 +20334,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;
 			}
@@ -19969,11 +20356,12 @@ var ContentManager = class {
 			type,
 			meta
 		}));
+		const markdown = yjsToMarkdown(fragment, label, meta, type);
 		return {
 			label,
 			type,
 			meta,
-			title,
+			title: label,
 			markdown,
 			children
 		};
@@ -19995,16 +20383,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);
 				});
 			}
 		}
@@ -20123,8 +20509,7 @@ var MetaManager = class {
 			...meta
 		};
 		this.validateOrThrow(docId, entry, mergedMeta);
-		treeMap.set(docId, {
-			...entry,
+		patchEntry(treeMap, docId, {
 			meta: mergedMeta,
 			updatedAt: Date.now()
 		});
@@ -20143,8 +20528,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()
 		});
@@ -20161,8 +20545,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()
 		});
@@ -20269,6 +20652,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;
 	}
@@ -20491,10 +20881,12 @@ exports.generateMnemonic = generateMnemonic;
 exports.isEncryptedContent = isEncryptedContent;
 exports.makeEncryptedYMap = makeEncryptedYMap;
 exports.makeEncryptedYText = makeEncryptedYText;
+exports.makeEntryMap = makeEntryMap;
 exports.mnemonicToEd25519Seed = mnemonicToEd25519Seed;
 exports.mnemonicToKeyPair = mnemonicToKeyPair;
 exports.normalizeRootId = normalizeRootId;
 exports.parseFrontmatter = parseFrontmatter;
+exports.patchEntry = patchEntry;
 exports.populateYDocFromMarkdown = populateYDocFromMarkdown;
 exports.readAuthMessage = readAuthMessage;
 exports.readBlocksFromFragment = readBlocksFromFragment;