@1agh/maude 1.2.0 → 1.3.1

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,
@@ -21,6 +21,7 @@ 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
@@ -28,8 +29,19 @@ import { dedupeCommentsById } from './sync/comment-identity.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,
@@ -63,6 +75,7 @@ import {
   setArtboardGuides,
   setArtboardHug,
   setArtboardKind,
+  setArtboardLabel,
   setArtboardPrint,
   setArtboardStyle,
   toggleClipHidden,
@@ -102,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
@@ -127,7 +141,7 @@ const HIDDEN_OK = new Set(['.ai', '.claude', '.design']);
 // an explicit enumerated list rather than a broad pattern so it can never
 // accidentally widen to swallow runtime JSON — findFiles already excludes
 // `_`-prefixed entries before this list is even consulted.
-const PREVIEW_ASSET_EXTS = [
+export const PREVIEW_ASSET_EXTS = [
   '.svg',
   '.png',
   '.jpg',
@@ -157,6 +171,30 @@ const PREVIEW_ASSET_EXTS = [
  * (`system/<ds>/preview/*.html`) intentionally stay `.html` and travel via
  * the DS-aware `findFiles()` path below.
  */
+/**
+ * True when `abs` is a directory tree holding nothing but folder placeholders
+ * (`.gitkeep`, `.DS_Store`) — what a folder projection leaves before any
+ * content arrives. False when it is absent, is not a directory, or holds
+ * anything real (a symlink counts as real: never followed, never removed).
+ */
+async function onlyFolderPlaceholders(abs: string, depth = 0): Promise<boolean> {
+  if (depth > 16) return false;
+  let entries: Dirent[];
+  try {
+    entries = await readdir(abs, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!(await onlyFolderPlaceholders(path.join(abs, e.name), depth + 1))) return false;
+    } else if (!(e.isFile() && (e.name === '.gitkeep' || e.name === '.DS_Store'))) {
+      return false;
+    }
+  }
+  return true;
+}
+
 export async function findHtmlFiles(absRoot: string, prefixUnderRepo: string): Promise<string[]> {
   const out: string[] = [];
   let entries: Dirent[];
@@ -189,7 +227,7 @@ export async function findHtmlFiles(absRoot: string, prefixUnderRepo: string): P
  * traversal instead of adding a second full walk of `system/` (the largest
  * group) just to enumerate directories.
  */
-async function findFiles(
+export async function findFiles(
   absRoot: string,
   prefix: string,
   exts: string[],
@@ -312,8 +350,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
@@ -374,7 +431,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. */
@@ -425,6 +484,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
@@ -442,6 +505,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: {
@@ -459,6 +524,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
@@ -662,6 +729,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;
@@ -736,9 +809,26 @@ export interface ApiHooks {
    * stays". Passing the list removes the read, and `publishComments` awaits
    * this hook BEFORE touching disk so the doc is never the stale side.
    */
-  onCommentsChanged: (file: string, comments: Comment[]) => void | Promise<void>;
+  /** `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
@@ -1009,7 +1099,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
@@ -1187,9 +1280,9 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
    * 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[]): Promise<void> {
+  async function publishComments(file: string, list: Comment[], base?: Comment[]): Promise<void> {
     const settled = dedupeCommentsById(list);
-    await onCommentsChanged(file, settled);
+    await onCommentsChanged(file, settled, base ? dedupeCommentsById(base) : undefined);
     await saveCommentsForFile(file, settled);
   }
 
@@ -1321,6 +1414,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()
@@ -1369,7 +1463,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       if (anchor.clipStableId != null || anchor.frame != null) c.timeline = anchor;
     }
     list.push(c);
-    await publishComments(payload.file, list);
+    await publishComments(payload.file, list, base);
     return c;
   }
 
@@ -1384,6 +1478,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()
@@ -1397,7 +1492,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       };
       entry.thread = [...entry.thread, reply];
       entry.mentions = mentionsUnion(entry);
-      await publishComments(file, list);
+      await publishComments(file, list, base);
       return entry;
     }
     return null;
@@ -1417,6 +1512,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       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;
@@ -1427,7 +1523,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
           entry.mentions = mentionsUnion(entry);
         }
       }
-      await publishComments(file, list);
+      await publishComments(file, list, base);
       return first;
     }
     return null;
@@ -1438,7 +1534,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     for (const [file, list] of Object.entries(all)) {
       const remaining = list.filter((c) => c.id !== id);
       if (remaining.length === list.length) continue;
-      await publishComments(file, remaining);
+      await publishComments(file, remaining, list);
       return true;
     }
     return false;
@@ -1946,7 +2042,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.
@@ -1986,7 +2085,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
@@ -2004,8 +2108,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
@@ -2016,6 +2130,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):
@@ -2754,6 +2894,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
@@ -2777,6 +3002,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
@@ -2886,6 +3118,176 @@ 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);
+    // A hub's own studio has no watcher to see this rename: announce both
+    // ends, or the journal learns of it only from the walk-import belt and a
+    // teammate waits minutes for a rename that took a second here.
+    announceWritten(rel);
+    announceWritten(toRel);
+    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);
+    announceWritten(rel);
+    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);
@@ -2942,6 +3344,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) {
@@ -3051,7 +3468,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' };
@@ -3067,17 +3488,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 {
@@ -3145,7 +3587,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' };
@@ -3313,7 +3755,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);
@@ -3389,7 +3835,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' };
@@ -3443,6 +3896,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
@@ -3464,6 +3933,17 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
 
     await mkdir(toDirAbs, { recursive: true });
+    // OUR OWN ACTION MAY ALREADY BE ON THIS DISK. The destination did not exist
+    // when this move was checked; the project accepted the move since, and its
+    // announcement can reach this machine's sync before the answer reaches this
+    // request — which materializes the destination folders (each with its
+    // `.gitkeep`). Renaming onto that non-empty placeholder failed (ENOTEMPTY),
+    // leaving the old folder in this person's tree while every teammate had
+    // the move (plan T31/L02). A destination holding nothing but placeholders
+    // is that projection; it is replaced, never merged into.
+    if (await onlyFolderPlaceholders(toDirFinalAbs)) {
+      await rm(toDirFinalAbs, { recursive: true, force: true });
+    }
     try {
       await rename(dirAbs, toDirFinalAbs);
     } catch (err) {
@@ -3612,6 +4092,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'), '');
 
@@ -3689,10 +4181,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);
@@ -3701,18 +4205,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,
@@ -3728,9 +4247,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
@@ -3755,8 +4277,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 : '';
@@ -3768,8 +4303,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 } : {}),
+      }
     );
   }
 
@@ -3802,7 +4352,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 } : {}) }
     );
   }
 
@@ -3812,9 +4363,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() : '';
@@ -3832,7 +4386,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' };
@@ -3853,7 +4419,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
@@ -3900,6 +4479,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) {
@@ -4315,6 +4902,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) {
@@ -4780,6 +5372,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) {
@@ -4827,6 +5425,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) {
@@ -4876,6 +5480,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) {
@@ -4898,6 +5503,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,
@@ -4931,6 +5580,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) {
@@ -5107,6 +5762,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) {
@@ -5151,6 +5807,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) {
@@ -5476,6 +6137,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,
@@ -5910,6 +6601,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     patchCanvasMeta,
     loadAnnotations,
     saveAnnotations,
+    projectAnnotations,
     saveAsset,
     listAssets,
     readAssetBytes,
@@ -5921,6 +6613,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     saveChatAttachment,
     resolveChatAttachment,
     createCanvas,
+    duplicateCanvas,
     deleteCanvas,
     moveCanvas,
     createFolder,
@@ -5945,6 +6638,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     setArtboardHugOp,
     setArtboardStyleOp,
     setArtboardKindOp,
+    setArtboardLabelOp,
     setArtboardGuidesOp,
     setArtboardPrintOp,
     deleteArtboardOp,