@abraca/dabra 2.3.0 → 2.5.0

package/src/TreeManager.ts

@@ -13,7 +13,12 @@ import type {
 	PageMeta,
 } from "./DocTypes.ts";
 import { resolvePageType } from "./DocTypes.ts";
-import { toPlain, normalizeRootId } from "./DocUtils.ts";
+import {
+	toPlain,
+	normalizeRootId,
+	makeEntryMap,
+	patchEntry,
+} from "./DocUtils.ts";
 import type { DocumentManager } from "./DocumentManager.ts";
 import {
 	projectTreeEntry,
@@ -21,9 +26,146 @@ import {
 	type TypedTreeEntry,
 } from "./SchemaTypes.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: number, ia: string, ob: number, ib: string): number {
+	if (oa !== ob) return oa < ob ? -1 : 1;
+	return ia < ib ? -1 : ia > ib ? 1 : 0;
+}
+function cmpEntry(a: TreeEntry, b: TreeEntry): number {
+	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: number, id: string): string {
+	return encodeURIComponent(JSON.stringify([order ?? 0, id]));
+}
+function decodeCursor(c: string): { order: number; id: string } | null {
+	try {
+		const v = JSON.parse(decodeURIComponent(c)) as unknown;
+		if (
+			Array.isArray(v) &&
+			typeof v[0] === "number" &&
+			typeof v[1] === "string"
+		) {
+			return { order: v[0], id: v[1] };
+		}
+	} catch {
+		// Garbage / tampered cursor → treat as "from the beginning".
+	}
+	return null;
+}
+
+export interface ChildrenPage {
+	entries: TreeEntry[];
+	/** Pass back as `cursor` for the next page; `null` when exhausted. */
+	nextCursor: string | null;
+}
+
 export class TreeManager {
 	constructor(private dm: DocumentManager) {}
 
+	// ── Path-1 prototype: lazy parent→children index ──────────────────────────
+	//
+	// Gated by `dm.treeIndexEnabled`. When off, every method below falls
+	// through to the original whole-map scan (unchanged). When on, tree
+	// WALKS resolve against a normalized adjacency index that is rebuilt
+	// lazily: an `observeDeep` on the bound `doc-tree` Y.Map only flips a
+	// dirty bit, so the O(n) rebuild happens at most once per mutation
+	// batch instead of once per read, and reads between writes are
+	// O(k)/O(result) instead of O(n)/O(n²). `readEntries`/`get` keep RAW
+	// parentId for round-trip consumers and are intentionally NOT indexed.
+	private _idxMap: Y.Map<unknown> | null = null;
+	private _idxObserver: (() => void) | null = null;
+	private _idxDirty = true;
+	private _byId = new Map<string, TreeEntry>();
+	private _childrenByParent = new Map<string | null, TreeEntry[]>();
+
+	/**
+	 * 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.
+	 */
+	private ensureIndex(): boolean {
+		if (!this.dm.treeIndexEnabled) return false;
+		const treeMap = this.dm.getTreeMap();
+		if (!treeMap) {
+			this.unbindIndex();
+			return false;
+		}
+		if (treeMap !== this._idxMap) {
+			// Root doc (space) swapped, or first use — rebind the observer.
+			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;
+	}
+
+	private unbindIndex(): void {
+		if (this._idxMap && this._idxObserver) {
+			this._idxMap.unobserveDeep(this._idxObserver);
+		}
+		this._idxMap = null;
+		this._idxObserver = null;
+		this._byId = new Map();
+		this._childrenByParent = new Map();
+		this._idxDirty = true;
+	}
+
+	private rebuildIndex(treeMap: Y.Map<unknown>): void {
+		const root = this.dm.rootDocId;
+		const byId = new Map<string, TreeEntry>();
+		const childrenByParent = new Map<string | null, TreeEntry[]>();
+		treeMap.forEach((raw: unknown, id: string) => {
+			const value = toPlain(raw) as Record<string, unknown>;
+			if (typeof value !== "object" || value === null) return;
+			const entry: TreeEntry = {
+				id,
+				label: (value.label as string) || "Untitled",
+				parentId: normalizeRootId(
+					(value.parentId as string | null) ?? null,
+					root,
+				),
+				order: (value.order as number) ?? 0,
+				type: value.type as string | undefined,
+				meta: value.meta as PageMeta | undefined,
+				createdAt: value.createdAt as number | undefined,
+				updatedAt: value.updatedAt as number | undefined,
+			};
+			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(): void {
+		this.unbindIndex();
+	}
+
 	// ── Reading ───────────────────────────────────────────────────────────────
 
 	/** Read all tree entries as plain objects. */
@@ -49,18 +191,100 @@ export class TreeManager {
 		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.
+	 */
+	private normalizedEntries(): TreeEntry[] {
+		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: string | null): TreeEntry[] {
 		const normalized = normalizeRootId(parentId, this.dm.rootDocId);
-		return this.readEntries()
+		if (this.ensureIndex()) {
+			// Copy: callers (descendantsOf, find, consumers) must not
+			// mutate the cached bucket.
+			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: string | null,
+		opts: { limit?: number; cursor?: string | null } = {},
+	): ChildrenPage {
+		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];
+		const nextCursor =
+			last && start + limit < all.length
+				? encodeCursor(last.order ?? 0, last.id)
+				: null;
+		return { entries, nextCursor };
+	}
+
 	/** Get all descendants recursively. */
 	descendantsOf(parentId: string | null): TreeEntry[] {
 		const normalized = normalizeRootId(parentId, this.dm.rootDocId);
-		const entries = this.readEntries();
+		if (this.ensureIndex()) {
+			const result: TreeEntry[] = [];
+			const visited = new Set<string>();
+			const walk = (pid: string | null) => {
+				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: TreeEntry[] = [];
 		const visited = new Set<string>();
 
@@ -87,10 +311,47 @@ export class TreeManager {
 			rootId ?? null,
 			this.dm.rootDocId,
 		);
-		const entries = this.readEntries();
+		if (this.ensureIndex()) {
+			return this._buildTreeIndexed(
+				normalized,
+				maxDepth,
+				0,
+				new Set(),
+			);
+		}
+		const entries = this.normalizedEntries();
 		return this._buildTree(entries, normalized, maxDepth, 0, new Set());
 	}
 
+	private _buildTreeIndexed(
+		rootId: string | null,
+		maxDepth: number,
+		currentDepth: number,
+		visited: Set<string>,
+	): TreeNode[] {
+		if (maxDepth >= 0 && currentDepth >= maxDepth) return [];
+		const children = this._childrenByParent.get(rootId) ?? [];
+		return children
+			.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,
+					),
+				};
+			});
+	}
+
 	private _buildTree(
 		entries: TreeEntry[],
 		rootId: string | null,
@@ -172,7 +433,7 @@ export class TreeManager {
 		query: string,
 		rootId?: string | null,
 	): TreeSearchResult[] {
-		const entries = this.readEntries();
+		const entries = this.normalizedEntries();
 		const lowerQuery = query.toLowerCase();
 
 		const normalized = normalizeRootId(
@@ -232,15 +493,18 @@ export class TreeManager {
 		const now = Date.now();
 
 		rootDoc.transact(() => {
-			treeMap.set(id, {
-				label: opts.label,
-				parentId: normalizedParent,
-				order: now,
-				type: opts.type,
-				meta: opts.meta as PageMeta,
-				createdAt: now,
-				updatedAt: now,
-			});
+			treeMap.set(
+				id,
+				makeEntryMap({
+					label: opts.label,
+					parentId: normalizedParent,
+					order: now,
+					type: opts.type,
+					meta: opts.meta as PageMeta,
+					createdAt: now,
+					updatedAt: now,
+				}),
+			);
 		});
 
 		return {
@@ -295,9 +559,8 @@ export class TreeManager {
 		const raw = treeMap.get(docId);
 		if (!raw) throw new Error(`Document ${docId} not found`);
 
-		const entry = toPlain(raw) as Record<string, unknown>;
 		rootDoc.transact(() => {
-			treeMap.set(docId, { ...entry, label, updatedAt: Date.now() });
+			patchEntry(treeMap, docId, { label, updatedAt: Date.now() });
 		});
 	}
 
@@ -314,10 +577,8 @@ export class TreeManager {
 		const raw = treeMap.get(docId);
 		if (!raw) throw new Error(`Document ${docId} not found`);
 
-		const entry = toPlain(raw) as Record<string, unknown>;
 		rootDoc.transact(() => {
-			treeMap.set(docId, {
-				...entry,
+			patchEntry(treeMap, docId, {
 				parentId: normalizeRootId(
 					newParentId ?? null,
 					this.dm.rootDocId,
@@ -337,9 +598,8 @@ export class TreeManager {
 		const raw = treeMap.get(docId);
 		if (!raw) throw new Error(`Document ${docId} not found`);
 
-		const entry = toPlain(raw) as Record<string, unknown>;
 		rootDoc.transact(() => {
-			treeMap.set(docId, { ...entry, type, updatedAt: Date.now() });
+			patchEntry(treeMap, docId, { type, updatedAt: Date.now() });
 		});
 	}
 
@@ -355,14 +615,17 @@ export class TreeManager {
 			throw new Error("Not connected");
 		}
 
-		const entries = this.readEntries();
-		const toDelete = [
-			docId,
-			...this._descendantIds(entries, docId),
-		];
-
 		const now = Date.now();
+		let deletedCount = 0;
+		// Compute the descendant set and trash it inside ONE synchronous
+		// Yjs transaction. transact() callbacks are atomic — no local or
+		// remote update interleaves — so a child concurrently added under
+		// this subtree cannot be stranded with a trashed parent the way a
+		// read-then-separate-write delete allowed.
 		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;
@@ -379,7 +642,7 @@ export class TreeManager {
 			}
 		});
 
-		return toDelete.length;
+		return deletedCount;
 	}
 
 	/** Duplicate a document (shallow clone). Returns the new entry. */
@@ -394,13 +657,16 @@ export class TreeManager {
 		const newId = crypto.randomUUID();
 		const now = Date.now();
 		const newLabel = ((entry.label as string) || "Untitled") + " (copy)";
-		treeMap.set(newId, {
-			...entry,
-			label: newLabel,
-			order: now,
-			createdAt: now,
-			updatedAt: now,
-		});
+		treeMap.set(
+			newId,
+			makeEntryMap({
+				...entry,
+				label: newLabel,
+				order: now,
+				createdAt: now,
+				updatedAt: now,
+			}),
+		);
 
 		return {
 			id: newId,
@@ -423,22 +689,52 @@ export class TreeManager {
 			throw new Error("Not connected");
 		}
 
-		const raw = trashMap.get(docId);
-		if (!raw) throw new Error(`Document ${docId} not found in trash`);
+		if (!trashMap.get(docId)) {
+			throw new Error(`Document ${docId} not found in trash`);
+		}
 
-		const entry = toPlain(raw) as Record<string, unknown>;
 		const now = Date.now();
+		// Restore docId AND its whole trashed subtree. delete() trashes
+		// the subtree as independent entries; restoring only the named id
+		// stranded every descendant in trash forever (audit RISK 4). The
+		// trash snapshot + descendant walk happen INSIDE the transaction,
+		// the same atomicity discipline delete() uses.
 		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 = new Map<string, Record<string, unknown>>();
+			trashMap.forEach((raw: unknown, id: string) => {
+				const v = toPlain(raw) as Record<string, unknown>;
+				if (typeof v === "object" && v !== null) trashed.set(id, v);
 			});
-			trashMap.delete(docId);
+
+			const toRestore: string[] = [];
+			const visited = new Set<string>();
+			const collect = (id: string) => {
+				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) as Record<string, unknown>;
+				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);
+			}
 		});
 	}
 

package/src/TreeTimestamps.ts

@@ -14,6 +14,8 @@
  */
 
 import * as Y from "yjs";
+
+import { patchEntry } from "./DocUtils.ts";
 import type { OfflineStore } from "./OfflineStore.ts";
 
 /**
@@ -47,8 +49,10 @@ export function attachUpdatedAtObserver(
 	function writeTs(ts: number): void {
 		const raw = treeMap.get(childDocId);
 		if (!raw) return;
-		const entry = raw instanceof Y.Map ? (raw as any).toJSON() : raw;
-		treeMap.set(childDocId, { ...entry, updatedAt: ts });
+		// Per-key set on the entry's nested Y.Map: the 5 s `updatedAt`
+		// write no longer clobbers a concurrent parentId/label edit
+		// (whole-entry-LWW fix, audit ⑦).
+		patchEntry(treeMap, childDocId, { updatedAt: ts });
 		lastFlushedAt = ts;
 	}
 

package/src/index.ts

@@ -128,6 +128,7 @@ export {
 export { DocumentManager } from "./DocumentManager.ts";
 export type { DocumentManagerConfig } from "./DocumentManager.ts";
 export { TreeManager } from "./TreeManager.ts";
+export type { ChildrenPage } from "./TreeManager.ts";
 export { ContentManager } from "./ContentManager.ts";
 export type { DocumentContent } from "./ContentManager.ts";
 export { MetaManager, MetaValidationError } from "./MetaManager.ts";
@@ -144,7 +145,14 @@ export type {
 	TypedDocsClient,
 } from "./SchemaTypes.ts";
 export * from "./DocTypes.ts";
-export { waitForSync, withTimeout, normalizeRootId, toPlain } from "./DocUtils.ts";
+export {
+	waitForSync,
+	withTimeout,
+	normalizeRootId,
+	toPlain,
+	makeEntryMap,
+	patchEntry,
+} from "./DocUtils.ts";
 export {
 	yjsToMarkdown,
 	populateYDocFromMarkdown,