drafted 1.17.12 → 1.17.13

package/mcp/server.mjs

@@ -309,6 +309,7 @@ const TOOL_ANNOTATIONS = {
 
   // Canvas / view
   focus:               { title: 'Focus on target',     readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Pan the canvas viewport for connected clients to a frame, lane, or layer.' },
+  tour:                { title: 'Guided tours',        readOnlyHint: false, destructiveHint: false, openWorldHint: false, description: 'Play or stop an agent-authored guided tour (driver.js) on the project surface for all connected clients. Tours live on a frame\'s metadata.tour — author them with fs(write, metadata={tour: {title, steps}}). Dispatch by `action`: play (frameId) starts the walkthrough, stop (projectId) ends it. Use for presentations and collaborative walkthroughs.' },
   screenshot:          { title: 'Screenshot',          readOnlyHint: true,  destructiveHint: false, openWorldHint: false, description: 'Render a PNG via headless browser. `scope=frame` for a single frame, `scope=canvas` for a region of the project surface.' },
 
   // Minions — checklist-driven intake surfaces bound to a project
@@ -418,7 +419,7 @@ function tool(name, descOrSchema, schemaOrHandler, handler) {
           const v = args[0][k];
           if (typeof v === 'string' && v.trim()) {
             try { args[0][k] = JSON.parse(v); }
-            catch { return err(new Error(`Param "${k}" must be a JSON-encoded ${['excalidraw_data', 'frontmatter', 'target', 'output', 'state'].includes(k) ? 'object' : 'array'} string; JSON.parse failed.`)); }
+            catch { return err(new Error(`Param "${k}" must be a JSON-encoded ${['excalidraw_data', 'frontmatter', 'target', 'output', 'state', 'metadata'].includes(k) ? 'object' : 'array'} string; JSON.parse failed.`)); }
           }
         }
       }
@@ -2299,6 +2300,27 @@ tool('trigger', {
   } catch (error) { return err(error); }
 });
 
+tool('tour', {
+  action: z.enum(['play', 'stop']).describe('play: start a guided tour on the project surface for all connected clients. stop: end the currently playing tour.'),
+  frameId: z.string().optional().describe('[play] Tour frame: a frame path (/projects/<project>/<layer>/<lane>/<file>), frame URL, or frame UUID. The frame must carry metadata.tour (steps: [{target, title?, body?, side?, advanceOnClick?}]).'),
+  projectId: z.string().optional().describe('[stop] Project UUID or slug owning the tour.'),
+}, async ({ action, frameId, projectId }) => {
+  try {
+    if (action === 'play') {
+      if (!frameId) throw new Error('frameId is required for tour play');
+      const { frameId: fid } = await resolveFsFramePath(frameId);
+      const result = await api('POST', '/api/tour/play', { frameId: fid });
+      return ok(result);
+    }
+    if (action === 'stop') {
+      if (!projectId) throw new Error('projectId is required for tour stop');
+      const result = await api('POST', '/api/tour/stop', { projectId });
+      return ok(result);
+    }
+    throw new Error(`Unknown tour action: ${action}`);
+  } catch (error) { return err(error); }
+});
+
 tool('focus', {
   target: z.string().describe('What to pan the canvas to: a frame path (/projects/<project>/<layer>/<lane>/<file>), a frame URL (any URL containing /f/{uuid} or /o/<org>/projects/...), or a frame ID (UUID). When a user shares a Drafted link, pass it directly here.'),
 }, async ({ target }) => {
@@ -2565,7 +2587,7 @@ server.resource('info', 'drafted://info', {
           skills: '/o/<org>/skills/<slug>',
           projects: '/o/<org>/projects/<folder?>/<project>/<layer>/<lane>/<file>',
         },
-        tools: ['fs (ls/read/write/edit/mv/rm/mkdir/search)', 'whoami', 'auth', 'session', 'trigger', 'focus', 'screenshot', 'minion'],
+        tools: ['fs (ls/read/write/edit/mv/rm/mkdir/search)', 'whoami', 'auth', 'session', 'trigger', 'focus', 'tour', 'screenshot', 'minion'],
       }, null, 2),
     }],
   };
@@ -2583,13 +2605,14 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
   title: z.string().optional().describe('[write + googleType] title for a new native file'),
   ops: z.array(z.any()).optional().describe('[edit] hashline ops for text frames. Apply ONLY against a fresh fs(read) of the frame: each op = {type, lineHash, newContent} where type is one of replace | delete | insertAfter | insertBefore, and lineHash is the FULL anchor from the read output (line number + hash, e.g. the token left of the |, like 42srt) — NOT a bare hash. delete/replace consume the target line; at most one replace/delete per line per edit (combine into one replace). If an op targets a line that changed since read it is rejected — re-read and retry. Element ops for excalidraw ({id,x,y,...}), or structured ops for office'),
   state: z.any().optional().describe('[write] app-frame state (JSON) to persist for a deployed windowType:"app" frame; the canvas hydrates the app from it on load. Max 64KB.'),
+  metadata: z.any().optional().describe('[write] JSON metadata to attach to the written frame (e.g. {"tour": {title, auto?, steps}} to define a guided tour on this frame). Max 64KB.'),
   recursive: z.boolean().optional().describe('[ls] recurse into subdirectories'),
   lines: z.string().optional().describe('[read] line range (e.g. "1-50") — partial read; content is hashline-annotated so a later edit stays surgical'),
   pattern: z.string().optional().describe('[ls] filter filenames (e.g. "*.html")'),
   org: z.string().optional().describe('Org (id or name) for bare /wiki and /skills paths (org-scoped /o/<org>/... paths don\'t need it). Per-request only; project paths self-derive org from the project row.'),
   projectId: PROJECT_OVERRIDE_PARAM,
 }, async (args) => {
-  const { action, path: rawPath, to: rawTo, query, content, file_path, base64, googleType, title, ops, state, recursive, pattern, lines, org } = args;
+  const { action, path: rawPath, to: rawTo, query, content, file_path, base64, googleType, title, ops, state, metadata, recursive, pattern, lines, org } = args;
   // Org-scoped path (Shape A): /o/<org>/<root>/... — strip the org segment here,
   // carry it as the per-request org scope (orgHeader), validate per-root below.
   // The PATH is the address; the org= param is legacy for bare roots only, and a
@@ -2969,6 +2992,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
           }
           else if (base64) body.base64 = base64;
           else return err(new Error('write requires one of content / file_path / base64 / googleType / state'));
+          if (metadata !== undefined) body.metadata = metadata;
           const result = await api('PUT', `/api/fs/${filePath}`, body, orgHeader);
           if (state !== undefined && result?.id) {
             try { await api('POST', `/api/file/${result.id}/state`, { state }); } catch { /* state best-effort */ }

package/package.json

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