drafted 1.22.6 → 1.22.7

package/cli/drafted.mjs

@@ -285,6 +285,29 @@ function withQuery(base, params) {
   return qs ? `${base}?${qs}` : base;
 }
 
+const UUID_REF_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// A share URL pasted from the address bar is the pathname plus an origin the
+// server does not want — strip it so the canonical /o/<org>/... form is what the
+// resolver sees. Without this, `drafted read https://drafted.live/o/...` fell
+// through to frameReadPath as "not a URL" and was rejected.
+function stripUrlOrigin(input) {
+  return String(input || '').replace(/^https?:\/\/[^/]+/i, '');
+}
+
+// Resolve a --project value (UUID, slug or name) to the project id /api/fs takes.
+// The server's project scope casts the id to uuid and 500s on a slug, so a
+// perfectly reasonable `--project my-project` used to be an Internal server error.
+async function resolveProjectRef(command, ref) {
+  if (!ref || UUID_REF_RE.test(ref)) return ref;
+  const data = await readApiGet(command, '/api/projects');
+  const want = String(ref).toLowerCase();
+  const hit = (data.projects || []).find((p) =>
+    p.id === ref || [p.slug, p.name].some((v) => String(v || '').toLowerCase() === want));
+  if (!hit) failRead(command, `project not found: ${ref} — list them with: drafted projects`);
+  return hit.id;
+}
+
 // GET a Drafted API path with the stored session and return parsed JSON.
 // Strictly read-only: callers only ever issue GETs through this seam. An
 // optional --org override is forwarded as the X-Drafted-Org header (the server
@@ -349,8 +372,14 @@ function failRead(command, msg) {
 // "this project is empty" when it is not. So split the address here, the way
 // the MCP fs tool does, and refuse anything that does not name a project.
 async function resolveCanonicalPath(command, path, projectId) {
-  const m = String(path || '').match(/^\/o\/([^/]+)(?:\/(.*))?$/);
-  if (!m) return { path, projectId };
+  // --project may be a UUID, slug or name; the server resolves scope by UUID only.
+  const resolvedProjectId = await resolveProjectRef(command, projectId);
+  const cleaned = stripUrlOrigin(path);
+  const m = String(cleaned || '').match(/^\/o\/([^/]+)(?:\/(.*))?$/);
+  if (!m) {
+    // Not an org-scoped address — just carry the resolved project through.
+    return { path: cleaned, projectId: resolvedProjectId };
+  }
   const org = m[1];
   const segs = (m[2] || '').split('/').filter(Boolean);
   const at = segs.indexOf('projects');
@@ -371,7 +400,7 @@ async function resolveCanonicalPath(command, path, projectId) {
     const folder = [...folderChain, ...tail.slice(0, i)].join('/');
     const hit = inOrg.find(p => named(p, tail[i]) && (i === 0 || (p.folder || '') === folder));
     if (!hit) continue;
-    if (projectId && projectId !== hit.id) {
+    if (resolvedProjectId && resolvedProjectId !== hit.id) {
       failRead(command, `--project ${projectId} conflicts with the project in the path (${hit.id})`);
     }
     return { path: '/' + tail.slice(i + 1).join('/'), projectId: hit.id };

package/cli/mail-watch.mjs

@@ -109,7 +109,7 @@ export function buildBrief({ thread, message, userEmail }) {
     'Do this, and work only in that project:',
     `1. Name your session: session(action="name", name="mail: ${thread.title.slice(0, 30)}").`,
     `2. Read the project (fs ls/read under ${projectPath}) to understand the context.`,
-    `3. Write one frame at ${projectPath}/mail/${thread.id.slice(0, 8)}/reply-${new Date().toISOString().slice(0, 10)}.md, starting with front matter "drafted:status: needs_review": a short summary in your own words (do not paste the email, do not copy addresses), what it asks, what should happen next, and a reply draft.`,
+    `3. Write one frame at ${projectPath}/mail/${thread.id.slice(0, 8)}/reply-${new Date().toISOString().slice(0, 10)}.md, starting with front matter "drafted:status: in_review": a short summary in your own words (do not paste the email, do not copy addresses), what it asks, what should happen next, and a reply draft.`,
     `4. If a reply should be sent, PROPOSE it; the user approves it in Drafted: action(action="propose", type="send_email", payload=<a JSON object with "from":"${userEmail || '<the user\'s connected Gmail address>'}", "to": the sender's address from the From line, "subject": "Re: " plus the Subject line (unless it already starts with Re:), "body": your draft, "threadId":"${thread.gmailThreadId}"${messageId ? ', and "inReplyTo": the Message-ID line' : ''}>, reason="Reply to ${thread.title.replace(/"/g, "'")}"). If it is refused (for example Gmail is not connected for sending in Drafted), say so in the frame. Never send any other way.`,
     '5. Stop. Leave the thread marked as a new reply; the user clears it after reviewing your work.',
     '',

package/mcp/server.mjs

@@ -490,7 +490,7 @@ const TOOL_ANNOTATIONS = {
   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
-  minion:              { title: 'Minions',             readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage Minions: Drafted\'s agent for people OUTSIDE the org (bidders, clients, suppliers). A visitor opens a shareable /c/<slug>-<token> link (issued only to a person in Drafted — create returns url:null to an agent; tell the user to generate the link there), the Minion guides them through a checklist, writes ONE submission record into the project, and on submit marks it needs_review and queues it on output.handoff (a queue trigger) for YOUR agent to claim with trigger pending/claim/complete. A Minion never sends, shares or contacts anyone — outbound follow-up is your job. Everything in a Minion\'s config and its context pack is visible to anyone holding the link. Dispatch by `action`: meta, list, get, create, update, enable, disable, delete. QA your own Minions with test_start/test_say (works even when disabled). Requires the agent allowlist.' },
+  minion:              { title: 'Minions',             readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage Minions: Drafted\'s agent for people OUTSIDE the org (bidders, clients, suppliers). A visitor opens a shareable /c/<slug>-<token> link (issued only to a person in Drafted — create returns url:null to an agent; tell the user to generate the link there), the Minion guides them through a checklist, writes ONE submission record into the project, and on submit marks it in_review and queues it on output.handoff (a queue trigger) for YOUR agent to claim with trigger pending/claim/complete. A Minion never sends, shares or contacts anyone — outbound follow-up is your job. Everything in a Minion\'s config and its context pack is visible to anyone holding the link. Dispatch by `action`: meta, list, get, create, update, enable, disable, delete. QA your own Minions with test_start/test_say (works even when disabled). Requires the agent allowlist.' },
   trigger:             { title: 'Inbound triggers',    readOnlyHint: false, destructiveHint: true,  openWorldHint: true,  description: 'Manage inbound webhook triggers for the ACTIVE PROJECT: an external system (AppSheet bot, GitHub, form tool) POSTs to the trigger URL and the server runs an agent conversation in the project from the stored prompt template + payload. Dispatch by `action`: create (creates the trigger; its webhook URL + token are issued only to a person in Drafted — agent sessions get none, so tell the user to rotate it there), list, update (enable/disable, edit template, daily limit, executor), rotate (a person in the browser only), test (fire a synthetic delivery), deliveries (audit log), delete; for executor="queue" triggers, pending/claim/complete let a LOCAL agent poll and work queued deliveries. Requires the agent allowlist.' },
   fs:                  { title: 'Filesystem',           readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Navigate Drafted like a local filesystem: /wiki/<path> pages, /skills/<slug> procedures, /projects/<folder?>/<project>/<layer>/<lane>/<file> frames. Verbs: ls, read, write, edit, mv, rm, search, link, unlink, links.' },
   // Google Drive mirror triage. Mutating (resolve/retry_all/sync rewrite frame
@@ -3371,7 +3371,7 @@ server.resource('info', 'drafted://info', {
   };
 });
 
-tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single container and the org is the folder at depth 0: `fs(ls, path="/")` lists the orgs you can address, `/o/<org>` is that org, and every folder level — the org included — carries the SAME four roots:\n\n- `<folder>/wiki/<path>` — knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `<folder>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside; slugs stay unique per ORG, so a skill resolves by slug from anywhere)\n- `<folder>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. `drafted:assignee:` is a REFERENCE: write a member\'s email or userId (look them up with the `members` tool), or `agent:<name>` to assign an agent. A bare name is resolved against members by unique email local-part; an unknown or ambiguous one is REJECTED with the candidate list, never stored as free text. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: open, in_progress, scheduled, needs_review, needs_decision, done, failed (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task. `read` also projects `drafted:id:` (BEO-42), the org-scoped handle a human says out loud: READ-ONLY and server-allocated, so writing or inventing one is silently dropped rather than stored. Quote it back to the user; it resolves at /o/<org>/t/<id> and survives a rename or a move.\n- `<folder>/projects/<project>/<layer>/<lane>/<file>` — producible frames (then exactly layer → lane → file)\n\nFolders nest arbitrarily: `/o/<org>/engineering/backend/wiki/deploy`. The ROOT KEYWORD IS THE SEPARATOR — everything before `wiki`/`skills`/`tasks`/`projects` is the folder chain, everything after is the path inside that root, so `/o/<org>/wiki/engineering/foo` (the org wiki, nested page) and `/o/<org>/engineering/wiki/foo` (the engineering folder\'s wiki) are different pages. The four names are therefore RESERVED: a folder cannot be called one. `fs(ls, path="/o/<org>/<folder>")` shows a folder\'s four roots plus the folders inside it; `fs(mkdir, path="/o/<org>/<folder>")` creates one.\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org, at that org\'s root.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move — at THREE scopes, same as `rm`: a FILE path moves one frame; a LANE or LAYER path (`/<layer>/<lane>`, `/<layer>`) moves the whole set in one call, in-project or into another project, carrying frame ids, version history, connectors and assets; a PROJECT path (`/o/<org>/projects/<project>`) renames the project, with `to` as the new display name — the slug and every existing URL stay put), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/o/<org>")` fans out across wiki + skills + projects in one call. SEARCH MUST NAME ITS ORG — put it in the path, or pass org=. If you belong to more than one org an unaddressed search is REFUSED rather than silently scoped, because "no matches" from one org is indistinguishable from "nowhere" and you would stop looking. Search several orgs with one call each; every result says which org it came from), `link` / `unlink` / `links` (relate one frame to another frame, to a project, or to an external url — `links` lists a frame\'s edges plus its backlinks, and on a project path lists the tasks linked to that project; a link is stored by ID, so `mv` never breaks it). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, attached-skill gates fire on mutations, anchored frames must be read before editing a layer, `.skillinstall/` is stripped on skill push.', {
+tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single container and the org is the folder at depth 0: `fs(ls, path="/")` lists the orgs you can address, `/o/<org>` is that org, and every folder level — the org included — carries the SAME four roots:\n\n- `<folder>/wiki/<path>` — knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `<folder>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside; slugs stay unique per ORG, so a skill resolves by slug from anywhere)\n- `<folder>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. `drafted:assignee:` is a REFERENCE: write a member\'s email or userId (look them up with the `members` tool), or `agent:<name>` to assign an agent. A bare name is resolved against members by unique email local-part; an unknown or ambiguous one is REJECTED with the candidate list, never stored as free text. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: backlog, todo, in_progress, in_review, done, canceled (the six are the Linear set, and the names this system used to store -- open, scheduled, needs_review, needs_decision, failed -- are still ACCEPTED and normalised) (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task. `read` also projects `drafted:id:` (BEO-42), the org-scoped handle a human says out loud: READ-ONLY and server-allocated, so writing or inventing one is silently dropped rather than stored. Quote it back to the user; it resolves at /o/<org>/t/<id> and survives a rename or a move.\n- `<folder>/projects/<project>/<layer>/<lane>/<file>` — producible frames (then exactly layer → lane → file)\n\nFolders nest arbitrarily: `/o/<org>/engineering/backend/wiki/deploy`. The ROOT KEYWORD IS THE SEPARATOR — everything before `wiki`/`skills`/`tasks`/`projects` is the folder chain, everything after is the path inside that root, so `/o/<org>/wiki/engineering/foo` (the org wiki, nested page) and `/o/<org>/engineering/wiki/foo` (the engineering folder\'s wiki) are different pages. The four names are therefore RESERVED: a folder cannot be called one. `fs(ls, path="/o/<org>/<folder>")` shows a folder\'s four roots plus the folders inside it; `fs(mkdir, path="/o/<org>/<folder>")` creates one.\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org, at that org\'s root.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move — at THREE scopes, same as `rm`: a FILE path moves one frame; a LANE or LAYER path (`/<layer>/<lane>`, `/<layer>`) moves the whole set in one call, in-project or into another project, carrying frame ids, version history, connectors and assets; a PROJECT path (`/o/<org>/projects/<project>`) renames the project, with `to` as the new display name — the slug and every existing URL stay put), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/o/<org>")` fans out across wiki + skills + projects in one call. SEARCH MUST NAME ITS ORG — put it in the path, or pass org=. If you belong to more than one org an unaddressed search is REFUSED rather than silently scoped, because "no matches" from one org is indistinguishable from "nowhere" and you would stop looking. Search several orgs with one call each; every result says which org it came from), `link` / `unlink` / `links` (relate one frame to another frame, to a project, or to an external url — `links` lists a frame\'s edges plus its backlinks, and on a project path lists the tasks linked to that project; a link is stored by ID, so `mv` never breaks it). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, attached-skill gates fire on mutations, anchored frames must be read before editing a layer, `.skillinstall/` is stripped on skill push.', {
   action: z.enum(['ls', 'read', 'write', 'edit', 'mv', 'rm', 'mkdir', 'search', 'link', 'unlink', 'links']).describe('Filesystem verb.'),
   path: z.string().describe('Drafted path: /o/<org>[/<folder…>]/wiki/... | .../skills/... | .../tasks/... | .../projects/... — a folder chain may precede any root (bare /wiki, /skills, /tasks, /projects also work; for mv: source)'),
   to: z.string().optional().describe('[mv] destination — a frame path for a frame, a container path (/<layer> or /<layer>/<lane>, optionally prefixed /o/<org>/projects/<other-project>/… to move across projects) for a lane or layer, or the NEW NAME when the source path is a project; [link/unlink] target path — a frame path, or a project path (/o/<org>/projects/<project>) to link a task to a project'),
@@ -3668,7 +3668,11 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
       try { await api('PATCH', `/api/project/${created.id}`, { folder: projectFolder }, orgHeader); } catch { /* folder best-effort */ }
     }
     projectRefCache.set(projectRef, { id: created.id, slug: created.slug, name: created.name, orgId: created.orgId, orgSlug: created.orgSlug });
-    return ok({ created: true, name: created.name, slug: created.slug, id: created.id, path: `${folderBase}/projects/${created.slug}`, projectUrl: `${getServerUrl()}/o/${created.orgId || org || ''}/projects/${created.slug}` });
+    // The folder rides the same path the listing prints (ls shows
+    // /projects/<folder>/<slug>), so the mkdir receipt is feedable back in.
+    // Omitting it here is what made mkdir and ls disagree on where the project is.
+    const createdPath = [projectFolder, created.slug].filter(Boolean).join('/');
+    return ok({ created: true, name: created.name, slug: created.slug, id: created.id, folder: projectFolder || null, path: `${folderBase}/projects/${createdPath}`, projectUrl: `${getServerUrl()}/o/${created.orgId || org || ''}/projects/${createdPath}` });
   }
 
   // ── Root: /wiki/... ────────────────────────────────────────────
@@ -4214,16 +4218,45 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
           const scope = rmScope(layer, lane, filename);
           if (scope === 'project') {
             const pid = getState().projectId;
-            if (!pid) return err(new Error('could not resolve project id for rename'));
-            // `to` may be a bare new name or a full destination path — the last
-            // segment is the name either way.
-            const newName = String(to || '').replace(/^\/+|\/+$/g, '').split('/').filter(Boolean).pop();
-            if (!newName) return err(new Error('mv on a project path renames it — pass the new name, e.g. to="Onboarding — source of truth"'));
-            const renamed = await api('PATCH', `/api/project/${pid}`, { name: newName }, orgHeader);
+            if (!pid) return err(new Error('could not resolve project id for mv'));
             const meta = getState().projectMeta || {};
+            const destPath = `/o/${meta.orgSlug || orgFromPath || ''}/projects`;
+            const raw = String(to || '').replace(/^\/+|\/+$/g, '');
+            if (!raw) return err(new Error('mv on a project path needs a destination — a bare new display name to rename, or /o/<org>/projects/<folder>/<slug> to move it into a folder'));
+            // A destination that ADDRESSES a project (.../projects/<folder…>/<slug>)
+            // moves it into that folder; a bare name renames it. Both leave the slug
+            // (and every URL) alone. Before this, the last segment was always taken
+            // as a new display name, so a folder path renamed the project to its own
+            // slug and left it at the org root.
+            const segs = raw.split('/').filter(Boolean);
+            const at = segs.lastIndexOf('projects');
+            if (at !== -1) {
+              const after = segs.slice(at + 1);
+              const last = after[after.length - 1];
+              const folder = after.slice(0, -1).join('/');
+              if (!last || last !== meta.slug) {
+                return err(new Error(`mv moves a project into a folder but cannot change its slug — the destination must end with the current slug "${meta.slug}" (got "${last || ''}"). Pass a bare name to rename instead.`));
+              }
+              if (folder === (meta.folder || '')) {
+                return ok({
+                  moved: false, projectId: pid, folder: folder || null, name: meta.name, slug: meta.slug,
+                  path: `${destPath}/${[folder, meta.slug].filter(Boolean).join('/')}`,
+                  note: 'The project is already in that folder — nothing changed.',
+                });
+              }
+              const updated = await api('PATCH', `/api/project/${pid}`, { folder }, orgHeader);
+              return ok({
+                moved: true, projectId: pid, folder: folder || null,
+                name: updated?.name || meta.name, slug: meta.slug,
+                path: `${destPath}/${[folder, meta.slug].filter(Boolean).join('/')}`,
+                slugNote: 'Slug and URLs are UNCHANGED — a folder move sets the project\u2019s folder only, so links already shared keep working.',
+              });
+            }
+            // Bare name (no /projects segment) → rename, display name only.
+            const renamed = await api('PATCH', `/api/project/${pid}`, { name: raw }, orgHeader);
             return ok({
-              renamed: true, projectId: pid, name: renamed?.name || newName, slug: meta.slug,
-              path: `/o/${meta.orgSlug || orgFromPath || ''}/projects/${[meta.folder, meta.slug || pid].filter(Boolean).join('/')}`,
+              renamed: true, projectId: pid, name: renamed?.name || raw, slug: meta.slug,
+              path: `${destPath}/${[meta.folder, meta.slug || pid].filter(Boolean).join('/')}`,
               // Say this before the agent hands a human a URL it inferred from the
               // new name. Renaming is a DISPLAY-name change, exactly as in the web
               // UI: the slug is left alone so every link already shared keeps working.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.22.6",
+  "version": "1.22.7",
   "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",
   "bin": {

package/src/shared/excalidraw.mjs

@@ -58,13 +58,19 @@ 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.
+// Element-level merge for surgical edits: shallow-merge `upserts` ONTO the
+// existing element with the same id (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. 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.
+//
+// An id that does NOT exist is an ERROR, not an append. The silent-append shape
+// shipped first and bit an agent: a typo'd/changed id added a partial
+// `{id,strokeStyle,…}` object with no type/x/y beside the untouched original, so
+// the render kept showing the old element and the write reported ok. Adding
+// elements is a full-scene job (write_excalidraw); edit is for existing ones.
 export function mergeExcalidrawElements(existing, upserts = [], removeIds = []) {
   const scene = normalizeExcalidrawScene(existing);
   const removeSet = new Set(Array.isArray(removeIds) ? removeIds : []);
@@ -78,7 +84,11 @@ export function mergeExcalidrawElements(existing, upserts = [], removeIds = [])
       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);
+    const prev = byId.get(el.id);
+    if (!prev) {
+      throw new Error(`No element with id "${el.id}" in this scene — element-level edit updates existing elements; write the whole scene (write_excalidraw) to add or replace one.`);
+    }
+    byId.set(el.id, { ...prev, ...el });
   }
   return { ...scene, elements: Array.from(byId.values()) };
 }

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

@@ -18,9 +18,8 @@ assert.deepStrictEqual(r.elements.map(e => e.id), ['a', 'b', 'c'], 'order preser
 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');
+// add of an unknown id is an error, not an append (silent append shipped once)
+assert.throws(() => mergeExcalidrawElements(base, [{ id: 'd', type: 'diamond', x: 5 }]), /No element with id/);
 
 // remove drops by id
 r = mergeExcalidrawElements(base, [], ['a', 'c']);
@@ -31,8 +30,8 @@ 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');
+r = mergeExcalidrawElements(JSON.stringify(base), [{ id: 'a', x: 42 }]);
+assert.strictEqual(r.elements[0].x, 42, 'parses stored string content and merges');
 
 // linear elements without points are repaired (Excalidraw crashes on restore otherwise)
 r = mergeExcalidrawElements({