drafted 1.14.13 → 1.14.14

package/mcp/server.mjs

@@ -1460,11 +1460,12 @@ async function requireBoundOrgForProjectlessMutation(explicitOrg) {
       `Which org? A project-less wiki/skill write needs one, and you belong to ${orgs.length}: ` +
       `${names.join(', ')}. Don't guess — an unaddressed write lands in whichever org this ` +
       `session inherited, which is how a page meant for one org ends up in another.\n` +
-      `Recover in ONE call:\n` +
-      `  • get_org(action="use", org="<name>") — binds this session's working org; every ` +
-      `later project-less wiki/skill write then just works, no project needed.\n` +
-      `  • or pass org="<name>" on this single call.\n` +
-      `  • or project(action="open") if the work belongs to a project — the org derives from it.\n` +
+      `Recover with ONE call: get_org(action="use", org="<name>"). That binds this session's ` +
+      `working org — every later project-less wiki/skill write then just works, with no project ` +
+      `and no org= to repeat. Prefer it over passing org= per call, which pays this toll on ` +
+      `every write.\n` +
+      `(Alternatives: org="<name>" on this single call; or project(action="open") if the work ` +
+      `belongs to a project — the org derives from it.)\n` +
       `Pick from the conversation if the org is clear from context; ask the user only if it isn't.`
     );
   }
@@ -1863,6 +1864,12 @@ async function sessionSurfaceBlock() {
       color: agentSurface.color,
       surfaced: true,
       alive: !!agentSurface.alive,
+      // `alive` was ambiguous: agents couldn't tell whether it meant "your writes are
+      // no-ops" (act differently) or "the user's canvas tab is closed" (ignore). It's the
+      // latter — say so, so nobody changes behavior over it.
+      aliveMeaning: agentSurface.alive
+        ? 'A canvas/desktop surface is live for this session — focus and presence calls will be seen.'
+        : 'No canvas surface is currently open for this session. Frame, wiki, and skill writes all persist normally — only focus/presence have nothing to draw on. Do not change what you write because of this.',
     };
   }
   // No WS ack yet — best-effort identity from /auth/me so callers still get a userId/org.
@@ -2671,7 +2678,7 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
   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.'),
+  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.'),
   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.'),
@@ -3178,8 +3185,9 @@ tool('ls', 'List contents of the ACTIVE PROJECT. Use ls / after project(action="
   recursive: z.boolean().optional().describe('List contents of subdirectories. When true, forces summary mode (metadata only, no full content) to keep results under the 25k token cap.'),
   summary: z.boolean().optional().describe('Include size, updatedAt, title for frames'),
   pattern: z.string().optional().describe('Glob pattern to filter filenames (e.g. "*.html")'),
+  head: z.number().optional().describe('Include the first N lines of EACH frame inline (max 50). Survey a whole lane in one call instead of one frame(action="read") per frame — read only the frames the heads show you actually need.'),
   limit: z.number().optional().default(500).describe('Max entries to return (default 500, max 2000). Use pattern or path to scope further.'),
-}, async ({ path, recursive, summary, pattern, limit }) => {
+}, async ({ path, recursive, summary, pattern, head, limit }) => {
   try {
     const params = new URLSearchParams();
     params.set('path', path);
@@ -3194,6 +3202,7 @@ tool('ls', 'List contents of the ACTIVE PROJECT. Use ls / after project(action="
     } else if (summary) {
       params.set('summary', 'true');
     }
+    if (head) params.set('head', String(head));
     if (pattern) params.set('pattern', pattern);
     const result = await api('GET', `/api/fs/?${params.toString()}`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.14.13",
+  "version": "1.14.14",
   "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": [