drafted 1.18.1 → 1.18.2

package/package.json

@@ -1,38 +1,102 @@
 {
   "name": "drafted",
-  "version": "1.18.1",
-  "description": "Shared surface for AI-human collaboration — MCP server and CLI",
+  "version": "1.18.2",
+  "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/",
+    "plugin/skills/",
+    "plugin/commands/",
+    "install-mcp.sh"
+  ],
   "bin": {
     "drafted": "./cli/drafted.mjs",
     "drafted-mcp": "./mcp/server.mjs"
   },
-  "files": [
-    "mcp/",
-    "cli/",
-    "shared/",
-    "skills/",
-    "README.md"
-  ],
+  "scripts": {
+    "dev": "./dev.sh",
+    "dev:server": "tsx watch --import ./server/instrument.mjs server/server.mjs",
+    "dev:local": "node server/server-local.mjs",
+    "install-global": "npm install -g .",
+    "db:migrate": "psql $DATABASE_URL -f drizzle/migrate.sql",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "migrate-fs": "tsx server/migrate-fs.ts",
+    "db:clean-sessions": "tsx src/auth/cleanup.ts",
+    "import:legacy": "tsx scripts/import-legacy.mts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "version": "node scripts/sync-versions.mjs && git add plugin/.claude-plugin/plugin.json .claude-plugin/marketplace.json web-plugin/plugin/.claude-plugin/plugin.json web-plugin/.claude-plugin/marketplace.json",
+    "version:check": "node scripts/sync-versions.mjs",
+    "postpublish": "bash scripts/sync-plugin.sh \"chore: sync plugin to v$npm_package_version\" && bash scripts/sync-web-plugin.sh \"chore: sync web-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:office-viewer": "node scripts/build-office-viewer.mjs",
+    "prepublishOnly": "node scripts/check-npm-package.mjs",
+    "test:marketing": "node server/lib/marketing/test-marketing.mjs"
+  },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.1007.0",
+    "@aws-sdk/s3-request-presigner": "^3.1008.0",
+    "@clerk/backend": "^3.2.12",
+    "@clerk/express": "^2.1.4",
+    "@clerk/mcp-tools": "^0.3.1",
+    "@excalidraw/excalidraw": "^0.18.1",
+    "@modelcontextprotocol/ext-apps": "^1.6.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@sentry/browser": "^10.53.1",
+    "@sentry/node": "^10.53.1",
+    "@xmldom/xmldom": "^0.9.10",
     "commander": "^11.1.0",
+    "dagre": "^0.8.5",
+    "docx": "^9.7.1",
+    "dotenv": "^17.3.1",
+    "drizzle-orm": "^0.45.1",
+    "esbuild": "^0.28.0",
+    "exceljs": "^4.4.0",
+    "express": "^4.18.2",
+    "jszip": "^3.10.1",
+    "lucide": "^1.16.0",
+    "mdast-util-from-markdown": "^2.0.3",
+    "multer": "^2.1.1",
+    "nodemailer": "^8.0.2",
+    "parse5": "^8.0.1",
+    "pg": "^8.20.0",
+    "playwright": "^1.58.2",
+    "puppeteer": "^24.37.5",
     "qrcode-terminal": "^0.12.0",
-    "ws": "^8.16.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "sharp": "^0.34.5",
+    "ws": "^8.21.3",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },
   "keywords": [
-    "drafted",
     "design",
-    "mcp",
-    "claude",
-    "ai",
-    "canvas"
+    "canvas",
+    "preview",
+    "html",
+    "claude"
   ],
   "author": "ddfourtwo",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ddfourtwo/drafted.git"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/nodemailer": "^7.0.11",
+    "@types/pg": "^8.18.0",
+    "docx-preview": "^0.3.7",
+    "drizzle-kit": "^0.31.9",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
 }

package/plugin/commands/create-project.md

@@ -0,0 +1,20 @@
+---
+description: Start a new project — or a reusable template — with proper search of knowledge and skills first
+argument-hint: <project name and what you want to do>
+---
+
+Spin up a project on the surface, or generalize one into a reusable template. Goal: $ARGUMENTS
+
+First ask: **a new project, or a reusable template?** (This command does both.)
+
+Search before creating (also satisfies the gates):
+1. `fs(search, path="/o/<org>/wiki", query="<terms>")` for relevant knowledge. [G1]
+2. `fs(search, path="/o/<org>/skills", query="<topic>")` for procedures that should be attached. [G2/G3]
+
+Then:
+- Create the project — a project is a folder: `fs(mkdir, path="/o/<org>/projects/<name>")`. It starts with **no layers**; you define them by writing into them.
+- `fs(write, path="/o/<org>/projects/<name>/<layer>/<lane>/brief.md", content=...)` a real brief at the earliest layer (goal, audience, constraints — 6-12 lines, not a placeholder). The layer + lane auto-create.
+- Attach the relevant skills you found via the skill gates.
+- `fs(ls, path="/o/<org>/projects/<name>")` to confirm the structure, and hand the user the `projectUrl` from the response.
+
+For a **template**: build the layer structure + anchored guidance, then note how to fork it next time. Don't speculatively fill downstream frames — wait for direction.

package/plugin/commands/create-skill.md

@@ -0,0 +1,18 @@
+---
+description: Capture a repeatable procedure as an org skill — with proper knowledge and prior-art search
+argument-hint: <what the procedure is for>
+---
+
+Turn a repeatable way of working into a Drafted skill so every future agent in the org follows it. Procedure: $ARGUMENTS
+
+Do the searches first (they also satisfy the gates):
+1. `fs(search, path="/o/<org>/wiki", query="<terms>")` for relevant org knowledge the procedure should reference. [G1]
+2. `fs(search, path="/o/<org>/skills", query="<topic>")` for prior art — an existing skill to improve instead of duplicating. [G2 — also enforced on writing a new skill.] If a close match exists, prefer `/drafted:improve-skill`.
+
+Then define a PROPER procedure, not a vague note:
+- a clear trigger ("when to use this"),
+- ordered, concrete steps,
+- success criteria / what "done right" looks like,
+- written in the second person so any agent can follow it directly. Keep it sharp (~40 lines).
+
+Show the draft to the user with a proposed `name` (Title Case), one-line `description`, `tags` (3-5), and `triggerPatterns`. After approval, write it with `fs(write, path="/o/<org>/skills/<slug>", content=...)` — the slug is derived from the name. Confirm with the slug and note it will auto-surface on matching tasks.

package/plugin/commands/extract.md

@@ -0,0 +1,16 @@
+---
+description: Deposit what this session produced into the harness — knowledge, a skill, and/or a template
+argument-hint: <optional: what to capture>
+---
+
+Session-end deposit. Harvest what's durable from this conversation back into the harness so the next session starts smarter. Focus: $ARGUMENTS
+
+Review the session, then **present the user options for which store(s) to deposit into** — don't auto-decide. Offer any that apply:
+
+- **Knowledge → wiki** — durable facts, decisions, or findings worth keeping. Search first (`fs(search, path="/o/<org>/wiki", ...)`) to avoid fragmenting, then `fs(write, path="/o/<org>/wiki/<path>", ...)`.
+- **Procedure → skill** — a repeatable way of working that emerged. Follow `/drafted:create-skill`.
+- **Template → surface** — a reusable project structure that emerged. Build it as a project via `fs(mkdir, ...)` + frames.
+
+Show the user the candidate deposits per store, let them pick which to keep, then write the chosen ones with their approval. Confirm what landed where.
+
+One command, all three stores — because at session end the human shouldn't have to remember which store is which.

package/plugin/commands/improve-project-harness.md

@@ -0,0 +1,16 @@
+---
+description: Turn corrections you made in a project into enforced gates (anchors, attached skills, layer rules)
+argument-hint: <optional: the correction to enforce>
+---
+
+When the user had to correct the work in this project, codify the correction so future work is compelled to comply. This is the nurture → enforce bridge. Correction: $ARGUMENTS
+
+1. Identify the recurring correction(s) or standing rule from this session.
+2. Choose the right Drafted-side gate per correction (each counts toward the project's context budget):
+   - **Project anchor** — a brief, constraint, or style guide that must be in context project-wide: `fs(write, path="/o/<org>/projects/<project>/<layer>/<lane>/<file>", content=...)` it, then anchor it so it surfaces on open. [G5]
+   - **Attached skill** — a procedure that must be loaded before work: `/drafted:create-skill` (or `fs(search, path="/o/<org>/skills", ...)` for an existing one), then attach it to the project. [G4]
+   - **Layer rule** — a standing instruction for one stage: set that layer's rules so work in it is gated. [G6]
+3. Propose which mechanism for each correction, confirm with the user, then apply.
+4. Confirm what is now enforced — the next session in this project will be gated on it automatically.
+
+Keep within the project's context budget — if a deposit would exceed it, tighten existing gates instead of piling on.

package/plugin/commands/improve-skill.md

@@ -0,0 +1,14 @@
+---
+description: Fix a skill you noticed is inefficient, wrong, or missing a step
+argument-hint: <which skill, and what's off>
+---
+
+Improve an existing org skill when it underperformed in practice. Skill / issue: $ARGUMENTS
+
+1. `fs(search, path="/o/<org>/skills", query="<slug>")` then `fs(read, path="/o/<org>/skills/<slug>")` the skill in question — read it fully.
+2. Pinpoint the inefficiency: a missing step, a wrong instruction, an ambiguous trigger, or a step that wastes effort.
+3. Propose the specific edit to the user — show before/after of the changed steps.
+4. After approval, `fs(write, path="/o/<org>/skills/<slug>", content=<updated>)` — writing an existing skill updates it (the version bumps automatically). If it was archived, writing restores it.
+5. Confirm what changed so the next agent benefits.
+
+Skills are the org's stable processes — every fix compounds across everyone who uses them.

package/plugin/commands/improve-wiki.md

@@ -0,0 +1,14 @@
+---
+description: Fix the wiki — reconcile stale, wrong, fragmented, or contradictory knowledge
+argument-hint: <what's wrong, or the topic to clean up>
+---
+
+Improve the org wiki when knowledge has drifted. Issue/topic: $ARGUMENTS
+
+1. `fs(search, path="/o/<org>/wiki", query="<terms>")` (3-5 paraphrased queries) and `fs(read, path="/o/<org>/wiki/<path>")` the affected pages — don't trust titles, open them.
+2. Diagnose: duplicate pages, a stale fact, a contradiction, or knowledge fragmented across pages.
+3. Propose the fix to the user: consolidate duplicates, correct the fact, reconcile the contradiction, or re-link fragments.
+4. Apply with `fs(write, path="/o/<org>/wiki/<path>", content=<updated>)` (hashline `edit` for surgical changes) or `fs(mv, path="/o/<org>/wiki/<from>", to="/o/<org>/wiki/<to>")` (which rewrites inbound links). Check what links to a page before moving or archiving it.
+5. Never hard-delete — `fs(rm, path="/o/<org>/wiki/<path>")` moves a page to the archive folder.
+
+Leave the wiki more coherent than you found it — fewer, sharper, better-linked pages.

package/plugin/commands/ingest.md

@@ -0,0 +1,20 @@
+---
+description: Bring knowledge into the wiki — from a research output, existing documents, or by interrogating you
+argument-hint: <optional: what to ingest, or a source>
+---
+
+Feed durable knowledge into the org wiki. Source/intent: $ARGUMENTS
+
+First decide WHAT to ingest. If it's obvious from the conversation (a research run just finished, or the user named a source), use that. Otherwise ask which of these three modes fits:
+
+1. **A research producible** — the output of a research run (a provider-native `/deep-research` or similar). Structure it into wiki pages.
+2. **Existing documents** — the user points at local / remote / connected folders. Scour them (spawn sub-agents if there are many) for relevant material, shortlist, confirm, then ingest the right ones. Folder scour needs file access (desktop / Cowork); on web, use connected sources.
+3. **Interrogate the user** (grill-me) — when the knowledge is in their head. Interview relentlessly, walking ONE branch of the decision tree at a time and proposing your recommended answer at each step, until you reach shared understanding. Then structure what you captured.
+
+Then deposit:
+- `fs(search, path="/o/<org>/wiki", query="<terms>")` first (3-5 paraphrased queries) so you don't fragment existing pages.
+- Propose the page set to the user before writing.
+- Write with `fs(write, path="/o/<org>/wiki/<path>", content=...)` per page. Cross-link related pages.
+- Confirm what landed where, with the page links.
+
+The wiki is the org's durable knowledge — write for the next agent and teammate, not just this session.

package/plugin/commands/onboard-drafted.md

@@ -0,0 +1,17 @@
+---
+description: First-run setup — orient to Drafted and bootstrap the harness (wiki, skills, first project)
+argument-hint: <optional: what you want to start working on>
+---
+
+Onboard the user to Drafted — a producibles harness that compounds across three primitives: knowledge (the wiki), procedures (skills), and the project surface. Goal/context: $ARGUMENTS
+
+This is the over-arching prime command: orient, then seed all three stores so every later session starts smart.
+
+1. **Orient** — in 3-4 lines explain the loop: you *prime* from the harness (the system makes you search the wiki, and auto-loads the project's attached skills, anchors, and layer rules before you work), you *build*, then you *compound* (deposit what you learned). The more it's used, the less searching and the more stable the work. Drafted is navigated like a filesystem — one `fs` tool, three roots: `/wiki`, `/skills`, `/projects`.
+2. **Name the org** — the org is an address, not a cursor: address wiki/skills with `org=...` on the call, and projects self-derive their org from the path. Never rely on an "active" org: a project-less create by a multi-org user is refused rather than guessed.
+3. **Seed knowledge** — run the `/drafted:ingest` flow: help the user point at existing business materials (folders, docs, past research) or interrogate them for tacit knowledge, and land durable pages in the wiki.
+4. **Seed procedures** — from those materials and the conversation, surface 1-3 candidate SOPs. For the most valuable, run the `/drafted:create-skill` flow.
+5. **Seed the surface** — run the `/drafted:create-project` flow for the user's immediate piece of work (or a reusable template).
+6. Close by showing what now exists (wiki pages, skills, project) and restate the one-line loop: prime → build → compound.
+
+Keep it guided and conversational — one step at a time, confirming before each deposit. Don't dump everything at once.

package/plugin/skills/drafted/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: drafted
+description: Use the Drafted producibles harness — a compounding workspace that uplifts any AI across three primitives: knowledge (the org wiki), procedures (skills), and the project surface (frames on a shared real-time canvas). Drafted is navigated like a filesystem — one fs tool, one path grammar, org first: `fs(ls, path="/")` lists your orgs, then `/o/<org>/<root>/...`. Prime from the harness before working, build durable artifacts as frames instead of burying output in chat, and deposit what you learned back so the next session starts smarter. When Google Drive is connected, prefer Google Workspace frames for docs, sheets, and slides.
+---
+
+# Drafted — a producibles harness that compounds
+
+Drafted makes any AI more effective by giving it a memory and a workspace that get better with use. It has three primitives that layer:
+
+- **Knowledge — the org wiki.** Durable facts, decisions, conventions. *More knowledge = less searching.*
+- **Procedures — skills.** Reusable SOPs the org has encoded. *Better skills = more stable process.*
+- **Surface — projects.** Reviewable work as frames on a shared zoomable canvas the user watches live at `https://drafted.live`. *Reusable projects + anchors = velocity with accuracy.*
+
+The point is the **compounding loop**: you don't produce in a vacuum, you draw on what the org already knows and leave it richer each pass.
+
+## The surface is a filesystem — one tool, one path grammar
+
+There is exactly **one** tool to know: `fs`. It looks, feels, and behaves like a local filesystem, and an **org is the top folder** — you address an org, you never switch to it:
+
+```
+fs(ls, path="/")                                   → the orgs you belong to
+fs(ls, path="/o/<org>")                            → that org's wiki · skills · projects
+/o/<org>/wiki/<path>                                org knowledge pages (markdown, free nesting)
+/o/<org>/skills/<slug>                              reusable procedures (flat: one dir per skill)
+/o/<org>/projects/<project>/<layer>/<lane>/<file>   frames on the surface (project → layer → lane → file)
+```
+
+Verbs: `ls` (list) · `read` (cat, hashline-annotated) · `write` (create/overwrite) · `edit` (hashline ops) · `mv` (rename/move) · `rm` (move to archive) · `mkdir` (create a project) · `search` (grep).
+
+**A project is a folder.** It starts with **no layers** — writing to `/o/<org>/projects/<name>/<layer>/...` auto-creates the layer (mkdir -p). The agent defines the filesystem structure by writing into it. URLs are the same paths: `https://drafted.live/o/<org>/projects/<project>/<layer>/<lane>/<file>` — the URL's pathname IS the fs path (one canonical link for both humans and agents). Bare `/wiki`, `/skills`, `/projects` roots still work via the session's working org.
+
+## The loop — prime → build → compound
+
+- **Prime (session start).** Pull accumulated value in. The system *enforces* this: you must search the wiki before working (G1), and a project's attached skills and anchored frames are required reading when you open it. Don't fight the gates — they make you start smart.
+- **Build (the work).** Produce artifacts as frames on the surface.
+- **Compound (session end / when you notice something).** Deposit learning back: capture knowledge, distill or fix a skill, harden the project. This is *your* responsibility — the system can't force it, so do it.
+
+## The gates you'll encounter (and how to satisfy them)
+
+These reset every session. A gate that blocks you tells you exactly what to call next — do it, don't work around it.
+
+- **G1 — wiki search before work.** Before reading or editing anything, `fs(search, path="/o/<org>/wiki", query="<terms>")` for relevant org knowledge.
+- **G2 — prior-art before a new skill.** Writing a new `/o/<org>/skills/<slug>` requires `fs(search, path="/o/<org>/skills", query="<topic>")` first.
+- **G3 — prior-art before a new project.** Creating a project requires wiki + skill searches first.
+- **G4 — attached skills** are auto-injected when you open a project. Follow them — they're how the org does this work.
+- **G5 — the project's anchored frames** are required reading (briefs, constraints, style guides).
+- **G6 — a layer's rules** are surfaced when you work in that layer. Honor them.
+
+## The commands (when to reach for each)
+
+These bookend the loop. Prime/feed at the start, deposit at the end.
+
+- `/drafted:onboard-drafted` — first run: orient + bootstrap the harness (seed wiki, starter skills, first project).
+- `/drafted:ingest` — bring knowledge into the wiki (a research output, existing documents, or by interrogating the user).
+- `/drafted:create-skill` — capture a repeatable procedure (with knowledge + prior-art search).
+- `/drafted:create-project` — start a project or a reusable template (with knowledge/skill/template search).
+- `/drafted:improve-wiki` — fix stale / wrong / fragmented knowledge.
+- `/drafted:improve-skill` — fix a skill that underperformed.
+- `/drafted:improve-project-harness` — turn corrections into enforced gates (anchors / attached skills / layer rules).
+- `/drafted:extract` — session-end: deposit knowledge, a skill, and/or a template (the user picks which).
+
+## Working on the surface
+
+- **Navigate by path, exactly like a filesystem.** `fs(ls, path="/")` to see your orgs; `fs(ls, path="/o/<org>/projects")` to see a project list; `fs(ls, path="/o/<org>/projects/<project>")` for layers/lanes; `fs(ls, path="/o/<org>/projects/<project>/<layer>")` for frames. The project is resolved from the path itself — no separate "open" step.
+- **Create a project with `fs(mkdir, path="/o/<org>/projects/<name>")`** — or just `fs(write, path="/o/<org>/projects/<name>/<layer>/<lane>/<file>", content=...)` and the project + layer auto-create in the addressed org.
+- **Default to the surface for substantive artifacts.** When asked to draft, write, plan, analyze, compare, design, document, summarize, report, spec, model, or make a deck/table, create or update frames instead of leaving the durable result only in chat. One visible frame per artifact or section.
+- **Read before editing.** `fs(read)` returns every line hashline-annotated (`1abc|<content>`); `fs(edit, ops=[{type:"replace", lineHash:"1abc", newContent:"..."}])` targets exactly that line. For partial reads, pass `lines: "2-50"` — you get back just that range, still hash-annotated, and can edit within it.
+- **Prefer Google Workspace when Drive is connected.** Use `fs(write, path=".../<name>.google-doc"|".google-sheet"|".google-slide")` for docs, sheets, and decks; populate immediately with the matching native write action.
+- **`fs(mv, from="/o/<org>/projects/<p>/<layer>/<lane>/<file>", to="...")`** renames or moves (cross-project too). **`fs(rm, path="/o/<org>/projects/<project>")` archives** — agents never hard-delete; the archive is in the web UI.
+- **Return a clickable link** for what you touched — the `frameUrl`/`projectUrl` in the fs response is the URL the user opens.
+
+## Quality conventions
+
+- **Match format to layer intent.** Research/strategy/copy are usually markdown; visual work (wireframes, designs, dashboards) is HTML.
+- **Wireframes are low-fidelity** (grayscale, placeholders); reserve color and real content for the designs/final layer.
+- **Choose dimensions to fit content** — `autoSize: true` for HTML, or explicit `width`/`height`.
+- **Don't re-read unchanged frames** you already have this conversation.
+- **Diagrams: prefer native Excalidraw.** For flowcharts, process maps, architecture/system/data-flow diagrams, or visual maps, write a `.excalidraw` file (scene JSON) and load the `excalidraw-drafted` skill for the authoring guidance. Use HTML/markdown frames for web/UI mockups, rich layouts, or non-editable artifacts.
+
+## Skill authoring
+
+- **Git is the source of truth for skills; Drafted renders, indexes, and searches.** When a repo is connected to a folder, the skills under `.agents/skills/` in that repo ARE the skills for that folder — authoring happens by committing to git, not by writing into Drafted. Drafted write paths for a repo-owned skill return `409 repo_owned` naming the repo, branch, and path to commit to. Use `repo(action="rescan")` after a push so the index reflects the change.
+- **For a folder with NO connected repo, author skills in Drafted** with `fs(write, path="/o/<org>/skills/<slug>", content=..., readme=...)` (G2 gate first). A `README.md` is required (the `readme` param) so the skill directory is self-documenting. `fs(mv, path="/o/<org>/skills/<old>", to="/o/<org>/skills/<new>")` renames.
+- **Knowledge goes in the wiki, procedure in skills.** Drafted owns org knowledge (wiki pages via `fs` under `/o/<org>/wiki/`); git owns reusable procedure (skills under `.agents/skills/`). Don't put a skill body in a wiki page or a knowledge doc in a SKILL.md.
+- **Machine-specific build output is never portable.** Build `node_modules`, downloaded browsers, compiled binaries into a `.skillinstall/` directory inside the skill — Drafted always strips it on push and skill push auto-gitignores it, so the rebuildable bundle stays local while the method and recipe live in git/Drafted.
+- **Improve skills when you find a better way.** Fix or distill a skill that underperformed rather than leaving it stale.
+
+## Surface URL recognition
+
+Any URL containing `/f/{uuid}` is a Drafted frame link — `fs(read, path=URL)` gets its content. Canonical links are the fs paths themselves: `/o/<org>/wiki/...`, `/o/<org>/skills/<slug>`, `/o/<org>/projects/<project>/<layer>/<lane>/<file>`. Never `WebFetch` Drafted URLs — the MCP tools authenticate properly.

package/server/lib/umami.mjs

@@ -0,0 +1,162 @@
+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', 'matchKey']);
+
+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;
+  // Account de-dupe: when the event carries a userId, send it as Umami's distinct id
+  // (`payload.id`). Umami then derives sessionId = uuid(websiteId, userId) with no IP/UA/date
+  // salt, so server-side events land in the SAME canonical session as the browser's
+  // umami.identify(userId) call — collapsing each account to one session across devices/time.
+  const distinctId = (typeof data.userId === 'string' && data.userId.length <= 64) ? data.userId : undefined;
+  const payload = {
+    type: 'event',
+    payload: {
+      website: umami.websiteId,
+      name,
+      ...(distinctId ? { id: distinctId } : {}),
+      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));
+}

package/src/shared/excalidraw.mjs

@@ -0,0 +1,84 @@
+export const EXCALIDRAW_MIME = 'application/vnd.excalidraw+json';
+
+// Linear elements (arrow/line/freedraw) REQUIRE a `points` array — Excalidraw's scene
+// restore reads points.length and crashes ("Cannot read properties of undefined (reading
+// 'length')") → eternal "Loading scene" spinner. Hand-authored/agent-written scenes
+// routinely omit it (source: "https://excalidraw.com", ids like "el1"), so repair it
+// here: every read (serve) and write path funnels through normalizeExcalidrawScene, so
+// existing broken frames open and new bad writes are fixed before they land.
+const LINEAR_ELEMENT_TYPES = new Set(['arrow', 'line', 'freedraw']);
+
+function repairLinearElement(el) {
+  if (!LINEAR_ELEMENT_TYPES.has(el.type)) return el;
+  const pts = el.points;
+  const valid = Array.isArray(pts) && pts.length > 0 &&
+    pts.every((p) => Array.isArray(p) && p.length >= 2 && typeof p[0] === 'number' && typeof p[1] === 'number');
+  if (valid) return el;
+  const w = typeof el.width === 'number' && el.width > 0 ? el.width : 1;
+  const h = typeof el.height === 'number' && el.height > 0 ? el.height : 0;
+  return { ...el, points: [[0, 0], [w, h]] };
+}
+
+export function emptyExcalidrawScene() {
+  return {
+    type: 'excalidraw',
+    version: 2,
+    source: 'https://drafted.live',
+    elements: [],
+    appState: {},
+    files: {},
+  };
+}
+
+export function normalizeExcalidrawScene(input) {
+  const scene = typeof input === 'string' ? JSON.parse(input) : input;
+  if (!scene || typeof scene !== 'object' || Array.isArray(scene)) {
+    throw new Error('Excalidraw data must be an object');
+  }
+  if (!Array.isArray(scene.elements)) {
+    throw new Error('Excalidraw data must include elements array');
+  }
+  const appState = scene.appState && typeof scene.appState === 'object' && !Array.isArray(scene.appState)
+    ? scene.appState
+    : {};
+  const files = scene.files && typeof scene.files === 'object' && !Array.isArray(scene.files)
+    ? scene.files
+    : {};
+  return {
+    type: scene.type || 'excalidraw',
+    version: scene.version || 2,
+    source: scene.source || 'https://drafted.live',
+    elements: scene.elements.map(repairLinearElement).filter(Boolean),
+    appState,
+    files,
+  };
+}
+
+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()) };
+}