affine-mcp-server 1.13.0 → 2.0.0

package/dist/tools/docs.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
+import { generateKeyBetween } from "fractional-indexing";
 import { receipt, text } from "../util/mcp.js";
 import { wsUrlFromGraphQLEndpoint, connectWorkspaceSocket, joinWorkspace, loadDoc, pushDocUpdate, deleteDoc as wsDeleteDoc } from "../ws.js";
 import * as Y from "yjs";
 import { parseMarkdownToOperations } from "../markdown/parse.js";
 import { renderBlocksToMarkdown } from "../markdown/render.js";
+import { DEFAULT_NOTE_XYWH, DEFAULT_STACK_GAP_HORIZONTAL, DEFAULT_STACK_GAP_VERTICAL, SIDE_TO_NORMALIZED_POSITION, encloseBounds, estimateConnectorLabelXYWH, estimateNoteHeightForMarkdown, formatXywhString, parseXywhString, pickConnectorSides, pickFurthestInDirection, sortByFractionalIndex, stackRelativeTo, } from "../edgeless/layout.js";
 const WorkspaceId = z.string().min(1, "workspaceId required");
 const DocId = z.string().min(1, "docId required");
 const MarkdownContent = z.string().min(1, "markdown required");
@@ -519,6 +521,24 @@ export function registerDocTools(server, gql, defaults) {
         }
         return null;
     }
+    function pruneFromFrameChildElementIds(blocks, deletedIds) {
+        if (deletedIds.length === 0)
+            return;
+        const idSet = new Set(deletedIds);
+        for (const [, value] of blocks) {
+            if (!(value instanceof Y.Map))
+                continue;
+            if (value.get("sys:flavour") !== "affine:frame")
+                continue;
+            const owned = value.get("prop:childElementIds");
+            if (!(owned instanceof Y.Map))
+                continue;
+            for (const id of idSet) {
+                if (owned.has(id))
+                    owned.delete(id);
+            }
+        }
+    }
     function ensureNoteBlock(blocks) {
         const existingNoteId = findBlockIdByFlavour(blocks, "affine:note");
         if (existingNoteId) {
@@ -528,20 +548,29 @@ export function registerDocTools(server, gql, defaults) {
         if (!pageId) {
             throw new Error("Document has no page block; unable to insert content.");
         }
+        // Mirror BlockSuite's createDefaultDoc shape so the editor doesn't re-seed
+        // its own default note alongside ours.
         const noteId = generateId();
         const note = new Y.Map();
         setSysFields(note, noteId, "affine:note");
         note.set("sys:parent", null);
-        note.set("sys:children", new Y.Array());
-        note.set("prop:xywh", "[0,0,800,95]");
+        const noteChildren = new Y.Array();
+        note.set("sys:children", noteChildren);
+        note.set("prop:xywh", DEFAULT_NOTE_XYWH);
         note.set("prop:index", "a0");
         note.set("prop:hidden", false);
         note.set("prop:displayMode", "both");
-        const background = new Y.Map();
-        background.set("light", "#ffffff");
-        background.set("dark", "#252525");
-        note.set("prop:background", background);
+        note.set("prop:background", buildDefaultNoteBackground());
         blocks.set(noteId, note);
+        const paragraphId = generateId();
+        const paragraph = new Y.Map();
+        setSysFields(paragraph, paragraphId, "affine:paragraph");
+        paragraph.set("sys:parent", null);
+        paragraph.set("sys:children", new Y.Array());
+        paragraph.set("prop:type", "text");
+        paragraph.set("prop:text", makeText(""));
+        blocks.set(paragraphId, paragraph);
+        noteChildren.push([paragraphId]);
         const page = blocks.get(pageId);
         let pageChildren = page.get("sys:children");
         if (!(pageChildren instanceof Y.Array)) {
@@ -551,6 +580,12 @@ export function registerDocTools(server, gql, defaults) {
         pageChildren.push([noteId]);
         return noteId;
     }
+    function buildDefaultNoteBackground() {
+        const map = new Y.Map();
+        map.set("light", "#ffffff");
+        map.set("dark", "#252525");
+        return map;
+    }
     function ensureSurfaceBlock(blocks) {
         const existingSurfaceId = findBlockIdByFlavour(blocks, "affine:surface");
         if (existingSurfaceId) {
@@ -834,9 +869,20 @@ export function registerDocTools(server, gql, defaults) {
         const design = parsed.design ?? "";
         const reference = (parsed.reference ?? "").trim();
         const refFlavour = (parsed.refFlavour ?? "").trim();
-        const width = Number.isFinite(parsed.width) ? Math.max(1, Math.floor(parsed.width)) : 100;
-        const height = Number.isFinite(parsed.height) ? Math.max(1, Math.floor(parsed.height)) : 100;
-        const background = (parsed.background ?? "transparent").trim() || "transparent";
+        const x = Number.isFinite(parsed.x) ? Math.floor(parsed.x) : 0;
+        const y = Number.isFinite(parsed.y) ? Math.floor(parsed.y) : 0;
+        const widthProvided = Number.isFinite(parsed.width);
+        const heightProvided = Number.isFinite(parsed.height);
+        const width = widthProvided ? Math.max(1, Math.floor(parsed.width)) : 100;
+        let height = heightProvided ? Math.max(1, Math.floor(parsed.height)) : 100;
+        // Pre-inflate the stored height so stackAfter'd siblings don't overlap the
+        // note before the editor's ResizeObserver corrects it on first render.
+        if (typeInfo.type === "note" && !heightProvided && typeof parsed.markdown === "string" && parsed.markdown.length > 0) {
+            height = Math.max(height, estimateNoteHeightForMarkdown(parsed.markdown, widthProvided ? width : 400));
+        }
+        const background = typeof parsed.background === "string"
+            ? (parsed.background.trim() || "transparent")
+            : (parsed.background && typeof parsed.background === "object" ? parsed.background : "transparent");
         const sourceId = (parsed.sourceId ?? "").trim();
         const name = (parsed.name ?? "attachment").trim() || "attachment";
         const mimeType = (parsed.mimeType ?? "application/octet-stream").trim() || "application/octet-stream";
@@ -860,6 +906,8 @@ export function registerDocTools(server, gql, defaults) {
             design,
             reference,
             refFlavour,
+            x,
+            y,
             width,
             height,
             background,
@@ -882,6 +930,14 @@ export function registerDocTools(server, gql, defaults) {
             tableData,
             deltas: parsed.deltas,
             tableCellDeltas,
+            childElementIds: Array.isArray(parsed.childElementIds) ? parsed.childElementIds : undefined,
+            stackAfter: parsed.stackAfter,
+            padding: Number.isFinite(parsed.padding) ? Math.max(0, Math.floor(parsed.padding)) : undefined,
+            xProvided: Number.isFinite(parsed.x),
+            yProvided: Number.isFinite(parsed.y),
+            widthProvided,
+            heightProvided,
+            markdown: typeof parsed.markdown === "string" ? parsed.markdown : undefined,
         };
         validateNormalizedAppendBlockInput(normalized, parsed);
         return normalized;
@@ -1565,10 +1621,15 @@ export function registerDocTools(server, gql, defaults) {
                 block.set("sys:parent", null);
                 block.set("sys:children", new Y.Array());
                 block.set("prop:title", makeText(content || "Frame"));
-                block.set("prop:background", normalized.background);
-                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
+                // 'transparent' matches FrameBlockSchema; any other value renders as a
+                // solid fill (the border is separate).
+                block.set("prop:background", normalized.background ?? "transparent");
+                block.set("prop:xywh", `[${normalized.x},${normalized.y},${normalized.width},${normalized.height}]`);
                 block.set("prop:index", "a0");
-                block.set("prop:childElementIds", new Y.Map());
+                const childIds = new Y.Map();
+                for (const id of normalized._frameOwnedIds ?? [])
+                    childIds.set(id, true);
+                block.set("prop:childElementIds", childIds);
                 block.set("prop:presentationIndex", "a0");
                 block.set("prop:lockedBySelf", false);
                 return { blockId, block, flavour: "affine:frame" };
@@ -1576,27 +1637,54 @@ export function registerDocTools(server, gql, defaults) {
             case "edgeless_text": {
                 setSysFields(block, blockId, "affine:edgeless-text");
                 block.set("sys:parent", null);
-                block.set("sys:children", new Y.Array());
-                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
+                const edgelessTextChildren = new Y.Array();
+                block.set("prop:xywh", `[${normalized.x},${normalized.y},${normalized.width},${normalized.height}]`);
                 block.set("prop:index", "a0");
                 block.set("prop:lockedBySelf", false);
                 block.set("prop:scale", 1);
                 block.set("prop:rotate", 0);
                 block.set("prop:hasMaxWidth", false);
                 block.set("prop:comments", undefined);
-                block.set("prop:color", "black");
+                // Theme-adaptive token so canvas text stays legible in dark mode.
+                block.set("prop:color", "--affine-text-primary-color");
                 block.set("prop:fontFamily", "Inter");
                 block.set("prop:fontStyle", "normal");
                 block.set("prop:fontWeight", "regular");
                 block.set("prop:textAlign", "left");
-                return { blockId, block, flavour: "affine:edgeless-text" };
+                const edgelessTextExtraBlocks = [];
+                if (content) {
+                    const paraId = generateId();
+                    const para = new Y.Map();
+                    setSysFields(para, paraId, "affine:paragraph");
+                    para.set("sys:parent", null);
+                    para.set("sys:children", new Y.Array());
+                    para.set("prop:type", "text");
+                    para.set("prop:text", makeText(normalized.deltas ?? content));
+                    edgelessTextChildren.push([paraId]);
+                    edgelessTextExtraBlocks.push({ blockId: paraId, block: para });
+                }
+                block.set("sys:children", edgelessTextChildren);
+                return { blockId, block, flavour: "affine:edgeless-text", extraBlocks: edgelessTextExtraBlocks };
             }
             case "note": {
                 setSysFields(block, blockId, "affine:note");
                 block.set("sys:parent", null);
-                block.set("sys:children", new Y.Array());
-                block.set("prop:xywh", `[0,0,${normalized.width},${normalized.height}]`);
-                block.set("prop:background", normalized.background);
+                const noteChildren = new Y.Array();
+                block.set("prop:xywh", `[${normalized.x},${normalized.y},${normalized.width},${normalized.height}]`);
+                // BlockSuite reads the adaptive-bg case as a Y.Map; a plain JS object
+                // would serialize to a JSON string and break theme switching.
+                const bg = normalized.background;
+                if (bg && typeof bg === "object" && !Array.isArray(bg) && ("light" in bg || "dark" in bg)) {
+                    const bgMap = new Y.Map();
+                    if (typeof bg.light === "string")
+                        bgMap.set("light", bg.light);
+                    if (typeof bg.dark === "string")
+                        bgMap.set("dark", bg.dark);
+                    block.set("prop:background", bgMap);
+                }
+                else {
+                    block.set("prop:background", bg);
+                }
                 block.set("prop:index", "a0");
                 block.set("prop:lockedBySelf", false);
                 block.set("prop:hidden", false);
@@ -1610,7 +1698,152 @@ export function registerDocTools(server, gql, defaults) {
                 edgeless.set("style", style);
                 block.set("prop:edgeless", edgeless);
                 block.set("prop:comments", undefined);
-                return { blockId, block, flavour: "affine:note" };
+                const noteExtraBlocks = [];
+                if (content) {
+                    const paraId = generateId();
+                    const para = new Y.Map();
+                    setSysFields(para, paraId, "affine:paragraph");
+                    para.set("sys:parent", null);
+                    para.set("sys:children", new Y.Array());
+                    para.set("prop:type", "text");
+                    para.set("prop:text", makeText(normalized.deltas ?? content));
+                    noteChildren.push([paraId]);
+                    noteExtraBlocks.push({ blockId: paraId, block: para });
+                }
+                block.set("sys:children", noteChildren);
+                return { blockId, block, flavour: "affine:note", extraBlocks: noteExtraBlocks };
+            }
+        }
+    }
+    function resolveBlockBoundAsBound(blocks, blockId) {
+        const b = blocks.get(blockId);
+        if (b instanceof Y.Map) {
+            const xywh = parseXywhString(b.get("prop:xywh"));
+            if (xywh)
+                return { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height };
+        }
+        return null;
+    }
+    function resolveEdgelessLayoutHints(blocks, normalized) {
+        const defaultPadding = normalized.padding ?? 40;
+        let placed = false;
+        if (normalized.stackAfter) {
+            const idList = Array.isArray(normalized.stackAfter.blockId)
+                ? normalized.stackAfter.blockId
+                : [normalized.stackAfter.blockId];
+            const direction = normalized.stackAfter.direction ?? "down";
+            const missing = [];
+            const bounds = [];
+            for (const id of idList) {
+                const b = resolveBlockBoundAsBound(blocks, id);
+                if (!b)
+                    missing.push(id);
+                else
+                    bounds.push(b);
+            }
+            const ref = pickFurthestInDirection(bounds, direction);
+            if (!ref) {
+                throw new Error(`stackAfter: no blockIds resolved to xywh. Missing: ${JSON.stringify(missing)}`);
+            }
+            // Gap precedence: explicit `gap` > explicit `padding` > direction default
+            // (horizontal larger because notes are wide-short and tight sideways).
+            const isHorizontal = direction === "left" || direction === "right";
+            const directionDefaultGap = isHorizontal ? DEFAULT_STACK_GAP_HORIZONTAL : DEFAULT_STACK_GAP_VERTICAL;
+            const gap = normalized.stackAfter.gap
+                ?? (normalized.padding !== undefined ? normalized.padding : directionDefaultGap);
+            // Center on the anchor group's orthogonal-axis union; caller x/y wins.
+            const isVertical = direction === "down" || direction === "up";
+            let preserveX;
+            let preserveY;
+            if (normalized.xProvided === true) {
+                preserveX = normalized.x;
+            }
+            else if (isVertical) {
+                const minX = bounds.reduce((m, b) => Math.min(m, b.x), Infinity);
+                const maxX = bounds.reduce((m, b) => Math.max(m, b.x + b.w), -Infinity);
+                preserveX = Math.round((minX + maxX) / 2 - normalized.width / 2);
+            }
+            if (normalized.yProvided === true) {
+                preserveY = normalized.y;
+            }
+            else if (!isVertical) {
+                const minY = bounds.reduce((m, b) => Math.min(m, b.y), Infinity);
+                const maxY = bounds.reduce((m, b) => Math.max(m, b.y + b.h), -Infinity);
+                preserveY = Math.round((minY + maxY) / 2 - normalized.height / 2);
+            }
+            const { x, y } = stackRelativeTo(ref, { w: normalized.width, h: normalized.height }, { direction, gap, preserveX, preserveY });
+            normalized.x = x;
+            normalized.y = y;
+            placed = true;
+        }
+        // prop:childElementIds accepts both surface-element ids and block ids —
+        // that's what the editor writes when you drag a note into a frame.
+        if (normalized.type === "frame" && normalized.childElementIds && normalized.childElementIds.length > 0) {
+            const surfaceCtx = getSurfaceElementsValueMap(blocks, { create: false });
+            const surfaceValueMap = surfaceCtx?.value ?? new Y.Map();
+            const ownedIds = [];
+            const missing = [];
+            const kids = [];
+            for (const id of normalized.childElementIds) {
+                const resolved = resolveChildBound(surfaceValueMap, blocks, id);
+                if (resolved.kind === "missing") {
+                    missing.push(id);
+                }
+                else {
+                    ownedIds.push(id);
+                    if (resolved.bound)
+                        kids.push(resolved.bound);
+                }
+            }
+            if (ownedIds.length === 0) {
+                throw new Error(`None of the ids in childElementIds were found: ${JSON.stringify(missing)}.`);
+            }
+            normalized._frameOwnedIds = ownedIds;
+            normalized._frameMissing = missing;
+            if (!normalized.widthProvided || !normalized.heightProvided || !normalized.xProvided || !normalized.yProvided) {
+                const wrapped = encloseBounds(kids, { padding: defaultPadding, titleBand: 60 });
+                if (wrapped) {
+                    if (!normalized.xProvided)
+                        normalized.x = wrapped.x;
+                    if (!normalized.yProvided)
+                        normalized.y = wrapped.y;
+                    if (!normalized.widthProvided)
+                        normalized.width = wrapped.w;
+                    if (!normalized.heightProvided)
+                        normalized.height = wrapped.h;
+                    placed = true;
+                }
+            }
+        }
+        // Auto-stack-below fallback: avoids dropping new edgeless blocks on top of
+        // the seeded default note at [0,0,…] when the caller gave no placement.
+        const isEdgelessBlock = normalized.type === "frame" ||
+            normalized.type === "note" ||
+            normalized.type === "edgeless_text";
+        if (!placed && isEdgelessBlock && !normalized.yProvided) {
+            const existing = [];
+            for (const [, b] of blocks.entries()) {
+                if (!(b instanceof Y.Map))
+                    continue;
+                const flavour = b.get("sys:flavour");
+                if (flavour !== "affine:note" &&
+                    flavour !== "affine:frame" &&
+                    flavour !== "affine:edgeless-text")
+                    continue;
+                const xywh = parseXywhString(b.get("prop:xywh"));
+                if (!xywh)
+                    continue;
+                existing.push({ x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height });
+            }
+            const ref = pickFurthestInDirection(existing, "down");
+            if (ref) {
+                const { x, y } = stackRelativeTo(ref, { w: normalized.width, h: normalized.height }, {
+                    direction: "down",
+                    gap: defaultPadding,
+                    preserveX: normalized.xProvided === true ? normalized.x : undefined,
+                });
+                normalized.x = x;
+                normalized.y = y;
             }
         }
     }
@@ -1631,6 +1864,7 @@ export function registerDocTools(server, gql, defaults) {
             }
             const prevSV = Y.encodeStateVector(doc);
             const blocks = doc.getMap("blocks");
+            resolveEdgelessLayoutHints(blocks, normalized);
             const context = resolveInsertContext(blocks, normalized);
             const { blockId, block, flavour, blockType, extraBlocks } = createBlock(normalized);
             blocks.set(blockId, block);
@@ -1647,7 +1881,16 @@ export function registerDocTools(server, gql, defaults) {
             }
             const delta = Y.encodeStateAsUpdate(doc, prevSV);
             await pushDocUpdate(socket, workspaceId, normalized.docId, Buffer.from(delta).toString("base64"));
-            return { appended: true, blockId, flavour, blockType, normalizedType: normalized.type, legacyType: normalized.legacyType || null };
+            return {
+                appended: true,
+                blockId,
+                flavour,
+                blockType,
+                normalizedType: normalized.type,
+                legacyType: normalized.legacyType || null,
+                ownedIds: normalized._frameOwnedIds,
+                missing: normalized._frameMissing,
+            };
         }
         finally {
             socket.disconnect();
@@ -2420,30 +2663,26 @@ export function registerDocTools(server, gql, defaults) {
             setSysFields(note, noteId, "affine:note");
             note.set("sys:parent", null);
             note.set("prop:displayMode", "both");
-            note.set("prop:xywh", "[0,0,800,95]");
+            note.set("prop:xywh", DEFAULT_NOTE_XYWH);
             note.set("prop:index", "a0");
             note.set("prop:hidden", false);
-            const background = new Y.Map();
-            background.set("light", "#ffffff");
-            background.set("dark", "#252525");
-            note.set("prop:background", background);
+            note.set("prop:background", buildDefaultNoteBackground());
             const noteChildren = new Y.Array();
             note.set("sys:children", noteChildren);
             blocks.set(noteId, note);
             children.push([noteId]);
-            if (parsed.content) {
-                const paraId = generateId();
-                const para = new Y.Map();
-                setSysFields(para, paraId, "affine:paragraph");
-                para.set("sys:parent", null);
-                para.set("sys:children", new Y.Array());
-                para.set("prop:type", "text");
-                const paragraphText = new Y.Text();
+            const paraId = generateId();
+            const para = new Y.Map();
+            setSysFields(para, paraId, "affine:paragraph");
+            para.set("sys:parent", null);
+            para.set("sys:children", new Y.Array());
+            para.set("prop:type", "text");
+            const paragraphText = new Y.Text();
+            if (parsed.content)
                 paragraphText.insert(0, parsed.content);
-                para.set("prop:text", paragraphText);
-                blocks.set(paraId, para);
-                noteChildren.push([paraId]);
-            }
+            para.set("prop:text", paragraphText);
+            blocks.set(paraId, para);
+            noteChildren.push([paraId]);
             const meta = ydoc.getMap("meta");
             meta.set("id", docId);
             meta.set("title", title);
@@ -2562,16 +2801,23 @@ export function registerDocTools(server, gql, defaults) {
         setSysFields(note, noteId, "affine:note");
         note.set("sys:parent", null);
         note.set("prop:displayMode", "both");
-        note.set("prop:xywh", "[0,0,800,95]");
+        note.set("prop:xywh", DEFAULT_NOTE_XYWH);
         note.set("prop:index", "a0");
         note.set("prop:hidden", false);
-        const background = new Y.Map();
-        background.set("light", "#ffffff");
-        background.set("dark", "#252525");
-        note.set("prop:background", background);
-        note.set("sys:children", new Y.Array());
+        note.set("prop:background", buildDefaultNoteBackground());
+        const skeletonNoteChildren = new Y.Array();
+        note.set("sys:children", skeletonNoteChildren);
         blocks.set(noteId, note);
         page.get("sys:children").push([noteId]);
+        const skeletonParaId = generateId();
+        const skeletonPara = new Y.Map();
+        setSysFields(skeletonPara, skeletonParaId, "affine:paragraph");
+        skeletonPara.set("sys:parent", null);
+        skeletonPara.set("sys:children", new Y.Array());
+        skeletonPara.set("prop:type", "text");
+        skeletonPara.set("prop:text", new Y.Text());
+        blocks.set(skeletonParaId, skeletonPara);
+        skeletonNoteChildren.push([skeletonParaId]);
         const meta = doc.getMap("meta");
         meta.set("id", docId);
         meta.set("title", title);
@@ -3553,24 +3799,30 @@ export function registerDocTools(server, gql, defaults) {
                     knownUnsupportedFlavours: [...KNOWN_BLOCK_FLAVOURS].filter(flavour => !MARKDOWN_EXPORT_SUPPORTED_FLAVOURS.has(flavour)).sort(),
                 },
                 highLevelAuthoring: {
-                    semanticPageComposer: false,
-                    nativeTemplateInstantiation: false,
-                    createDocWithPlacement: false,
-                    semanticSectionEditing: false,
+                    semanticPageComposer: true,
+                    nativeTemplateInstantiation: true,
+                    createDocWithPlacement: true,
+                    semanticSectionEditing: true,
+                },
+                edgelessCanvas: {
+                    blockMutation: true,
+                    surfaceElementMutation: true,
+                    canvasReadback: true,
+                    frameOwnershipMutation: true,
                 },
             },
             database: {
                 supported: true,
                 columnTypes: [...DATABASE_COLUMN_TYPE_VALUES],
                 initialViewModes: [...APPEND_BLOCK_DATA_VIEW_MODE_VALUES],
-                advancedViewMutation: false,
-                intentDrivenComposition: false,
+                advancedViewMutation: true,
+                intentDrivenComposition: true,
                 linkedDocRows: true,
             },
             workspace: {
                 organizeToolsExperimental: true,
-                ruleBackedCollections: false,
-                workspaceBlueprints: false,
+                ruleBackedCollections: true,
+                workspaceBlueprints: true,
             },
             collaboration: {
                 docComments: true,
@@ -3859,36 +4111,31 @@ export function registerDocTools(server, gql, defaults) {
             callouts: z.array(z.string().min(1)).optional().describe("Callout blocks to append under the new section."),
         },
     }, appendSemanticSectionHandler);
-    // APPEND PARAGRAPH
-    const appendParagraphHandler = async (parsed) => {
-        const result = await appendBlockInternal({
-            workspaceId: parsed.workspaceId,
-            docId: parsed.docId,
-            type: "paragraph",
-            text: parsed.text,
-        });
-        return receipt("doc.append_paragraph", {
-            workspaceId: parsed.workspaceId || defaults.workspaceId || null,
-            docId: parsed.docId,
-            appended: result.appended,
-            blockId: result.blockId,
-            paragraphId: result.blockId,
-            blockType: result.blockType || null,
-            normalizedType: result.normalizedType,
-            legacyType: result.legacyType,
-        });
-    };
-    server.registerTool('append_paragraph', {
-        title: 'Append Paragraph',
-        description: 'Append a text paragraph block to a document',
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string(),
-            text: z.string(),
-        },
-    }, appendParagraphHandler);
     const appendBlockHandler = async (parsed) => {
-        const result = await appendBlockInternal(parsed);
+        // Drop `text` when `markdown` is set so markdown-parsed children don't
+        // sit next to a stale one-paragraph echo.
+        const shouldApplyMarkdown = parsed.type === "note" && !!parsed.markdown;
+        const coreParsed = shouldApplyMarkdown ? { ...parsed, text: undefined } : parsed;
+        const result = await appendBlockInternal(coreParsed);
+        let markdownApplied;
+        if (shouldApplyMarkdown && result.appended && result.blockId) {
+            const parsedMd = parseMarkdownToOperations(parsed.markdown);
+            if (parsedMd.operations.length > 0) {
+                const applied = await applyMarkdownOperationsInternal({
+                    workspaceId: parsed.workspaceId || defaults.workspaceId,
+                    docId: parsed.docId,
+                    operations: parsedMd.operations,
+                    strict: parsed.strict,
+                    placement: { parentId: result.blockId },
+                });
+                markdownApplied = {
+                    appendedCount: applied.appendedCount,
+                    skippedCount: applied.skippedCount,
+                    blockIds: applied.blockIds,
+                    warnings: parsedMd.warnings,
+                };
+            }
+        }
         return receipt("doc.append_block", {
             workspaceId: parsed.workspaceId || defaults.workspaceId || null,
             docId: parsed.docId,
@@ -3899,6 +4146,9 @@ export function registerDocTools(server, gql, defaults) {
             blockType: result.blockType || null,
             normalizedType: result.normalizedType,
             legacyType: result.legacyType,
+            ...(result.ownedIds ? { ownedIds: result.ownedIds } : {}),
+            ...(result.missing ? { missing: result.missing } : {}),
+            ...(markdownApplied ? { markdown: markdownApplied } : {}),
         });
     };
     server.registerTool("append_block", {
@@ -3916,9 +4166,19 @@ export function registerDocTools(server, gql, defaults) {
             design: z.string().optional().describe("Design payload for embed_html"),
             reference: z.string().optional().describe("Target id for surface_ref"),
             refFlavour: z.string().optional().describe("Target flavour for surface_ref (e.g. affine:frame)"),
-            width: z.number().int().min(1).max(10000).optional().describe("Width for frame/edgeless_text/note"),
-            height: z.number().int().min(1).max(10000).optional().describe("Height for frame/edgeless_text/note"),
-            background: z.string().optional().describe("Background for frame/note"),
+            x: z.number().int().optional().describe("X position on the edgeless canvas for frame/edgeless_text/note (default 0). Prefer ≥40px between sibling bounds; BlockSuite does not auto-arrange."),
+            y: z.number().int().optional().describe("Y position on the edgeless canvas for frame/edgeless_text/note (default 0)."),
+            width: z.number().int().min(1).max(10000).optional().describe("Width for frame/edgeless_text/note."),
+            height: z.number().int().min(1).max(10000).optional().describe("Height for frame/edgeless_text/note. When `markdown` is set and height is omitted, an over-estimate is computed from the content — AFFiNE's render-time ResizeObserver corrects `prop:xywh` to the true DOM-measured height on first browser open."),
+            background: z.any().optional().describe("Background for frame/note. Frame default 'transparent'. For notes, prefer AFFiNE's adaptive `--affine-note-background-<color>` family — `blue` / `purple` / `yellow` / `green` / `teal` / `red` / `orange` / `magenta` / `grey` / `white` / `black`. For specific per-theme colors, pass a `{light, dark}` hex object like `{light:'#fff', dark:'#252525'}`."),
+            markdown: z.string().optional().describe("When type='note', parse this markdown into heading/paragraph/list/code child blocks inside the note (BlockSuite-native: mirrors what happens when you paste markdown into an edgeless note). Takes precedence over 'text' for note children. Ignored for other block types."),
+            childElementIds: z.array(z.string()).optional().describe("For type='frame' only. The frame's contents. Accepts ids of surface elements (shapes/connectors/groups) AND edgeless blocks (notes/frames/edgeless-text) — BlockSuite's prop:childElementIds holds both, matching what the editor writes when you drag a note into a frame. Dragging the frame drags every owned member. Ids that don't resolve come back under 'missing'. When width/height are omitted the frame is sized to the union of resolvable child bounds + padding + a 30px title band."),
+            stackAfter: z.object({
+                blockId: z.union([z.string(), z.array(z.string())]).describe("Block(s) to stack relative to. String = a single anchor; array = pick whichever is furthest in the stack direction (bottommost for 'down', rightmost for 'right', etc.)."),
+                direction: z.enum(["down", "up", "right", "left"]).optional().describe("Direction (default 'down')"),
+                gap: z.number().int().optional().describe("Gap in px between the anchor and the new block. Default is direction-aware: 80 for left/right, 40 for down/up — mirrors native-flowchart spacing where the flow axis gets more breathing room than the cross axis. Explicit `padding` on the block overrides this default; explicit `gap` wins over both."),
+            }).optional().describe("Layout helper — position this block relative to one or more existing edgeless blocks. Picks the furthest anchor in `direction` for the stack axis, and centers the new block on the anchor group's union on the orthogonal axis (matches how BlockSuite aligns selection-derived blocks; reduces to inherit-anchor-x when widths match). Caller-provided x/y on the orthogonal axis still wins. Works for frame/note/edgeless_text. Example: `stackAfter: { blockId: [f1, f2, f3], gap: 80 }` stacks below whichever column frame ends lowest, centered across all three. Note heights shift at first render (page-root grows with the title, content notes shrink/grow with their children); give extra gap and fix up with `update_edgeless_block` if the down/right chain drifts."),
+            padding: z.number().int().optional().describe("Default padding (px) for `childElementIds` auto-sizing on frames (each side, plus +30px title band) and fallback gap for `stackAfter` (default 40)."),
             sourceId: z.string().optional().describe("Blob source id for image/attachment"),
             name: z.string().optional().describe("Attachment file name"),
             mimeType: z.string().optional().describe("Attachment mime type"),
@@ -4103,7 +4363,7 @@ export function registerDocTools(server, gql, defaults) {
         },
     }, exportWithFidelityReportHandler);
     // Core logic for creating a doc from markdown — returns structured data, no MCP envelope.
-    // Used by both createDocFromMarkdownHandler and batchCreateDocsHandler.
+    // Used by createDocFromMarkdownHandler and internal markdown-based flows.
     const createDocFromMarkdownCore = async (parsed) => {
         const parsedMarkdown = parseMarkdownToOperations(parsed.markdown);
         let operations = [...parsedMarkdown.operations];
@@ -4174,46 +4434,53 @@ export function registerDocTools(server, gql, defaults) {
             parentDocId: z.string().optional().describe("If provided, the new doc is automatically embedded into this parent doc as a linked child (visible in sidebar)."),
         },
     }, createDocFromMarkdownHandler);
-    // batch_create_docs: create up to 20 docs in one call
-    const batchCreateDocsHandler = async (parsed) => {
+    const createDocFromTemplateCore = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId)
             throw new Error("workspaceId is required.");
-        if (!Array.isArray(parsed.docs) || parsed.docs.length === 0)
-            throw new Error("docs array is required.");
-        if (parsed.docs.length > 20)
-            throw new Error("Maximum 20 docs per batch.");
-        const results = [];
-        for (const item of parsed.docs) {
-            try {
-                const d = await createDocFromMarkdownCore({ workspaceId, title: item.title, markdown: item.markdown, parentDocId: item.parentDocId });
-                results.push({
-                    title: d.title,
-                    docId: d.docId,
-                    parentDocId: d.parentDocId,
-                    linkedToParent: d.linkedToParent,
-                    warnings: d.warnings ?? [],
-                });
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const snap = await loadDoc(socket, workspaceId, parsed.templateDocId);
+            if (!snap.missing)
+                throw new Error(`Template doc ${parsed.templateDocId} not found.`);
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
+            const collected = collectDocForMarkdown(doc, new Map());
+            const rendered = renderBlocksToMarkdown({ rootBlockIds: collected.rootBlockIds, blocksById: collected.blocksById });
+            let markdown = rendered.markdown;
+            const vars = parsed.variables ?? {};
+            for (const [key, value] of Object.entries(vars)) {
+                const pattern = new RegExp(`\\{\\{\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\}}`, "g");
+                markdown = markdown.replace(pattern, value);
             }
-            catch (err) {
-                results.push({ title: item.title, docId: "", parentDocId: item.parentDocId ?? null, linkedToParent: false, warnings: [`Failed: ${err?.message ?? String(err)}`] });
+            const unfilled = [...markdown.matchAll(/\{\{\s*[\w.-]+\s*\}\}/g)].map(match => match[0]);
+            socket.disconnect();
+            const created = await createDocFromMarkdownCore({ workspaceId, title: parsed.title, markdown, parentDocId: parsed.parentDocId });
+            return {
+                workspaceId,
+                sourceTemplateDocId: parsed.templateDocId,
+                docId: created.docId,
+                title: created.title,
+                parentDocId: created.parentDocId,
+                linkedToParent: created.linkedToParent,
+                cloneMode: "markdown-roundtrip",
+                lossy: Boolean(created.lossy ?? (created.warnings?.length ?? 0) > 0),
+                warnings: created.warnings ?? [],
+                stats: created.stats ?? null,
+                unfilledVariables: unfilled,
+            };
+        }
+        catch (err) {
+            try {
+                socket.disconnect();
             }
+            catch { /* already disconnected */ }
+            throw err;
         }
-        const failed = results.filter(r => !r.docId).length;
-        return text({ created: results.length - failed, failed, results });
     };
-    server.registerTool("batch_create_docs", {
-        title: "Batch Create Documents",
-        description: "Create multiple AFFiNE documents in a single call. Each doc can optionally be linked to a parent (parentDocId) to appear in the sidebar. Max 20 docs per batch.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docs: z.array(z.object({
-                title: z.string().describe("Document title."),
-                markdown: z.string().describe("Markdown content."),
-                parentDocId: z.string().optional().describe("Parent doc ID — if provided, the new doc is embedded under this parent in the sidebar."),
-            })).min(1).max(20).describe("Array of docs to create (max 20)."),
-        },
-    }, batchCreateDocsHandler);
     const appendMarkdownHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId) {
@@ -4352,194 +4619,6 @@ export function registerDocTools(server, gql, defaults) {
         description: 'Delete a document and remove from workspace list',
         inputSchema: { workspaceId: z.string().optional(), docId: z.string() },
     }, deleteDocHandler);
-    // ─── cleanup_orphan_embeds ──────────────────────────────────────────────────
-    const cleanupOrphanEmbedsHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const snap = await loadDoc(socket, workspaceId, parsed.docId);
-            if (!snap.missing)
-                throw new Error(`Doc ${parsed.docId} not found.`);
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-            const blocks = doc.getMap("blocks");
-            const orphans = [];
-            for (const [blockId, raw] of blocks) {
-                if (!(raw instanceof Y.Map))
-                    continue;
-                if (raw.get("sys:flavour") !== "affine:embed-linked-doc")
-                    continue;
-                const targetId = raw.get("prop:pageId");
-                if (typeof targetId !== "string" || !targetId) {
-                    orphans.push({ blockId, targetDocId: targetId ?? "" });
-                    continue;
-                }
-                const targetSnap = await loadDoc(socket, workspaceId, targetId);
-                if (!targetSnap.missing)
-                    orphans.push({ blockId, targetDocId: targetId });
-            }
-            if (parsed.dryRun || orphans.length === 0) {
-                return text({ docId: parsed.docId, dryRun: parsed.dryRun ?? false, orphansFound: orphans.length, orphans });
-            }
-            const prevSV = Y.encodeStateVector(doc);
-            for (const { blockId } of orphans) {
-                for (const [, parentRaw] of blocks) {
-                    if (!(parentRaw instanceof Y.Map))
-                        continue;
-                    const children = parentRaw.get("sys:children");
-                    if (!(children instanceof Y.Array))
-                        continue;
-                    const ids = childIdsFrom(children);
-                    const idx = ids.indexOf(blockId);
-                    if (idx !== -1) {
-                        children.delete(idx, 1);
-                        break;
-                    }
-                }
-                blocks.delete(blockId);
-            }
-            const delta = Y.encodeStateAsUpdate(doc, prevSV);
-            await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
-            return text({ docId: parsed.docId, dryRun: false, orphansRemoved: orphans.length, orphans });
-        }
-        finally {
-            socket.disconnect();
-        }
-    };
-    server.registerTool("cleanup_orphan_embeds", {
-        title: "Cleanup Orphan Embed Links",
-        description: "Remove embed_linked_doc blocks that point to deleted/non-existent docs. Use dryRun=true to preview without making changes.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string().describe("The doc to clean up orphan embeds from."),
-            dryRun: z.boolean().optional().describe("If true, only report orphans without deleting (default: false)."),
-        },
-    }, cleanupOrphanEmbedsHandler);
-    // ─── find_and_replace ───────────────────────────────────────────────────────
-    const findAndReplaceHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const snap = await loadDoc(socket, workspaceId, parsed.docId);
-            if (!snap.missing)
-                throw new Error(`Doc ${parsed.docId} not found.`);
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-            const blocks = doc.getMap("blocks");
-            let totalMatches = 0;
-            const matchLog = [];
-            const matchAll = parsed.matchAll !== false;
-            for (const [blockId, raw] of blocks) {
-                if (!(raw instanceof Y.Map))
-                    continue;
-                const flavour = raw.get("sys:flavour");
-                for (const [, val] of raw) {
-                    if (!(val instanceof Y.Text))
-                        continue;
-                    const original = val.toString();
-                    if (!original.includes(parsed.search))
-                        continue;
-                    const replaced = matchAll
-                        ? original.split(parsed.search).join(parsed.replace)
-                        : original.replace(parsed.search, parsed.replace);
-                    const count = matchAll ? original.split(parsed.search).length - 1 : 1;
-                    totalMatches += count;
-                    matchLog.push({ blockId, flavour: flavour ?? "unknown", original, replaced });
-                    if (!parsed.dryRun) {
-                        const prevSV = Y.encodeStateVector(doc);
-                        val.delete(0, val.length);
-                        val.insert(0, replaced);
-                        const delta = Y.encodeStateAsUpdate(doc, prevSV);
-                        await pushDocUpdate(socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
-                    }
-                }
-            }
-            return text({
-                docId: parsed.docId, search: parsed.search, replace: parsed.replace,
-                dryRun: parsed.dryRun ?? false, totalMatches, blocksAffected: matchLog.length, matches: matchLog,
-            });
-        }
-        finally {
-            socket.disconnect();
-        }
-    };
-    server.registerTool("find_and_replace", {
-        title: "Find and Replace in Document",
-        description: "Find and replace text across all Y.Text fields in a document (paragraphs, headings, titles). matchAll defaults to true. Use dryRun=true to preview before applying.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string().describe("The doc to search in."),
-            search: z.string().min(1).describe("Text to find (must not be empty)."),
-            replace: z.string().describe("Replacement text."),
-            matchAll: z.boolean().optional().describe("Replace all occurrences (default: true)."),
-            dryRun: z.boolean().optional().describe("If true, only report matches without replacing (default: false)."),
-        },
-    }, findAndReplaceHandler);
-    // ─── get_docs_by_tag ────────────────────────────────────────────────────────
-    const getDocsByTagHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const wsSnap = await loadDoc(socket, workspaceId, workspaceId);
-            if (!wsSnap.missing)
-                return text({ tag: parsed.tag, count: 0, docs: [] });
-            const wsDoc = new Y.Doc();
-            Y.applyUpdate(wsDoc, Buffer.from(wsSnap.missing, "base64"));
-            const meta = wsDoc.getMap("meta");
-            const { byId, options } = getWorkspaceTagOptionMaps(meta);
-            const q = parsed.tag.toLowerCase();
-            const matchingTagIds = new Set(options.filter(o => o.value.toLowerCase().includes(q)).map(o => o.id));
-            if (matchingTagIds.size === 0) {
-                return text({
-                    tag: parsed.tag,
-                    count: 0,
-                    docs: [],
-                    availableTags: options.map(o => o.value),
-                });
-            }
-            const pages = getWorkspacePageEntries(meta);
-            const baseUrl = (process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '');
-            const matched = pages
-                .map(p => {
-                const rawTagIds = getStringArray(p.tagsArray);
-                return { p, rawTagIds };
-            })
-                .filter(({ rawTagIds }) => rawTagIds.some(tid => matchingTagIds.has(tid)))
-                .map(({ p, rawTagIds }) => ({
-                docId: p.id,
-                title: p.title ?? "Untitled",
-                tags: resolveTagLabels(rawTagIds, byId),
-                url: `${baseUrl}/workspace/${workspaceId}/${p.id}`,
-            }));
-            return text({ tag: parsed.tag, count: matched.length, docs: matched });
-        }
-        finally {
-            socket.disconnect();
-        }
-    };
-    server.registerTool("get_docs_by_tag", {
-        title: "Get Documents by Tag",
-        description: "Filter documents by tag name (case-insensitive substring match). Returns matching docs with their full tag list. If no match, also returns availableTags for discoverability.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            tag: z.string().describe("Tag name to filter by (substring match, case-insensitive)."),
-        },
-    }, getDocsByTagHandler);
     // ─── list_workspace_tree ────────────────────────────────────────────────────
     const listWorkspaceTreeHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
@@ -4774,260 +4853,49 @@ export function registerDocTools(server, gql, defaults) {
             title: z.string().describe("New title."),
         },
     }, updateDocTitleHandler);
-    // ─── get_doc_by_title ────────────────────────────────────────────────────────
-    const getDocByTitleHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
+    async function syncRawTagsToDoc(parsed) {
+        if (parsed.tags.length === 0) {
+            return;
+        }
         const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
         const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
         const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
         try {
-            await joinWorkspace(socket, workspaceId);
-            const wsSnap = await loadDoc(socket, workspaceId, workspaceId);
-            if (!wsSnap.missing)
-                return text({ query: parsed.query, found: false, results: [] });
+            await joinWorkspace(socket, parsed.workspaceId);
+            const workspaceSnapshot = await loadDoc(socket, parsed.workspaceId, parsed.workspaceId);
+            if (!workspaceSnapshot.missing) {
+                throw new Error(`Workspace root document not found for workspace ${parsed.workspaceId}`);
+            }
             const wsDoc = new Y.Doc();
-            Y.applyUpdate(wsDoc, Buffer.from(wsSnap.missing, "base64"));
-            const q = parsed.query.toLowerCase();
-            const limit = parsed.limit ?? 1;
-            const matches = getWorkspacePageEntries(wsDoc.getMap("meta"))
-                .filter(p => p.title && p.title.toLowerCase().includes(q)).slice(0, limit);
-            if (matches.length === 0)
-                return text({ query: parsed.query, found: false, results: [] });
-            const results = [];
-            for (const match of matches) {
-                const snap = await loadDoc(socket, workspaceId, match.id);
-                if (!snap.missing) {
-                    results.push({ docId: match.id, title: match.title, found: false });
-                    continue;
-                }
-                const doc = new Y.Doc();
-                Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-                const collected = collectDocForMarkdown(doc, new Map());
-                const rendered = renderBlocksToMarkdown({ rootBlockIds: collected.rootBlockIds, blocksById: collected.blocksById });
-                results.push({ docId: match.id, title: match.title, found: true, markdown: rendered.markdown,
-                    url: `${(process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '')}/workspace/${workspaceId}/${match.id}` });
+            Y.applyUpdate(wsDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
+            const wsPrevSV = Y.encodeStateVector(wsDoc);
+            const wsMeta = wsDoc.getMap("meta");
+            const page = getWorkspacePageEntries(wsMeta).find(entry => entry.id === parsed.docId);
+            if (!page) {
+                throw new Error(`docId ${parsed.docId} is not present in workspace ${parsed.workspaceId}`);
+            }
+            const pageTags = ensureTagArray(page.entry);
+            pageTags.delete(0, pageTags.length);
+            for (const tag of parsed.tags) {
+                pageTags.push([tag]);
+            }
+            const wsDelta = Y.encodeStateAsUpdate(wsDoc, wsPrevSV);
+            await pushDocUpdate(socket, parsed.workspaceId, parsed.workspaceId, Buffer.from(wsDelta).toString("base64"));
+            const docSnapshot = await loadDoc(socket, parsed.workspaceId, parsed.docId);
+            if (!docSnapshot.missing) {
+                throw new Error(`Document ${parsed.docId} not found in workspace ${parsed.workspaceId}`);
             }
-            return text({ query: parsed.query, found: results.some(r => r.found), results });
-        }
-        finally {
-            socket.disconnect();
-        }
-    };
-    server.registerTool("get_doc_by_title", {
-        title: "Get Document by Title",
-        description: "Find a document by title and return its content as markdown in a single call. Combines search_docs + export_doc_markdown. Returns the first match by default; use limit for multiple.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            query: z.string().describe("Title search query (case-insensitive substring match)."),
-            limit: z.number().optional().describe("Max docs to return with content (default: 1)."),
-        },
-    }, getDocByTitleHandler);
-    // ─── list_backlinks ──────────────────────────────────────────────────────────
-    const listBacklinksHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const wsSnap = await loadDoc(socket, workspaceId, workspaceId);
-            if (!wsSnap.missing)
-                return text({ docId: parsed.docId, count: 0, backlinks: [] });
-            const wsDoc = new Y.Doc();
-            Y.applyUpdate(wsDoc, Buffer.from(wsSnap.missing, "base64"));
-            const pages = getWorkspacePageEntries(wsDoc.getMap("meta"));
-            const titleById = new Map(pages.map(p => [p.id, p.title]));
-            const backlinks = [];
-            for (const page of pages) {
-                if (page.id === parsed.docId)
-                    continue;
-                const snap = await loadDoc(socket, workspaceId, page.id);
-                if (!snap.missing)
-                    continue;
-                const doc = new Y.Doc();
-                Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-                const blocks = doc.getMap("blocks");
-                for (const [, raw] of blocks) {
-                    if (!(raw instanceof Y.Map))
-                        continue;
-                    if (raw.get("sys:flavour") === "affine:embed-linked-doc" && raw.get("prop:pageId") === parsed.docId) {
-                        backlinks.push({ docId: page.id, title: titleById.get(page.id) ?? null,
-                            url: `${(process.env.AFFINE_BASE_URL || endpoint.replace(/\/graphql\/?$/, '')).replace(/\/$/, '')}/workspace/${workspaceId}/${page.id}` });
-                        break;
-                    }
-                }
-            }
-            return text({ docId: parsed.docId, count: backlinks.length, backlinks });
-        }
-        finally {
-            socket.disconnect();
-        }
-    };
-    server.registerTool("list_backlinks", {
-        title: "List Document Backlinks",
-        description: "Find all documents that embed-link to a given doc (its parents/references in the sidebar). Scans all docs — may be slow on large workspaces.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string().describe("The doc to find backlinks for."),
-        },
-    }, listBacklinksHandler);
-    // ─── duplicate_doc ───────────────────────────────────────────────────────────
-    const duplicateDocHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const snap = await loadDoc(socket, workspaceId, parsed.docId);
-            if (!snap.missing)
-                throw new Error(`Doc ${parsed.docId} not found.`);
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-            const collected = collectDocForMarkdown(doc, new Map());
-            const rendered = renderBlocksToMarkdown({ rootBlockIds: collected.rootBlockIds, blocksById: collected.blocksById });
-            const newTitle = (parsed.title ?? `${collected.title || "Untitled"} (copy)`).trim();
-            socket.disconnect();
-            const created = await createDocFromMarkdownCore({ workspaceId, title: newTitle, markdown: rendered.markdown, parentDocId: parsed.parentDocId });
-            return receipt("doc.duplicate", {
-                workspaceId,
-                sourceDocId: parsed.docId,
-                docId: created.docId,
-                title: created.title,
-                parentDocId: created.parentDocId,
-                linkedToParent: created.linkedToParent,
-                cloneMode: "markdown-roundtrip",
-                lossy: Boolean(created.lossy ?? (created.warnings?.length ?? 0) > 0),
-                warnings: created.warnings ?? [],
-                stats: created.stats ?? null,
-            });
-        }
-        catch (err) {
-            try {
-                socket.disconnect();
-            }
-            catch { /* already disconnected */ }
-            throw err;
-        }
-    };
-    server.registerTool("duplicate_doc", {
-        title: "Duplicate Document",
-        description: "Clone a document by copying its markdown content into a new doc. Optionally set a new title and/or parentDocId to place it in the sidebar.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            docId: z.string().describe("The source doc to duplicate."),
-            title: z.string().optional().describe("Title for the new doc. Defaults to '<original title> (copy)'."),
-            parentDocId: z.string().optional().describe("Parent doc to link the new doc under in the sidebar."),
-        },
-    }, duplicateDocHandler);
-    // ─── create_doc_from_template ───────────────────────────────────────────────
-    const createDocFromTemplateHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required.");
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, workspaceId);
-            const snap = await loadDoc(socket, workspaceId, parsed.templateDocId);
-            if (!snap.missing)
-                throw new Error(`Template doc ${parsed.templateDocId} not found.`);
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(snap.missing, "base64"));
-            const collected = collectDocForMarkdown(doc, new Map());
-            const rendered = renderBlocksToMarkdown({ rootBlockIds: collected.rootBlockIds, blocksById: collected.blocksById });
-            let markdown = rendered.markdown;
-            const vars = parsed.variables ?? {};
-            for (const [key, value] of Object.entries(vars)) {
-                const pattern = new RegExp(`\\{\\{\\s*${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*\\}}`, "g");
-                markdown = markdown.replace(pattern, value);
-            }
-            const unfilled = [...markdown.matchAll(/\{\{\s*[\w.-]+\s*\}\}/g)].map(match => match[0]);
-            socket.disconnect();
-            const created = await createDocFromMarkdownCore({ workspaceId, title: parsed.title, markdown, parentDocId: parsed.parentDocId });
-            return receipt("doc.create_from_template", {
-                workspaceId,
-                sourceTemplateDocId: parsed.templateDocId,
-                docId: created.docId,
-                title: created.title,
-                parentDocId: created.parentDocId,
-                linkedToParent: created.linkedToParent,
-                cloneMode: "markdown-roundtrip",
-                lossy: Boolean(created.lossy ?? (created.warnings?.length ?? 0) > 0),
-                warnings: created.warnings ?? [],
-                stats: created.stats ?? null,
-                unfilledVariables: unfilled,
-            });
-        }
-        catch (err) {
-            try {
-                socket.disconnect();
-            }
-            catch { /* already disconnected */ }
-            throw err;
-        }
-    };
-    server.registerTool("create_doc_from_template", {
-        title: "Create Document from Template",
-        description: "Clone a template doc and substitute {{variable}} placeholders. Returns a warning for any unfilled variables. Optionally link to a parent doc in the sidebar.",
-        inputSchema: {
-            workspaceId: z.string().optional(),
-            templateDocId: z.string().describe("The template doc to clone from."),
-            title: z.string().describe("Title for the new doc."),
-            variables: z.record(z.string(), z.string()).optional().describe("Key-value map of {{variable}} substitutions."),
-            parentDocId: z.string().optional().describe("Parent doc to link the new doc under in the sidebar."),
-        },
-    }, createDocFromTemplateHandler);
-    async function syncRawTagsToDoc(parsed) {
-        if (parsed.tags.length === 0) {
-            return;
-        }
-        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
-        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
-        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
-        try {
-            await joinWorkspace(socket, parsed.workspaceId);
-            const workspaceSnapshot = await loadDoc(socket, parsed.workspaceId, parsed.workspaceId);
-            if (!workspaceSnapshot.missing) {
-                throw new Error(`Workspace root document not found for workspace ${parsed.workspaceId}`);
-            }
-            const wsDoc = new Y.Doc();
-            Y.applyUpdate(wsDoc, Buffer.from(workspaceSnapshot.missing, "base64"));
-            const wsPrevSV = Y.encodeStateVector(wsDoc);
-            const wsMeta = wsDoc.getMap("meta");
-            const page = getWorkspacePageEntries(wsMeta).find(entry => entry.id === parsed.docId);
-            if (!page) {
-                throw new Error(`docId ${parsed.docId} is not present in workspace ${parsed.workspaceId}`);
-            }
-            const pageTags = ensureTagArray(page.entry);
-            pageTags.delete(0, pageTags.length);
-            for (const tag of parsed.tags) {
-                pageTags.push([tag]);
-            }
-            const wsDelta = Y.encodeStateAsUpdate(wsDoc, wsPrevSV);
-            await pushDocUpdate(socket, parsed.workspaceId, parsed.workspaceId, Buffer.from(wsDelta).toString("base64"));
-            const docSnapshot = await loadDoc(socket, parsed.workspaceId, parsed.docId);
-            if (!docSnapshot.missing) {
-                throw new Error(`Document ${parsed.docId} not found in workspace ${parsed.workspaceId}`);
-            }
-            const doc = new Y.Doc();
-            Y.applyUpdate(doc, Buffer.from(docSnapshot.missing, "base64"));
-            const docPrevSV = Y.encodeStateVector(doc);
-            const docMeta = doc.getMap("meta");
-            const docTags = ensureTagArray(docMeta);
-            docTags.delete(0, docTags.length);
-            for (const tag of parsed.tags) {
-                docTags.push([tag]);
-            }
-            const docDelta = Y.encodeStateAsUpdate(doc, docPrevSV);
-            await pushDocUpdate(socket, parsed.workspaceId, parsed.docId, Buffer.from(docDelta).toString("base64"));
+            const doc = new Y.Doc();
+            Y.applyUpdate(doc, Buffer.from(docSnapshot.missing, "base64"));
+            const docPrevSV = Y.encodeStateVector(doc);
+            const docMeta = doc.getMap("meta");
+            const docTags = ensureTagArray(docMeta);
+            docTags.delete(0, docTags.length);
+            for (const tag of parsed.tags) {
+                docTags.push([tag]);
+            }
+            const docDelta = Y.encodeStateAsUpdate(doc, docPrevSV);
+            await pushDocUpdate(socket, parsed.workspaceId, parsed.docId, Buffer.from(docDelta).toString("base64"));
         }
         finally {
             socket.disconnect();
@@ -5120,14 +4988,13 @@ export function registerDocTools(server, gql, defaults) {
                 if (!allowFallback) {
                     throw new Error(`Native template instantiation is not supported: ${nativeSummary.fallbackReasons.join(" | ")}`);
                 }
-                const fallbackResult = await createDocFromTemplateHandler({
+                const created = await createDocFromTemplateCore({
                     workspaceId,
                     templateDocId: parsed.templateDocId,
                     title: targetTitle,
                     variables: parsed.variables,
                     parentDocId: parsed.parentDocId,
                 });
-                const created = JSON.parse(fallbackResult.content[0].text);
                 return text({
                     ...created,
                     mode: "markdown_fallback",
@@ -5930,56 +5797,6 @@ export function registerDocTools(server, gql, defaults) {
             databaseBlockId: z.string().min(1).describe("Block ID of the affine:database block"),
         },
     }, readDatabaseColumnsHandler);
-    const updateDatabaseCellHandler = async (parsed) => {
-        const workspaceId = parsed.workspaceId || defaults.workspaceId;
-        if (!workspaceId)
-            throw new Error("workspaceId is required");
-        const ctx = await loadDatabaseDocContext(workspaceId, parsed.docId, parsed.databaseBlockId);
-        try {
-            const rowBlock = getDatabaseRowBlock(ctx.blocks, ctx.dbBlock, parsed.databaseBlockId, parsed.rowBlockId);
-            const rowCells = ensureDatabaseRowCells(ctx.cellsMap, parsed.rowBlockId);
-            const col = findDatabaseColumn(parsed.column, ctx);
-            if (!col) {
-                if (!isTitleAliasKey(parsed.column)) {
-                    throw new Error(`Column '${parsed.column}' not found. Available columns: ${availableDatabaseColumns(ctx)}`);
-                }
-            }
-            else {
-                writeDatabaseCellValue(rowCells, col, parsed.value, parsed.createOption ?? true);
-            }
-            if (parsed.linkedDocId) {
-                rowBlock.set("prop:text", makeLinkedDocText(parsed.linkedDocId));
-            }
-            else if (isTitleAliasKey(parsed.column) || (col && (col.type === "title" || isTitleAliasKey(col.name)))) {
-                rowBlock.set("prop:text", makeText(String(parsed.value ?? "")));
-            }
-            const delta = Y.encodeStateAsUpdate(ctx.doc, ctx.prevSV);
-            await pushDocUpdate(ctx.socket, workspaceId, parsed.docId, Buffer.from(delta).toString("base64"));
-            return text({
-                updated: true,
-                rowBlockId: parsed.rowBlockId,
-                column: parsed.column,
-                value: parsed.value ?? null,
-            });
-        }
-        finally {
-            ctx.socket.disconnect();
-        }
-    };
-    server.registerTool("update_database_cell", {
-        title: "Update Database Cell",
-        description: "Update a single cell on an existing AFFiNE database row. Use `title` to update the row title shown in Kanban card headers.",
-        inputSchema: {
-            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
-            docId: DocId.describe("Document ID containing the database"),
-            databaseBlockId: z.string().min(1).describe("Block ID of the affine:database block"),
-            rowBlockId: z.string().min(1).describe("Row paragraph block ID"),
-            column: z.string().min(1).describe("Column name or ID. Use `title` for the built-in row title."),
-            value: z.unknown().describe("New cell value"),
-            createOption: z.boolean().optional().describe("For select and multi-select columns, create the option label if it does not exist (default true)"),
-            linkedDocId: z.string().optional().describe("Link this row to an existing doc by ID. Replaces any existing title with a linked doc reference."),
-        },
-    }, updateDatabaseCellHandler);
     const updateDatabaseRowHandler = async (parsed) => {
         const workspaceId = parsed.workspaceId || defaults.workspaceId;
         if (!workspaceId)
@@ -6231,4 +6048,1256 @@ export function registerDocTools(server, gql, defaults) {
             width: z.number().optional().describe("Column width in pixels (default 200)"),
         },
     }, addDatabaseColumnHandler);
+    function resolveSurfaceNewlines(s) {
+        return s.replace(/\\n/g, "\n");
+    }
+    function getSurfaceElementsValueMap(blocks, options) {
+        let surfaceId = findBlockIdByFlavour(blocks, "affine:surface");
+        if (!surfaceId) {
+            if (!options.create)
+                return null;
+            surfaceId = ensureSurfaceBlock(blocks);
+        }
+        const surface = blocks.get(surfaceId);
+        let elements = surface.get("prop:elements");
+        if (!(elements instanceof Y.Map)) {
+            if (!options.create)
+                return null;
+            elements = new Y.Map();
+            elements.set("type", "$blocksuite:internal:native$");
+            elements.set("value", new Y.Map());
+            surface.set("prop:elements", elements);
+        }
+        let value = elements.get("value");
+        if (!(value instanceof Y.Map)) {
+            if (!options.create)
+                return null;
+            value = new Y.Map();
+            elements.set("value", value);
+        }
+        return { surfaceId, value };
+    }
+    function serializeSurfaceElement(elementId, el) {
+        const out = { id: elementId };
+        for (const [k, v] of el.entries()) {
+            if (v instanceof Y.Text) {
+                out[k] = v.toString();
+            }
+            else if (v instanceof Y.Map) {
+                out[k] = v.toJSON();
+            }
+            else if (v instanceof Y.Array) {
+                out[k] = v.toArray();
+            }
+            else {
+                out[k] = v;
+            }
+        }
+        const xywh = parseXywhString(out.xywh);
+        if (xywh)
+            out.bounds = xywh;
+        return out;
+    }
+    function buildShapeElementData(elementId, seed, index, input) {
+        const x = input.x ?? 0;
+        const y = input.y ?? 0;
+        const w = input.width ?? 100;
+        const h = input.height ?? 100;
+        const data = {
+            type: "shape",
+            id: elementId,
+            index,
+            seed,
+            xywh: formatXywhString(x, y, w, h),
+            rotate: 0,
+            shapeType: input.shapeType ?? "rect",
+            shapeStyle: "General",
+            radius: input.radius ?? 0,
+            filled: input.filled ?? true,
+            fillColor: input.fillColor ?? "--affine-palette-shape-yellow",
+            strokeWidth: input.strokeWidth ?? 2,
+            strokeColor: input.strokeColor ?? "--affine-palette-line-yellow",
+            strokeStyle: input.strokeStyle ?? "solid",
+            roughness: 1.4,
+            // Fixed #000000 matches BlockSuite's shape tool: shape fills don't
+            // theme-adapt, so label color stays pinned too. Override for dark fills.
+            color: input.color ?? "#000000",
+            fontFamily: "blocksuite:surface:Inter",
+            fontSize: input.fontSize ?? 20,
+            fontStyle: "normal",
+            fontWeight: input.fontWeight ?? "600",
+            textAlign: "center",
+            textHorizontalAlign: "center",
+            textVerticalAlign: "center",
+            textResizing: 1,
+            maxWidth: false,
+            padding: [10, 20],
+            shadow: null,
+        };
+        if (input.text) {
+            const yText = new Y.Text();
+            yText.insert(0, resolveSurfaceNewlines(input.text));
+            data.text = yText;
+        }
+        return data;
+    }
+    function resolveConnectorEndpointBoundAsBound(surfaceValueMap, blocks, endpointId) {
+        if (!endpointId)
+            return null;
+        const surfaceEl = surfaceValueMap.get(endpointId);
+        if (surfaceEl instanceof Y.Map) {
+            const xywh = parseXywhString(surfaceEl.get("xywh"));
+            if (xywh)
+                return { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height };
+        }
+        const block = blocks.get(endpointId);
+        if (block instanceof Y.Map) {
+            const xywh = parseXywhString(block.get("prop:xywh"));
+            if (xywh)
+                return { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height };
+        }
+        return null;
+    }
+    function resolveChildBound(surfaceValueMap, blocks, id) {
+        const surfaceEl = surfaceValueMap.get(id);
+        if (surfaceEl instanceof Y.Map) {
+            const xywh = parseXywhString(surfaceEl.get("xywh"));
+            return {
+                kind: "surface",
+                bound: xywh ? { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height } : null,
+            };
+        }
+        const block = blocks.get(id);
+        if (block instanceof Y.Map) {
+            const xywh = parseXywhString(block.get("prop:xywh"));
+            return {
+                kind: "block",
+                bound: xywh ? { x: xywh.x, y: xywh.y, w: xywh.width, h: xywh.height } : null,
+            };
+        }
+        return { kind: "missing", bound: null };
+    }
+    function resolveConnectorEndpointCenter(surfaceValueMap, blocks, endpointId, endpointPosition) {
+        if (endpointPosition && Array.isArray(endpointPosition) && endpointPosition.length === 2) {
+            return { x: endpointPosition[0], y: endpointPosition[1] };
+        }
+        if (!endpointId)
+            return null;
+        const surfaceEl = surfaceValueMap.get(endpointId);
+        if (surfaceEl instanceof Y.Map) {
+            const xywh = parseXywhString(surfaceEl.get("xywh"));
+            if (xywh)
+                return { x: xywh.x + xywh.width / 2, y: xywh.y + xywh.height / 2 };
+        }
+        const block = blocks.get(endpointId);
+        if (block instanceof Y.Map) {
+            const xywh = parseXywhString(block.get("prop:xywh"));
+            if (xywh)
+                return { x: xywh.x + xywh.width / 2, y: xywh.y + xywh.height / 2 };
+        }
+        return null;
+    }
+    function buildConnectorElementData(elementId, seed, index, input) {
+        const source = {};
+        if (input.sourceId) {
+            source.id = input.sourceId;
+            if (input.sourcePosition)
+                source.position = input.sourcePosition;
+        }
+        else if (input.sourcePosition) {
+            source.position = input.sourcePosition;
+        }
+        const target = {};
+        if (input.targetId) {
+            target.id = input.targetId;
+            if (input.targetPosition)
+                target.position = input.targetPosition;
+        }
+        else if (input.targetPosition) {
+            target.position = input.targetPosition;
+        }
+        const data = {
+            type: "connector",
+            id: elementId,
+            index,
+            seed,
+            mode: input.mode ?? 2,
+            // Theme-adaptive token so connectors stay legible in dark mode.
+            stroke: input.stroke ?? "--affine-text-primary-color",
+            strokeWidth: input.strokeWidth ?? 2,
+            strokeStyle: input.strokeStyle ?? "solid",
+            roughness: 1.4,
+            frontEndpointStyle: input.frontEndpointStyle ?? "None",
+            rearEndpointStyle: input.rearEndpointStyle ?? "Arrow",
+            source,
+            target,
+            labelDisplay: true,
+            labelOffset: { distance: 0.5, anchor: "center" },
+            labelStyle: {
+                color: "--affine-text-primary-color",
+                fontFamily: "blocksuite:surface:Inter",
+                fontSize: 16,
+                fontStyle: "normal",
+                fontWeight: "400",
+                textAlign: "center",
+            },
+            labelConstraints: { hasMaxWidth: true, maxWidth: 280 },
+        };
+        if (input.label) {
+            const yText = new Y.Text();
+            yText.insert(0, resolveSurfaceNewlines(input.label));
+            data.text = yText;
+        }
+        return data;
+    }
+    function buildTextElementData(elementId, seed, index, input) {
+        const x = input.x ?? 0;
+        const y = input.y ?? 0;
+        const w = input.width ?? 200;
+        const h = input.height ?? 30;
+        const yText = new Y.Text();
+        if (input.text)
+            yText.insert(0, resolveSurfaceNewlines(input.text));
+        return {
+            type: "text",
+            id: elementId,
+            index,
+            seed,
+            xywh: formatXywhString(x, y, w, h),
+            rotate: 0,
+            text: yText,
+            color: input.color ?? "--affine-text-primary-color",
+            fontFamily: "blocksuite:surface:Inter",
+            fontSize: input.fontSize ?? 16,
+            fontStyle: "normal",
+            fontWeight: input.fontWeight ?? "400",
+            textAlign: "center",
+            hasMaxWidth: false,
+        };
+    }
+    function buildGroupElementData(elementId, seed, index, input) {
+        const childMap = new Y.Map();
+        for (const childId of input.children ?? []) {
+            childMap.set(childId, true);
+        }
+        const yTitle = new Y.Text();
+        if (input.title)
+            yTitle.insert(0, input.title);
+        return {
+            type: "group",
+            id: elementId,
+            index,
+            seed,
+            children: childMap,
+            title: yTitle,
+        };
+    }
+    function nextSurfaceElementIndex(valueMap) {
+        let maxIndex = null;
+        for (const [, el] of valueMap.entries()) {
+            if (!(el instanceof Y.Map))
+                continue;
+            const idx = el.get("index");
+            if (typeof idx !== "string")
+                continue;
+            if (maxIndex === null || idx > maxIndex)
+                maxIndex = idx;
+        }
+        return generateKeyBetween(maxIndex, null);
+    }
+    function buildSurfaceElementData(type, index, input) {
+        const elementId = generateId();
+        const seed = Math.floor(Math.random() * 2 ** 31);
+        switch (type) {
+            case "shape":
+                return { elementId, data: buildShapeElementData(elementId, seed, index, input) };
+            case "connector":
+                return { elementId, data: buildConnectorElementData(elementId, seed, index, input) };
+            case "text":
+                return { elementId, data: buildTextElementData(elementId, seed, index, input) };
+            case "group":
+                return { elementId, data: buildGroupElementData(elementId, seed, index, input) };
+        }
+    }
+    function writeSurfaceElement(valueMap, elementId, data) {
+        const el = new Y.Map();
+        for (const [k, v] of Object.entries(data)) {
+            el.set(k, v);
+        }
+        valueMap.set(elementId, el);
+    }
+    const addSurfaceElementHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (snapshot.missing) {
+                Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            }
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const ctx = getSurfaceElementsValueMap(blocks, { create: true });
+            const index = params.index ?? nextSurfaceElementIndex(ctx.value);
+            // Mirror updateSurfaceElementHandler: report inapplicable gated fields
+            // in `ignored` instead of silently dropping them at the per-type builder.
+            const ignored = [];
+            for (const [field, applicable] of Object.entries(FIELD_APPLICABILITY)) {
+                if (params[field] === undefined)
+                    continue;
+                if (!applicable.includes(params.type))
+                    ignored.push(field);
+            }
+            const { elementId, data } = buildSurfaceElementData(params.type, index, params);
+            if (params.type === "connector") {
+                const srcBounds = resolveConnectorEndpointBoundAsBound(ctx.value, blocks, params.sourceId);
+                const tgtBounds = resolveConnectorEndpointBoundAsBound(ctx.value, blocks, params.targetId);
+                // Auto-snap to the four tangent-carrying sides when the caller only
+                // supplied ids — the renderer needs tangents to draw arrow heads.
+                if (srcBounds && tgtBounds && !params.sourcePosition && !params.targetPosition) {
+                    const natural = pickConnectorSides(srcBounds, tgtBounds);
+                    data.source = { ...data.source, position: SIDE_TO_NORMALIZED_POSITION[natural.from] };
+                    data.target = { ...data.target, position: SIDE_TO_NORMALIZED_POSITION[natural.to] };
+                }
+                if (params.label) {
+                    const srcCenter = srcBounds
+                        ? { x: srcBounds.x + srcBounds.w / 2, y: srcBounds.y + srcBounds.h / 2 }
+                        : resolveConnectorEndpointCenter(ctx.value, blocks, params.sourceId, params.sourcePosition);
+                    const tgtCenter = tgtBounds
+                        ? { x: tgtBounds.x + tgtBounds.w / 2, y: tgtBounds.y + tgtBounds.h / 2 }
+                        : resolveConnectorEndpointCenter(ctx.value, blocks, params.targetId, params.targetPosition);
+                    const midpoint = srcCenter && tgtCenter
+                        ? { x: (srcCenter.x + tgtCenter.x) / 2, y: (srcCenter.y + tgtCenter.y) / 2 }
+                        : (srcCenter ?? tgtCenter);
+                    data.labelXYWH = estimateConnectorLabelXYWH(params.label, 16, midpoint, 280);
+                }
+            }
+            writeSurfaceElement(ctx.value, elementId, data);
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({
+                added: true,
+                elementId,
+                type: params.type,
+                surfaceBlockId: ctx.surfaceId,
+                ignored,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const listSurfaceElementsHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                return text({
+                    docId: params.docId,
+                    exists: false,
+                    surfaceBlockId: null,
+                    count: 0,
+                    elements: [],
+                });
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const blocks = doc.getMap("blocks");
+            const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+            if (!ctx) {
+                return text({
+                    docId: params.docId,
+                    exists: true,
+                    surfaceBlockId: null,
+                    count: 0,
+                    elements: [],
+                });
+            }
+            const elements = [];
+            for (const [id, value] of ctx.value.entries()) {
+                const entryId = String(id);
+                if (params.elementId && entryId !== params.elementId)
+                    continue;
+                if (!(value instanceof Y.Map))
+                    continue;
+                const serialized = serializeSurfaceElement(entryId, value);
+                if (params.type && serialized.type !== params.type)
+                    continue;
+                elements.push(serialized);
+            }
+            const sorted = sortByFractionalIndex(elements);
+            return text({
+                docId: params.docId,
+                exists: true,
+                surfaceBlockId: ctx.surfaceId,
+                count: sorted.length,
+                elements: sorted,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    // Also parsed by scripts/verify-surface-element-gating.mjs — adding a styling
+    // field to surfaceElementFieldSchemas without a row here fails that gate.
+    // Per-type rows mirror blocksuite's @field decorators (toeverything/blocksuite@5cb5cb6
+    // packages/affine/model/src/elements/{connector,shape}.ts).
+    const FIELD_APPLICABILITY = {
+        shapeType: ["shape"],
+        radius: ["shape"],
+        filled: ["shape"],
+        fillColor: ["shape"],
+        strokeColor: ["shape"], // connectors use top-level `stroke`
+        strokeWidth: ["shape", "connector"],
+        strokeStyle: ["shape", "connector"],
+        color: ["shape", "text"], // connectors use labelStyle.*
+        fontSize: ["shape", "text"],
+        fontWeight: ["shape", "text"],
+        stroke: ["connector"],
+        mode: ["connector"],
+        frontEndpointStyle: ["connector"],
+        rearEndpointStyle: ["connector"],
+    };
+    const updateSurfaceElementHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+            if (!ctx)
+                throw new Error("Document has no surface elements to update.");
+            const el = ctx.value.get(params.elementId);
+            if (!(el instanceof Y.Map)) {
+                throw new Error(`Surface element '${params.elementId}' not found.`);
+            }
+            const elementType = el.get("type");
+            const changed = [];
+            const ignored = [];
+            const geomProvided = params.x !== undefined ||
+                params.y !== undefined ||
+                params.width !== undefined ||
+                params.height !== undefined;
+            if (geomProvided) {
+                if (elementType === "shape" || elementType === "text") {
+                    const current = parseXywhString(el.get("xywh")) ?? {
+                        x: 0,
+                        y: 0,
+                        width: 100,
+                        height: 100,
+                    };
+                    const nx = params.x ?? current.x;
+                    const ny = params.y ?? current.y;
+                    const nw = params.width ?? current.width;
+                    const nh = params.height ?? current.height;
+                    el.set("xywh", formatXywhString(nx, ny, nw, nh));
+                    changed.push("xywh");
+                }
+                else {
+                    if (params.x !== undefined)
+                        ignored.push("x");
+                    if (params.y !== undefined)
+                        ignored.push("y");
+                    if (params.width !== undefined)
+                        ignored.push("width");
+                    if (params.height !== undefined)
+                        ignored.push("height");
+                }
+            }
+            const setYText = (key, value) => {
+                const yText = new Y.Text();
+                yText.insert(0, resolveSurfaceNewlines(value));
+                el.set(key, yText);
+                changed.push(key);
+            };
+            if (params.text !== undefined) {
+                if (elementType === "shape" || elementType === "text" || elementType === "connector") {
+                    setYText("text", params.text);
+                }
+                else {
+                    ignored.push("text");
+                }
+            }
+            if (params.label !== undefined) {
+                if (elementType === "connector") {
+                    setYText("text", params.label);
+                }
+                else {
+                    ignored.push("label");
+                }
+            }
+            if (params.title !== undefined) {
+                if (elementType === "group") {
+                    setYText("title", params.title);
+                }
+                else {
+                    ignored.push("title");
+                }
+            }
+            for (const [field, applicable] of Object.entries(FIELD_APPLICABILITY)) {
+                const key = field;
+                if (params[key] === undefined)
+                    continue;
+                if (applicable.includes(elementType)) {
+                    el.set(field, params[key]);
+                    changed.push(field);
+                }
+                else {
+                    ignored.push(field);
+                }
+            }
+            if (params.index !== undefined) {
+                el.set("index", params.index);
+                changed.push("index");
+            }
+            if (params.sourceId !== undefined || params.sourcePosition !== undefined) {
+                if (elementType === "connector") {
+                    const source = {};
+                    if (params.sourceId)
+                        source.id = params.sourceId;
+                    if (params.sourcePosition)
+                        source.position = params.sourcePosition;
+                    el.set("source", source);
+                    changed.push("source");
+                }
+                else {
+                    if (params.sourceId !== undefined)
+                        ignored.push("sourceId");
+                    if (params.sourcePosition !== undefined)
+                        ignored.push("sourcePosition");
+                }
+            }
+            if (params.targetId !== undefined || params.targetPosition !== undefined) {
+                if (elementType === "connector") {
+                    const target = {};
+                    if (params.targetId)
+                        target.id = params.targetId;
+                    if (params.targetPosition)
+                        target.position = params.targetPosition;
+                    el.set("target", target);
+                    changed.push("target");
+                }
+                else {
+                    if (params.targetId !== undefined)
+                        ignored.push("targetId");
+                    if (params.targetPosition !== undefined)
+                        ignored.push("targetPosition");
+                }
+            }
+            if (params.children !== undefined) {
+                if (elementType === "group") {
+                    const childMap = new Y.Map();
+                    for (const childId of params.children)
+                        childMap.set(childId, true);
+                    el.set("children", childMap);
+                    changed.push("children");
+                }
+                else {
+                    ignored.push("children");
+                }
+            }
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({
+                updated: changed.length > 0,
+                elementId: params.elementId,
+                type: typeof elementType === "string" ? elementType : null,
+                changed,
+                ignored,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const deleteSurfaceElementHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+            if (!ctx) {
+                return text({
+                    deleted: false,
+                    elementId: params.elementId,
+                    reason: "no-surface",
+                    prunedConnectors: [],
+                });
+            }
+            const existing = ctx.value.get(params.elementId);
+            if (!(existing instanceof Y.Map)) {
+                return text({
+                    deleted: false,
+                    elementId: params.elementId,
+                    reason: "not-found",
+                    prunedConnectors: [],
+                });
+            }
+            ctx.value.delete(params.elementId);
+            const prunedConnectors = [];
+            if (params.pruneConnectors) {
+                const toDelete = [];
+                for (const [otherId, otherVal] of ctx.value.entries()) {
+                    if (!(otherVal instanceof Y.Map))
+                        continue;
+                    if (otherVal.get("type") !== "connector")
+                        continue;
+                    const source = otherVal.get("source");
+                    const target = otherVal.get("target");
+                    const srcId = source && typeof source === "object" ? source.id : undefined;
+                    const tgtId = target && typeof target === "object" ? target.id : undefined;
+                    if (srcId === params.elementId || tgtId === params.elementId) {
+                        toDelete.push(String(otherId));
+                    }
+                }
+                for (const id of toDelete) {
+                    ctx.value.delete(id);
+                    prunedConnectors.push(id);
+                }
+            }
+            pruneFromFrameChildElementIds(blocks, [params.elementId, ...prunedConnectors]);
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({ deleted: true, elementId: params.elementId, prunedConnectors });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const updateFrameChildrenHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const frameBlock = blocks.get(params.blockId);
+            if (!(frameBlock instanceof Y.Map) || frameBlock.get("sys:flavour") !== "affine:frame") {
+                throw new Error(`Frame block '${params.blockId}' not found.`);
+            }
+            // All-missing is legit here: it's how callers clear ownership.
+            const surfaceCtx = getSurfaceElementsValueMap(blocks, { create: false });
+            const surfaceValueMap = surfaceCtx?.value ?? new Y.Map();
+            const ownedIds = [];
+            const missing = [];
+            const kids = [];
+            for (const id of params.childElementIds) {
+                const resolved = resolveChildBound(surfaceValueMap, blocks, id);
+                if (resolved.kind === "missing") {
+                    missing.push(id);
+                }
+                else {
+                    ownedIds.push(id);
+                    if (resolved.bound)
+                        kids.push(resolved.bound);
+                }
+            }
+            const childMap = new Y.Map();
+            for (const id of ownedIds)
+                childMap.set(id, true);
+            frameBlock.set("prop:childElementIds", childMap);
+            // Resize-to-fit is default; skip on all-missing so clear-ownership
+            // doesn't collapse the frame to zero.
+            const resize = params.resizeToFit !== false;
+            const padding = Number.isFinite(params.padding)
+                ? Math.max(0, Math.floor(params.padding))
+                : 40;
+            let xywh = null;
+            if (resize && kids.length > 0) {
+                const wrapped = encloseBounds(kids, { padding, titleBand: 60 });
+                if (wrapped) {
+                    xywh = { x: wrapped.x, y: wrapped.y, width: wrapped.w, height: wrapped.h };
+                    frameBlock.set("prop:xywh", formatXywhString(xywh.x, xywh.y, xywh.width, xywh.height));
+                }
+            }
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({
+                updated: true,
+                blockId: params.blockId,
+                flavour: "affine:frame",
+                ownedIds,
+                missing,
+                resized: xywh !== null,
+                ...(xywh ? { xywh } : {}),
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const updateEdgelessBlockHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const block = blocks.get(params.blockId);
+            if (!(block instanceof Y.Map)) {
+                throw new Error(`Block '${params.blockId}' not found.`);
+            }
+            const flavour = block.get("sys:flavour");
+            if (flavour !== "affine:note" && flavour !== "affine:frame" && flavour !== "affine:edgeless-text") {
+                throw new Error(`Block '${params.blockId}' has flavour '${String(flavour)}' — update_edgeless_block only mutates note/frame/edgeless-text blocks.`);
+            }
+            const changed = [];
+            const ignored = [];
+            if (params.x !== undefined || params.y !== undefined || params.width !== undefined || params.height !== undefined) {
+                const prev = parseXywhString(block.get("prop:xywh")) ?? { x: 0, y: 0, width: 0, height: 0 };
+                block.set("prop:xywh", formatXywhString(params.x ?? prev.x, params.y ?? prev.y, params.width ?? prev.width, params.height ?? prev.height));
+                changed.push("xywh");
+            }
+            if (params.background !== undefined) {
+                if (flavour === "affine:edgeless-text") {
+                    ignored.push("background"); // edgeless-text has no prop:background
+                }
+                else {
+                    const bg = params.background;
+                    if (bg && typeof bg === "object" && !Array.isArray(bg) && ("light" in bg || "dark" in bg)) {
+                        const bgMap = new Y.Map();
+                        if (typeof bg.light === "string")
+                            bgMap.set("light", bg.light);
+                        if (typeof bg.dark === "string")
+                            bgMap.set("dark", bg.dark);
+                        block.set("prop:background", bgMap);
+                    }
+                    else {
+                        block.set("prop:background", bg);
+                    }
+                    changed.push("background");
+                }
+            }
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({ updated: changed.length > 0, blockId: params.blockId, flavour, changed, ignored });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const deleteBlockHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                throw new Error(`Document '${params.docId}' not found or has no content.`);
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const prevSV = Y.encodeStateVector(doc);
+            const blocks = doc.getMap("blocks");
+            const block = blocks.get(params.blockId);
+            if (!(block instanceof Y.Map)) {
+                return text({ deleted: false, blockId: params.blockId, reason: "not-found" });
+            }
+            const flavour = block.get("sys:flavour");
+            if (flavour === "affine:page") {
+                throw new Error(`Refusing to delete page-root block '${params.blockId}' — use delete_doc for whole-doc removal.`);
+            }
+            const deletedIds = [];
+            const deleteRecursive = params.deleteChildren !== false;
+            const walk = (id) => {
+                const b = blocks.get(id);
+                if (!(b instanceof Y.Map))
+                    return;
+                if (deleteRecursive) {
+                    const children = b.get("sys:children");
+                    if (children instanceof Y.Array) {
+                        for (const c of children.toArray()) {
+                            if (typeof c === "string")
+                                walk(c);
+                        }
+                    }
+                }
+                blocks.delete(id);
+                deletedIds.push(id);
+            };
+            walk(params.blockId);
+            for (const [, maybeParent] of blocks.entries()) {
+                if (!(maybeParent instanceof Y.Map))
+                    continue;
+                const kids = maybeParent.get("sys:children");
+                if (!(kids instanceof Y.Array))
+                    continue;
+                const arr = kids.toArray();
+                for (let i = arr.length - 1; i >= 0; i--) {
+                    if (typeof arr[i] === "string" && deletedIds.includes(arr[i])) {
+                        kids.delete(i, 1);
+                    }
+                }
+            }
+            // Mirror delete_surface_element's pruneConnectors semantics.
+            const prunedConnectors = [];
+            if (params.pruneConnectors) {
+                const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+                if (ctx) {
+                    const toDelete = [];
+                    for (const [otherId, otherVal] of ctx.value.entries()) {
+                        if (!(otherVal instanceof Y.Map))
+                            continue;
+                        if (otherVal.get("type") !== "connector")
+                            continue;
+                        const source = otherVal.get("source");
+                        const target = otherVal.get("target");
+                        const srcId = source && typeof source === "object" ? source.id : undefined;
+                        const tgtId = target && typeof target === "object" ? target.id : undefined;
+                        if ((typeof srcId === "string" && deletedIds.includes(srcId)) ||
+                            (typeof tgtId === "string" && deletedIds.includes(tgtId))) {
+                            toDelete.push(String(otherId));
+                        }
+                    }
+                    for (const id of toDelete) {
+                        ctx.value.delete(id);
+                        prunedConnectors.push(id);
+                    }
+                }
+            }
+            pruneFromFrameChildElementIds(blocks, [...deletedIds, ...prunedConnectors]);
+            const delta = Y.encodeStateAsUpdate(doc, prevSV);
+            await pushDocUpdate(socket, workspaceId, params.docId, Buffer.from(delta).toString("base64"));
+            return text({ deleted: true, blockId: params.blockId, deletedIds, prunedConnectors });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const getEdgelessCanvasHandler = async (params) => {
+        const workspaceId = params.workspaceId || defaults.workspaceId;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required. Provide it as a parameter or set AFFINE_WORKSPACE_ID in environment.");
+        }
+        const { endpoint, cookie, bearer } = await getCookieAndEndpoint();
+        const wsUrl = wsUrlFromGraphQLEndpoint(endpoint);
+        const socket = await connectWorkspaceSocket(wsUrl, cookie, bearer);
+        try {
+            await joinWorkspace(socket, workspaceId);
+            const doc = new Y.Doc();
+            const snapshot = await loadDoc(socket, workspaceId, params.docId);
+            if (!snapshot.missing) {
+                return text({
+                    docId: params.docId,
+                    exists: false,
+                    surfaceBlockId: null,
+                    edgelessBlocks: [],
+                    surfaceElements: [],
+                    bounds: null,
+                    elementCounts: { shape: 0, connector: 0, text: 0, group: 0 },
+                });
+            }
+            Y.applyUpdate(doc, Buffer.from(snapshot.missing, "base64"));
+            const blocks = doc.getMap("blocks");
+            const edgelessFlavours = new Set([
+                "affine:frame",
+                "affine:edgeless-text",
+                "affine:note",
+            ]);
+            const collectNoteText = (rootId) => {
+                const out = [];
+                const seen = new Set();
+                const visit = (id) => {
+                    if (seen.has(id))
+                        return;
+                    seen.add(id);
+                    const b = blocks.get(id);
+                    if (!(b instanceof Y.Map))
+                        return;
+                    const t = asText(b.get("prop:text"));
+                    if (t)
+                        out.push(t);
+                    for (const childId of childIdsFrom(b.get("sys:children"))) {
+                        visit(childId);
+                    }
+                };
+                const root = blocks.get(rootId);
+                if (root instanceof Y.Map) {
+                    for (const childId of childIdsFrom(root.get("sys:children"))) {
+                        visit(childId);
+                    }
+                }
+                return out;
+            };
+            // Structured tree rather than flat-joined text so markdown-seeded notes
+            // round-trip with heading/paragraph/list structure intact.
+            const collectNoteChildren = (rootId) => {
+                const result = [];
+                const seen = new Set();
+                const visit = (id) => {
+                    if (seen.has(id))
+                        return null;
+                    seen.add(id);
+                    const b = blocks.get(id);
+                    if (!(b instanceof Y.Map))
+                        return null;
+                    const childFlavour = b.get("sys:flavour");
+                    if (typeof childFlavour !== "string")
+                        return null;
+                    const entry = { id, flavour: childFlavour };
+                    const t = asText(b.get("prop:text"));
+                    if (t)
+                        entry.text = t;
+                    const propType = b.get("prop:type");
+                    if (typeof propType === "string")
+                        entry.type = propType;
+                    const checked = b.get("prop:checked");
+                    if (typeof checked === "boolean")
+                        entry.checked = checked;
+                    const language = b.get("prop:language");
+                    if (typeof language === "string" && language.length > 0)
+                        entry.language = language;
+                    const subChildren = [];
+                    for (const childId of childIdsFrom(b.get("sys:children"))) {
+                        const c = visit(childId);
+                        if (c)
+                            subChildren.push(c);
+                    }
+                    if (subChildren.length)
+                        entry.children = subChildren;
+                    return entry;
+                };
+                const root = blocks.get(rootId);
+                if (root instanceof Y.Map) {
+                    for (const childId of childIdsFrom(root.get("sys:children"))) {
+                        const c = visit(childId);
+                        if (c)
+                            result.push(c);
+                    }
+                }
+                return result;
+            };
+            const edgelessBlocks = [];
+            for (const [id, raw] of blocks.entries()) {
+                if (!(raw instanceof Y.Map))
+                    continue;
+                const flavour = raw.get("sys:flavour");
+                if (typeof flavour !== "string" || !edgelessFlavours.has(flavour))
+                    continue;
+                const xywhRaw = raw.get("prop:xywh");
+                const bounds = parseXywhString(xywhRaw);
+                const propIndex = raw.get("prop:index");
+                const entry = {
+                    id: String(id),
+                    flavour,
+                    xywh: typeof xywhRaw === "string" ? xywhRaw : null,
+                    bounds,
+                    index: typeof propIndex === "string" ? propIndex : null,
+                };
+                if (flavour === "affine:frame") {
+                    entry.title = asText(raw.get("prop:title")) || null;
+                    const bg = raw.get("prop:background");
+                    entry.background = bg instanceof Y.Map ? bg.toJSON() : bg ?? null;
+                    const owned = raw.get("prop:childElementIds");
+                    entry.childElementIds = owned instanceof Y.Map ? Object.keys(owned.toJSON()) : [];
+                }
+                else if (flavour === "affine:edgeless-text") {
+                    const lines = collectNoteText(String(id));
+                    entry.text = lines.length ? lines.join("\n") : null;
+                    entry.color = raw.get("prop:color") ?? null;
+                }
+                else if (flavour === "affine:note") {
+                    const lines = collectNoteText(String(id));
+                    entry.text = lines.length ? lines.join("\n") : null;
+                    // `text` is the flat-join legacy view; `children` carries structure.
+                    entry.children = collectNoteChildren(String(id));
+                    entry.displayMode = raw.get("prop:displayMode") ?? null;
+                    const bg = raw.get("prop:background");
+                    entry.background = bg instanceof Y.Map ? bg.toJSON() : bg ?? null;
+                }
+                edgelessBlocks.push(entry);
+            }
+            const ctx = getSurfaceElementsValueMap(blocks, { create: false });
+            const surfaceElements = [];
+            const counts = {
+                shape: 0,
+                connector: 0,
+                text: 0,
+                group: 0,
+            };
+            if (ctx) {
+                for (const [elId, val] of ctx.value.entries()) {
+                    if (!(val instanceof Y.Map))
+                        continue;
+                    const serialized = serializeSurfaceElement(String(elId), val);
+                    surfaceElements.push(serialized);
+                    const t = serialized.type;
+                    if (t && t in counts)
+                        counts[t]++;
+                }
+            }
+            const sortedSurfaceElements = sortByFractionalIndex(surfaceElements);
+            let minX = Infinity;
+            let minY = Infinity;
+            let maxX = -Infinity;
+            let maxY = -Infinity;
+            let hasAny = false;
+            const include = (b) => {
+                if (!b)
+                    return;
+                hasAny = true;
+                minX = Math.min(minX, b.x);
+                minY = Math.min(minY, b.y);
+                maxX = Math.max(maxX, b.x + b.width);
+                maxY = Math.max(maxY, b.y + b.height);
+            };
+            const sortedEdgelessBlocks = sortByFractionalIndex(edgelessBlocks);
+            for (const eb of sortedEdgelessBlocks)
+                include(eb.bounds);
+            for (const se of sortedSurfaceElements)
+                include(se.bounds);
+            return text({
+                docId: params.docId,
+                exists: true,
+                surfaceBlockId: ctx?.surfaceId ?? null,
+                edgelessBlocks: sortedEdgelessBlocks,
+                surfaceElements: sortedSurfaceElements,
+                elementCounts: counts,
+                bounds: hasAny
+                    ? { minX, minY, maxX, maxY, width: maxX - minX, height: maxY - minY }
+                    : null,
+            });
+        }
+        finally {
+            socket.disconnect();
+        }
+    };
+    const surfaceElementFieldSchemas = {
+        x: z.number().optional().describe("X position on canvas (shape/text; default 0)."),
+        y: z.number().optional().describe("Y position on canvas (shape/text; default 0)."),
+        width: z.number().optional().describe("Width (shape default 100, text default 200)."),
+        height: z.number().optional().describe("Height (shape default 100, text default 30)."),
+        shapeType: z
+            .enum(["rect", "ellipse", "diamond", "triangle"])
+            .optional()
+            .describe("Shape type (default rect). Shape only."),
+        radius: z.number().optional().describe("Corner radius for rect (0.1 = rounded). Shape only."),
+        filled: z.boolean().optional().describe("Whether shape is filled (default true). Shape only."),
+        fillColor: z
+            .string()
+            .optional()
+            .describe("Fill color. Prefer the `--affine-palette-shape-<color>` family (yellow/orange/red/magenta/purple/navy/blue/green/teal/grey/white/black). These are fixed colors — AFFiNE shape colors are not theme-adaptive by design. Shape only."),
+        strokeColor: z.string().optional().describe("Stroke color. Prefer the `--affine-palette-line-<color>` family (same color names as fillColor). Fixed colors, not theme-adaptive. Shape only."),
+        strokeWidth: z.number().optional().describe("Stroke width (default 2). Shape/connector."),
+        strokeStyle: z
+            .enum(["solid", "dash", "none"])
+            .optional()
+            .describe("Stroke style. Shape/connector."),
+        text: z
+            .string()
+            .optional()
+            .describe("Text content (shape/text) or connector label. Replaces existing Y.Text on update."),
+        color: z.string().optional().describe("Text color. Shape default `#000000` — keep unless the fill is dark, then pass a contrasting hex. Canvas text default `--affine-text-primary-color` (theme-adaptive). Shape/text."),
+        fontSize: z
+            .number()
+            .optional()
+            .describe("Font size (shape default 20, text default 16). Shape/text."),
+        fontWeight: z
+            .string()
+            .optional()
+            .describe("Font weight (shape default 600, text default 400). Shape/text."),
+        sourceId: z.string().optional().describe("Connector source element id. Connector only."),
+        targetId: z.string().optional().describe("Connector target element id. Connector only."),
+        sourcePosition: z
+            .array(z.number())
+            .length(2)
+            .optional()
+            .describe("Source [x,y]: relative [0-1] if sourceId set, absolute otherwise. Connector only."),
+        targetPosition: z
+            .array(z.number())
+            .length(2)
+            .optional()
+            .describe("Target [x,y]: relative [0-1] if targetId set, absolute otherwise. Connector only. When both source/target are bound by id and neither position is provided, endpoints snap to the BlockSuite side-midpoint facing the other endpoint so connectors flow in a clear direction. Pass [0.5,0] top, [0.5,1] bottom, [0,0.5] left, [1,0.5] right to force a specific side."),
+        mode: z
+            .number()
+            .optional()
+            .describe("Connector mode: 0=straight, 1=orthogonal (elbow), 2=curve (default 2). Connector only."),
+        frontEndpointStyle: z
+            .enum(["None", "Arrow", "Triangle", "Circle", "Diamond"])
+            .optional()
+            .describe("Front endpoint style (default None). Connector only."),
+        rearEndpointStyle: z
+            .enum(["None", "Arrow", "Triangle", "Circle", "Diamond"])
+            .optional()
+            .describe("Rear endpoint style (default Arrow). Connector only."),
+        stroke: z.string().optional().describe("Connector stroke color (default '--affine-text-primary-color' — theme-adaptive, near-black in light / near-white in dark). Accepts any CSS color or AFFiNE palette token. Connector only."),
+        label: z.string().optional().describe("Connector label (stored as text on the connector). Connector only."),
+        children: z.array(z.string()).optional().describe("Child element ids. Group only."),
+        title: z.string().optional().describe("Group title. Group only."),
+        index: z
+            .string()
+            .optional()
+            .describe("BlockSuite fractional-index string controlling z-order. On add, defaults to a key above every existing element's index (new elements render on top). On update, replaces the stored value — pass a key less than some existing index to send-to-back, or greater to bring-to-front. Use the value returned by list_surface_elements to pick a specific position."),
+    };
+    server.registerTool("add_surface_element", {
+        title: "Add Surface Element",
+        description: "Add a shape, connector, text, or group to the AFFiNE edgeless canvas surface. Shapes support rect/ellipse/diamond/triangle with fill, stroke, and text. Connectors draw arrows between shapes (by id) or between absolute points. Use for building diagrams programmatically. Style fields that don't apply to the chosen element type are reported in the response 'ignored' list (mirrors update_surface_element).",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            type: z.enum(["shape", "connector", "text", "group"]).describe("Element type"),
+            ...surfaceElementFieldSchemas,
+        },
+    }, addSurfaceElementHandler);
+    server.registerTool("list_surface_elements", {
+        title: "List Surface Elements",
+        description: "List all shape/connector/text/group elements on the AFFiNE edgeless canvas surface. Returns raw xywh strings plus parsed {x,y,width,height} bounds, with Y.Text fields serialized to plain strings. Optional filters by element type or id.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            type: z
+                .enum(["shape", "connector", "text", "group"])
+                .optional()
+                .describe("Filter by element type"),
+            elementId: z.string().optional().describe("Filter to a single element id"),
+        },
+    }, listSurfaceElementsHandler);
+    server.registerTool("update_surface_element", {
+        title: "Update Surface Element",
+        description: "Partially update a surface element by id. x/y/width/height merge with the element's current xywh (move without resizing, or vice versa). text/label/title replace their Y.Text wholesale. Fields that don't apply to the element's type are reported in the response 'ignored' list.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            elementId: z.string().min(1).describe("Element ID to update"),
+            ...surfaceElementFieldSchemas,
+        },
+    }, updateSurfaceElementHandler);
+    server.registerTool("delete_surface_element", {
+        title: "Delete Surface Element",
+        description: "Delete a surface element by id. Set pruneConnectors=true to also delete any connectors whose source or target referenced the deleted element.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            elementId: z.string().min(1).describe("Element ID to delete"),
+            pruneConnectors: z
+                .boolean()
+                .optional()
+                .describe("Also delete connectors referencing this element (default false)"),
+        },
+    }, deleteSurfaceElementHandler);
+    server.registerTool("update_frame_children", {
+        title: "Update Frame Children",
+        description: "Replace a frame block's contents wholesale. Accepts ids of surface elements (shapes/connectors/groups) AND edgeless blocks (notes/frames/edgeless-text) — all go into BlockSuite's prop:childElementIds map, matching what the editor writes when you drag members into a frame. Dragging the frame drags every owned member. Ids that don't resolve come back under 'missing'. By default the frame is resized to fit its new contents (plus padding + title band); set resizeToFit=false to leave xywh untouched. Pass `[]` to clear ownership (resize is skipped in that case).",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            blockId: z.string().min(1).describe("Frame block id (flavour affine:frame)."),
+            childElementIds: z
+                .array(z.string())
+                .describe("Full list of ids the frame should own/contain. Replaces any existing ownership."),
+            resizeToFit: z
+                .boolean()
+                .optional()
+                .describe("If true (default), recompute xywh from the union of resolvable child bounds + padding + title band. Set to false to preserve the frame's current box (useful when you want ownership-only edits or manual positioning)."),
+            padding: z
+                .number()
+                .int()
+                .optional()
+                .describe("Padding (px) used when resizeToFit is true (default 40). Ignored when resizeToFit=false."),
+        },
+    }, updateFrameChildrenHandler);
+    server.registerTool("update_edgeless_block", {
+        title: "Update Edgeless Block",
+        description: "Partially update a note/frame/edgeless-text block by id. x/y/width/height merge with current prop:xywh (move without resizing, or vice versa). background replaces prop:background (AFFiNE token or `{light, dark}` hex object). Fields that don't apply to the block's flavour come back under `ignored`.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            blockId: z.string().min(1).describe("Block id (flavour affine:note/affine:frame/affine:edgeless-text)."),
+            x: z.number().optional(),
+            y: z.number().optional(),
+            width: z.number().optional(),
+            height: z.number().optional(),
+            background: z
+                .union([
+                z.string(),
+                z.object({ light: z.string().optional(), dark: z.string().optional() }),
+            ])
+                .optional()
+                .describe("Note/frame only. Prefer `--affine-note-background-<color>` or `{light, dark}` hex."),
+        },
+    }, updateEdgelessBlockHandler);
+    server.registerTool("delete_block", {
+        title: "Delete Block",
+        description: "Delete a block by id. Removes descendants and unlinks from the parent's sys:children by default; set deleteChildren=false to keep descendants orphaned (for re-parenting), or pruneConnectors=true to also drop surface connectors referencing any deleted id. Refuses affine:page — use delete_doc for whole docs.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+            blockId: z.string().min(1).describe("Block id to delete."),
+            deleteChildren: z.boolean().optional().describe("Also delete descendants (default true)."),
+            pruneConnectors: z.boolean().optional().describe("Also delete connectors bound to any deleted id (default false)."),
+        },
+    }, deleteBlockHandler);
+    server.registerTool("get_edgeless_canvas", {
+        title: "Get Edgeless Canvas",
+        description: "Read the full edgeless canvas: all edgeless-positioned blocks (notes, frames, edgeless-text) with their xywh, plus all surface elements (shapes, connectors, text, groups). Includes aggregate bounding box and per-type element counts. Use this when you need to understand canvas layout end-to-end before placing new elements.",
+        inputSchema: {
+            workspaceId: z.string().optional().describe("Workspace ID (optional if default set)"),
+            docId: DocId.describe("Document ID"),
+        },
+    }, getEdgelessCanvasHandler);
 }