@abraca/dabra 1.8.2 → 2.0.0

package/src/DocConverters.ts

@@ -0,0 +1,1862 @@
+/**
+ * Document content converters — markdown ↔ Y.js.
+ *
+ * Canonical implementations for converting between Markdown text and TipTap-
+ * compatible Y.XmlFragment structures.  Previously lived in
+ * `mcp/converters/` — now the authoritative home is the provider package so
+ * any consumer of `@abraca/dabra` can use them without pulling in MCP deps.
+ */
+import * as Y from "yjs";
+import type { PageMeta } from "./DocTypes.ts";
+
+// ══════════════════════════════════════════════════════════════════════════════
+//  Y.XmlFragment → Markdown  (yjsToMarkdown)
+// ══════════════════════════════════════════════════════════════════════════════
+
+// ── Inline text serialization ────────────────────────────────────────────────
+
+function deltaToMarkdown(
+	delta: { insert: string; attributes?: Record<string, any> }[],
+): string {
+	return delta
+		.map((op) => {
+			let text = op.insert as string;
+			if (!op.attributes) return text;
+
+			const a = op.attributes;
+
+			if (a.code) text = `\`${text}\``;
+			if (a.bold) text = `**${text}**`;
+			if (a.italic) text = `*${text}*`;
+			if (a.strike) text = `~~${text}~~`;
+			if (a.link?.href) text = `[${text}](${a.link.href})`;
+			if (a.badge) text = `:badge[${a.badge.label || text}]`;
+			if (a.kbd) text = `:kbd{value="${a.kbd.value || text}"}`;
+			if (a.proseIcon) text = `:icon{name="${a.proseIcon.name}"}`;
+
+			return text;
+		})
+		.join("");
+}
+
+function xmlTextToMarkdown(xmlText: Y.XmlText): string {
+	const delta = xmlText.toDelta();
+	return deltaToMarkdown(delta);
+}
+
+function elementTextContent(el: Y.XmlElement | Y.XmlFragment): string {
+	const parts: string[] = [];
+	for (let i = 0; i < el.length; i++) {
+		const child = el.get(i);
+		if (child instanceof Y.XmlText) {
+			parts.push(xmlTextToMarkdown(child));
+		} else if (child instanceof Y.XmlElement) {
+			if (child.nodeName === "docLink") {
+				const docId = child.getAttribute("docId");
+				if (docId) parts.push(`[[${docId}]]`);
+				continue;
+			}
+			parts.push(elementTextContent(child));
+		}
+	}
+	return parts.join("");
+}
+
+// ── Block serialization ──────────────────────────────────────────────────────
+
+function serializeElement(el: Y.XmlElement, indent = ""): string {
+	const name = el.nodeName;
+
+	switch (name) {
+		case "documentHeader":
+		case "documentMeta":
+			return "";
+
+		case "heading": {
+			const level = Number(el.getAttribute("level")) || 1;
+			const prefix = "#".repeat(level);
+			return `${prefix} ${elementTextContent(el)}`;
+		}
+
+		case "paragraph":
+			return elementTextContent(el);
+
+		case "bulletList":
+			return serializeList(el, "bullet", indent);
+
+		case "orderedList":
+			return serializeList(el, "ordered", indent);
+
+		case "taskList":
+			return serializeTaskList(el, indent);
+
+		case "codeBlock": {
+			const lang = el.getAttribute("language") || "";
+			const code = elementTextContent(el);
+			return `\`\`\`${lang}\n${code}\n\`\`\``;
+		}
+
+		case "blockquote": {
+			const lines: string[] = [];
+			for (let i = 0; i < el.length; i++) {
+				const child = el.get(i);
+				if (child instanceof Y.XmlElement) {
+					lines.push(serializeElement(child, indent));
+				}
+			}
+			return lines.map((l) => `> ${l}`).join("\n");
+		}
+
+		case "horizontalRule":
+			return "---";
+
+		case "table":
+			return serializeTable(el);
+
+		case "docEmbed": {
+			const docId = el.getAttribute("docId");
+			if (!docId) return "";
+			const seamlessAttr = el.getAttribute("seamless");
+			const seamless =
+				(seamlessAttr as unknown) === true || seamlessAttr === "true";
+			return seamless ? `![[${docId}]]{seamless}` : `![[${docId}]]`;
+		}
+
+		case "svgEmbed": {
+			const svg = el.getAttribute("svg") || "";
+			const svgTitle = el.getAttribute("title") || "";
+			if (!svg) return "";
+			return `\`\`\`svg${svgTitle ? ` ${svgTitle}` : ""}\n${svg}\n\`\`\``;
+		}
+
+		case "image": {
+			const src = el.getAttribute("src") || "";
+			const alt = el.getAttribute("alt") || "";
+			const w = el.getAttribute("width");
+			const h = el.getAttribute("height");
+			let attrs = "";
+			if (w || h) {
+				const imgParts: string[] = [];
+				if (w) imgParts.push(`width="${w}"`);
+				if (h) imgParts.push(`height="${h}"`);
+				attrs = `{${imgParts.join(" ")}}`;
+			}
+			return `![${alt}](${src})${attrs}`;
+		}
+
+		case "callout": {
+			const type = el.getAttribute("type") || "note";
+			const inner = serializeChildren(el, indent);
+			return `::${type}\n${inner}\n::`;
+		}
+
+		case "collapsible": {
+			const label = el.getAttribute("label") || "Details";
+			const open = el.getAttribute("open");
+			const props: string[] = [`label="${label}"`];
+			if ((open as unknown) === true || open === "true") props.push('open="true"');
+			const inner = serializeChildren(el, indent);
+			return `::collapsible{${props.join(" ")}}\n${inner}\n::`;
+		}
+
+		case "steps": {
+			const inner = serializeChildren(el, indent);
+			return `::steps\n${inner}\n::`;
+		}
+
+		case "card": {
+			const title = el.getAttribute("title") || "";
+			const icon = el.getAttribute("icon") || "";
+			const to = el.getAttribute("to") || "";
+			const props: string[] = [];
+			if (title) props.push(`title="${title}"`);
+			if (icon) props.push(`icon="${icon}"`);
+			if (to) props.push(`to="${to}"`);
+			const inner = serializeChildren(el, indent);
+			return `::card{${props.join(" ")}}\n${inner}\n::`;
+		}
+
+		case "cardGroup": {
+			const inner = serializeChildren(el, indent);
+			return `::card-group\n${inner}\n::`;
+		}
+
+		case "codeCollapse": {
+			const inner = serializeChildren(el, indent);
+			return `::code-collapse\n${inner}\n::`;
+		}
+
+		case "codeGroup": {
+			const inner = serializeChildren(el, indent);
+			return `::code-group\n${inner}\n::`;
+		}
+
+		case "codePreview": {
+			const inner = serializeChildren(el, indent);
+			return `::code-preview\n${inner}\n::`;
+		}
+
+		case "codeTree": {
+			const files = el.getAttribute("files") || "[]";
+			return `::code-tree{files="${files}"}\n::`;
+		}
+
+		case "accordion":
+			return serializeSlottedComponent(
+				el,
+				"accordion",
+				"accordionItem",
+				"item",
+			);
+
+		case "tabs":
+			return serializeSlottedComponent(el, "tabs", "tabsItem", "tab");
+
+		case "field": {
+			const fieldName = el.getAttribute("name") || "";
+			const fieldType = el.getAttribute("type") || "string";
+			const required = el.getAttribute("required");
+			const props: string[] = [];
+			if (fieldName) props.push(`name="${fieldName}"`);
+			props.push(`type="${fieldType}"`);
+			if ((required as unknown) === true || required === "true")
+				props.push('required="true"');
+			const inner = serializeChildren(el, indent);
+			return `::field{${props.join(" ")}}\n${inner}\n::`;
+		}
+
+		case "fieldGroup": {
+			const inner = serializeChildren(el, indent);
+			return `::field-group\n${inner}\n::`;
+		}
+
+		default: {
+			return serializeChildren(el, indent);
+		}
+	}
+}
+
+function serializeList(
+	el: Y.XmlElement,
+	type: "bullet" | "ordered",
+	indent: string,
+): string {
+	const lines: string[] = [];
+	for (let i = 0; i < el.length; i++) {
+		const item = el.get(i);
+		if (
+			item instanceof Y.XmlElement &&
+			item.nodeName === "listItem"
+		) {
+			const prefix = type === "bullet" ? "- " : `${i + 1}. `;
+			const content = elementTextContent(item);
+			lines.push(`${indent}${prefix}${content}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+function serializeTaskList(el: Y.XmlElement, indent: string): string {
+	const lines: string[] = [];
+	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 marker =
+				(checked as unknown) === true || checked === "true" ? "[x]" : "[ ]";
+			const content = elementTextContent(item);
+			lines.push(`${indent}- ${marker} ${content}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+function serializeTable(el: Y.XmlElement): string {
+	const rows: string[][] = [];
+
+	for (let i = 0; i < el.length; i++) {
+		const row = el.get(i);
+		if (
+			!(row instanceof Y.XmlElement) ||
+			row.nodeName !== "tableRow"
+		)
+			continue;
+
+		const cells: string[] = [];
+		for (let j = 0; j < row.length; j++) {
+			const cell = row.get(j);
+			if (cell instanceof Y.XmlElement) {
+				cells.push(elementTextContent(cell));
+			}
+		}
+		rows.push(cells);
+	}
+
+	if (!rows.length) return "";
+
+	const headerRow = rows[0]!;
+	const lines = [`| ${headerRow.join(" | ")} |`];
+
+	// Separator
+	lines.push(`| ${headerRow.map(() => "---").join(" | ")} |`);
+
+	// Data rows
+	for (let i = 1; i < rows.length; i++) {
+		lines.push(`| ${rows[i]!.join(" | ")} |`);
+	}
+
+	return lines.join("\n");
+}
+
+function serializeSlottedComponent(
+	el: Y.XmlElement,
+	componentName: string,
+	childNodeName: string,
+	slotName: string,
+): string {
+	const parts: string[] = [`::${componentName}`];
+
+	for (let i = 0; i < el.length; i++) {
+		const child = el.get(i);
+		if (
+			!(child instanceof Y.XmlElement) ||
+			child.nodeName !== childNodeName
+		)
+			continue;
+
+		const label = child.getAttribute("label") || `Item ${i + 1}`;
+		const icon = child.getAttribute("icon") || "";
+		const props: string[] = [`label="${label}"`];
+		if (icon) props.push(`icon="${icon}"`);
+		parts.push(`#${slotName}{${props.join(" ")}}`);
+
+		const inner = serializeChildren(child, "");
+		if (inner) parts.push(inner);
+	}
+
+	parts.push("::");
+	return parts.join("\n");
+}
+
+function serializeChildren(
+	el: Y.XmlElement | Y.XmlFragment,
+	indent: string,
+): string {
+	const parts: string[] = [];
+	for (let i = 0; i < el.length; i++) {
+		const child = el.get(i);
+		if (child instanceof Y.XmlElement) {
+			const serialized = serializeElement(child, indent);
+			if (serialized) parts.push(serialized);
+		} else if (child instanceof Y.XmlText) {
+			const text = xmlTextToMarkdown(child);
+			if (text) parts.push(text);
+		}
+	}
+	return parts.join("\n\n");
+}
+
+// ── Public: Y.js → Markdown ─────────────────────────────────────────────────
+
+/**
+ * Converts a Y.XmlFragment (TipTap document) to markdown.
+ * Extracts the title from the documentHeader element.
+ *
+ * @returns `{ title, markdown }` where title is the H1/header text
+ */
+export function yjsToMarkdown(
+	fragment: Y.XmlFragment,
+): { title: string; markdown: string } {
+	let title = "Untitled";
+	const bodyParts: string[] = [];
+
+	for (let i = 0; i < fragment.length; i++) {
+		const child = fragment.get(i);
+		if (!(child instanceof Y.XmlElement)) continue;
+
+		if (child.nodeName === "documentHeader") {
+			title = elementTextContent(child) || "Untitled";
+			continue;
+		}
+
+		if (child.nodeName === "documentMeta") {
+			continue;
+		}
+
+		const serialized = serializeElement(child);
+		if (serialized !== "") {
+			bodyParts.push(serialized);
+		}
+	}
+
+	return { title, markdown: bodyParts.join("\n\n") };
+}
+
+// ══════════════════════════════════════════════════════════════════════════════
+//  Markdown → Y.XmlFragment  (populateYDocFromMarkdown)
+// ══════════════════════════════════════════════════════════════════════════════
+
+// ── Filename → readable label ────────────────────────────────────────────────
+
+export function filenameToLabel(raw: string): string {
+	const base = raw.replace(/\.[^.]+$/, "");
+	const spaced = base.replace(/([a-z])([A-Z])/g, "$1 $2");
+	const clean = spaced
+		.replace(/[-_.]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	return clean.charAt(0).toUpperCase() + clean.slice(1);
+}
+
+// ── YAML frontmatter parser ──────────────────────────────────────────────────
+
+export interface FrontmatterResult {
+	title?: string;
+	meta: Partial<PageMeta>;
+	body: string;
+}
+
+function parseInlineArray(raw: string): string[] {
+	return raw
+		.slice(1, -1)
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+export function parseFrontmatter(markdown: string): FrontmatterResult {
+	const noResult: FrontmatterResult = { meta: {}, body: markdown };
+
+	const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+	if (!match) return noResult;
+
+	const yamlBlock = match[1]!;
+	const body = markdown.slice(match[0].length);
+
+	const raw: Record<string, string | string[]> = {};
+	const lines = yamlBlock.split("\n");
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i]!;
+		const blockSeqKey = line.match(/^(\w[\w-]*):\s*$/);
+		if (
+			blockSeqKey &&
+			i + 1 < lines.length &&
+			/^\s+-\s/.test(lines[i + 1]!)
+		) {
+			const key = blockSeqKey[1]!;
+			const items: string[] = [];
+			i++;
+			while (i < lines.length && /^\s+-\s/.test(lines[i]!)) {
+				items.push(lines[i]!.replace(/^\s+-\s/, "").trim());
+				i++;
+			}
+			raw[key] = items;
+			continue;
+		}
+		const kvMatch = line.match(/^(\w[\w-]*):\s*(.*)$/);
+		if (kvMatch) {
+			const key = kvMatch[1]!;
+			const val = kvMatch[2]!.trim();
+			if (val.startsWith("[") && val.endsWith("]")) {
+				raw[key] = parseInlineArray(val);
+			} else {
+				raw[key] = val;
+			}
+		}
+		i++;
+	}
+
+	const meta: Partial<PageMeta> = {};
+
+	const getStr = (keys: string[]): string | undefined => {
+		for (const k of keys) {
+			const v = raw[k];
+			if (typeof v === "string" && v) return v;
+		}
+	};
+
+	if (raw["tags"])
+		meta.tags = Array.isArray(raw["tags"])
+			? raw["tags"]
+			: [raw["tags"] as string];
+	const color = getStr(["color"]);
+	if (color) meta.color = color;
+	const icon = getStr(["icon"]);
+	if (icon) meta.icon = icon;
+	const status = getStr(["status"]);
+	if (status) meta.status = status;
+
+	const priorityRaw = getStr(["priority"]);
+	if (priorityRaw !== undefined) {
+		const map: Record<string, number> = {
+			low: 1,
+			medium: 2,
+			high: 3,
+			urgent: 4,
+		};
+		meta.priority =
+			map[priorityRaw.toLowerCase()] ?? (Number(priorityRaw) || 0);
+	}
+
+	const checkedRaw = raw["checked"] ?? raw["done"];
+	if (checkedRaw !== undefined)
+		meta.checked = checkedRaw === "true" || (checkedRaw as unknown) === true;
+
+	const dateStart = getStr(["date", "created"]);
+	if (dateStart) meta.dateStart = dateStart;
+	const dateEnd = getStr(["due"]);
+	if (dateEnd) meta.dateEnd = dateEnd;
+
+	const subtitle = getStr(["description", "subtitle"]);
+	if (subtitle) meta.subtitle = subtitle;
+	const url = getStr(["url"]);
+	if (url) meta.url = url;
+	const email = getStr(["email"]);
+	if (email) meta.email = email;
+	const phone = getStr(["phone"]);
+	if (phone) meta.phone = phone;
+
+	const ratingRaw = getStr(["rating"]);
+	if (ratingRaw !== undefined) {
+		const n = Number(ratingRaw);
+		if (!Number.isNaN(n)) meta.rating = Math.min(5, Math.max(0, n));
+	}
+
+	// Datetime fields
+	const datetimeStart = getStr(["datetimeStart"]);
+	if (datetimeStart) meta.datetimeStart = datetimeStart;
+	const datetimeEnd = getStr(["datetimeEnd"]);
+	if (datetimeEnd) meta.datetimeEnd = datetimeEnd;
+	const allDayRaw = raw["allDay"];
+	if (allDayRaw !== undefined)
+		meta.allDay = allDayRaw === "true" || (allDayRaw as unknown) === true;
+
+	// Geo fields
+	const geoLatRaw = getStr(["geoLat"]);
+	if (geoLatRaw !== undefined) {
+		const n = Number(geoLatRaw);
+		if (!Number.isNaN(n)) meta.geoLat = n;
+	}
+	const geoLngRaw = getStr(["geoLng"]);
+	if (geoLngRaw !== undefined) {
+		const n = Number(geoLngRaw);
+		if (!Number.isNaN(n)) meta.geoLng = n;
+	}
+	const geoType = getStr(["geoType"]);
+	if (
+		geoType &&
+		(geoType === "marker" || geoType === "line" || geoType === "measure")
+	) {
+		meta.geoType = geoType;
+	}
+	const geoDescription = getStr(["geoDescription"]);
+	if (geoDescription) meta.geoDescription = geoDescription;
+
+	// Numeric fields
+	const numberRaw = getStr(["number"]);
+	if (numberRaw !== undefined) {
+		const n = Number(numberRaw);
+		if (!Number.isNaN(n)) meta.number = n;
+	}
+	const unit = getStr(["unit"]);
+	if (unit) meta.unit = unit;
+
+	// Note
+	const note = getStr(["note"]);
+	if (note) meta.note = note;
+
+	const title = typeof raw["title"] === "string" ? raw["title"] : undefined;
+
+	return { title, meta, body };
+}
+
+// ── Inline token parsing ─────────────────────────────────────────────────────
+
+interface InlineToken {
+	text: string;
+	attrs?: Record<string, unknown>;
+	/** If set, emit an inline Y.XmlElement with this nodeName instead of text+marks. */
+	node?: string;
+	/** Attributes for the inline node (when node is set). */
+	nodeAttrs?: Record<string, string>;
+}
+
+function parseMdcProps(
+	propsStr: string | undefined,
+): Record<string, string> {
+	if (!propsStr) return {};
+	const result: Record<string, string> = {};
+	const re = /(\w[\w-]*)="([^"]*)"/g;
+	let m: RegExpExecArray | null;
+	while ((m = re.exec(propsStr)) !== null) {
+		result[m[1]!] = m[2]!;
+	}
+	return result;
+}
+
+function parseInline(text: string): InlineToken[] {
+	const stripped = text
+		.replace(/\{lang="[^"]*"\}/g, "")
+		.replace(
+			/:(?!badge|icon|kbd)(\w[\w-]*)\[([^\]]*)\](\{[^}]*\})?/g,
+			"$2",
+		)
+		.replace(/:(?!badge|icon|kbd)(\w[\w-]*)(\{[^}]*\})/g, "");
+
+	const tokens: InlineToken[] = [];
+	const re =
+		/:badge\[([^\]]*)\](\{[^}]*\})?|:icon\{([^}]*)\}|:kbd\{([^}]*)\}|!?\[\[([^\]|]+?)(?:\|([^\]]+?))?\]\]|~~(.+?)~~|\*\*(.+?)\*\*|\*(.+?)\*|_(.+?)_|`(.+?)`|\[(.+?)\]\((.+?)\)/g;
+	let lastIndex = 0;
+	let match: RegExpExecArray | null;
+
+	while ((match = re.exec(stripped)) !== null) {
+		if (match.index > lastIndex) {
+			tokens.push({ text: stripped.slice(lastIndex, match.index) });
+		}
+		if (match[1] !== undefined) {
+			const badgeProps = parseMdcProps(match[2]);
+			tokens.push({
+				text: match[1] || "Badge",
+				attrs: {
+					badge: {
+						label: match[1] || "Badge",
+						color: badgeProps["color"] || "neutral",
+						variant: badgeProps["variant"] || "subtle",
+					},
+				},
+			});
+		} else if (match[3] !== undefined) {
+			const iconProps = parseMdcProps(`{${match[3]}}`);
+			tokens.push({
+				text: "\u200B",
+				attrs: {
+					proseIcon: {
+						name: iconProps["name"] || "i-lucide-star",
+					},
+				},
+			});
+		} else if (match[4] !== undefined) {
+			const kbdProps = parseMdcProps(`{${match[4]}}`);
+			tokens.push({
+				text: kbdProps["value"] || "",
+				attrs: { kbd: { value: kbdProps["value"] || "" } },
+			});
+		} else if (match[5] !== undefined) {
+			tokens.push({
+				text: "",
+				node: "docLink",
+				nodeAttrs: { docId: match[5]! },
+			});
+		} else if (match[7] !== undefined) {
+			tokens.push({ text: match[7], attrs: { strike: true } });
+		} else if (match[8] !== undefined) {
+			tokens.push({ text: match[8], attrs: { bold: true } });
+		} else if (match[9] !== undefined) {
+			tokens.push({ text: match[9], attrs: { italic: true } });
+		} else if (match[10] !== undefined) {
+			tokens.push({ text: match[10], attrs: { italic: true } });
+		} else if (match[11] !== undefined) {
+			tokens.push({ text: match[11], attrs: { code: true } });
+		} else if (match[12] !== undefined && match[13] !== undefined) {
+			tokens.push({
+				text: match[12],
+				attrs: { link: { href: match[13] } },
+			});
+		}
+		lastIndex = match.index + match[0].length;
+	}
+
+	if (lastIndex < stripped.length) {
+		tokens.push({ text: stripped.slice(lastIndex) });
+	}
+	return tokens.filter((t) => t.node || t.text.length > 0);
+}
+
+// ── Block-level parser ───────────────────────────────────────────────────────
+
+interface TaskItem {
+	text: string;
+	checked: boolean;
+}
+
+type Block =
+	| { type: "heading"; level: number; text: string }
+	| { type: "paragraph"; text: string }
+	| { type: "bulletList"; items: string[] }
+	| { type: "orderedList"; items: string[] }
+	| { type: "taskList"; items: TaskItem[] }
+	| { type: "codeBlock"; lang: string; code: string }
+	| { type: "blockquote"; lines: string[] }
+	| { type: "table"; headerRow: string[]; dataRows: string[][] }
+	| { type: "hr" }
+	| { type: "callout"; calloutType: string; innerBlocks: Block[] }
+	| {
+			type: "collapsible";
+			label: string;
+			open: boolean;
+			innerBlocks: Block[];
+	  }
+	| { type: "steps"; innerBlocks: Block[] }
+	| {
+			type: "card";
+			title: string;
+			icon: string;
+			to: string;
+			innerBlocks: Block[];
+	  }
+	| { type: "cardGroup"; cards: Block[] }
+	| { type: "codeCollapse"; codeBlocks: Block[] }
+	| { type: "codeGroup"; codeBlocks: Block[] }
+	| { type: "codePreview"; innerBlocks: Block[]; codeBlocks: Block[] }
+	| { type: "codeTree"; files: string }
+	| {
+			type: "accordion";
+			items: { label: string; icon: string; innerBlocks: Block[] }[];
+	  }
+	| {
+			type: "tabs";
+			items: { label: string; icon: string; innerBlocks: Block[] }[];
+	  }
+	| {
+			type: "field";
+			name: string;
+			fieldType: string;
+			required: boolean;
+			innerBlocks: Block[];
+	  }
+	| { type: "fieldGroup"; fields: Block[] }
+	| {
+			type: "image";
+			src: string;
+			alt: string;
+			width?: string;
+			height?: string;
+	  }
+	| { type: "docEmbed"; docId: string; seamless?: boolean }
+	| { type: "svgEmbed"; svg: string; title: string };
+
+function parseTableRow(line: string): string[] {
+	const parts = line.split("|");
+	return parts.slice(1, parts.length - 1).map((c) => c.trim());
+}
+
+function isTableSeparator(line: string): boolean {
+	return /^\|[\s|:-]+\|$/.test(line.trim());
+}
+
+function extractFencedCode(lines: string[]): Block[] {
+	const result: Block[] = [];
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i]!;
+		const fenceMatch = line.match(/^(`{3,})(\w*)/);
+		if (fenceMatch) {
+			const fence = fenceMatch[1]!;
+			const lang = fenceMatch[2] ?? "";
+			const codeLines: string[] = [];
+			i++;
+			while (i < lines.length && !lines[i]!.startsWith(fence)) {
+				codeLines.push(lines[i]!);
+				i++;
+			}
+			i++;
+			result.push({
+				type: "codeBlock",
+				lang,
+				code: codeLines.join("\n"),
+			});
+			continue;
+		}
+		i++;
+	}
+	return result;
+}
+
+function parseMdcChildren(
+	innerLines: string[],
+	slotPrefix: string,
+): { label: string; icon: string; innerBlocks: Block[] }[] {
+	const items: { label: string; icon: string; lines: string[] }[] = [];
+	let current: { label: string; icon: string; lines: string[] } | null =
+		null;
+	const slotRe = new RegExp(`^#${slotPrefix}(\\{[^}]*\\})?\\s*$`);
+
+	for (const line of innerLines) {
+		const slotMatch = line.match(slotRe);
+		if (slotMatch) {
+			if (current) items.push(current);
+			const props = parseMdcProps(slotMatch[1]);
+			current = {
+				label:
+					props["label"] ||
+					props["title"] ||
+					`Item ${items.length + 1}`,
+				icon: props["icon"] || "",
+				lines: [],
+			};
+			continue;
+		}
+		if (current) {
+			current.lines.push(line);
+		} else {
+			if (!items.length && !current) {
+				current = { label: "Item 1", icon: "", lines: [line] };
+			}
+		}
+	}
+	if (current) items.push(current);
+
+	return items.map((item) => ({
+		label: item.label,
+		icon: item.icon,
+		innerBlocks: parseBlocks(item.lines.join("\n")),
+	}));
+}
+
+const TASK_RE = /^[-*+]\s+\[([ xX])\]\s+(.*)/;
+
+function parseBlocks(markdown: string): Block[] {
+	const rawLines = markdown.split("\n");
+	let firstContentLine = 0;
+	while (firstContentLine < rawLines.length) {
+		const l = rawLines[firstContentLine]!;
+		if (l.trim() === "" || /^import\s/.test(l) || /^export\s/.test(l)) {
+			firstContentLine++;
+		} else {
+			break;
+		}
+	}
+	const stripped = rawLines.slice(firstContentLine).join("\n");
+
+	const blocks: Block[] = [];
+	const lines = stripped.split("\n");
+	let i = 0;
+
+	while (i < lines.length) {
+		const line = lines[i]!;
+
+		const fenceBlockMatch = line.match(/^(`{3,})(.*)$/);
+		if (fenceBlockMatch) {
+			const fence = fenceBlockMatch[1]!;
+			const lang = fenceBlockMatch[2]!
+				.trim()
+				.replace(/\{[^}]*\}$/, "")
+				.replace(/\s*\[.*\]$/, "")
+				.trim();
+			const codeLines: string[] = [];
+			i++;
+			while (i < lines.length && !lines[i]!.startsWith(fence)) {
+				codeLines.push(lines[i]!);
+				i++;
+			}
+			i++;
+			if (lang === "svg" || lang.startsWith("svg ")) {
+				const svgTitle =
+					lang === "svg" ? "" : lang.slice(4).trim();
+				blocks.push({
+					type: "svgEmbed",
+					svg: codeLines.join("\n"),
+					title: svgTitle,
+				});
+			} else {
+				blocks.push({
+					type: "codeBlock",
+					lang,
+					code: codeLines.join("\n"),
+				});
+			}
+			continue;
+		}
+
+		const headingMatch = line.match(/^(#{1,6})\s+(.*)/);
+		if (headingMatch) {
+			blocks.push({
+				type: "heading",
+				level: headingMatch[1]!.length,
+				text: headingMatch[2]!.trim(),
+			});
+			i++;
+			continue;
+		}
+
+		if (/^[-*_]{3,}\s*$/.test(line)) {
+			blocks.push({ type: "hr" });
+			i++;
+			continue;
+		}
+
+		const docEmbedMatch = line.match(
+			/^!\[\[([^\]|]+?)(?:\|[^\]]*?)?\]\](\{[^}]*\})?\s*$/,
+		);
+		if (docEmbedMatch) {
+			const props = parseMdcProps(docEmbedMatch[2]);
+			const seamless =
+				"seamless" in props ||
+				props["seamless"] === "true" ||
+				/\{[^}]*\bseamless\b[^}]*\}/.test(docEmbedMatch[2] ?? "");
+			blocks.push({
+				type: "docEmbed",
+				docId: docEmbedMatch[1]!,
+				seamless: seamless || undefined,
+			});
+			i++;
+			continue;
+		}
+
+		const imgMatch = line.match(
+			/^!\[([^\]]*)\]\(([^)]+)\)(\{[^}]*\})?\s*$/,
+		);
+		if (imgMatch) {
+			const alt = imgMatch[1] ?? "";
+			const src = imgMatch[2] ?? "";
+			const attrs = parseMdcProps(imgMatch[3]);
+			blocks.push({
+				type: "image",
+				src,
+				alt,
+				width: attrs["width"],
+				height: attrs["height"],
+			});
+			i++;
+			continue;
+		}
+
+		if (line.startsWith("> ") || line === ">") {
+			const bqLines: string[] = [];
+			while (
+				i < lines.length &&
+				(lines[i]!.startsWith("> ") || lines[i] === ">")
+			) {
+				bqLines.push(lines[i]!.replace(/^>\s?/, ""));
+				i++;
+			}
+			blocks.push({ type: "blockquote", lines: bqLines });
+			continue;
+		}
+
+		if (/^\s*\|/.test(line)) {
+			const tableLines: string[] = [];
+			while (i < lines.length && /^\s*\|/.test(lines[i]!)) {
+				tableLines.push(lines[i]!);
+				i++;
+			}
+			if (
+				tableLines.length >= 2 &&
+				isTableSeparator(tableLines[1]!)
+			) {
+				const headerRow = parseTableRow(tableLines[0]!);
+				const dataRows = tableLines
+					.slice(2)
+					.filter((l) => !isTableSeparator(l))
+					.map(parseTableRow);
+				blocks.push({ type: "table", headerRow, dataRows });
+			} else {
+				for (const l of tableLines)
+					blocks.push({ type: "paragraph", text: l });
+			}
+			continue;
+		}
+
+		const MDC_OPEN = /^\s*(:{2,})(\w[\w-]*)(\{[^}]*\})?\s*$/;
+		if (MDC_OPEN.test(line)) {
+			const colons =
+				line.match(/^\s*(:+)/)?.[1]?.length ?? 2;
+			const componentName =
+				line.match(/^\s*:{2,}(\w[\w-]*)/)?.[1] ?? "";
+			const innerLines: string[] = [];
+			i++;
+			while (i < lines.length) {
+				const l = lines[i]!;
+				if (
+					new RegExp(`^\\s*:{${colons}}\\s*$`).test(l)
+				) {
+					i++;
+					break;
+				}
+				const innerFence = l.match(/^(\s*`{3,})/);
+				if (innerFence) {
+					const fenceStr = innerFence[1]!.trimStart();
+					innerLines.push(l);
+					i++;
+					while (
+						i < lines.length &&
+						!lines[i]!.trimStart().startsWith(fenceStr)
+					) {
+						innerLines.push(lines[i]!);
+						i++;
+					}
+					if (i < lines.length) {
+						innerLines.push(lines[i]!);
+						i++;
+					}
+					continue;
+				}
+				innerLines.push(l);
+				i++;
+			}
+
+			const nonBlank = innerLines.filter(
+				(l) => l.trim().length > 0,
+			);
+			if (nonBlank.length) {
+				const minIndent = Math.min(
+					...nonBlank.map(
+						(l) => l.match(/^(\s*)/)?.[1]?.length ?? 0,
+					),
+				);
+				if (minIndent > 0) {
+					for (let j = 0; j < innerLines.length; j++) {
+						innerLines[j] = innerLines[j]!.slice(
+							Math.min(minIndent, innerLines[j]!.length),
+						);
+					}
+				}
+			}
+
+			let contentStart = 0;
+			if (innerLines[0]?.trim() === "---") {
+				const fmEnd = innerLines.findIndex(
+					(l, idx) => idx > 0 && l.trim() === "---",
+				);
+				if (fmEnd !== -1) contentStart = fmEnd + 1;
+			}
+			const contentLines = innerLines.slice(contentStart);
+
+			const defaultSlotLines: string[] = [];
+			const codeSlotLines: string[] = [];
+			let currentSlot: "default" | "code" | "other" = "default";
+			for (const l of contentLines) {
+				if (/^#code\s*$/.test(l)) {
+					currentSlot = "code";
+					continue;
+				}
+				if (/^#\w+/.test(l) && !/^#{2,}\s/.test(l)) {
+					currentSlot = "other";
+					continue;
+				}
+				if (currentSlot === "default") defaultSlotLines.push(l);
+				else if (currentSlot === "code") codeSlotLines.push(l);
+			}
+			const innerBlocks = parseBlocks(defaultSlotLines.join("\n"));
+
+			const codeBlocks = extractFencedCode(codeSlotLines);
+
+			const CALLOUT_NAMES = new Set([
+				"tip",
+				"note",
+				"info",
+				"warning",
+				"caution",
+				"danger",
+				"callout",
+				"alert",
+			]);
+			if (CALLOUT_NAMES.has(componentName.toLowerCase())) {
+				blocks.push({
+					type: "callout",
+					calloutType: componentName.toLowerCase(),
+					innerBlocks,
+				});
+			} else {
+				const mdcProps = parseMdcProps(
+					line.match(MDC_OPEN)?.[3],
+				);
+				const lc = componentName.toLowerCase();
+
+				if (lc === "collapsible") {
+					blocks.push({
+						type: "collapsible",
+						label: mdcProps["label"] || "Details",
+						open: mdcProps["open"] === "true",
+						innerBlocks,
+					});
+				} else if (lc === "steps") {
+					blocks.push({ type: "steps", innerBlocks });
+				} else if (lc === "card") {
+					blocks.push({
+						type: "card",
+						title: mdcProps["title"] || "",
+						icon: mdcProps["icon"] || "",
+						to: mdcProps["to"] || "",
+						innerBlocks,
+					});
+				} else if (lc === "card-group") {
+					const cards = innerBlocks.filter(
+						(b) => b.type === "card",
+					);
+					if (cards.length) {
+						blocks.push({ type: "cardGroup", cards });
+					} else {
+						blocks.push(...innerBlocks);
+					}
+				} else if (lc === "code-collapse") {
+					blocks.push({
+						type: "codeCollapse",
+						codeBlocks: codeBlocks.length
+							? codeBlocks
+							: innerBlocks.filter(
+									(b) => b.type === "codeBlock",
+								),
+					});
+				} else if (lc === "code-group") {
+					const allCode = [
+						...innerBlocks.filter(
+							(b) => b.type === "codeBlock",
+						),
+						...codeBlocks,
+					];
+					blocks.push({ type: "codeGroup", codeBlocks: allCode });
+				} else if (lc === "code-preview") {
+					blocks.push({
+						type: "codePreview",
+						innerBlocks,
+						codeBlocks,
+					});
+				} else if (lc === "code-tree") {
+					blocks.push({
+						type: "codeTree",
+						files: mdcProps["files"] || "[]",
+					});
+				} else if (lc === "accordion") {
+					const items = parseMdcChildren(
+						contentLines,
+						"item",
+					);
+					if (items.length) {
+						blocks.push({ type: "accordion", items });
+					} else {
+						blocks.push({
+							type: "accordion",
+							items: [
+								{
+									label: "Item 1",
+									icon: "",
+									innerBlocks,
+								},
+							],
+						});
+					}
+				} else if (lc === "tabs") {
+					const items = parseMdcChildren(
+						contentLines,
+						"tab",
+					);
+					if (items.length) {
+						blocks.push({ type: "tabs", items });
+					} else {
+						blocks.push({
+							type: "tabs",
+							items: [
+								{
+									label: "Tab 1",
+									icon: "",
+									innerBlocks,
+								},
+							],
+						});
+					}
+				} else if (lc === "field") {
+					blocks.push({
+						type: "field",
+						name: mdcProps["name"] || "",
+						fieldType: mdcProps["type"] || "string",
+						required: mdcProps["required"] === "true",
+						innerBlocks,
+					});
+				} else if (lc === "field-group") {
+					const fields = innerBlocks.filter(
+						(b) => b.type === "field",
+					);
+					if (fields.length) {
+						blocks.push({ type: "fieldGroup", fields });
+					} else {
+						blocks.push(...innerBlocks);
+					}
+				} else {
+					blocks.push(...innerBlocks);
+					blocks.push(...codeBlocks);
+				}
+			}
+			continue;
+		}
+
+		if (TASK_RE.test(line)) {
+			const items: TaskItem[] = [];
+			while (i < lines.length && TASK_RE.test(lines[i]!)) {
+				const m = lines[i]!.match(TASK_RE)!;
+				items.push({
+					checked: m[1]!.toLowerCase() === "x",
+					text: m[2]!,
+				});
+				i++;
+			}
+			blocks.push({ type: "taskList", items });
+			continue;
+		}
+
+		if (/^[-*+]\s+/.test(line)) {
+			const items: string[] = [];
+			while (
+				i < lines.length &&
+				/^[-*+]\s+/.test(lines[i]!) &&
+				!TASK_RE.test(lines[i]!)
+			) {
+				items.push(lines[i]!.replace(/^[-*+]\s+/, ""));
+				i++;
+			}
+			if (items.length) {
+				blocks.push({ type: "bulletList", items });
+				continue;
+			}
+		}
+
+		if (/^\d+\.\s+/.test(line)) {
+			const items: string[] = [];
+			while (i < lines.length && /^\d+\.\s+/.test(lines[i]!)) {
+				items.push(lines[i]!.replace(/^\d+\.\s+/, ""));
+				i++;
+			}
+			blocks.push({ type: "orderedList", items });
+			continue;
+		}
+
+		if (line.trim() === "") {
+			i++;
+			continue;
+		}
+
+		const paraLines: string[] = [];
+		while (
+			i < lines.length &&
+			lines[i]!.trim() !== "" &&
+			!/^(#{1,6}\s|[-*+]\s|\d+\.\s|>|`{3,}|\s*\||[-*_]{3,}\s*$|\s*:{2,}\w)/.test(
+				lines[i]!,
+			)
+		) {
+			paraLines.push(lines[i]!);
+			i++;
+		}
+		if (paraLines.length) {
+			blocks.push({ type: "paragraph", text: paraLines.join(" ") });
+		}
+	}
+
+	return blocks;
+}
+
+// ── Y.js content population helpers ──────────────────────────────────────────
+
+function fillTextInto(
+	el: Y.XmlElement,
+	tokens: InlineToken[],
+): void {
+	const filtered = tokens.filter((t) => t.node || t.text.length > 0);
+	if (!filtered.length) return;
+
+	const children: (Y.XmlText | Y.XmlElement)[] = filtered.map((tok) => {
+		if (tok.node) {
+			const xe = new Y.XmlElement(tok.node);
+			if (tok.nodeAttrs) {
+				for (const [k, v] of Object.entries(tok.nodeAttrs))
+					xe.setAttribute(k, v);
+			}
+			return xe;
+		}
+		return new Y.XmlText();
+	});
+	el.insert(0, children);
+
+	filtered.forEach((tok, i) => {
+		if (tok.node) return;
+		const xt = children[i] as Y.XmlText;
+		if (tok.attrs) {
+			xt.insert(
+				0,
+				tok.text,
+				tok.attrs as Record<string, boolean | object>,
+			);
+		} else {
+			xt.insert(0, tok.text);
+		}
+	});
+}
+
+function blockElName(b: Block): string {
+	switch (b.type) {
+		case "heading":
+			return "heading";
+		case "paragraph":
+			return "paragraph";
+		case "bulletList":
+			return "bulletList";
+		case "orderedList":
+			return "orderedList";
+		case "taskList":
+			return "taskList";
+		case "codeBlock":
+			return "codeBlock";
+		case "blockquote":
+			return "blockquote";
+		case "table":
+			return "table";
+		case "hr":
+			return "horizontalRule";
+		case "callout":
+			return "callout";
+		case "collapsible":
+			return "collapsible";
+		case "steps":
+			return "steps";
+		case "card":
+			return "card";
+		case "cardGroup":
+			return "cardGroup";
+		case "codeCollapse":
+			return "codeCollapse";
+		case "codeGroup":
+			return "codeGroup";
+		case "codePreview":
+			return "codePreview";
+		case "codeTree":
+			return "codeTree";
+		case "accordion":
+			return "accordion";
+		case "tabs":
+			return "tabs";
+		case "field":
+			return "field";
+		case "fieldGroup":
+			return "fieldGroup";
+		case "image":
+			return "image";
+		case "docEmbed":
+			return "docEmbed";
+		case "svgEmbed":
+			return "svgEmbed";
+	}
+}
+
+function fillBlock(el: Y.XmlElement, block: Block): void {
+	switch (block.type) {
+		case "heading": {
+			el.setAttribute("level", block.level as any);
+			fillTextInto(el, parseInline(block.text));
+			break;
+		}
+		case "paragraph": {
+			fillTextInto(el, parseInline(block.text));
+			break;
+		}
+		case "bulletList":
+		case "orderedList": {
+			const listItemEls = block.items.map(
+				() => new Y.XmlElement("listItem"),
+			);
+			el.insert(0, listItemEls);
+			block.items.forEach((text, i) => {
+				const paraEl = new Y.XmlElement("paragraph");
+				listItemEls[i]!.insert(0, [paraEl]);
+				fillTextInto(paraEl, parseInline(text));
+			});
+			break;
+		}
+		case "taskList": {
+			const taskItemEls = block.items.map(
+				() => new Y.XmlElement("taskItem"),
+			);
+			el.insert(0, taskItemEls);
+			block.items.forEach((item, i) => {
+				taskItemEls[i]!.setAttribute(
+					"checked",
+					item.checked as any,
+				);
+				const paraEl = new Y.XmlElement("paragraph");
+				taskItemEls[i]!.insert(0, [paraEl]);
+				fillTextInto(paraEl, parseInline(item.text));
+			});
+			break;
+		}
+		case "codeBlock": {
+			if (block.lang) el.setAttribute("language", block.lang);
+			const xt = new Y.XmlText();
+			el.insert(0, [xt]);
+			xt.insert(0, block.code);
+			break;
+		}
+		case "blockquote": {
+			const paraEls = block.lines.map(
+				() => new Y.XmlElement("paragraph"),
+			);
+			el.insert(0, paraEls);
+			block.lines.forEach((line, i) =>
+				fillTextInto(paraEls[i]!, parseInline(line)),
+			);
+			break;
+		}
+		case "table": {
+			const headerRowEl = new Y.XmlElement("tableRow");
+			const dataRowEls = block.dataRows.map(
+				() => new Y.XmlElement("tableRow"),
+			);
+			el.insert(0, [headerRowEl, ...dataRowEls]);
+
+			const headerCellEls = block.headerRow.map(
+				() => new Y.XmlElement("tableHeader"),
+			);
+			headerRowEl.insert(0, headerCellEls);
+			block.headerRow.forEach((cellText, i) => {
+				const paraEl = new Y.XmlElement("paragraph");
+				headerCellEls[i]!.insert(0, [paraEl]);
+				fillTextInto(paraEl, parseInline(cellText));
+			});
+
+			block.dataRows.forEach((row, ri) => {
+				const cellEls = row.map(
+					() => new Y.XmlElement("tableCell"),
+				);
+				dataRowEls[ri]!.insert(0, cellEls);
+				row.forEach((cellText, ci) => {
+					const paraEl = new Y.XmlElement("paragraph");
+					cellEls[ci]!.insert(0, [paraEl]);
+					fillTextInto(paraEl, parseInline(cellText));
+				});
+			});
+			break;
+		}
+		case "hr":
+			break;
+		case "callout": {
+			el.setAttribute("type", block.calloutType);
+			if (!block.innerBlocks.length) {
+				const paraEl = new Y.XmlElement("paragraph");
+				el.insert(0, [paraEl]);
+				break;
+			}
+			const innerEls = block.innerBlocks.map(
+				(b) => new Y.XmlElement(blockElName(b)),
+			);
+			el.insert(0, innerEls);
+			block.innerBlocks.forEach((b, i) =>
+				fillBlock(innerEls[i]!, b),
+			);
+			break;
+		}
+		case "collapsible": {
+			el.setAttribute("label", block.label);
+			el.setAttribute("open", block.open as any);
+			const inner = block.innerBlocks.length
+				? block.innerBlocks
+				: [{ type: "paragraph" as const, text: "" }];
+			const innerEls = inner.map(
+				(b) => new Y.XmlElement(blockElName(b)),
+			);
+			el.insert(0, innerEls);
+			inner.forEach((b, i) => fillBlock(innerEls[i]!, b));
+			break;
+		}
+		case "steps": {
+			const inner = block.innerBlocks.length
+				? block.innerBlocks
+				: [{ type: "paragraph" as const, text: "" }];
+			const innerEls = inner.map(
+				(b) => new Y.XmlElement(blockElName(b)),
+			);
+			el.insert(0, innerEls);
+			inner.forEach((b, i) => fillBlock(innerEls[i]!, b));
+			break;
+		}
+		case "card": {
+			if (block.title) el.setAttribute("title", block.title);
+			if (block.icon) el.setAttribute("icon", block.icon);
+			if (block.to) el.setAttribute("to", block.to);
+			const inner = block.innerBlocks.length
+				? block.innerBlocks
+				: [{ type: "paragraph" as const, text: "" }];
+			const innerEls = inner.map(
+				(b) => new Y.XmlElement(blockElName(b)),
+			);
+			el.insert(0, innerEls);
+			inner.forEach((b, i) => fillBlock(innerEls[i]!, b));
+			break;
+		}
+		case "cardGroup": {
+			const cardEls = block.cards.map(
+				(b) => new Y.XmlElement(blockElName(b)),
+			);
+			el.insert(0, cardEls);
+			block.cards.forEach((b, i) => fillBlock(cardEls[i]!, b));
+			break;
+		}
+		case "codeCollapse": {
+			const codes = block.codeBlocks.length
+				? block.codeBlocks
+				: [{ type: "codeBlock" as const, lang: "", code: "" }];
+			const codeEl = new Y.XmlElement("codeBlock");
+			el.insert(0, [codeEl]);
+			fillBlock(codeEl, codes[0]!);
+			break;
+		}
+		case "codeGroup": {
+			const codes = block.codeBlocks.length
+				? block.codeBlocks
+				: [{ type: "codeBlock" as const, lang: "", code: "" }];
+			const codeEls = codes.map(() => new Y.XmlElement("codeBlock"));
+			el.insert(0, codeEls);
+			codes.forEach((b, i) => fillBlock(codeEls[i]!, b));
+			break;
+		}
+		case "codePreview": {
+			const all = [...block.innerBlocks, ...block.codeBlocks];
+			const inner = all.length
+				? all
+				: [{ type: "paragraph" as const, text: "" }];
+			const innerEls = inner.map(
+				(b) => new Y.XmlElement(blockElName(b)),
+			);
+			el.insert(0, innerEls);
+			inner.forEach((b, i) => fillBlock(innerEls[i]!, b));
+			break;
+		}
+		case "codeTree": {
+			el.setAttribute("files", block.files);
+			break;
+		}
+		case "accordion": {
+			const itemEls = block.items.map(
+				() => new Y.XmlElement("accordionItem"),
+			);
+			el.insert(0, itemEls);
+			block.items.forEach((item, i) => {
+				itemEls[i]!.setAttribute("label", item.label);
+				if (item.icon)
+					itemEls[i]!.setAttribute("icon", item.icon);
+				const inner = item.innerBlocks.length
+					? item.innerBlocks
+					: [{ type: "paragraph" as const, text: "" }];
+				const childEls = inner.map(
+					(b) => new Y.XmlElement(blockElName(b)),
+				);
+				itemEls[i]!.insert(0, childEls);
+				inner.forEach((b, ci) => fillBlock(childEls[ci]!, b));
+			});
+			break;
+		}
+		case "tabs": {
+			const itemEls = block.items.map(
+				() => new Y.XmlElement("tabsItem"),
+			);
+			el.insert(0, itemEls);
+			block.items.forEach((item, i) => {
+				itemEls[i]!.setAttribute("label", item.label);
+				if (item.icon)
+					itemEls[i]!.setAttribute("icon", item.icon);
+				const inner = item.innerBlocks.length
+					? item.innerBlocks
+					: [{ type: "paragraph" as const, text: "" }];
+				const childEls = inner.map(
+					(b) => new Y.XmlElement(blockElName(b)),
+				);
+				itemEls[i]!.insert(0, childEls);
+				inner.forEach((b, ci) => fillBlock(childEls[ci]!, b));
+			});
+			break;
+		}
+		case "field": {
+			if (block.name) el.setAttribute("name", block.name);
+			el.setAttribute("type", block.fieldType);
+			el.setAttribute("required", block.required as any);
+			const inner = block.innerBlocks.length
+				? block.innerBlocks
+				: [{ type: "paragraph" as const, text: "" }];
+			const innerEls = inner.map(
+				(b) => new Y.XmlElement(blockElName(b)),
+			);
+			el.insert(0, innerEls);
+			inner.forEach((b, i) => fillBlock(innerEls[i]!, b));
+			break;
+		}
+		case "fieldGroup": {
+			const fieldEls = block.fields.map(
+				(b) => new Y.XmlElement(blockElName(b)),
+			);
+			el.insert(0, fieldEls);
+			block.fields.forEach((b, i) => fillBlock(fieldEls[i]!, b));
+			break;
+		}
+		case "image": {
+			el.setAttribute("src", block.src);
+			if (block.alt) el.setAttribute("alt", block.alt);
+			if (block.width) el.setAttribute("width", block.width);
+			if (block.height) el.setAttribute("height", block.height);
+			break;
+		}
+		case "docEmbed": {
+			el.setAttribute("docId", block.docId);
+			if (block.seamless) el.setAttribute("seamless", "true");
+			break;
+		}
+		case "svgEmbed": {
+			el.setAttribute("svg", block.svg);
+			if (block.title) el.setAttribute("title", block.title);
+			break;
+		}
+	}
+}
+
+// ── Public: Markdown → Y.js ─────────────────────────────────────────────────
+
+export function populateYDocFromMarkdown(
+	fragment: Y.XmlFragment,
+	markdown: string,
+	fallbackTitle = "Untitled",
+): void {
+	const ydoc = fragment.doc;
+	if (!ydoc) {
+		console.warn(
+			"[markdownToYjs] fragment has no doc — skipping population",
+		);
+		return;
+	}
+
+	const blocks = parseBlocks(markdown);
+
+	let title = fallbackTitle;
+	let contentBlocks = blocks;
+	const h1 = blocks.findIndex(
+		(b) => b.type === "heading" && b.level === 1,
+	);
+	if (h1 !== -1) {
+		title = (
+			blocks[h1] as { type: "heading"; level: number; text: string }
+		).text;
+		contentBlocks = blocks.filter((_, i) => i !== h1);
+	}
+	if (!contentBlocks.length)
+		contentBlocks = [{ type: "paragraph", text: "" }];
+
+	ydoc.transact(() => {
+		const headerEl = new Y.XmlElement("documentHeader");
+		const metaEl = new Y.XmlElement("documentMeta");
+		const bodyEls: Y.XmlElement[] = contentBlocks.map((b) => {
+			switch (b.type) {
+				case "heading":
+					return new Y.XmlElement("heading");
+				case "paragraph":
+					return new Y.XmlElement("paragraph");
+				case "bulletList":
+					return new Y.XmlElement("bulletList");
+				case "orderedList":
+					return new Y.XmlElement("orderedList");
+				case "taskList":
+					return new Y.XmlElement("taskList");
+				case "codeBlock":
+					return new Y.XmlElement("codeBlock");
+				case "blockquote":
+					return new Y.XmlElement("blockquote");
+				case "table":
+					return new Y.XmlElement("table");
+				case "hr":
+					return new Y.XmlElement("horizontalRule");
+				case "callout":
+					return new Y.XmlElement("callout");
+				case "collapsible":
+					return new Y.XmlElement("collapsible");
+				case "steps":
+					return new Y.XmlElement("steps");
+				case "card":
+					return new Y.XmlElement("card");
+				case "cardGroup":
+					return new Y.XmlElement("cardGroup");
+				case "codeCollapse":
+					return new Y.XmlElement("codeCollapse");
+				case "codeGroup":
+					return new Y.XmlElement("codeGroup");
+				case "codePreview":
+					return new Y.XmlElement("codePreview");
+				case "codeTree":
+					return new Y.XmlElement("codeTree");
+				case "accordion":
+					return new Y.XmlElement("accordion");
+				case "tabs":
+					return new Y.XmlElement("tabs");
+				case "field":
+					return new Y.XmlElement("field");
+				case "fieldGroup":
+					return new Y.XmlElement("fieldGroup");
+				case "image":
+					return new Y.XmlElement("image");
+				case "docEmbed":
+					return new Y.XmlElement("docEmbed");
+				case "svgEmbed":
+					return new Y.XmlElement("svgEmbed");
+			}
+		});
+
+		fragment.insert(0, [headerEl, metaEl, ...bodyEls]);
+
+		const headerXt = new Y.XmlText();
+		headerEl.insert(0, [headerXt]);
+		headerXt.insert(0, title);
+
+		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) };
+	}
+}