drafted 1.7.19 → 1.7.21

package/install-mcp.sh

@@ -215,8 +215,18 @@ export PATH="$HOME/.drafted/npm-global/bin:$PATH"
 
 step "Installing Drafted"
 
-npm install -g drafted@latest --force --silent 2>/dev/null
+npm install -g drafted@latest --force
 hash -r 2>/dev/null || true
+NPM_ROOT="$(npm root -g 2>/dev/null || true)"
+MCP_SERVER_MODULE="$NPM_ROOT/drafted/mcp/server.mjs"
+if [ -n "$NPM_ROOT" ] && [ -f "$MCP_SERVER_MODULE" ]; then
+  node -e "import('node:url').then(({ pathToFileURL }) => import(pathToFileURL(process.argv[1]).href)).then(() => process.exit(0), (err) => { console.error(err); process.exit(1); })" "$MCP_SERVER_MODULE"
+elif [ "${DRAFTED_HEADLESS:-}" = "1" ]; then
+  echo -e "    ${DIM}Skipping package import check in headless installer test.${RESET}"
+else
+  echo -e "    ${RED}Could not find installed MCP server module at $MCP_SERVER_MODULE${RESET}"
+  exit 1
+fi
 ok "Installed $(drafted --version 2>/dev/null || echo 'drafted') via npm"
 
 # ── Configure ─────────────────────────────────────────────────────

package/mcp/server.mjs

@@ -20,7 +20,21 @@ import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/e
 import WebSocket from 'ws';
 import { LAYERS } from '../src/shared/constants.mjs';
 import { emptyExcalidrawScene, excalidrawSceneFromMermaid, stringifyExcalidrawScene } from '../src/shared/excalidraw.mjs';
-import { UMAMI_EVENTS, trackUmamiEvent } from '../server/lib/umami.mjs';
+const { UMAMI_EVENTS, trackUmamiEvent } = await (async () => {
+  try {
+    return await import('../server/lib/umami.mjs');
+  } catch {
+    return {
+      UMAMI_EVENTS: Object.freeze({
+        MCP_CONNECTED: 'mcp_connected',
+        MCP_TOOL_CALLED: 'mcp_tool_called',
+        DRAFTED_MCP_REQUEST: 'drafted_mcp_request',
+        DRAFTED_MCP_ERROR: 'drafted_mcp_error',
+      }),
+      trackUmamiEvent: () => {},
+    };
+  }
+})();
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -150,7 +164,7 @@ const TOOL_ANNOTATIONS = {
 
   // Frames — filesystem
   ls:                  { title: 'List frames',         readOnlyHint: true,  destructiveHint: false, openWorldHint: false, widgetUri: 'ui://widget/drafted-canvas-overview.html' },
-  frame:               { title: 'Frames',              readOnlyHint: false, destructiveHint: true,  openWorldHint: false, widgetUri: 'ui://widget/drafted-frame-preview.html', description: 'Read, write, edit, move, anchor, search, or restore frame versions in the ACTIVE PROJECT. Dispatch by `action`. Use `ls` to browse, `rm` to delete.' },
+  frame:               { title: 'Frames',              readOnlyHint: false, destructiveHint: true,  openWorldHint: true, widgetUri: 'ui://widget/drafted-frame-preview.html', description: 'Read, write, edit, move, anchor, search, restore frame versions, create Google Workspace frames, or write values into Google Sheet frames in the ACTIVE PROJECT. Dispatch by `action`. Use `ls` to browse, `rm` to delete.' },
   rm:                  { title: 'Delete frame',        readOnlyHint: false, destructiveHint: true,  openWorldHint: false },
   // batch:               { title: 'Batch operations',   readOnlyHint: false, destructiveHint: true,  openWorldHint: false },
 
@@ -1514,6 +1528,7 @@ async function getGoogleDriveAvailability() {
   }
 }
 
+
 tool('get_org', {
   action: z.enum(['get', 'switch']).optional().describe('Default: "get" returns active org and member info. Use "switch" with orgId to change the active org without opening a project.'),
   orgId: z.string().optional().describe('[switch] target org ID to switch to. Must be one of the orgs the user is a member of.'),
@@ -1570,18 +1585,41 @@ 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), 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**Write — content, file, or Google Workspace frame:** Provide `content` (HTML/markdown/text), `file_path` (absolute path to a local file), `googleType` (`google-doc`, `google-sheet`, `google-slide`), OR `write_excalidraw` with `excalidraw_data` or `mermaid`. Call get_org first; when `googleDrive.connected` is true, strongly prefer Google Workspace frames for business artifacts: use `google-doc` for memos/reports/briefs/SOPs/proposals, `google-sheet` for tables/trackers/budgets/research matrices/models, and `google-slide` for decks/presentation outlines. 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`. For binary files (images, PDFs), use `file_path` — uploaded to storage and displayed as an asset frame.\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`.', {
-  action: z.enum(['read', 'write', 'write_excalidraw', 'edit', 'mv', 'anchor', 'search', 'versions', 'read_version', 'restore_version']).describe('Operation to perform.'),
+tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by path, frame URL, or UUID), write (new frame or overwrite), 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 that, populate native Google Docs with `write_doc_content`/`append_doc_content` and native Google Slides with `write_slide_content`/`append_slides`; read them with `read_doc_content`/`read_slide_content`. Do NOT use inline `frame.write(content)` or hashline `frame.edit` to populate Google Doc/Slide frames — those actions are for Drafted inline frame files, not native Workspace document bodies.\n\n**Write — content, binary, or Google Workspace frame:** 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`. 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`.', {
+  action: z.enum(['read', 'write', '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', '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.'),
   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. Mutually exclusive with file_path. Use a .html path for complete HTML documents and a .md path for Markdown.'),
+  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.'),
   mermaid: z.string().optional().describe('[write_excalidraw] Mermaid source to convert into an editable Excalidraw scene.'),
-  file_path: z.string().optional().describe('[write] absolute path to a local file to upload. Mutually exclusive with content.'),
+  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.'),
+  content_type: z.string().optional().describe('[write + base64] MIME type for base64 binary content, e.g. image/png, application/pdf. Defaults from the path extension or application/octet-stream.'),
   googleType: z.enum(['google-doc', 'google-sheet', 'google-slide']).optional().describe('[write] Create or attach a native Google Workspace frame. Use with title to create new, or url/googleId to attach existing.'),
-  title: z.string().optional().describe('[write + googleType] Title for a new Google Doc/Sheet/Slide. Defaults to filename from path.'),
-  url: z.string().optional().describe('[write + googleType] Existing Google Doc/Sheet/Slide URL to attach.'),
-  googleId: z.string().optional().describe('[write + googleType] Existing Google file ID to attach.'),
+  title: z.string().optional().describe('[write + googleType] Title for a new native file. Defaults to filename from path.'),
+  url: z.string().optional().describe('[write + googleType] Existing Google file URL to attach.'),
+  googleId: z.string().optional().describe('[write + googleType] Existing Google file ID to attach. [Sheet/Doc/Slide actions] Native Google file ID to use when not resolving from path/frame.'),
+  format: z.enum(['plain_text', 'markdown']).optional().describe('[write_doc_content|append_doc_content] Source format hint. Currently plain_text and minimal markdown are accepted as text.'),
+  mode: z.enum(['replace', 'append', 'clear']).optional().describe('[Doc/Slide content actions] Optional mode hint for clients; prefer the explicit write/append/clear action names.'),
+  slides: z.array(z.object({
+    title: z.string().optional(),
+    bullets: z.array(z.string()).optional(),
+    speakerNotes: z.string().optional(),
+    layout: z.string().optional(),
+  }).passthrough()).optional().describe('[write_slide_content|append_slides] Structured slide spec: [{ title, bullets, speakerNotes?, layout? }].'),
+  requests: z.array(z.any()).optional().describe('[update_doc|update_slide] Raw Google Docs/Slides batchUpdate requests for advanced updates only; common Doc/Slide population should use write_doc_content/append_doc_content/write_slide_content/append_slides.'),
+  slideObjectIds: z.array(z.string()).optional().describe('[clear_slides] Optional slide object IDs to delete. Omit to clear all slides.'),
+  range: z.string().optional().describe('[Sheet value actions] A1 range, e.g. Sheet1!A1 or Data!A:Z.'),
+  values: z.array(z.array(z.any())).optional().describe('[write_sheet_values|append_sheet_rows] 2D array of row values.'),
+  valueInputOption: z.enum(['RAW', 'USER_ENTERED']).optional().describe('[write_sheet_values|append_sheet_rows] Google Sheets value input option. Defaults to USER_ENTERED.'),
+  majorDimension: z.enum(['ROWS', 'COLUMNS']).optional().describe('[Sheet value actions] Major dimension for values. Defaults to ROWS when writing/appending.'),
+  valueRenderOption: z.enum(['FORMATTED_VALUE', 'UNFORMATTED_VALUE', 'FORMULA']).optional().describe('[read_sheet_values] How values should be rendered. Defaults to Google Sheets API default.'),
+  dateTimeRenderOption: z.enum(['SERIAL_NUMBER', 'FORMATTED_STRING']).optional().describe('[read_sheet_values] How dates/times should be rendered.'),
+  insertDataOption: z.enum(['OVERWRITE', 'INSERT_ROWS']).optional().describe('[append_sheet_rows] How new rows are inserted. Defaults to INSERT_ROWS.'),
+  operation: z.enum(['add_sheet', 'rename_sheet']).optional().describe('[update_sheet] Sheet tab operation.'),
+  sheetTitle: z.string().optional().describe('[update_sheet add_sheet] Title for the new sheet tab.'),
+  sheetId: z.number().optional().describe('[update_sheet rename_sheet] Numeric sheet/tab id.'),
+  newTitle: z.string().optional().describe('[update_sheet rename_sheet] New title for the sheet tab.'),
   autoSize: z.boolean().optional().describe('[write] measure HTML content and size frame to fit. Content only, not file_path.'),
   width: z.number().optional().describe('[write] explicit width in pixels. Overrides layer default. Ignored if autoSize=true.'),
   height: z.number().optional().describe('[write] explicit height in pixels. Overrides layer default. Ignored if autoSize=true.'),
@@ -1607,6 +1645,26 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
     // write landed before it can develop a wrong assumption.
     const projectCtx = getCurrentProjectContext();
     const withProject = (result) => ({ ...result, project: projectCtx });
+    const workspaceBody = (kind) => {
+      const { path, googleId } = args;
+      const body = {};
+      const frameUrlMatch = path?.match(/\/f\/([a-f0-9-]{36})/);
+      const uuidMatch = path?.match(/^[a-f0-9-]{36}$/);
+      if (googleId) {
+        if (kind === 'sheet') body.spreadsheetId = googleId;
+        else if (kind === 'doc') body.documentId = googleId;
+        else body.presentationId = googleId;
+      } else if (frameUrlMatch?.[1] || uuidMatch) {
+        body.frameId = frameUrlMatch?.[1] || path;
+      } else if (path) {
+        body.path = path;
+        body.projectId = getState().projectId;
+      } else {
+        const label = kind === 'sheet' ? 'Google Sheet' : kind === 'doc' ? 'Google Doc' : 'Google Slide';
+        throw new Error(`Provide path to a ${label} frame, frame ID/URL, or googleId/native file ID`);
+      }
+      return body;
+    };
     switch (action) {
       case 'read': {
         const { path, lines } = args;
@@ -1646,12 +1704,117 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
           _meta: { frameHtml: result.content },
         });
       }
+      case 'get_sheet':
+      case 'read_sheet_values':
+      case 'write_sheet_values':
+      case 'append_sheet_rows':
+      case 'clear_sheet_range':
+      case 'update_sheet': {
+        const { path, googleId, range, values, valueInputOption, majorDimension, valueRenderOption, dateTimeRenderOption, insertDataOption, operation, sheetTitle, sheetId, newTitle } = args;
+        const body = workspaceBody('sheet');
+        if (range) body.range = range;
+        if (majorDimension) body.majorDimension = majorDimension;
+        if (action === 'write_sheet_values' || action === 'append_sheet_rows') {
+          if (!values || !Array.isArray(values)) throw new Error(`values required for action=${action}`);
+          body.values = values;
+          body.valueInputOption = valueInputOption || 'USER_ENTERED';
+          body.majorDimension = majorDimension || 'ROWS';
+        }
+        if (action === 'read_sheet_values') {
+          if (valueRenderOption) body.valueRenderOption = valueRenderOption;
+          if (dateTimeRenderOption) body.dateTimeRenderOption = dateTimeRenderOption;
+        }
+        if (action === 'append_sheet_rows') body.insertDataOption = insertDataOption || 'INSERT_ROWS';
+        if (action === 'update_sheet') {
+          body.operation = operation;
+          if (sheetTitle) body.sheetTitle = sheetTitle;
+          if (sheetId != null) body.sheetId = sheetId;
+          if (newTitle) body.newTitle = newTitle;
+        }
+        const endpoint = action === 'get_sheet'
+          ? '/api/google/workspace/sheet'
+          : action === 'read_sheet_values'
+          ? '/api/google/workspace/sheet-values/read'
+          : action === 'write_sheet_values'
+          ? '/api/google/workspace/sheet-values'
+          : action === 'append_sheet_rows'
+          ? '/api/google/workspace/sheet-values/append'
+          : action === 'clear_sheet_range'
+          ? '/api/google/workspace/sheet-values/clear'
+          : '/api/google/workspace/sheet-update';
+        const result = await api('POST', endpoint, body);
+        return ok(withProject(result));
+      }
+      case 'get_doc':
+      case 'read_doc_content':
+      case 'write_doc_content':
+      case 'append_doc_content':
+      case 'clear_doc_content':
+      case 'update_doc': {
+        const { content, format, mode, requests } = args;
+        const body = workspaceBody('doc');
+        if (format) body.format = format;
+        if (mode) body.mode = mode;
+        if (action === 'write_doc_content' || action === 'append_doc_content') {
+          if (typeof content !== 'string') throw new Error(`content string required for action=${action}`);
+          body.content = content;
+        }
+        if (action === 'update_doc') {
+          if (!Array.isArray(requests)) throw new Error('requests array required for action=update_doc');
+          body.requests = requests;
+        }
+        const endpoint = action === 'get_doc'
+          ? '/api/google/workspace/doc'
+          : action === 'read_doc_content'
+          ? '/api/google/workspace/doc-content/read'
+          : action === 'write_doc_content'
+          ? '/api/google/workspace/doc-content'
+          : action === 'append_doc_content'
+          ? '/api/google/workspace/doc-content/append'
+          : action === 'clear_doc_content'
+          ? '/api/google/workspace/doc-content/clear'
+          : '/api/google/workspace/doc-update';
+        const result = await api('POST', endpoint, body);
+        return ok(withProject(result));
+      }
+      case 'get_slide':
+      case 'read_slide_content':
+      case 'write_slide_content':
+      case 'append_slides':
+      case 'clear_slides':
+      case 'update_slide': {
+        const { slides, requests, slideObjectIds, mode } = args;
+        const body = workspaceBody('slide');
+        if (mode) body.mode = mode;
+        if (action === 'write_slide_content' || action === 'append_slides') {
+          if (!Array.isArray(slides)) throw new Error(`slides array required for action=${action}`);
+          body.slides = slides;
+        }
+        if (action === 'clear_slides' && Array.isArray(slideObjectIds)) body.slideObjectIds = slideObjectIds;
+        if (action === 'update_slide') {
+          if (!Array.isArray(requests)) throw new Error('requests array required for action=update_slide');
+          body.requests = requests;
+        }
+        const endpoint = action === 'get_slide'
+          ? '/api/google/workspace/slide'
+          : action === 'read_slide_content'
+          ? '/api/google/workspace/slide-content/read'
+          : action === 'write_slide_content'
+          ? '/api/google/workspace/slide-content'
+          : action === 'append_slides'
+          ? '/api/google/workspace/slides/append'
+          : action === 'clear_slides'
+          ? '/api/google/workspace/slides/clear'
+          : '/api/google/workspace/slide-update';
+        const result = await api('POST', endpoint, body);
+        return ok(withProject(result));
+      }
       case 'write': {
-        const { path, content, file_path, autoSize, width, height, color, googleType, title, url, googleId } = args;
+        const { path, content, file_path, base64, content_type, autoSize, width, height, color, googleType, title, url, googleId } = args;
         if (!path) throw new Error('path required for action=write');
-        const writeSources = [content != null, !!file_path, !!googleType].filter(Boolean).length;
-        if (writeSources > 1) throw new Error('Provide only one of content, file_path, or googleType');
-        if (writeSources === 0) throw new Error('Provide content, file_path, or googleType');
+        const writeSources = [content != null, !!file_path, base64 != null, !!googleType].filter(Boolean).length;
+        if (writeSources > 1) throw new Error('Provide only one of content, file_path, base64, or googleType');
+        if (writeSources === 0) throw new Error('Provide content, file_path, base64, or googleType');
         const skillErr = await checkProjectSkills(getState().projectId);
         if (skillErr) return err(new Error(skillErr));
         const anchorErr = await checkAnchors(parseLayer(path));
@@ -1698,6 +1861,8 @@ tool('frame', 'Frame CRUD in the ACTIVE PROJECT. Dispatch by `action`: read (by
             const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf', '.mp4': 'video/mp4', '.webm': 'video/webm', '.mov': 'video/quicktime', '.m4v': 'video/x-m4v' };
             body = { base64: buffer.toString('base64'), contentType: MIME[ext] || 'application/octet-stream' };
           }
+        } else if (base64 != null) {
+          body = { base64, contentType: content_type || mimeFromExt(extname(parts[2])) };
         } else {
           body = { content };
           if (autoSize) body.autoSize = true;

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "drafted",
-  "version": "1.7.19",
+  "version": "1.7.21",
   "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": [
     "cli/",
     "mcp/",
+    "server/lib/umami.mjs",
     "src/shared/",
     "agent-instructions/",
     "install-mcp.sh"
@@ -31,7 +32,8 @@
     "version:check": "node scripts/sync-versions.mjs",
     "postpublish": "bash scripts/sync-plugin.sh \"chore: sync plugin to v$npm_package_version\"",
     "deploy:check:google": "node scripts/check-google-drive-deploy.mjs",
-    "build:excalidraw": "node scripts/build-excalidraw-editor.mjs"
+    "build:excalidraw": "node scripts/build-excalidraw-editor.mjs",
+    "prepublishOnly": "node scripts/check-npm-package.mjs"
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1007.0",

package/server/lib/umami.mjs

@@ -0,0 +1,156 @@
+export const UMAMI_EVENTS = Object.freeze({
+  SIGNUP_STARTED: 'signup_started',
+  SIGNUP_COMPLETED: 'signup_completed',
+  ORG_CREATED: 'org_created',
+  PROJECT_CREATED: 'project_created',
+  PROJECT_OPENED: 'project_opened',
+  TEMPLATE_USED: 'template_used',
+  FRAME_CREATED: 'frame_created',
+  FRAME_UPDATED: 'frame_updated',
+  FRAME_DELETED: 'frame_deleted',
+  SHARE_CREATED: 'share_created',
+  SHARE_ACCEPTED: 'share_accepted',
+  INVITE_SENT: 'invite_sent',
+  MCP_CONNECTED: 'mcp_connected',
+  MCP_TOOL_CALLED: 'mcp_tool_called',
+  WIKI_PAGE_CREATED: 'wiki_page_created',
+  SKILL_ATTACHED: 'skill_attached',
+  DRIVE_CONNECTED: 'drive_connected',
+  DRIVE_SYNC_COMPLETED: 'drive_sync_completed',
+  DRAFTED_INSTALL: 'drafted_install',
+  DRAFTED_UPDATE: 'drafted_update',
+  DRAFTED_HEARTBEAT: 'drafted_heartbeat',
+  DRAFTED_MCP_CONFIGURED: 'drafted_mcp_configured',
+  DRAFTED_MCP_REQUEST: 'drafted_mcp_request',
+  DRAFTED_MCP_ERROR: 'drafted_mcp_error',
+  DRAFTED_UPDATE_HELPER_STARTED: 'drafted_update_helper_started',
+  DRAFTED_UPDATE_HELPER_FAILED: 'drafted_update_helper_failed',
+  CTA_CLICKED: 'cta_clicked',
+  TEMPLATE_SELECTED: 'template_selected',
+  PROJECT_NAVIGATED: 'project_navigated',
+  SHARE_MODAL_OPENED: 'share_modal_opened',
+  SHARE_MODAL_ACTION: 'share_modal_action',
+  SURFACE_LOADED: 'surface_loaded',
+  SIDEBAR_USED: 'sidebar_used',
+  TOOL_PANEL_USED: 'tool_panel_used',
+});
+
+const BLOCKED_KEYS = new Set([
+  'email', 'userEmail', 'name', 'userName', 'orgName', 'projectName', 'label', 'title',
+  'content', 'html', 'markdown', 'body', 'prompt', 'token', 'cookie', 'authorization',
+  'password', 'secret', 'apiKey', 'request', 'headers', 'file', 'buffer', 'dataUrl',
+]);
+const ID_KEYS = new Set(['userId', 'orgId', 'projectId', 'projectSlug', 'frameId', 'shareId', 'skillId', 'templateId', 'templateSlug', 'userRole', 'role', 'buildId', 'pageType', 'tool', 'action', 'source', 'layer', 'lane', 'mode', 'installId', 'schemaVersion', 'installerVersion', 'cliVersion', 'osFamily', 'osVersion', 'arch', 'nodeVersion', 'npmVersion', 'claudeDesktop', 'claudeCode', 'codex', 'cursor', 'updateHelperStatus', 'mcpMode', 'errorCode']);
+
+export function getUmamiConfig(config = {}) {
+  const hostUrl = (config.umamiHostUrl || process.env.UMAMI_HOST_URL || '').replace(/\/$/, '');
+  const websiteId = config.umamiWebsiteId || process.env.UMAMI_WEBSITE_ID || '';
+  return { hostUrl, websiteId, enabled: Boolean(hostUrl && websiteId) };
+}
+
+export function sanitizeUmamiEventData(data = {}) {
+  const output = {};
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return output;
+  for (const [key, value] of Object.entries(data)) {
+    if (BLOCKED_KEYS.has(key)) continue;
+    if (value === undefined || value === null) continue;
+    if (typeof value === 'object') continue;
+    if (!ID_KEYS.has(key) && /email|name|content|html|markdown|body|prompt|token|cookie|auth|secret|password|key|file/i.test(key)) continue;
+    if (typeof value === 'string') {
+      if (value.length > 120) continue;
+      if (/@/.test(value)) continue;
+      output[key] = value;
+    } else if (typeof value === 'number' || typeof value === 'boolean') {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+
+export function getUmamiHead(config = {}) {
+  const umami = getUmamiConfig(config);
+  if (!umami.enabled) return '';
+  const ctx = sanitizeUmamiEventData({
+    userId: config.userId,
+    orgId: config.orgId,
+    projectId: config.projectId,
+    projectSlug: config.projectSlug,
+    userRole: config.userRole,
+    buildId: config.buildId,
+    pageType: config.pageType,
+  });
+  return `<script defer src="${umami.hostUrl}/script.js" data-website-id="${umami.websiteId}"></script>
+<script>
+window.__DRAFTED_ANALYTICS__ = ${JSON.stringify(ctx)};
+window.draftedTrack = function(name, data) {
+  var base = window.__DRAFTED_ANALYTICS__ || {};
+  var payload = Object.assign({}, base, data || {});
+  if (window.umami && typeof window.umami.track === 'function') window.umami.track(name, payload);
+};
+window.addEventListener('load', function() {
+  var c = window.__DRAFTED_ANALYTICS__ || {};
+  if (c.userId && window.umami && typeof window.umami.identify === 'function') window.umami.identify(c.userId, { orgId: c.orgId, role: c.userRole });
+});
+</script>`;
+}
+
+export function getUmamiInteractionScript(pageType) {
+  return `<script>
+(function() {
+  function track(name, data) { if (window.draftedTrack) window.draftedTrack(name, Object.assign({ pageType: ${JSON.stringify(pageType)} }, data || {})); }
+  window.addEventListener('load', function() {
+    if (${JSON.stringify(pageType)} === 'surface') track('surface_loaded');
+  });
+  document.addEventListener('click', function(event) {
+    var el = event.target && event.target.closest && event.target.closest('a,button,[data-analytics-event],[data-template-slug],[data-project-id]');
+    if (!el) return;
+    var eventName = el.getAttribute('data-analytics-event');
+    if (eventName) return track(eventName, { action: el.getAttribute('data-analytics-action') || undefined });
+    var href = el.getAttribute('href') || '';
+    var cls = el.className || '';
+    if (el.matches('.nav-cta,.btn-primary,.btn-secondary')) track('cta_clicked', { action: href || (el.textContent || '').trim().slice(0, 40) });
+    if (el.getAttribute('data-template-slug')) track('template_selected', { templateSlug: el.getAttribute('data-template-slug') });
+    if (el.getAttribute('data-project-id')) track('project_navigated', { projectId: el.getAttribute('data-project-id') });
+    if (/share/i.test(String(cls)) || /share/i.test(el.textContent || '')) track('share_modal_action');
+    if (/sidebar/i.test(String(cls))) track('sidebar_used');
+    if (/tool|panel/i.test(String(cls))) track('tool_panel_used');
+  }, true);
+})();
+</script>`;
+}
+
+function getRequestUrl(req) {
+  if (!req) return undefined;
+  const host = typeof req.get === 'function' ? req.get('host') : req.headers?.host;
+  const protocol = req.protocol || 'https';
+  return host ? `${protocol}://${host}${req.originalUrl || req.url || ''}` : undefined;
+}
+
+export function trackUmamiEvent(name, data = {}, req = null) {
+  const umami = getUmamiConfig();
+  if (!umami.enabled || !name || name.length > 50) return;
+  const payload = {
+    type: 'event',
+    payload: {
+      website: umami.websiteId,
+      name,
+      url: getRequestUrl(req) || process.env.BASE_URL || 'https://drafted.live',
+      hostname: req?.hostname || 'drafted.live',
+      language: req?.headers?.['accept-language'],
+      referrer: req?.headers?.referer,
+      data: sanitizeUmamiEventData(data),
+    },
+  };
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1500);
+  fetch(`${umami.hostUrl}/api/send`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': req?.headers?.['user-agent'] || 'Drafted Server Analytics',
+      'X-Forwarded-For': req?.ip || req?.headers?.['x-forwarded-for'] || '',
+    },
+    body: JSON.stringify(payload),
+    signal: controller.signal,
+  }).catch(() => {}).finally(() => clearTimeout(timeout));
+}