@1agh/maude 1.0.11 → 1.3.0

package/apps/studio/api.ts

@@ -2,7 +2,7 @@
 // Returns plain objects; http.ts wraps them in Response.json().
 
 import crypto from 'node:crypto';
-import type { Dirent } from 'node:fs';
+import { type Dirent, renameSync } from 'node:fs';
 import {
   lstat,
   mkdir,
@@ -17,7 +17,11 @@ import path from 'node:path';
 import { createAssetMirror, s3ConfigFromEnv } from './assets-s3.ts';
 import { canvasArtifacts, locatorKeyFor, relocatedName } from './canvas-artifacts.ts';
 import { renderBriefBoard, validateCanvasName, validateFolderName } from './canvas-create.ts';
+import { rewriteRelativeImports } from './canvas-imports.ts';
 import { canvasSlugFromRel } from './canvas-slug.ts';
+import { atomicWrite } from './sync/atomic-write.ts';
+import { dedupeCommentsById } from './sync/comment-identity.ts';
+import { isRuntimeStateRel } from './sync/file-membership.ts';
 
 // Re-exported so existing external callers (canvas-list-watch.ts, tests) keep
 // importing it from api.ts — the actual implementation now lives in
@@ -25,8 +29,19 @@ import { canvasSlugFromRel } from './canvas-slug.ts';
 // without a cycle back through api.ts.
 export { canvasSlugFromRel } from './canvas-slug.ts';
 
+/** Plan T17/L03 — the supporting files the file tree can move, rename and
+ *  delete: what it previews (notes, styles, data, images, media, fonts), minus
+ *  the canvas's own sidecars, which only ever travel with their canvas. */
+export function isSupportingFileRel(rel: string): boolean {
+  if (/\.(meta\.json|annotations\.svg|registry\.json)$/i.test(rel)) return false;
+  return /\.(md|css|json|txt|ya?ml|svg|png|jpe?g|gif|webp|avif|mp4|webm|mov|mp3|wav|ogg|m4a|woff2?|ttf|otf)$/i.test(
+    rel
+  );
+}
+
 import {
   type AssembleClip,
+  type AttributeState,
   assembleCompSource,
   CanvasEditError,
   type ClipInfo,
@@ -60,6 +75,7 @@ import {
   setArtboardGuides,
   setArtboardHug,
   setArtboardKind,
+  setArtboardLabel,
   setArtboardPrint,
   setArtboardStyle,
   toggleClipHidden,
@@ -99,6 +115,7 @@ import { clearLocatorSlug, readLocator, writeLocator } from './locator.ts';
 import { STICKERS_DIR } from './paths.ts';
 import { getPaperPreset, MAX_PRINT_MM } from './print/units.ts';
 import { sessionDir } from './session-scope.ts';
+import { describeSourceOp } from './sync/source-ops.ts';
 import { isWorkspaceMode } from './workspace-mode.ts';
 
 // Directories that never hold user-facing canvases. Exported so the
@@ -309,8 +326,27 @@ export type CreateFolderResult =
 
 /** Phase 12 — result of an in-canvas direct edit (`editCss` / `editText`). */
 export type EditOpResult =
-  | { ok: true; delta: number; seq?: number }
-  | { ok: false; status: number; error: string };
+  /** `previous` — what a css/attr write replaced (`null` = was unset); absent
+   *  when it was an expression no literal undo can restore. */
+  | { ok: true; delta: number; seq?: number; previous?: string | null }
+  /** `conflict` = the target no longer held the caller's expected value. */
+  | { ok: false; status: number; error: string; conflict?: true };
+
+/**
+ * Optional expected-current value for a css/attr write (audit 2026-09-13 P1
+ * #5). An absent `expected` key keeps the unconditional legacy behaviour; a
+ * present one must be a bounded string or `null` ("currently unset").
+ */
+function expectedValueOf(input: {
+  expected?: unknown;
+}): { ok: true; expected?: string | null } | { ok: false } {
+  if (!Object.hasOwn(input, 'expected') || input.expected === undefined) return { ok: true };
+  if (input.expected === null) return { ok: true, expected: null };
+  if (typeof input.expected === 'string' && input.expected.length <= 256) {
+    return { ok: true, expected: input.expected };
+  }
+  return { ok: false };
+}
 
 /**
  * Phase 12.1 (DDR-138) — result of a node-move reorder. Carries the re-settle
@@ -371,7 +407,9 @@ export interface Api {
   ): Promise<Record<string, unknown> | null>;
   // Annotations sidecar (Phase 5 — .design/<slug>.annotations.svg)
   loadAnnotations(file: string): Promise<string | null>;
-  saveAnnotations(file: string, svg: string): Promise<boolean>;
+  saveAnnotations(file: string, svg: string, writeId?: string, base?: string): Promise<boolean>;
+  /** Materialize a document snapshot without publishing it as another user edit. */
+  projectAnnotations(file: string, svg: string, isCurrent: () => boolean): Promise<boolean>;
   // Phase 23 — content-addressed binary image write (drag-drop / paste / picker)
   saveAsset(bytes: Uint8Array): Promise<SaveAssetResult>;
   /** Stage F1 — list content-addressed image/video assets for the AssetPicker. */
@@ -422,6 +460,10 @@ export interface Api {
     width?: unknown;
     height?: unknown;
   }): Promise<CreateCanvasResult>;
+  // Duplicate a canvas beside itself ("<name> copy") — POST /_api/canvas
+  // { duplicateOf }. Source, meta and the whiteboard layer; not comments or
+  // history, which belong to the original.
+  duplicateCanvas(input: { file?: unknown }): Promise<CreateCanvasResult>;
   // Soft-delete a canvas from the browser (Phase 22 — DELETE /_api/canvas)
   deleteCanvas(input: { file?: unknown }): Promise<DeleteCanvasResult>;
   // feature-file-tree-drag-drop-folders (Task 3) — move/rename a canvas + its
@@ -439,6 +481,8 @@ export interface Api {
     value?: unknown;
     reset?: unknown;
     idIndex?: unknown;
+    /** Expected current value (string) or `null` = currently unset. Absent = unconditional. */
+    expected?: unknown;
   }): Promise<EditOpResult>;
   // Phase 12 (DDR-103) — inline text-content edit (POST /_api/edit-text). Main-origin only.
   editText(input: {
@@ -456,6 +500,8 @@ export interface Api {
     id?: unknown;
     attr?: unknown;
     value?: unknown;
+    reset?: unknown;
+    expected?: unknown;
   }): Promise<EditOpResult>;
   // Phase 12.1 (DDR-138) — node-move reorder (POST /_api/reorder). Main-origin
   // only. Moves the element with data-cd-id `id` to `position` relative to
@@ -659,6 +705,12 @@ export interface Api {
     artboardId?: unknown;
     kind?: unknown;
   }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
+  /** Rename an artboard (T25/L08 — double-click its name on the canvas). */
+  setArtboardLabelOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    label?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }>;
   /** Generic layout guides (T5) — replace-whole-prop write. */
   setArtboardGuidesOp(input: {
     canvas?: unknown;
@@ -720,9 +772,39 @@ export interface Api {
 }
 
 export interface ApiHooks {
-  onCommentsChanged: (file: string) => void;
+  /**
+   * Publish a comments mutation to the SHARED DOC (and the shell's sidebar).
+   *
+   * `comments` is the post-mutation list, handed over IN MEMORY — issue #111.
+   * The hook used to take only `file` and re-read `_comments/<slug>.json`
+   * itself, which put a full disk round-trip between the mutation's write and
+   * the doc publish. `Room.flush()` fires on ANY doc update (every hub update
+   * re-arms it), so on a hub-linked project a flush landed inside that window,
+   * projected the PRE-mutation doc back over the file, and the new comment was
+   * gone before the hook's own read reached it — "only the first comment
+   * stays". Passing the list removes the read, and `publishComments` awaits
+   * this hook BEFORE touching disk so the doc is never the stale side.
+   */
+  /** `base` — the list this mutation started from (a merge hint for the project). */
+  onCommentsChanged: (file: string, comments: Comment[], base?: Comment[]) => void | Promise<void>;
   /** Phase 8 Task 5 — fires after a successful PUT /_api/annotations write. */
-  onAnnotationsChanged?: (file: string, svg: string) => void;
+  onAnnotationsChanged?: (file: string, svg: string, writeId?: string, base?: string) => void;
+  /**
+   * Accepted-revisions mode (DDR-241): propose a folder operation as ONE
+   * project action before touching disk. Absent, or answering `null`, means
+   * the project is not in that mode and the local operation is the whole story.
+   */
+  /**
+   * A layout (shared meta) write, with the file text it replaced — accepted
+   * revisions propose it with that base instead of inferring one.
+   */
+  onMetaChanged?: (file: string, text: string, baseText: string | null) => void;
+  proposeFolder?: (
+    op:
+      | { op: 'dir.create'; path: string }
+      | { op: 'dir.delete'; path: string }
+      | { op: 'dir.move'; from: string; to: string }
+  ) => Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean }> | null;
   /**
    * feature-file-tree-drag-drop-folders (Task 3) — is a collab room pinned
    * (a shared-doc hub provider attached, DDR-064)? `moveCanvas` refuses the
@@ -993,7 +1075,10 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   // stores in its undo record. Ephemeral by design: a server restart drops it
   // (undo answers 404 and the canvas stack entry is a no-op, honest failure).
   const REORDER_LOG_CAP = 50;
-  const reorderLog = new Map<number, { abs: string; before: string; after: string }>();
+  const reorderLog = new Map<
+    number,
+    { abs: string; before: string; after: string; undoActionId?: string }
+  >();
   let reorderSeq = 0;
 
   // DDR-150 dogfood #1 — the SAME whole-file log backs the Timeline clip ops
@@ -1095,7 +1180,14 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       // Phase 6 — default-fill `author` / `thread` / `mentions` for legacy
       // rows. No write-back here; the on-disk shape stays stable until the
       // next mutation persists the upgraded record.
-      return arr.map(backfillComment);
+      //
+      // Deduped by comment identity first (issue #112). This is the read half
+      // of the repair: a project whose `_comments/<slug>.json` was already
+      // doubled by the pre-fix sync lane heals the moment it is loaded, and no
+      // consumer — pins, sidebar, `/_comments`, the /design:edit agent — ever
+      // sees the same comment eight times. First occurrence wins, matching the
+      // rule the codec and the cold-start union use.
+      return dedupeCommentsById(arr).map(backfillComment);
     } catch {
       return [];
     }
@@ -1135,7 +1227,39 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   }
 
   async function saveCommentsForFile(file: string, list: Comment[]) {
-    await Bun.write(commentsPath(file), JSON.stringify(list, null, 2));
+    // The write half of the #112 repair, and the reason it belongs HERE: this
+    // is the one choke point every writer passes through — the API mutations,
+    // and the collab room's `persistJson`, which materializes the Y.Array
+    // straight to disk. Deduping at the door means a doc caught mid-convergence
+    // (or a peer still running the old wholesale write) cannot persist a
+    // duplicated list as the canvas's new truth, which is how the doubling
+    // survived restarts and compounded.
+    await Bun.write(commentsPath(file), JSON.stringify(dedupeCommentsById(list), null, 2));
+  }
+
+  /**
+   * Land one comments mutation: SHARED DOC FIRST, disk second (issue #111).
+   *
+   * The order is the fix, not a style choice. Under DDR-064 the room's Y.Doc is
+   * the shared object and `_comments/<slug>.json` is its projection — and
+   * `Room.flush()` projects doc→file on an 800 ms trailing debounce that ANY
+   * doc update re-arms, hub traffic included. So on a linked project a flush is
+   * almost always pending, and any window in which the doc is behind the file
+   * is a window in which that flush silently writes the older list back.
+   *
+   * Publishing to the doc first removes the window instead of narrowing it: a
+   * flush firing at any point from here on carries a doc that already holds the
+   * mutation. Both halves are awaited, so the HTTP response cannot report a
+   * comment the doc never received.
+   *
+   * The list is deduped ONCE here so the doc and the file are handed byte-equal
+   * content — otherwise the file→doc import that follows the write would see a
+   * difference and re-enter the loop.
+   */
+  async function publishComments(file: string, list: Comment[], base?: Comment[]): Promise<void> {
+    const settled = dedupeCommentsById(list);
+    await onCommentsChanged(file, settled, base ? dedupeCommentsById(base) : undefined);
+    await saveCommentsForFile(file, settled);
   }
 
   async function loadAllComments(): Promise<Record<string, Comment[]>> {
@@ -1266,6 +1390,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     if (!payload || typeof payload.file !== 'string' || !payload.file) return null;
     if (typeof payload.text !== 'string' || !payload.text.trim()) return null;
     const list = await loadCommentsForFile(payload.file);
+    const base = structuredClone(list);
     const text = String(payload.text).trim().slice(0, 4000);
     const author =
       typeof payload.author === 'string' && payload.author.trim()
@@ -1314,8 +1439,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       if (anchor.clipStableId != null || anchor.frame != null) c.timeline = anchor;
     }
     list.push(c);
-    await saveCommentsForFile(payload.file, list);
-    onCommentsChanged(payload.file);
+    await publishComments(payload.file, list, base);
     return c;
   }
 
@@ -1330,6 +1454,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       if (i < 0) continue;
       const entry = list[i];
       if (!entry) continue;
+      const base = structuredClone(list);
       const body = payload.body.trim().slice(0, 4000);
       const author =
         typeof payload.author === 'string' && payload.author.trim()
@@ -1343,31 +1468,39 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       };
       entry.thread = [...entry.thread, reply];
       entry.mentions = mentionsUnion(entry);
-      await saveCommentsForFile(file, list);
-      onCommentsChanged(file);
+      await publishComments(file, list, base);
       return entry;
     }
     return null;
   }
 
+  // Mutations are ID-TOTAL, not first-match (issue #112). `loadAllComments`
+  // dedupes, so under normal operation there is exactly one entry per id and
+  // these behave as they always did. They stay total as defense in depth: the
+  // reporter's second symptom — "I can't then close or resolve the comments" —
+  // was a `findIndex` + `return` marking copy 1 of 8 resolved while the overlay
+  // (which filters `status !== 'resolved'`) kept drawing the other seven, and a
+  // delete removing one copy per click. A duplicated list can still reach these
+  // from an older peer mid-upgrade; resolve must resolve either way.
   async function commentsPatch(id: string, patch: Partial<Comment>) {
     const all = await loadAllComments();
     for (const [file, list] of Object.entries(all)) {
-      const i = list.findIndex((c) => c.id === id);
-      if (i < 0) continue;
-      const entry = list[i];
-      if (!entry) continue;
-      if (patch.status === 'resolved' || patch.status === 'open') {
-        entry.status = patch.status;
-        entry.resolved_at = patch.status === 'resolved' ? new Date().toISOString() : null;
-      }
-      if (typeof patch.text === 'string' && patch.text.trim()) {
-        entry.text = patch.text.trim().slice(0, 4000);
-        entry.mentions = mentionsUnion(entry);
+      const matches = list.filter((c) => c.id === id);
+      const first = matches[0];
+      if (!first) continue;
+      const base = structuredClone(list);
+      for (const entry of matches) {
+        if (patch.status === 'resolved' || patch.status === 'open') {
+          entry.status = patch.status;
+          entry.resolved_at = patch.status === 'resolved' ? new Date().toISOString() : null;
+        }
+        if (typeof patch.text === 'string' && patch.text.trim()) {
+          entry.text = patch.text.trim().slice(0, 4000);
+          entry.mentions = mentionsUnion(entry);
+        }
       }
-      await saveCommentsForFile(file, list);
-      onCommentsChanged(file);
-      return entry;
+      await publishComments(file, list, base);
+      return first;
     }
     return null;
   }
@@ -1375,11 +1508,9 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   async function commentsDelete(id: string): Promise<boolean> {
     const all = await loadAllComments();
     for (const [file, list] of Object.entries(all)) {
-      const i = list.findIndex((c) => c.id === id);
-      if (i < 0) continue;
-      list.splice(i, 1);
-      await saveCommentsForFile(file, list);
-      onCommentsChanged(file);
+      const remaining = list.filter((c) => c.id !== id);
+      if (remaining.length === list.length) continue;
+      await publishComments(file, remaining, list);
       return true;
     }
     return false;
@@ -1887,7 +2018,10 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       next.last_modified = new Date().toISOString();
       // Trailing newline — consistent with canvas-create.ts + sync/codec.ts
       // (mergeSharedMetaIntoLocal), so a layout edit doesn't churn the newline.
-      await Bun.write(metaAbs, `${JSON.stringify(next, null, 2)}\n`);
+      const baseText = Object.keys(current).length ? JSON.stringify(current) : null;
+      const nextText = `${JSON.stringify(next, null, 2)}\n`;
+      await Bun.write(metaAbs, nextText);
+      hooks.onMetaChanged?.(file, nextText, baseText);
       // Same reason as the annotations sidecar below, and the same bug: this
       // lane writes the FILE and nothing else, so in a cell — where there is no
       // `fs.watch` — the layout never entered the doc and never reached a peer.
@@ -1927,7 +2061,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
-  async function saveAnnotations(file: string, svg: string): Promise<boolean> {
+  async function saveAnnotations(
+    file: string,
+    svg: string,
+    writeId?: string,
+    base?: string
+  ): Promise<boolean> {
     if (typeof svg !== 'string') return false;
     if (svg.length > 1024 * 1024) return false;
     // Cheap content gate — must look like an <svg> document. Avoids accidental
@@ -1945,8 +2084,18 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // (strokesToSvg) is purely presentational — path/rect/ellipse/g/line/
     // polyline/text — so stripping executable constructs is zero-regression.
     const clean = sanitizeAnnotationSvg(svg);
+    // The edit's base travels only as a merge hint for the project — bounded
+    // and sanitized like the value itself, never written anywhere.
+    const cleanBase =
+      typeof base === 'string' &&
+      base.length <= 1024 * 1024 &&
+      (base === '' || /^\s*<svg[\s>]/i.test(base))
+        ? base === ''
+          ? ''
+          : sanitizeAnnotationSvg(base)
+        : undefined;
     await Bun.write(annotationsPath(file), clean);
-    onAnnotationsChanged?.(file, clean);
+    onAnnotationsChanged?.(file, clean, writeId, cleanBase);
     // Annotations reach OTHER VIEWERS over the collab room, which is why this
     // never needed an `fs:any`. But the file is also a versioned, file-plane
     // sidecar (DDR-115), and the file plane learns about a cell's own writes
@@ -1957,6 +2106,32 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return true;
   }
 
+  async function projectAnnotations(
+    file: string,
+    svg: string,
+    isCurrent: () => boolean
+  ): Promise<boolean> {
+    if (typeof svg !== 'string' || svg.length > 1024 * 1024 || !/^\s*<svg[\s>]/i.test(svg))
+      return false;
+    if (!isCurrent()) return false;
+    const clean = sanitizeAnnotationSvg(svg);
+    // Runtime scratch stays out of the file plane. The async IO must not touch
+    // the serving file until we recheck the document; another edit may have
+    // arrived while Bun.write was pending. Check + rename have no await gap.
+    const scratch = path.join(paths.designRoot, '_state');
+    await mkdir(scratch, { recursive: true });
+    const temp = path.join(scratch, `annotations-${crypto.randomUUID()}.tmp`);
+    try {
+      await Bun.write(temp, clean);
+      if (!isCurrent()) return false;
+      renameSync(temp, annotationsPath(file));
+      announceWritten(`${fileSlug(file)}.annotations.svg`);
+      return true;
+    } finally {
+      await rm(temp, { force: true });
+    }
+  }
+
   // Phase 23 — content-addressed asset write. Reachable from the (potentially
   // untrusted, DDR-054) canvas origin, so every cap is load-bearing, NOT
   // optional (DDR Task 9):
@@ -2695,6 +2870,91 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return { ok: true, file: path.posix.join(paths.designRel, rel), rel, slug };
   }
 
+  async function duplicateCanvas(input: { file?: unknown }): Promise<CreateCanvasResult> {
+    const raw = input?.file;
+    if (typeof raw !== 'string' || !raw.trim()) {
+      return { ok: false, status: 400, error: 'file is required' };
+    }
+    let rel = raw.trim();
+    try {
+      rel = decodeURIComponent(rel);
+    } catch {
+      /* leave as-is */
+    }
+    rel = rel.replace(/^\/+/, '');
+    const drPrefix = paths.designRel.replace(/^\/+|\/+$/g, '');
+    if (rel.startsWith(`${drPrefix}/`)) rel = rel.slice(drPrefix.length + 1);
+    if (rel.includes('..') || !/\.tsx$/i.test(rel)) {
+      return { ok: false, status: 400, error: 'invalid path' };
+    }
+    const fileAbs = path.resolve(path.join(paths.designRoot, rel));
+    const dirAbs = path.dirname(fileAbs);
+    const groups = cfg.canvasGroups.filter(
+      (g) => g.label !== 'Design system' && !/^system(\/|$)/.test(g.path)
+    );
+    const inGroup = groups.some((g) => {
+      const gAbs = path.resolve(path.join(paths.designRoot, g.path));
+      return dirAbs === gAbs || dirAbs.startsWith(`${gAbs}${path.sep}`);
+    });
+    if (!inGroup) {
+      return {
+        ok: false,
+        status: 400,
+        error: 'only canvases under a managed canvas group can be duplicated',
+      };
+    }
+    if (!(await assertRealpathContained(dirAbs))) {
+      return { ok: false, status: 400, error: 'source path escapes the design root via a symlink' };
+    }
+    if (!(await Bun.file(fileAbs).exists())) {
+      return { ok: false, status: 404, error: 'canvas not found' };
+    }
+    const base = path.basename(rel).replace(/\.tsx$/i, '');
+    const dir = path.posix.dirname(rel) === '.' ? '' : path.posix.dirname(rel);
+    // "<name> copy", then "<name> copy 2", … — the first free, valid name.
+    let name: string | null = null;
+    for (let n = 1; n < 100 && !name; n++) {
+      const suffix = n === 1 ? ' copy' : ` copy ${n}`;
+      const v = validateCanvasName(`${base.slice(0, 60 - suffix.length)}${suffix}`);
+      if (!v.ok || !v.name) return { ok: false, status: 400, error: v.error ?? 'invalid name' };
+      const candidate = path.posix.join(dir, `${v.name}.tsx`);
+      if (await Bun.file(path.join(paths.designRoot, candidate)).exists()) continue;
+      if (await fileForSlug(fileSlug(candidate))) continue;
+      name = v.name;
+    }
+    if (!name) return { ok: false, status: 409, error: 'too many copies of this canvas' };
+    const toRel = path.posix.join(dir, `${name}.tsx`);
+    const toAbs = path.join(paths.designRoot, toRel);
+    await Bun.write(toAbs, await Bun.file(fileAbs).arrayBuffer());
+    const metaAbs = fileAbs.replace(/\.tsx$/i, '.meta.json');
+    if (await Bun.file(metaAbs).exists()) {
+      let text = await Bun.file(metaAbs).text();
+      try {
+        const meta = JSON.parse(text) as Record<string, unknown>;
+        const now = new Date().toISOString();
+        if (typeof meta.title !== 'string' || meta.title === base) meta.title = name;
+        meta.created = now;
+        meta.last_modified = now;
+        text = `${JSON.stringify(meta, null, 2)}\n`;
+      } catch {
+        /* an unreadable meta is copied verbatim, like the source */
+      }
+      await Bun.write(toAbs.replace(/\.tsx$/i, '.meta.json'), text);
+    }
+    const slug = fileSlug(toRel);
+    // The whiteboard layer is slug-keyed at the design root (canvas-artifacts).
+    const annotationsAbs = path.join(paths.designRoot, `${fileSlug(rel)}.annotations.svg`);
+    if (await Bun.file(annotationsAbs).exists()) {
+      await Bun.write(
+        path.join(paths.designRoot, `${slug}.annotations.svg`),
+        await Bun.file(annotationsAbs).arrayBuffer()
+      );
+    }
+    ctx.bus.emit('canvas-list-update', { action: 'added', rel: toRel, slug });
+    ctx.bus.emit('canvas-created', { slug });
+    return { ok: true, file: path.posix.join(paths.designRel, toRel), rel: toRel, slug };
+  }
+
   // Phase 22 — SOFT-delete a canvas (DELETE /_api/canvas). Same trust boundary as
   // createCanvas: main-origin-only, never the untrusted canvas iframe origin
   // (DDR-054). Destructive, so it MOVES the whole sidecar set to
@@ -2718,6 +2978,13 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
 
     // Only a real `.tsx` canvas, no traversal.
     if (rel.includes('..')) return { ok: false, status: 400, error: 'invalid path' };
+    if (
+      !/\.tsx$/i.test(rel) &&
+      isSupportingFileRel(rel) &&
+      (await isRegularFile(path.join(paths.designRoot, rel)))
+    ) {
+      return deleteSupportingFile(rel);
+    }
     if (!/\.tsx$/i.test(rel)) {
       // feature-file-tree-drag-drop-folders (follow-up) — a non-.tsx target is
       // a folder delete (dogfood gap: the tree offered no way to remove a
@@ -2827,6 +3094,170 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   // itself (same `_trash/<stamp>__<slug>/` bundle shape, so a folder delete
   // is recoverable exactly like a single-canvas delete), then best-effort
   // removes whatever's left (empty subdirs, `.gitkeep` markers).
+  // ── Plan T17/L03 — supporting files ──────────────────────────────────────
+  // Notes, styles, data, images, media and fonts that live in a canvas folder
+  // beside the canvases. They move, rename and delete as themselves. One that a
+  // canvas, stylesheet or whiteboard still names is refused with the name of
+  // the file that uses it: a moved or deleted asset must never leave a broken
+  // image behind silently (L17).
+  async function isRegularFile(abs: string): Promise<boolean> {
+    try {
+      return (await statp(abs)).isFile();
+    } catch {
+      return false;
+    }
+  }
+
+  async function supportingFileGuard(
+    rel: string
+  ): Promise<{ ok: true; abs: string } | { ok: false; status: number; error: string }> {
+    if (rel.includes('..') || rel.startsWith('/') || isRuntimeStateRel(rel)) {
+      return { ok: false, status: 400, error: 'invalid path' };
+    }
+    const abs = path.resolve(path.join(paths.designRoot, rel));
+    const groups = cfg.canvasGroups.filter(
+      (g) => g.label !== 'Design system' && !/^system(\/|$)/.test(g.path)
+    );
+    const inGroup = groups.some((g) =>
+      abs.startsWith(`${path.resolve(path.join(paths.designRoot, g.path))}${path.sep}`)
+    );
+    if (!inGroup) {
+      return {
+        ok: false,
+        status: 400,
+        error: 'only files inside a canvas folder can be changed here',
+      };
+    }
+    if (!(await assertRealpathContained(path.dirname(abs)))) {
+      return { ok: false, status: 400, error: 'path escapes the design root via a symlink' };
+    }
+    if (!(await isRegularFile(abs))) return { ok: false, status: 404, error: 'file not found' };
+    return { ok: true, abs };
+  }
+
+  /** The first project file (canvas, stylesheet, meta, whiteboard) that names `rel`'s file. */
+  async function firstReferenceTo(rel: string): Promise<string | null> {
+    const base = path.posix.basename(rel);
+    const { readdir, readFile } = await import('node:fs/promises');
+    const walk = async (dirAbs: string, depth: number): Promise<string | null> => {
+      if (depth > 12) return null;
+      let entries: import('node:fs').Dirent[];
+      try {
+        entries = await readdir(dirAbs, { withFileTypes: true });
+      } catch {
+        return null;
+      }
+      for (const e of entries) {
+        if (e.name.startsWith('_') || e.name.startsWith('.') || e.name === 'node_modules') continue;
+        const abs = path.join(dirAbs, e.name);
+        if (e.isDirectory()) {
+          const hit = await walk(abs, depth + 1);
+          if (hit) return hit;
+        } else if (/\.(tsx|jsx|css|meta\.json|annotations\.svg)$/i.test(e.name)) {
+          const other = path.relative(paths.designRoot, abs).split(path.sep).join('/');
+          if (other === rel) continue;
+          const text = await readFile(abs, 'utf8').catch(() => '');
+          if (text.includes(base)) return other;
+        }
+      }
+      return null;
+    };
+    return walk(paths.designRoot, 0);
+  }
+
+  async function moveSupportingFile(
+    rel: string,
+    toDirRaw: unknown,
+    toNameRaw: unknown
+  ): Promise<MoveCanvasResult> {
+    const g = await supportingFileGuard(rel);
+    if (!g.ok) return g;
+    const ext = path.posix.extname(rel);
+    let base = path.posix.basename(rel);
+    if (toNameRaw !== undefined && toNameRaw !== null && toNameRaw !== '') {
+      const stem = String(toNameRaw).replace(new RegExp(`${ext.replace('.', '\\.')}$`, 'i'), '');
+      const v = validateCanvasName(stem);
+      if (!v.ok || !v.name) return { ok: false, status: 400, error: v.error ?? 'invalid name' };
+      base = `${v.name}${ext}`;
+    }
+    const drPrefix = paths.designRel.replace(/^\/+|\/+$/g, '');
+    let toDir =
+      typeof toDirRaw === 'string'
+        ? toDirRaw.trim().replace(/^\/+|\/+$/g, '')
+        : path.posix.dirname(rel);
+    if (toDir === drPrefix || toDir === '.') toDir = '';
+    else if (toDir.startsWith(`${drPrefix}/`)) toDir = toDir.slice(drPrefix.length + 1);
+    const toRel = path.posix.join(toDir, base);
+    if (toRel === rel)
+      return { ok: false, status: 400, error: 'source and destination are the same' };
+    const dest = await supportingFileGuard(toRel).then((d) =>
+      d.ok
+        ? { ok: false as const, status: 409, error: `a file named "${base}" already exists there` }
+        : d
+    );
+    if (!dest.ok && dest.status !== 404) return dest;
+    const toAbs = path.resolve(path.join(paths.designRoot, toRel));
+    if (!(await isRegularFile(path.join(paths.designRoot, rel))))
+      return { ok: false, status: 404, error: 'file not found' };
+    const toDirAbs = path.dirname(toAbs);
+    try {
+      if (!(await statp(toDirAbs)).isDirectory()) throw new Error('not a folder');
+    } catch {
+      return { ok: false, status: 400, error: 'destination folder does not exist' };
+    }
+    const user = await firstReferenceTo(rel);
+    if (user) {
+      return {
+        ok: false,
+        status: 409,
+        error: `${path.posix.basename(rel)} is used by ${user} — change that first`,
+      };
+    }
+    await rename(g.abs, toAbs);
+    ctx.bus.emit('canvas-list-update', {
+      action: 'moved',
+      rel: toRel,
+      slug: fileSlug(toRel),
+      fromRel: rel,
+      fromSlug: fileSlug(rel),
+    });
+    return {
+      ok: true,
+      fromRel: rel,
+      toRel,
+      fromSlug: fileSlug(rel),
+      toSlug: fileSlug(toRel),
+      moved: [toRel],
+    };
+  }
+
+  async function deleteSupportingFile(rel: string): Promise<DeleteCanvasResult> {
+    const g = await supportingFileGuard(rel);
+    if (!g.ok) return g;
+    const user = await firstReferenceTo(rel);
+    if (user) {
+      return {
+        ok: false,
+        status: 409,
+        error: `${path.posix.basename(rel)} is used by ${user} — remove it there first`,
+      };
+    }
+    const slug = fileSlug(rel);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const trashDir = path.join(paths.designRoot, '_trash', `${stamp}__${slug}`);
+    await mkdir(trashDir, { recursive: true });
+    const trashed = path.join(trashDir, path.posix.basename(rel));
+    await rename(g.abs, trashed);
+    ctx.bus.emit('canvas-list-update', { action: 'removed', rel, slug });
+    return {
+      ok: true,
+      rel,
+      slug,
+      trashed: [path.relative(paths.repoRoot, trashed)],
+      trashDir: path.relative(paths.repoRoot, trashDir),
+    };
+  }
+
   async function deleteFolder(relDir: string): Promise<DeleteCanvasResult> {
     if (relDir.includes('..')) return { ok: false, status: 400, error: 'invalid path' };
     const dirAbs = path.join(paths.designRoot, relDir);
@@ -2883,6 +3314,21 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       p.startsWith(`${drPrefix}/`) ? p.slice(drPrefix.length + 1) : p
     );
 
+    // ONE project action for the whole folder (accepted-revisions mode): the
+    // hub deletes every canvas under it and the folder entry together, so a
+    // peer never sees half a folder, and history shows one step.
+    const folderAction = await hooks.proposeFolder?.({
+      op: 'dir.delete',
+      path: relDir.replace(/\\/g, '/').replace(/^\/+|\/+$/g, ''),
+    });
+    if (folderAction?.status === 'rejected') {
+      return {
+        ok: false,
+        status: 409,
+        error: `the project did not accept deleting this folder (${folderAction.code ?? 'rejected'})`,
+      };
+    }
+
     const trashed: string[] = [];
     let lastTrashDir = '';
     for (const r of canvasRels) {
@@ -2946,6 +3392,44 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return realTarget === realRoot || realTarget.startsWith(`${realRoot}${path.sep}`);
   }
 
+  /**
+   * Re-root a moved canvas's relative imports for its new folder depth
+   * (issue #114). `fromDir` / `toDir` are POSIX, design-root-relative.
+   *
+   * Runs AFTER the rename, on the file at its destination. Best-effort by
+   * design: the move has already committed, and failing it here would leave a
+   * half-moved tree — strictly worse than the un-rewritten imports that were
+   * the status quo. A no-op rewrite writes nothing.
+   */
+  async function rewriteCanvasImports(abs: string, fromDir: string, toDir: string): Promise<void> {
+    if (fromDir === toDir) return;
+    try {
+      // NEVER DEREFERENCE A SYMLINK HERE. The move's containment checks cover
+      // the source *directory* (`assertRealpathContained(path.dirname(...))`)
+      // and the destination, but never the source FILE — which was inert while
+      // the move was a bare `rename()`, because renaming a symlink moves the
+      // LINK and no out-of-root byte is ever touched. This function is the
+      // first code on the path that reads and writes the file's contents, so
+      // without this guard a planted `ui/evil.tsx -> /elsewhere/secrets.ts`
+      // would turn an ordinary drag-and-drop into an out-of-root read AND an
+      // out-of-root write. `lstat` does not follow; a link is skipped, not
+      // repaired — its target is not ours to rewrite.
+      const st = await lstat(abs);
+      if (!st.isFile()) return;
+      const source = await readFile(abs, 'utf8');
+      const next = rewriteRelativeImports(source, fromDir, toDir);
+      // atomicWrite, not `writeFile` — this lands on a `.tsx` the fs-mirror is
+      // watching, so a truncate-then-write can surface a partial-content watch
+      // event (the exact hazard atomic-write.ts was built for), and a crash
+      // mid-write would leave a truncated canvas.
+      if (next !== source) atomicWrite(abs, next);
+    } catch (err) {
+      console.warn(
+        `[move] could not rewrite relative imports in ${abs}: ${(err as Error).message}`
+      );
+    }
+  }
+
   // feature-file-tree-drag-drop-folders (Task 3) — move/rename a canvas + its
   // full artifact set (POST /_api/fs-move). Same main-origin-only trust
   // boundary as createCanvas/deleteCanvas (DDR-054): never reachable from the
@@ -2954,7 +3438,11 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   // never wrong about where the canvas lives) and every relocation is logged
   // to `_history/<toSlug>/_move.json` for forensic recovery. See the DDR
   // (Task 14) for the accepted-limitation writeup.
-  async function moveCanvas(input: { file?: unknown; toDir?: unknown }): Promise<MoveCanvasResult> {
+  async function moveCanvas(input: {
+    file?: unknown;
+    toDir?: unknown;
+    toName?: unknown;
+  }): Promise<MoveCanvasResult> {
     const raw = input?.file;
     if (typeof raw !== 'string' || !raw.trim()) {
       return { ok: false, status: 400, error: 'file is required' };
@@ -2970,17 +3458,38 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     if (rel.startsWith(`${drPrefix}/`)) rel = rel.slice(drPrefix.length + 1);
     if (rel.includes('..')) return { ok: false, status: 400, error: 'invalid path' };
     if (!/\.tsx$/i.test(rel)) {
+      // Plan T17/L03 — a supporting file (notes, styles, images, media in a
+      // canvas folder) moves or renames as itself, never as a "folder".
+      if (isSupportingFileRel(rel) && (await isRegularFile(path.join(paths.designRoot, rel)))) {
+        return moveSupportingFile(rel, input?.toDir, input?.toName);
+      }
       // feature-file-tree-drag-drop-folders (Task 11) — a non-.tsx source is a
       // folder move (dragging a folder onto a folder). moveFolder does its own
       // existence + containment validation, so an invalid path still reports
       // the right error from there.
-      return moveFolder(rel, input?.toDir);
-    }
-
-    if (typeof input?.toDir !== 'string') {
+      return moveFolder(rel, input?.toDir, input?.toName);
+    }
+
+    // A rename is a move in place under a new name (`toName`, same allowlist as
+    // a new canvas's name); `toDir` defaults to the canvas's own folder then.
+    let newBase: string | null = null;
+    if (input?.toName !== undefined && input.toName !== null && input.toName !== '') {
+      const v = validateCanvasName(input.toName);
+      if (!v.ok || !v.name) return { ok: false, status: 400, error: v.error ?? 'invalid name' };
+      newBase = `${v.name}.tsx`;
+    }
+    const toDirInput =
+      typeof input?.toDir === 'string'
+        ? input.toDir
+        : newBase
+          ? path.posix.dirname(rel) === '.'
+            ? ''
+            : path.posix.dirname(rel)
+          : null;
+    if (typeof toDirInput !== 'string') {
       return { ok: false, status: 400, error: 'toDir is required' };
     }
-    let toDir = input.toDir.trim().replace(/^\/+|\/+$/g, '');
+    let toDir = toDirInput.trim().replace(/^\/+|\/+$/g, '');
     try {
       toDir = decodeURIComponent(toDir);
     } catch {
@@ -3048,7 +3557,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       return { ok: false, status: 404, error: 'canvas not found' };
     }
 
-    const base = path.basename(rel);
+    const base = newBase ?? path.basename(rel);
     const toRel = path.posix.join(toDir, base);
     if (path.posix.normalize(toRel) === path.posix.normalize(rel)) {
       return { ok: false, status: 400, error: 'source and destination are the same' };
@@ -3124,6 +3633,14 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       return { ok: false, status: 500, error: err instanceof Error ? err.message : 'move failed' };
     }
 
+    // The canvas is at a new depth now, so its relative specifiers point at the
+    // wrong place (issue #114). Bytes used to move without them, and the canvas
+    // 500s on the next build with `Could not resolve`. Best-effort: the move
+    // itself already succeeded, and a rewrite failure must not leave the tree
+    // half-moved — it leaves a build error the user can fix by hand, which is
+    // exactly where they were before this existed.
+    await rewriteCanvasImports(toAbs, path.posix.dirname(rel), path.posix.dirname(toRel));
+
     const moved: string[] = [path.relative(paths.repoRoot, toAbs)];
     for (const artifact of canvasArtifacts({ rel, paths })) {
       if (artifact.kind === 'primary') continue; // already moved above
@@ -3208,7 +3725,11 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   // nested canvas at once (they live inside the moved directory); only the
   // slug-keyed sidecars (flat dirs like `_history/<slug>/`, not nested by
   // folder structure) need their own per-canvas relocation afterward.
-  async function moveFolder(relDir: string, toDirRaw: unknown): Promise<MoveCanvasResult> {
+  async function moveFolder(
+    relDir: string,
+    toDirRaw: unknown,
+    toNameRaw?: unknown
+  ): Promise<MoveCanvasResult> {
     if (relDir.includes('..')) return { ok: false, status: 400, error: 'invalid path' };
     const dirAbs = path.join(paths.designRoot, relDir);
     const resolvedDesignRoot = path.resolve(paths.designRoot);
@@ -3284,7 +3805,14 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       return { ok: false, status: 400, error: 'cannot move a folder into itself' };
     }
 
-    const base = path.basename(relDir);
+    // A RENAME is a move to a new name in the same (or another) parent — one
+    // manifest action (dir.move), the same as any folder move (plan T17).
+    let base = path.basename(relDir);
+    if (toNameRaw !== undefined && toNameRaw !== null && toNameRaw !== '') {
+      const v = validateFolderName(toNameRaw);
+      if (!v.ok || !v.name) return { ok: false, status: 400, error: v.error ?? 'invalid name' };
+      base = v.name;
+    }
     const toRelDir = path.posix.join(toDir, base);
     if (path.posix.normalize(toRelDir) === path.posix.normalize(relDir)) {
       return { ok: false, status: 400, error: 'source and destination are the same' };
@@ -3338,6 +3866,22 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       }
     }
 
+    // ONE project action for the whole folder (accepted-revisions mode) —
+    // canvases, empty sub-folders and all. The per-canvas retire below then
+    // only lets go locally; it proposes nothing of its own.
+    const folderMove = await hooks.proposeFolder?.({
+      op: 'dir.move',
+      from: relDir.replace(/\\/g, '/').replace(/^\/+|\/+$/g, ''),
+      to: toRelDir,
+    });
+    if (folderMove?.status === 'rejected') {
+      return {
+        ok: false,
+        status: 409,
+        error: `the project did not accept this move (${folderMove.code ?? 'rejected'})`,
+      };
+    }
+
     // Collab guard for every canvas found, BEFORE any disk mutation. Same
     // coordinated retire as moveCanvas — refuse only when a pinned room could
     // not be retired, and retire even unpinned synced documents so none of
@@ -3371,6 +3915,14 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       const toRel = toRelDir + fromRel.slice(relDir.length);
       const fromSlug = fileSlug(fromRel);
       const toSlug = fileSlug(toRel);
+      // Same depth change as moveCanvas, once per nested canvas (issue #114).
+      // A folder move relocates every canvas inside it by the same delta, but
+      // each one's own dir differs, so the rewrite is per file, not per folder.
+      await rewriteCanvasImports(
+        path.join(paths.designRoot, toRel),
+        path.posix.dirname(fromRel),
+        path.posix.dirname(toRel)
+      );
       for (const artifact of canvasArtifacts({ rel: fromRel, paths })) {
         if (artifact.kind !== 'slug-keyed') continue; // primary/siblings already moved with the dir
         const dest = relocatedName(artifact, fromRel, toRel, paths);
@@ -3499,6 +4051,18 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       /* good — doesn't exist yet */
     }
 
+    const folderCreate = await hooks.proposeFolder?.({
+      op: 'dir.create',
+      path: path.posix.join(parent, v.name),
+    });
+    if (folderCreate?.status === 'rejected') {
+      return {
+        ok: false,
+        status: 409,
+        error: `the project did not accept this folder (${folderCreate.code ?? 'rejected'})`,
+      };
+    }
+
     await mkdir(dirAbs, { recursive: true });
     await Bun.write(path.join(dirAbs, '.gitkeep'), '');
 
@@ -3576,10 +4140,22 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
   // suppression BEFORE the write so it catches the debounced fs:any, disarm on
   // a no-op (delta 0 = no write) or throw so a failed edit can't mute the next
   // genuine agent edit's rim.
+  /** T24/T25 — say what a structural edit IS (sync/source-ops), for replay. */
+  function announceOp(
+    abs: string,
+    rel: string,
+    before: string,
+    op: Parameters<typeof describeSourceOp>[2]
+  ): void {
+    const described = describeSourceOp(abs, before, op);
+    if (described) ctx.bus.emit('source-op', { rel, op: described });
+  }
+
   async function suppressedEdit(
     abs: string,
-    run: () => Promise<{ delta: number; changed?: boolean }>,
-    errLabel: string
+    run: () => Promise<{ delta: number; changed?: boolean; previous?: AttributeState }>,
+    errLabel: string,
+    describe?: Parameters<typeof describeSourceOp>[2]
   ): Promise<EditOpResult> {
     const rel = path.relative(paths.designRoot, abs);
     ctx.bus.emit('activity:suppress', rel);
@@ -3588,18 +4164,33 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       // whole-file undo log (the Timeline replace-src path rides this; other
       // inspector edits get an undoable seq for free).
       const before = await Bun.file(abs).text();
+      // T24 — what this edit IS, so a lost race re-applies it instead of
+      // turning "we both picked a colour" into a conflict.
+      if (describe) {
+        const op = describeSourceOp(abs, before, describe);
+        if (op) ctx.bus.emit('source-op', { rel, op });
+      }
       const res = await run();
+      const previous =
+        res.previous?.kind === 'absent'
+          ? { previous: null }
+          : res.previous?.kind === 'literal'
+            ? { previous: res.previous.value }
+            : {};
       // `changed === false` = the op collapsed to a no-op and nothing hit disk —
       // NOT `delta === 0`, which an equal-length replacement also produces.
       if (res.changed === false) {
         ctx.bus.emit('activity:unsuppress', rel);
-        return { ok: true, delta: res.delta };
+        return { ok: true, delta: res.delta, ...previous };
       }
       const after = await Bun.file(abs).text();
       const seq = after !== before ? logUndo(abs, before, after) : undefined;
-      return { ok: true, delta: res.delta, seq };
+      return { ok: true, delta: res.delta, seq, ...previous };
     } catch (err) {
       ctx.bus.emit('activity:unsuppress', rel);
+      if (err instanceof CanvasEditError && err.conflict) {
+        return { ok: false, status: 409, error: err.message, conflict: true };
+      }
       return {
         ok: false,
         status: 422,
@@ -3615,9 +4206,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     value?: unknown;
     reset?: unknown;
     idIndex?: unknown;
+    expected?: unknown;
   }): Promise<EditOpResult> {
     const r = resolveCanvasAbs(input.canvas);
     if (!r.ok) return r;
+    const pre = expectedValueOf(input);
+    if (!pre.ok) return { ok: false, status: 400, error: 'invalid expected value' };
     const id = typeof input.id === 'string' ? input.id.trim() : '';
     if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
     // Stage H3 — optional DOM-occurrence index. Present only for a whole-instance
@@ -3642,8 +4236,21 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     if (input.reset === true) {
       return suppressedEdit(
         r.abs,
-        () => removeAttribute(r.abs, id, `style.${camel}`, idIndex),
-        'reset failed'
+        () =>
+          removeAttribute(
+            r.abs,
+            id,
+            `style.${camel}`,
+            idIndex,
+            pre.expected === undefined ? undefined : { expected: pre.expected, next: null }
+          ),
+        'reset failed',
+        {
+          kind: 'remove',
+          id,
+          attr: `style.${camel}`,
+          ...(idIndex !== undefined ? { occurrence: idIndex } : {}),
+        }
       );
     }
     const value = typeof input.value === 'string' ? input.value : '';
@@ -3655,8 +4262,23 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // `#fff`, `8px`, `700`, `1.5` all ride verbatim.
     return suppressedEdit(
       r.abs,
-      () => editAttribute(r.abs, id, `style.${camel}`, JSON.stringify(value), idIndex),
-      'edit failed'
+      () =>
+        editAttribute(
+          r.abs,
+          id,
+          `style.${camel}`,
+          JSON.stringify(value),
+          idIndex,
+          pre.expected === undefined ? undefined : { expected: pre.expected, next: value }
+        ),
+      'edit failed',
+      {
+        kind: 'set',
+        id,
+        attr: `style.${camel}`,
+        value: JSON.stringify(value),
+        ...(idIndex !== undefined ? { occurrence: idIndex } : {}),
+      }
     );
   }
 
@@ -3689,7 +4311,8 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return suppressedEdit(
       r.abs,
       () => runEditText(r.abs, id, text, { occurrence, before }),
-      'edit failed'
+      'edit failed',
+      { kind: 'text', id, text, ...(occurrence !== undefined ? { occurrence } : {}) }
     );
   }
 
@@ -3699,9 +4322,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     attr?: unknown;
     value?: unknown;
     reset?: unknown;
+    expected?: unknown;
   }): Promise<EditOpResult> {
     const r = resolveCanvasAbs(input.canvas);
     if (!r.ok) return r;
+    const pre = expectedValueOf(input);
+    if (!pre.ok) return { ok: false, status: 400, error: 'invalid expected value' };
     const id = typeof input.id === 'string' ? input.id.trim() : '';
     if (!CD_ID_RE.test(id)) return { ok: false, status: 400, error: 'invalid data-cd-id' };
     const attr = typeof input.attr === 'string' ? input.attr.trim() : '';
@@ -3719,7 +4345,19 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
     // Phase 12.3 — `reset: true` REMOVES the custom attribute. No-op if absent.
     if (input.reset === true) {
-      return suppressedEdit(r.abs, () => removeAttribute(r.abs, id, attr), 'reset failed');
+      return suppressedEdit(
+        r.abs,
+        () =>
+          removeAttribute(
+            r.abs,
+            id,
+            attr,
+            undefined,
+            pre.expected === undefined ? undefined : { expected: pre.expected, next: null }
+          ),
+        'reset failed',
+        { kind: 'remove', id, attr }
+      );
     }
     const value = typeof input.value === 'string' ? input.value : '';
     if (!value.trim()) return { ok: false, status: 400, error: 'value required' };
@@ -3740,7 +4378,20 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     // Pass the value RAW: editStringAttr quotes/escapes it itself (JSON.stringify
     // on replace, escapeAttr on insert) — pre-stringifying here double-encoded
     // the value (`data-x="\"ok\""`; knob-smoke finding, 2026-06-12).
-    return suppressedEdit(r.abs, () => editAttribute(r.abs, id, attr, value), 'edit failed');
+    return suppressedEdit(
+      r.abs,
+      () =>
+        editAttribute(
+          r.abs,
+          id,
+          attr,
+          value,
+          undefined,
+          pre.expected === undefined ? undefined : { expected: pre.expected, next: value }
+        ),
+      'edit failed',
+      { kind: 'set', id, attr, value }
+    );
   }
 
   // Phase 12.1 (DDR-138) — snapshot stack so a reorder is undoable via
@@ -3787,6 +4438,14 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     ctx.bus.emit('activity:suppress', rel);
     try {
       const before = await Bun.file(r.abs).text();
+      announceOp(r.abs, rel, before, {
+        kind: 'move',
+        id,
+        refId,
+        position: String(position),
+        ...(idIndex !== undefined ? { idIndex } : {}),
+        ...(refIndex !== undefined ? { refIndex } : {}),
+      });
       const res = await moveElement(r.abs, id, refId, position as MovePosition, idIndex, refIndex);
       const after = await Bun.file(r.abs).text();
       if (after === before) {
@@ -4202,6 +4861,11 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     ctx.bus.emit('activity:suppress', rel);
     try {
       const before = await Bun.file(r.abs).text();
+      announceOp(r.abs, rel, before, {
+        kind: 'delete',
+        id,
+        ...(idIndex !== undefined ? { occurrence: idIndex } : {}),
+      });
       const res = await deleteElement(r.abs, id, idIndex);
       const after = await Bun.file(r.abs).text();
       if (after === before) {
@@ -4667,6 +5331,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     ctx.bus.emit('activity:suppress', rel);
     try {
       const before = await Bun.file(r.abs).text();
+      announceOp(r.abs, rel, before, {
+        kind: 'artboard',
+        fn: 'resize',
+        artboardId,
+        args: [width, height],
+      });
       await resizeArtboard(r.abs, artboardId, width, height);
       const after = await Bun.file(r.abs).text();
       if (after === before) {
@@ -4714,6 +5384,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     ctx.bus.emit('activity:suppress', rel);
     try {
       const before = await Bun.file(r.abs).text();
+      announceOp(r.abs, rel, before, {
+        kind: 'artboard',
+        fn: 'hug',
+        artboardId,
+        args: [fixed, freezeHeight],
+      });
       await setArtboardHug(r.abs, artboardId, fixed, freezeHeight);
       const after = await Bun.file(r.abs).text();
       if (after === before) {
@@ -4763,6 +5439,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     ctx.bus.emit('activity:suppress', rel);
     try {
       const before = await Bun.file(r.abs).text();
+      announceOp(r.abs, rel, before, { kind: 'artboard', fn: 'kind', artboardId, args: [kind] });
       await setArtboardKind(r.abs, artboardId, kind);
       const after = await Bun.file(r.abs).text();
       if (after === before) {
@@ -4785,6 +5462,50 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
+  /** Rename an artboard (plan T25/L08 — double-click its name). */
+  async function setArtboardLabelOp(input: {
+    canvas?: unknown;
+    artboardId?: unknown;
+    label?: unknown;
+  }): Promise<{ ok: true; seq?: number } | { ok: false; status: number; error: string }> {
+    const r = resolveCanvasAbs(input.canvas);
+    if (!r.ok) return r;
+    if (!takeStructuralToken()) return RATE_LIMITED;
+    const artboardId = typeof input.artboardId === 'string' ? input.artboardId.trim() : '';
+    if (!/^[A-Za-z][\w-]{0,63}$/.test(artboardId)) {
+      return { ok: false, status: 400, error: 'invalid artboard id' };
+    }
+    if (typeof input.label !== 'string' || !input.label.trim()) {
+      return { ok: false, status: 400, error: 'name is required' };
+    }
+    const label = input.label;
+    const rel = path.relative(paths.designRoot, r.abs);
+    ctx.bus.emit('activity:suppress', rel);
+    try {
+      const before = await Bun.file(r.abs).text();
+      announceOp(r.abs, rel, before, { kind: 'artboard', fn: 'label', artboardId, args: [label] });
+      await setArtboardLabel(r.abs, artboardId, label);
+      const after = await Bun.file(r.abs).text();
+      if (after === before) {
+        ctx.bus.emit('activity:unsuppress', rel);
+        return { ok: true };
+      }
+      try {
+        await history.writeSnapshot(rel, before, 'pre-set-artboard-label');
+      } catch {
+        /* snapshot best-effort */
+      }
+      return { ok: true, seq: logUndo(r.abs, before, after) };
+    } catch (err) {
+      ctx.bus.emit('activity:unsuppress', rel);
+      return {
+        ok: false,
+        status: err instanceof CanvasEditError ? 422 : 500,
+        error: err instanceof Error ? err.message : 'set-artboard-label failed',
+      };
+    }
+  }
+
   const MAX_GUIDES_JSON_BYTES = 4096;
 
   /** Generic layout guides (T5) — Inspector/skill writer. Replace-whole-prop,
@@ -4818,6 +5539,12 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     ctx.bus.emit('activity:suppress', rel);
     try {
       const before = await Bun.file(r.abs).text();
+      announceOp(r.abs, rel, before, {
+        kind: 'artboard',
+        fn: 'guides',
+        artboardId,
+        args: [guides],
+      });
       await setArtboardGuides(r.abs, artboardId, guides);
       const after = await Bun.file(r.abs).text();
       if (after === before) {
@@ -4994,6 +5721,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     ctx.bus.emit('activity:suppress', rel);
     try {
       const before = await Bun.file(r.abs).text();
+      announceOp(r.abs, rel, before, { kind: 'artboard', fn: 'style', artboardId, args: [patch] });
       await setArtboardStyle(r.abs, artboardId, patch);
       const after = await Bun.file(r.abs).text();
       if (after === before) {
@@ -5038,6 +5766,11 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
         ctx.bus.emit('activity:unsuppress', rel);
         return { ok: false, status: 413, error: 'canvas source too large to grow' };
       }
+      announceOp(r.abs, rel, before, {
+        kind: 'duplicate',
+        id,
+        ...(idIndex !== undefined ? { occurrence: idIndex } : {}),
+      });
       const res = await duplicateElement(r.abs, id, idIndex);
       const after = await Bun.file(r.abs).text();
       if (after === before) {
@@ -5363,6 +6096,36 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       const current = await Bun.file(r.abs).text();
       const expect = dir === 'undo' ? entry.after : entry.before;
       const write = dir === 'undo' ? entry.before : entry.after;
+      // T26 — a project that saves through accepted revisions undoes the
+      // ACTION this edit became: effect-aware, so a teammate's later change
+      // elsewhere in the canvas neither blocks the undo nor gets reverted
+      // with it (a whole-file swap could do only one of those).
+      const runtime = ctx.syncControl?.current?.();
+      if (runtime?.acceptedMode?.()) {
+        const rel = path.relative(paths.repoRoot, r.abs);
+        // Undo targets the edit's action; redo targets the undo that
+        // reverted it (reverting a revert re-applies, effect-aware again).
+        const actionId =
+          dir === 'undo'
+            ? (runtime.acceptedActionForContent?.(rel, entry.after) ?? null)
+            : (entry.undoActionId ?? null);
+        if (actionId) {
+          const res = await runtime.acceptedUndo?.(actionId, dir === 'redo');
+          if (res?.status === 'accepted' || res?.queued) {
+            if (dir === 'undo') entry.undoActionId = res.actionId;
+            else delete entry.undoActionId;
+            return { ok: true, dir };
+          }
+          return {
+            ok: false,
+            status: 409,
+            error:
+              res?.code === 'base-conflict'
+                ? 'someone changed the same thing since — undo skipped'
+                : `undo refused (${res?.code ?? 'unknown'})`,
+          };
+        }
+      }
       if (current !== expect) {
         return {
           ok: false,
@@ -5797,6 +6560,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     patchCanvasMeta,
     loadAnnotations,
     saveAnnotations,
+    projectAnnotations,
     saveAsset,
     listAssets,
     readAssetBytes,
@@ -5808,6 +6572,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     saveChatAttachment,
     resolveChatAttachment,
     createCanvas,
+    duplicateCanvas,
     deleteCanvas,
     moveCanvas,
     createFolder,
@@ -5832,6 +6597,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     setArtboardHugOp,
     setArtboardStyleOp,
     setArtboardKindOp,
+    setArtboardLabelOp,
     setArtboardGuidesOp,
     setArtboardPrintOp,
     deleteArtboardOp,