@abraca/dabra 1.9.1 → 2.0.1

package/src/DocConverters.ts

@@ -118,7 +118,7 @@ function serializeElement(el: Y.XmlElement, indent = ""): string {
 			if (!docId) return "";
 			const seamlessAttr = el.getAttribute("seamless");
 			const seamless =
-				seamlessAttr === true || seamlessAttr === "true";
+				(seamlessAttr as unknown) === true || seamlessAttr === "true";
 			return seamless ? `![[${docId}]]{seamless}` : `![[${docId}]]`;
 		}
 
@@ -154,7 +154,7 @@ function serializeElement(el: Y.XmlElement, indent = ""): string {
 			const label = el.getAttribute("label") || "Details";
 			const open = el.getAttribute("open");
 			const props: string[] = [`label="${label}"`];
-			if (open === true || open === "true") props.push('open="true"');
+			if ((open as unknown) === true || open === "true") props.push('open="true"');
 			const inner = serializeChildren(el, indent);
 			return `::collapsible{${props.join(" ")}}\n${inner}\n::`;
 		}
@@ -219,7 +219,7 @@ function serializeElement(el: Y.XmlElement, indent = ""): string {
 			const props: string[] = [];
 			if (fieldName) props.push(`name="${fieldName}"`);
 			props.push(`type="${fieldType}"`);
-			if (required === true || required === "true")
+			if ((required as unknown) === true || required === "true")
 				props.push('required="true"');
 			const inner = serializeChildren(el, indent);
 			return `::field{${props.join(" ")}}\n${inner}\n::`;
@@ -266,7 +266,7 @@ function serializeTaskList(el: Y.XmlElement, indent: string): string {
 		) {
 			const checked = item.getAttribute("checked");
 			const marker =
-				checked === true || checked === "true" ? "[x]" : "[ ]";
+				(checked as unknown) === true || checked === "true" ? "[x]" : "[ ]";
 			const content = elementTextContent(item);
 			lines.push(`${indent}- ${marker} ${content}`);
 		}
@@ -504,7 +504,7 @@ export function parseFrontmatter(markdown: string): FrontmatterResult {
 
 	const checkedRaw = raw["checked"] ?? raw["done"];
 	if (checkedRaw !== undefined)
-		meta.checked = checkedRaw === "true" || checkedRaw === true;
+		meta.checked = checkedRaw === "true" || (checkedRaw as unknown) === true;
 
 	const dateStart = getStr(["date", "created"]);
 	if (dateStart) meta.dateStart = dateStart;
@@ -533,7 +533,7 @@ export function parseFrontmatter(markdown: string): FrontmatterResult {
 	if (datetimeEnd) meta.datetimeEnd = datetimeEnd;
 	const allDayRaw = raw["allDay"];
 	if (allDayRaw !== undefined)
-		meta.allDay = allDayRaw === "true" || allDayRaw === true;
+		meta.allDay = allDayRaw === "true" || (allDayRaw as unknown) === true;
 
 	// Geo fields
 	const geoLatRaw = getStr(["geoLat"]);
@@ -1705,3 +1705,158 @@ export function populateYDocFromMarkdown(
 		contentBlocks.forEach((block, i) => fillBlock(bodyEls[i]!, block));
 	});
 }
+
+// ── Block element builders (exported for ContentManager and SDK consumers) ────
+
+export function buildHeadingElement(text: string, level: 1|2|3|4|5|6 = 1): Y.XmlElement {
+	const el = new Y.XmlElement("heading");
+	el.setAttribute("level", level as any);
+	fillTextInto(el, parseInline(text));
+	return el;
+}
+
+export function buildParagraphElement(text: string): Y.XmlElement {
+	const el = new Y.XmlElement("paragraph");
+	fillTextInto(el, parseInline(text));
+	return el;
+}
+
+export function buildBulletListElement(items: string[]): Y.XmlElement {
+	const el = new Y.XmlElement("bulletList");
+	const itemEls = items.map(() => new Y.XmlElement("listItem"));
+	el.insert(0, itemEls);
+	items.forEach((text, i) => {
+		const paraEl = new Y.XmlElement("paragraph");
+		itemEls[i]!.insert(0, [paraEl]);
+		fillTextInto(paraEl, parseInline(text));
+	});
+	return el;
+}
+
+export function buildOrderedListElement(items: string[]): Y.XmlElement {
+	const el = new Y.XmlElement("orderedList");
+	const itemEls = items.map(() => new Y.XmlElement("listItem"));
+	el.insert(0, itemEls);
+	items.forEach((text, i) => {
+		const paraEl = new Y.XmlElement("paragraph");
+		itemEls[i]!.insert(0, [paraEl]);
+		fillTextInto(paraEl, parseInline(text));
+	});
+	return el;
+}
+
+export function buildTaskListElement(
+	items: Array<{ text: string; checked?: boolean }>,
+): Y.XmlElement {
+	const el = new Y.XmlElement("taskList");
+	const itemEls = items.map(() => new Y.XmlElement("taskItem"));
+	el.insert(0, itemEls);
+	items.forEach((item, i) => {
+		itemEls[i]!.setAttribute("checked", (item.checked ?? false) as any);
+		const paraEl = new Y.XmlElement("paragraph");
+		itemEls[i]!.insert(0, [paraEl]);
+		fillTextInto(paraEl, parseInline(item.text));
+	});
+	return el;
+}
+
+export function buildCodeBlockElement(code: string, language?: string): Y.XmlElement {
+	const el = new Y.XmlElement("codeBlock");
+	if (language) el.setAttribute("language", language);
+	const xt = new Y.XmlText();
+	el.insert(0, [xt]);
+	xt.insert(0, code);
+	return el;
+}
+
+export function buildBlockquoteElement(text: string): Y.XmlElement {
+	const el = new Y.XmlElement("blockquote");
+	const paraEl = new Y.XmlElement("paragraph");
+	el.insert(0, [paraEl]);
+	fillTextInto(paraEl, parseInline(text));
+	return el;
+}
+
+export function buildHorizontalRuleElement(): Y.XmlElement {
+	return new Y.XmlElement("horizontalRule");
+}
+
+/** Parse markdown into block Y.XmlElements (no header/meta). */
+export function buildBlocksFromMarkdown(markdown: string): Y.XmlElement[] {
+	const blocks = parseBlocks(markdown);
+	return blocks
+		.filter((b) => b.type !== "heading" || (b as any).level !== 1)
+		.map((b) => {
+			const el = new Y.XmlElement(blockElName(b));
+			fillBlock(el, b);
+			return el;
+		});
+}
+
+// ── Block reader ──────────────────────────────────────────────────────────────
+
+export interface DocumentBlock {
+	type: string;
+	attrs: Record<string, unknown>;
+	text: string;
+	items?: string[];
+	children?: DocumentBlock[];
+}
+
+export function readBlocksFromFragment(fragment: Y.XmlFragment): DocumentBlock[] {
+	const result: DocumentBlock[] = [];
+	for (let i = 0; i < fragment.length; i++) {
+		const child = fragment.get(i);
+		if (!(child instanceof Y.XmlElement)) continue;
+		const name = child.nodeName;
+		if (name === "documentHeader" || name === "documentMeta") continue;
+		result.push(_xmlElToBlock(child));
+	}
+	return result;
+}
+
+function _xmlElToBlock(el: Y.XmlElement): DocumentBlock {
+	const name = el.nodeName;
+	switch (name) {
+		case "heading":
+			return { type: "heading", attrs: { level: el.getAttribute("level") }, text: elementTextContent(el) };
+		case "paragraph":
+		case "blockquote":
+		case "horizontalRule":
+			return { type: name, attrs: {}, text: elementTextContent(el) };
+		case "codeBlock": {
+			const lang = el.getAttribute("language");
+			return { type: "codeBlock", attrs: lang ? { language: lang } : {}, text: elementTextContent(el) };
+		}
+		case "bulletList":
+		case "orderedList": {
+			const items: string[] = [];
+			for (let i = 0; i < el.length; i++) {
+				const item = el.get(i);
+				if (item instanceof Y.XmlElement && item.nodeName === "listItem")
+					items.push(elementTextContent(item));
+			}
+			return { type: name, attrs: {}, text: "", items };
+		}
+		case "taskList": {
+			const items: string[] = [];
+			const children: DocumentBlock[] = [];
+			for (let i = 0; i < el.length; i++) {
+				const item = el.get(i);
+				if (item instanceof Y.XmlElement && item.nodeName === "taskItem") {
+					const checked = item.getAttribute("checked");
+					const text = elementTextContent(item);
+					items.push(text);
+					children.push({
+						type: "taskItem",
+						attrs: { checked: checked === "true" || (checked as unknown) === true },
+						text,
+					});
+				}
+			}
+			return { type: "taskList", attrs: {}, text: "", items, children };
+		}
+		default:
+			return { type: name, attrs: {}, text: elementTextContent(el) };
+	}
+}

package/src/DocKeyManager.ts

@@ -45,16 +45,64 @@ export class DocKeyManager {
 		}
 
 		const envelope = await client.getMyKeyEnvelope(docId);
-		if (!envelope) return null;
+		if (envelope) {
+			const x25519PrivKey = await keystore.getX25519PrivateKey();
+			try {
+				const wrapped = fromBase64(envelope.encrypted_key);
+				const docKey = await this._unwrapKey(wrapped, x25519PrivKey, docId);
+				this.cache.set(docId, { key: docKey, epoch: envelope.key_epoch, fetchedAt: Date.now() });
+				return docKey;
+			} finally {
+				x25519PrivKey.fill(0);
+			}
+		}
 
-		const x25519PrivKey = await keystore.getX25519PrivateKey();
+		// Inheritance fallback. The doc has no envelope of our own — but it
+		// might inherit its encryption mode from an ancestor (e.g. a child
+		// page under an E2E space). The ancestor IS provisioned for us
+		// (otherwise we couldn't open the parent either). Resolve the
+		// encryption-source via /docs/:id/encryption.inherited_from, fetch
+		// OUR envelope on that source, unwrap with the source's salt,
+		// re-wrap for the current docId with its own salt, upload the new
+		// envelope so subsequent calls hit the direct-envelope path.
 		try {
-			const wrapped = fromBase64(envelope.encrypted_key);
-			const docKey = await this._unwrapKey(wrapped, x25519PrivKey, docId);
-			this.cache.set(docId, { key: docKey, epoch: envelope.key_epoch, fetchedAt: Date.now() });
-			return docKey;
-		} finally {
-			x25519PrivKey.fill(0);
+			const enc = await client.getDocEncryption(docId);
+			if (enc.effective_mode !== "e2e" || !enc.inherited_from || enc.inherited_from === docId) {
+				return null;
+			}
+			const sourceEnv = await client.getMyKeyEnvelope(enc.inherited_from);
+			if (!sourceEnv) return null;
+			const x25519PrivKey = await keystore.getX25519PrivateKey();
+			try {
+				const wrappedSrc = fromBase64(sourceEnv.encrypted_key);
+				const docKey = await this._unwrapKey(wrappedSrc, x25519PrivKey, enc.inherited_from);
+				this.cache.set(docId, { key: docKey, epoch: sourceEnv.key_epoch, fetchedAt: Date.now() });
+				// Re-wrap for the current doc + upload so future opens take
+				// the direct path. Best-effort — caller already has the key.
+				const me = await client.getMe();
+				if (me.publicKey) {
+					const myKeys = await client.listUserKeys(me.id);
+					const primaryKey = myKeys[0];
+					if (primaryKey?.x25519Key) {
+						const x25519Pub = fromBase64(primaryKey.x25519Key.replace(/-/g, "+").replace(/_/g, "/"));
+						const rewrapped = await this.wrapKeyForRecipient(docKey, x25519Pub, docId);
+						const b64 = (() => {
+							let s = "";
+							for (let i = 0; i < rewrapped.length; i++) s += String.fromCharCode(rewrapped[i]!);
+							return btoa(s);
+						})();
+						await client.uploadKeyEnvelopes(docId, {
+							key_epoch: sourceEnv.key_epoch,
+							envelopes: [{ recipient_key_id: primaryKey.id, encrypted_key: b64 }],
+						}).catch(() => null);
+					}
+				}
+				return docKey;
+			} finally {
+				x25519PrivKey.fill(0);
+			}
+		} catch {
+			return null;
 		}
 	}
 
@@ -73,11 +121,11 @@ export class DocKeyManager {
 
 		const salt = new TextEncoder().encode(docId);
 		const keyBytes = hkdf(sha256, sharedSecret, salt, HKDF_INFO, 32);
-		const wrapKey = await crypto.subtle.importKey("raw", keyBytes, { name: "AES-GCM" }, false, ["encrypt"]);
+		const wrapKey = await crypto.subtle.importKey("raw", keyBytes as BufferSource, { name: "AES-GCM" }, false, ["encrypt"]);
 
 		const rawDocKey = await crypto.subtle.exportKey("raw", docKey);
 		const nonce = crypto.getRandomValues(new Uint8Array(12));
-		const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce }, wrapKey, rawDocKey));
+		const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv: nonce as BufferSource }, wrapKey, rawDocKey));
 
 		const result = new Uint8Array(32 + 12 + ciphertext.length);
 		result.set(ephemeralPub, 0);
@@ -94,8 +142,8 @@ export class DocKeyManager {
 		const sharedSecret = x25519.getSharedSecret(recipientX25519PrivKey, ephemeralPub);
 		const salt = new TextEncoder().encode(docId);
 		const keyBytes = hkdf(sha256, sharedSecret, salt, HKDF_INFO, 32);
-		const wrapKey = await crypto.subtle.importKey("raw", keyBytes, { name: "AES-GCM" }, false, ["decrypt"]);
-		const rawDocKey = await crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce }, wrapKey, ciphertext);
+		const wrapKey = await crypto.subtle.importKey("raw", keyBytes as BufferSource, { name: "AES-GCM" }, false, ["decrypt"]);
+		const rawDocKey = await crypto.subtle.decrypt({ name: "AES-GCM", iv: nonce as BufferSource }, wrapKey, ciphertext as BufferSource);
 		return crypto.subtle.importKey("raw", rawDocKey, { name: "AES-GCM" }, true, ["encrypt", "decrypt"]);
 	}
 

package/src/DocTypes.ts

@@ -321,6 +321,16 @@ export const PAGE_TYPES: Record<string, PageTypeInfo> = {
     core: true,
     supportsChildren: true,
   },
+  prose: {
+    key: 'prose',
+    label: 'Prose',
+    icon: 'pen-tool',
+    description: 'Long-form prose with serif typography and a narrow readable measure',
+    core: true,
+    supportsChildren: true,
+    childLabel: 'Item',
+    defaultDepth: -1,
+  },
   kanban: {
     key: 'kanban',
     label: 'Kanban',

package/src/DocumentManager.ts

@@ -24,7 +24,9 @@
 import * as Y from "yjs";
 import { AbracadabraProvider } from "./AbracadabraProvider.ts";
 import { AbracadabraClient } from "./AbracadabraClient.ts";
-import type { ServerInfo, SpaceMeta, DocumentMeta } from "./types.ts";
+import type { AbracadabraWS } from "./AbracadabraWS.ts";
+import type { ServerInfo, DocumentMeta } from "./types.ts";
+import { Kind, SERVER_ROOT_ID } from "./types.ts";
 import { TreeManager } from "./TreeManager.ts";
 import { ContentManager } from "./ContentManager.ts";
 import { MetaManager } from "./MetaManager.ts";
@@ -52,26 +54,19 @@ export interface DocumentManagerConfig {
 	 * already authenticated or configured the client externally.
 	 */
 	client?: AbracadabraClient;
-}
-
-/** Map a DocumentMeta (REST API) to SpaceMeta shape for display compatibility. */
-function docToSpaceMeta(doc: DocumentMeta): SpaceMeta {
-	const publicAccess = doc.public_access;
-	let visibility: SpaceMeta["visibility"] = "private";
-	if (publicAccess && publicAccess !== "none") visibility = "public";
-
-	return {
-		id: doc.id,
-		doc_id: doc.id,
-		name: doc.label ?? doc.id,
-		description: doc.description ?? null,
-		visibility,
-		is_hub: doc.is_hub ?? false,
-		owner_id: doc.owner_id ?? null,
-		created_at: 0,
-		updated_at: doc.updated_at ?? 0,
-		public_access: publicAccess ?? null,
-	};
+	/**
+	 * Shared WebSocket connection. Required in Node.js environments — pass an
+	 * AbracadabraWS constructed with WebSocketPolyfill set to the `ws` package.
+	 * When omitted, each provider creates its own connection from client.wsUrl.
+	 * The caller owns this instance and must destroy it after dm.destroy().
+	 */
+	websocketProvider?: AbracadabraWS;
+	/**
+	 * Known root document ID. When provided, connect() skips server discovery
+	 * and connects directly to this document. Useful in tests or CLIs where
+	 * the entry-point docId is already known.
+	 */
+	rootDocId?: string;
 }
 
 interface CachedProvider {
@@ -92,7 +87,7 @@ export class DocumentManager {
 	private _config: DocumentManagerConfig;
 	private _serverInfo: ServerInfo | null = null;
 	private _rootDocId: string | null = null;
-	private _spaces: SpaceMeta[] = [];
+	private _spaces: DocumentMeta[] = [];
 	private _rootDoc: Y.Doc | null = null;
 	private _rootProvider: AbracadabraProvider | null = null;
 	private childCache = new Map<string, CachedProvider>();
@@ -138,7 +133,11 @@ export class DocumentManager {
 		return this._rootProvider;
 	}
 
-	get spaces(): SpaceMeta[] {
+	/**
+	 * Spaces visible to the caller — direct children of the server root with
+	 * `kind === "space"`. Populated by {@link connect}.
+	 */
+	get spaces(): DocumentMeta[] {
 		return this._spaces;
 	}
 
@@ -172,74 +171,42 @@ export class DocumentManager {
 	 * **Authentication must be done before calling connect().**
 	 * Call `dm.client.loginWithKey(publicKey, signFn)` or `dm.client.login()`
 	 * to authenticate first.
+	 *
+	 * When `rootDocId` is set in the config, server discovery is skipped and
+	 * the manager connects directly to that document.
 	 */
 	async connect(): Promise<void> {
-		// Step 1: Discover server info
+		// Step 1: Discover server info (used for awareness colour, name, etc.).
 		this._serverInfo = await this.client.serverInfo();
 
-		// Step 2: Discover root documents / spaces
-		let initialDocId: string | null =
-			this._serverInfo.index_doc_id ?? null;
-		try {
-			const roots = await this.client.listRootDocuments();
-			this._spaces = roots.map(docToSpaceMeta);
-			const hub = roots.find((d: any) => d.is_hub);
-			if (hub) {
-				initialDocId = hub.id;
-				this.log(
-					`Hub document: ${hub.label ?? hub.id} (${hub.id})`,
-				);
-			} else if (roots.length > 0) {
-				initialDocId = roots[0].id;
-				this.log(
-					`No hub, using first root doc: ${roots[0].label ?? roots[0].id}`,
-				);
-			}
-		} catch {
-			try {
-				this._spaces = await this.client.listSpaces();
-				const hub = this._spaces.find((s) => s.is_hub);
-				if (hub) {
-					initialDocId = hub.doc_id;
-				} else if (this._spaces.length > 0) {
-					initialDocId = this._spaces[0].doc_id;
-				}
-			} catch {
-				this.log(
-					"Neither /docs?root=true nor /spaces available, using index_doc_id",
-				);
+		// Step 2: Pick an entry-point doc.
+		//
+		// In the new model the dashboard's notion of "open the hub" maps to
+		// "open the first Space". A Space is a top-level doc with
+		// `kind === "space"`. If the caller pinned a `rootDocId`, honour it
+		// directly — useful in tests/CLIs where the entry doc is known.
+		let initialDocId: string | null = this._config.rootDocId ?? null;
+
+		if (!initialDocId) {
+			const roots = await this.client.listChildren();
+			this._spaces = roots.filter((d) => d.kind === Kind.Space);
+			const first = this._spaces[0] ?? roots[0];
+			if (first) {
+				initialDocId = first.id;
+				this.log(`Entry document: ${first.label ?? first.id} (${first.id})`);
 			}
 		}
 
 		if (!initialDocId) {
 			throw new Error(
-				"No entry point found: server has neither spaces nor index_doc_id configured.",
+				`No entry point found: server has no top-level documents under ${SERVER_ROOT_ID}. Create a Space first.`,
 			);
 		}
 
 		this._rootDocId = initialDocId;
 
 		// Step 3: Connect provider and sync
-		const doc = new Y.Doc({ guid: initialDocId });
-		const provider = new AbracadabraProvider({
-			name: initialDocId,
-			document: doc,
-			client: this.client,
-			disableOfflineStore:
-				this._config.disableOfflineStore ?? true,
-			subdocLoading: "lazy",
-		});
-
-		await waitForSync(provider);
-
-		provider.awareness.setLocalStateField("user", {
-			name: this.displayName,
-			color: this.displayColor,
-		});
-		provider.awareness.setLocalStateField("status", null);
-
-		this._rootDoc = doc;
-		this._rootProvider = provider;
+		await this._connectToRoot(initialDocId);
 		this.log("Connected and synced");
 	}
 
@@ -251,35 +218,45 @@ export class DocumentManager {
 		}
 		this.childCache.clear();
 
-		// Destroy current root provider
+		// Destroy current root provider (not the wsp — caller owns it)
 		if (this._rootProvider) {
 			this._rootProvider.destroy();
 			this._rootProvider = null;
 		}
 		this._rootDoc = null;
 
-		// Connect to new space
+		await this._connectToRoot(docId);
+		this._rootDocId = docId;
+		this.log(`Switched to space ${docId}`);
+	}
+
+	/** Create, sync, and set awareness on a root provider for the given docId. */
+	private async _connectToRoot(docId: string): Promise<void> {
 		const doc = new Y.Doc({ guid: docId });
+		const wsp = this._config.websocketProvider;
 		const provider = new AbracadabraProvider({
 			name: docId,
 			document: doc,
 			client: this.client,
-			disableOfflineStore:
-				this._config.disableOfflineStore ?? true,
+			disableOfflineStore: this._config.disableOfflineStore ?? true,
 			subdocLoading: "lazy",
+			...(wsp ? { websocketProvider: wsp } : {}),
 		});
 
+		// When a shared websocketProvider is supplied, manageSocket=false so
+		// the base constructor does NOT call attach(). We must do it ourselves.
+		if (wsp) provider.attach();
+
 		await waitForSync(provider);
 
-		provider.awareness.setLocalStateField("user", {
+		provider.awareness?.setLocalStateField("user", {
 			name: this.displayName,
 			color: this.displayColor,
 		});
+		provider.awareness?.setLocalStateField("status", null);
 
 		this._rootDoc = doc;
 		this._rootProvider = provider;
-		this._rootDocId = docId;
-		this.log(`Switched to space ${docId}`);
 	}
 
 	/** Graceful shutdown. */
@@ -290,7 +267,7 @@ export class DocumentManager {
 		this.childCache.clear();
 
 		if (this._rootProvider) {
-			this._rootProvider.awareness.setLocalStateField(
+			this._rootProvider.awareness?.setLocalStateField(
 				"status",
 				null,
 			);
@@ -319,7 +296,7 @@ export class DocumentManager {
 		const childProvider = await this._rootProvider.loadChild(docId);
 		await waitForSync(childProvider);
 
-		childProvider.awareness.setLocalStateField("user", {
+		childProvider.awareness?.setLocalStateField("user", {
 			name: this.displayName,
 			color: this.displayColor,
 		});