drafted 1.14.25 → 1.14.27

package/mcp/server.mjs

@@ -140,7 +140,7 @@ const LOCAL_ONLY_PARAMS = ['file_path'];
 // tool wrapper before the handler runs — so the stdio contract, the Zod runtime
 // validation, and every handler stay byte-for-byte unchanged.
 const REMOTE_JSON_STRING_PARAMS = {
-  frame: ['excalidraw_data', 'requests', 'state'],
+  frame: ['excalidraw_data', 'elements', 'requests', 'state'],
   wiki: ['frontmatter', 'pages'],
   project: ['layers'],
   template: ['layers'],
@@ -1131,6 +1131,39 @@ function shapeSkillCatalog(result, { limit, offset = 0, compact = false } = {})
   return result;
 }
 
+// Shape the template `list` array (a bare array from /api/templates) so it stays
+// within an agent's token budget: full layer bodies (prose descriptions across
+// every built-in + org + public template) blow past 90KB. compact (default)
+// returns identity + a layerCount; compact=false returns full bodies, paged.
+function compactTemplateEntry(t) {
+  if (!t || typeof t !== 'object') return t;
+  return {
+    id: t.id,
+    slug: t.slug,
+    name: t.name,
+    description: t.description,
+    layerCount: Array.isArray(t.layers) ? t.layers.length : undefined,
+    skillSlugs: t.skillSlugs,
+  };
+}
+function shapeTemplateCatalog(tpls, { limit, offset = 0, compact = true } = {}) {
+  if (!Array.isArray(tpls)) return tpls;
+  const total = tpls.length;
+  const start = Math.max(0, Math.floor(Number(offset) || 0));
+  const cap = Math.min(Math.max(1, Math.floor(Number(limit) || 25)), 100);
+  const page = tpls.slice(start, start + cap);
+  return {
+    templates: page.map(compact ? compactTemplateEntry : (t) => t),
+    totalAvailable: total,
+    offset: start,
+    returned: page.length,
+    truncated: start + page.length < total,
+    note: compact
+      ? 'Compact catalog: {id,slug,name,description,layerCount,skillSlugs}. Pass compact=false for full layer definitions; use limit/offset to page.'
+      : 'Full template bodies. Use limit/offset to page; pass compact=true for a leaner catalog.',
+  };
+}
+
 // Semantic frame URL (/o/<org>/<project>/<layer>/<lane>/<label>) from a row that
 // carries slugs (e.g. /api/search hits). Returns null when a slug is missing so the
 // caller can fall back to the /f/<uuid> resolver.
@@ -2202,6 +2235,9 @@ tool('template', 'Manage project templates in an org. Dispatch by `action`: list
   layers: z.array(z.object({}).passthrough()).optional().describe('[create|update] array of layer definitions'),
   skillSlugs: z.array(z.string()).optional().describe('[create|update] skill slugs to auto-attach to projects created from this template. Slugs are resolved against the org\'s skills (org-local first, built-in fallback) at project-create time; missing slugs are silently skipped. Pass an empty array on update to clear.'),
   visibility: z.string().optional().describe('[create|update] "org" or "public"'),
+  compact: z.boolean().optional().describe('[list] default true — return {id,slug,name,description,layerCount,skillSlugs} only. Pass false for full layer definitions.'),
+  limit: z.number().optional().describe('[list] max templates to return (default 25, max 100).'),
+  offset: z.number().optional().describe('[list] pagination offset.'),
   org: z.string().optional().describe('Org (id or name) to scope this call to — defaults to the open project\'s org. Per-request only.'),
 }, async (args) => {
   try {
@@ -2211,7 +2247,7 @@ tool('template', 'Manage project templates in an org. Dispatch by `action`: list
       case 'list': {
         const tpls = await api('GET', '/api/templates', undefined, orgHeader);
         markSearched(getSessionState().gates, 'template');
-        return ok(tpls);
+        return ok(shapeTemplateCatalog(tpls, { limit: args.limit, offset: args.offset, compact: args.compact !== false }));
       }
       case 'create': {
         const { name, description, layers, skillSlugs, visibility } = args;
@@ -2766,13 +2802,16 @@ tool('get_org', {
 
 // ── Filesystem tools (direct HTTP to /api/fs) ─────────────────────
 
-tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by path, frame URL, or UUID), write (new frame or overwrite), set_state / get_state (persist or read a deployed windowType:"app" frame\'s hydration state — push e.g. {specText} to drive a generic app frame with data after deploy; the canvas hydrates the app from it on load), Google Sheet actions (`get_sheet`, `read_sheet_values`, `write_sheet_values`, `append_sheet_rows`, `clear_sheet_range`, `update_sheet`), Google Doc actions (`get_doc`, `read_doc_content`, `write_doc_content`, `append_doc_content`, `clear_doc_content`, `update_doc`), Google Slide actions (`get_slide`, `read_slide_content`, `write_slide_content`, `append_slides`, `clear_slides`, `update_slide`), write_excalidraw (native editable Excalidraw diagram), edit (hashline ops), mv (rename/move), anchor (mark as required-read for the layer), search (match frame names). Use project(action="open") first. For listing use `ls`, for deletion use `rm`.\n\n**Google Workspace native content:** Create or attach Google Docs/Sheets/Slides with `frame(action="write", googleType=...)`. After creating, immediately populate the native file using the matching write action in the same tool — do NOT leave it empty and do NOT tell the user you cannot write to it. For Sheets: `write_sheet_values` or `append_sheet_rows` (pass `path` or `googleId` from the create response). For Docs: `write_doc_content`/`append_doc_content`. For Slides: `write_slide_content`/`append_slides`. Read with `read_sheet_values`/`read_doc_content`/`read_slide_content`. Do NOT use inline `frame.write(content)` or hashline `frame.edit` to populate Google Workspace frames.\n\n**Write — content, binary, or Google Workspace frame:** ' + (isRemote ? 'Provide exactly one of `content` (HTML/markdown/text), `base64` (base64-encoded binary with optional `content_type`), or `googleType` (`google-doc`, `google-sheet`, `google-slide`).' : 'Provide exactly one of `content` (HTML/markdown/text), `file_path` (absolute local file), `base64` (base64-encoded binary with optional `content_type`), or `googleType` (`google-doc`, `google-sheet`, `google-slide`).') + ' Call get_org first; when `googleDrive.connected` is true, strongly prefer Google Workspace frames for docs, sheets, and slides in that org. For inline content, filename extension matters: use `.html` for complete HTML documents and `.md` for Markdown. Never place a full HTML document in a `.md` or extensionless frame. For a new Google file, pass `googleType` and optional `title`; for an existing Google file, pass `googleType` plus `url` or `googleId`. ' + (isRemote ? 'For binary frames (images, PDFs, videos), pass `base64` with the binary bytes.' : 'For binary frames (images, PDFs, videos), use `file_path` when the file is local to the MCP host, or `base64` when the caller already has binary bytes.') + '\n\n**Write — dimensions:** By default, frames use the layer\'s default size (e.g. 1440×900 for designs, 1440×3000 for wireframes). Often too large for small content. Use `autoSize: true` to measure HTML content and size to fit, or pass explicit `width`/`height`.', {
+tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by path, frame URL, or UUID), write (new frame or overwrite), set_state / get_state (persist or read a deployed windowType:"app" frame\'s hydration state — push e.g. {specText} to drive a generic app frame with data after deploy; the canvas hydrates the app from it on load), Google Sheet actions (`get_sheet`, `read_sheet_values`, `write_sheet_values`, `append_sheet_rows`, `clear_sheet_range`, `update_sheet`), Google Doc actions (`get_doc`, `read_doc_content`, `write_doc_content`, `append_doc_content`, `clear_doc_content`, `update_doc`), Google Slide actions (`get_slide`, `read_slide_content`, `write_slide_content`, `append_slides`, `clear_slides`, `update_slide`), write_excalidraw (native editable Excalidraw diagram — full-scene replace), edit_excalidraw (element-level upsert/remove by id, for growing or surgically editing a large scene without resending it), edit (hashline ops), mv (rename/move), anchor (mark as required-read for the layer), search (match frame names). Use project(action="open") first. For listing use `ls`, for deletion use `rm`.\n\n**Google Workspace native content:** Create or attach Google Docs/Sheets/Slides with `frame(action="write", googleType=...)`. After creating, immediately populate the native file using the matching write action in the same tool — do NOT leave it empty and do NOT tell the user you cannot write to it. For Sheets: `write_sheet_values` or `append_sheet_rows` (pass `path` or `googleId` from the create response). For Docs: `write_doc_content`/`append_doc_content`. For Slides: `write_slide_content`/`append_slides`. Read with `read_sheet_values`/`read_doc_content`/`read_slide_content`. Do NOT use inline `frame.write(content)` or hashline `frame.edit` to populate Google Workspace frames.\n\n**Write — content, binary, or Google Workspace frame:** ' + (isRemote ? 'Provide exactly one of `content` (HTML/markdown/text), `base64` (base64-encoded binary with optional `content_type`), or `googleType` (`google-doc`, `google-sheet`, `google-slide`).' : 'Provide exactly one of `content` (HTML/markdown/text), `file_path` (absolute local file), `base64` (base64-encoded binary with optional `content_type`), or `googleType` (`google-doc`, `google-sheet`, `google-slide`).') + ' Call get_org first; when `googleDrive.connected` is true, strongly prefer Google Workspace frames for docs, sheets, and slides in that org. For inline content, filename extension matters: use `.html` for complete HTML documents and `.md` for Markdown. Never place a full HTML document in a `.md` or extensionless frame. For a new Google file, pass `googleType` and optional `title`; for an existing Google file, pass `googleType` plus `url` or `googleId`. ' + (isRemote ? 'For binary frames (images, PDFs, videos), pass `base64` with the binary bytes.' : 'For binary frames (images, PDFs, videos), use `file_path` when the file is local to the MCP host, or `base64` when the caller already has binary bytes.') + '\n\n**Write — dimensions:** By default, frames use the layer\'s default size (e.g. 1440×900 for designs, 1440×3000 for wireframes). Often too large for small content. Use `autoSize: true` to measure HTML content and size to fit, or pass explicit `width`/`height`.', {
   projectId: PROJECT_OVERRIDE_PARAM,
-  action: z.enum(['read', 'write', 'set_state', 'get_state', 'write_sheet_values', 'read_sheet_values', 'append_sheet_rows', 'clear_sheet_range', 'get_sheet', 'update_sheet', 'get_doc', 'read_doc_content', 'write_doc_content', 'append_doc_content', 'clear_doc_content', 'update_doc', 'get_slide', 'read_slide_content', 'write_slide_content', 'append_slides', 'clear_slides', 'update_slide', 'create_office', 'read_office', 'edit_office', 'write_excalidraw', 'edit', 'mv', 'anchor', 'search', 'versions', 'read_version', 'restore_version']).describe('Operation to perform. Use native Doc/Slide actions for Google Docs/Slides; do not use inline write/edit for native Workspace content.'),
+  action: z.enum(['read', 'write', 'set_state', 'get_state', 'write_sheet_values', 'read_sheet_values', 'append_sheet_rows', 'clear_sheet_range', 'get_sheet', 'update_sheet', 'get_doc', 'read_doc_content', 'write_doc_content', 'append_doc_content', 'clear_doc_content', 'update_doc', 'get_slide', 'read_slide_content', 'write_slide_content', 'append_slides', 'clear_slides', 'update_slide', 'create_office', 'read_office', 'edit_office', 'write_excalidraw', 'edit_excalidraw', 'edit', 'mv', 'anchor', 'search', 'versions', 'read_version', 'restore_version']).describe('Operation to perform. Use native Doc/Slide actions for Google Docs/Slides; do not use inline write/edit for native Workspace content.'),
   path: z.string().optional().describe('[read] /{layer}/{lane}/{filename}, frame URL, or UUID. [write|edit|anchor] /{layer}/{lane}/{filename}.'),
   lines: z.string().optional().describe('[read] line range (e.g. "1-50"). Omit to read all.'),
   content: z.string().optional().describe('[write] HTML/markdown/text for Drafted inline frames. [write_doc_content|append_doc_content] native Google Doc body text. Do not use action=write content to populate Google Doc/Slide frames.'),
-  excalidraw_data: z.any().optional().describe('[write_excalidraw] Excalidraw scene JSON object or JSON string. Defaults to an empty scene. WRITE LEAN SCENES: your MCP client caps tool-call arguments (a big scene is rejected before Drafted ever sees it), so emit only the fields that carry meaning — id, type, x, y, width, height, angle, text/label, strokeColor, backgroundColor, fillStyle, strokeWidth, and the binding ids for arrows. Omit every field the editor can default (version, versionNonce, seed, updated, groupIds, boundElements when empty, roundness, opacity at 100, frameId when null). The editor fills them on open; shipping them can triple the payload for no gain. For a big diagram, write it in passes: create the scene, then frame(action="write_excalidraw") again with the next batch of elements.'),
+  excalidraw_data: z.any().optional().describe('[write_excalidraw] Excalidraw scene JSON object or JSON string. Defaults to an empty scene. EVERY write_excalidraw REPLACES THE WHOLE SCENE — it does not merge; to grow a diagram, either resend all prior elements plus the new ones, or use action="edit_excalidraw" (element-level upsert/remove by id) which needs only the changed elements. WRITE LEAN SCENES: your MCP client caps tool-call arguments (a big scene is rejected before Drafted ever sees it — once a scene exceeds that cap, edit it with edit_excalidraw, not write_excalidraw), so emit only the fields that carry meaning — id, type, x, y, width, height, angle, text/label, strokeColor, backgroundColor, fillStyle, strokeWidth, and the binding ids for arrows. Omit every field the editor can default (version, versionNonce, seed, updated, groupIds, boundElements when empty, roundness, opacity at 100, frameId when null). The editor fills them on open; shipping them can triple the payload for no gain.'),
+  elements: z.array(z.any()).optional().describe('[edit_excalidraw] Excalidraw elements to upsert by id: an element whose id already exists is shallow-merged (a partial {id,x,y} moves it, keeping its other props); a new id is appended. Send only the changed elements — the rest of the scene is preserved. Same lean-fields guidance as excalidraw_data.'),
+  remove: z.array(z.string()).optional().describe('[edit_excalidraw] Element ids to delete from the scene.'),
+  raw: z.boolean().optional().describe('[read] return the frame content as stored bytes (no NNNhash| line-number prefixes) — use when you need to parse the content as JSON (e.g. an Excalidraw scene). Note: edit ops require the hashline anchors, so omit raw when you intend to edit.'),
   state: z.any().optional().describe('[set_state] App-frame state object (JSON) to persist for a deployed windowType:"app" frame — e.g. {specText:"..."} for the AS/NZS electrical app. The canvas hydrates the app from this on load (the host posts a "hydrate" message with it when the frame mounts), so you can deploy a generic app frame once and drive it with data afterwards. Max 64KB. Frame must be an app frame.'),
   file_path: z.string().optional().describe('[write] absolute path to a local file to upload. Mutually exclusive with content/base64/googleType.'),
   base64: z.string().optional().describe('[write] base64-encoded binary content. Mutually exclusive with content/file_path/googleType. Use with content_type when known.'),
@@ -2909,9 +2948,12 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
     };
     switch (action) {
       case 'read': {
-        const { path, lines } = args;
+        const { path, lines, raw } = args;
         if (!path) throw new Error('path required for action=read');
-        const query = lines ? `?lines=${encodeURIComponent(lines)}` : '';
+        const qs = [];
+        if (lines) qs.push(`lines=${encodeURIComponent(lines)}`);
+        if (raw) qs.push('raw=1');
+        const query = qs.length ? `?${qs.join('&')}` : '';
         const frameUrlMatch = path.match(/\/f\/([a-f0-9-]{36})/);
         const uuidMatch = path.match(/^[a-f0-9-]{36}$/);
         const frameId = frameUrlMatch?.[1] || (uuidMatch ? path : null);
@@ -2920,8 +2962,10 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
           result = await api('GET', `/api/fs/by-id/${frameId}${query}`);
         } else {
           const parts = path.replace(/^\/+/, '').split('/');
-          if (parts.length !== 3) throw new Error('Path must be /{layer}/{lane}/{filename}, a frame URL, or a frame ID');
-          result = await api('GET', `/api/fs/${parts[0]}/${parts[1]}/${parts[2]}${query}`);
+          // 2 segments = a layer-root frame (empty lane, e.g. /designs/AGENTS.md);
+          // 3 = /{layer}/{lane}/{filename}. Both resolve server-side.
+          if (parts.length !== 2 && parts.length !== 3) throw new Error('Path must be /{layer}/{filename}, /{layer}/{lane}/{filename}, a frame URL, or a frame ID');
+          result = await api('GET', `/api/fs/${parts.map(encodeURIComponent).join('/')}${query}`);
         }
         // Surface content as the visible text. Some Claude clients prefer
         // structuredContent over text when both are present and structured looks
@@ -3180,6 +3224,20 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
           _meta: { frameHtml: body.content },
         });
       }
+      case 'edit_excalidraw': {
+        const { path, elements, remove } = args;
+        if (!path) throw new Error('path required for action=edit_excalidraw');
+        const parts = path.replace(/^\/+/, '').split('/');
+        if (parts.length !== 3) throw new Error('Path must be /{layer}/{lane}/{filename}');
+        const filename = parts[2].toLowerCase().endsWith('.excalidraw') ? parts[2] : parts[2] + '.excalidraw';
+        if (!Array.isArray(elements) && !Array.isArray(remove)) {
+          throw new Error('Provide elements[] to add/update and/or remove[] element ids');
+        }
+        const result = await api('POST', '/api/fs/edit-excalidraw', { path: `/${parts[0]}/${parts[1]}/${filename}`, elements, remove });
+        return ok(withProject(withFrameBreadcrumb(result, { hint: true })), {
+          structuredContent: frameStructuredContent(result, projectCtx),
+        });
+      }
       case 'edit': {
         const { path, operations } = args;
         if (!path) throw new Error('path required for action=edit');
@@ -4382,23 +4440,6 @@ tool('wiki', 'Per-org wiki. Markdown pages with paths as hierarchy. You and othe
       // Hashlines come from `read` (which now formats content as
       // `LINE+ID|content`). The server applies the ops via the same
       // hashline algorithm — no client-side re-hashing, no algorithm drift.
-      case 'write_excalidraw': {
-        const { path, excalidraw_data, width, height, color } = args;
-        if (!path) throw new Error('path required for action=write_excalidraw');
-        const parts = path.replace(/^\/+/, '').split('/');
-        if (parts.length !== 3) throw new Error('Path must be /{layer}/{lane}/{filename}');
-        const filename = parts[2].toLowerCase().endsWith('.excalidraw') ? parts[2] : parts[2] + '.excalidraw';
-        const scene = excalidraw_data ?? emptyExcalidrawScene();
-        const body = { content: stringifyExcalidrawScene(scene) };
-        if (width) body.width = width;
-        if (height) body.height = height;
-        if (color) body.color = color;
-        const result = await api('PUT', `/api/fs/${parts[0]}/${parts[1]}/${filename}`, body);
-        return ok(withProject(withFrameBreadcrumb(result, { hint: true })), {
-          structuredContent: frameStructuredContent(result, projectCtx),
-          _meta: { frameHtml: body.content },
-        });
-      }
       case 'edit': {
         const { path: editPath, pageId: editPageId, operations: editOps } = args;
         if (!Array.isArray(editOps) || editOps.length === 0) throw new Error('operations (array) required for action=edit');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.14.25",
+  "version": "1.14.27",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "files": [

package/src/shared/excalidraw.mjs

@@ -38,3 +38,28 @@ export function normalizeExcalidrawScene(input) {
 export function stringifyExcalidrawScene(input) {
   return JSON.stringify(normalizeExcalidrawScene(input), null, 2);
 }
+
+// Element-level merge for surgical edits: upsert `upserts` into the stored scene
+// by element id (shallow-merge onto an existing element so a partial {id,x,y}
+// moves it without dropping its other props), and drop every id in `removeIds`.
+// Existing element order is preserved (z-order = array order); updated elements
+// keep their position, new ones append. This is the accumulate/merge path that
+// write_excalidraw (full replace) is not — it lets a large scene be edited with
+// a small payload instead of resending the whole thing.
+export function mergeExcalidrawElements(existing, upserts = [], removeIds = []) {
+  const scene = normalizeExcalidrawScene(existing);
+  const removeSet = new Set(Array.isArray(removeIds) ? removeIds : []);
+  const byId = new Map();
+  for (const el of scene.elements) {
+    if (!el || removeSet.has(el.id)) continue;
+    byId.set(el.id, el);
+  }
+  for (const el of (Array.isArray(upserts) ? upserts : [])) {
+    if (!el || typeof el !== 'object' || Array.isArray(el) || !el.id) {
+      throw new Error('Each element to upsert must be an object with an id');
+    }
+    if (removeSet.has(el.id)) continue;
+    byId.set(el.id, byId.has(el.id) ? { ...byId.get(el.id), ...el } : el);
+  }
+  return { ...scene, elements: Array.from(byId.values()) };
+}

package/src/shared/test-excalidraw-merge.mjs

@@ -0,0 +1,40 @@
+// Runnable self-check for mergeExcalidrawElements. No framework: `node src/shared/test-excalidraw-merge.mjs`.
+import assert from 'node:assert';
+import { mergeExcalidrawElements } from './excalidraw.mjs';
+
+const base = {
+  type: 'excalidraw', version: 2, source: 'x',
+  elements: [
+    { id: 'a', type: 'rectangle', x: 0, y: 0, strokeColor: '#000' },
+    { id: 'b', type: 'text', x: 10, y: 10, text: 'hi' },
+    { id: 'c', type: 'ellipse', x: 20, y: 20 },
+  ],
+  appState: {}, files: {},
+};
+
+// update (partial, shallow-merge keeps other props) + keeps position
+let r = mergeExcalidrawElements(base, [{ id: 'b', x: 99 }]);
+assert.deepStrictEqual(r.elements.map(e => e.id), ['a', 'b', 'c'], 'order preserved on update');
+assert.strictEqual(r.elements[1].x, 99, 'x updated');
+assert.strictEqual(r.elements[1].text, 'hi', 'other props preserved on partial update');
+
+// add appends
+r = mergeExcalidrawElements(base, [{ id: 'd', type: 'diamond', x: 5 }]);
+assert.deepStrictEqual(r.elements.map(e => e.id), ['a', 'b', 'c', 'd'], 'new element appended');
+
+// remove drops by id
+r = mergeExcalidrawElements(base, [], ['a', 'c']);
+assert.deepStrictEqual(r.elements.map(e => e.id), ['b'], 'ids removed');
+
+// remove wins over upsert of the same id
+r = mergeExcalidrawElements(base, [{ id: 'a', x: 1 }], ['a']);
+assert.deepStrictEqual(r.elements.map(e => e.id), ['b', 'c'], 'remove beats upsert');
+
+// accepts a JSON string as stored content (frame.content is a string)
+r = mergeExcalidrawElements(JSON.stringify(base), [{ id: 'e', type: 'text', x: 0 }]);
+assert.strictEqual(r.elements.length, 4, 'parses stored string content');
+
+// upsert without id is rejected
+assert.throws(() => mergeExcalidrawElements(base, [{ x: 1 }]), /must be an object with an id/);
+
+console.log('ok: mergeExcalidrawElements');