@1agh/maude 1.4.6 → 1.5.1

package/apps/studio/annotations-model.ts

@@ -25,6 +25,8 @@
  *   - sticky / polygon / image / link — see the per-tool serializers below.
  */
 
+import { defOf } from './annotations/registry.ts';
+import type { AnnotationElement, GeomCtx } from './annotations/types.ts';
 import {
   ARROW_HEADS,
   type ArrowHead,
@@ -318,7 +320,21 @@ export interface SectionStroke extends StrokeBase {
   color: string;
 }
 
+/**
+ * DDR-242 (Task 25) — an element of a registered type with no stroke form of
+ * its own. Its world-space record rides along and every geometry question is
+ * answered by its registry definition, so a new element type is one model file:
+ * the whiteboard draws, selects, moves, syncs and hands it to the AI verbs
+ * without another `tool ===` branch.
+ */
+export interface ElementStroke extends StrokeBase {
+  tool: 'element';
+  /** The element in WORLD coordinates, without `parent`. */
+  el: AnnotationElement;
+}
+
 export type Stroke =
+  | ElementStroke
   | PenStroke
   | RectStroke
   | EllipseStroke
@@ -671,7 +687,7 @@ export function rid(): string {
  * and reload — and is what external references (comments' `annotationId`)
  * hold. A migration must carry ids over unchanged.
  */
-export function stableAnnotationId(el: Element, seen: Map<string, number>): string {
+export function stableAnnotationId(el: SvgElLike, seen: Map<string, number>): string {
   const content = el.outerHTML;
   const n = seen.get(content) ?? 0;
   seen.set(content, n + 1);
@@ -1047,6 +1063,8 @@ export function strokeToSvgEl(s: Stroke): string {
 }
 
 function strokeToSvgElBase(s: Stroke): string {
+  // No legacy SVG form: such an element only ever lives in a v2 board.
+  if (s.tool === 'element') return '';
   if (s.tool === 'text') {
     // Phase 21 — anchored text keeps the byte-identical Phase 5.1 form;
     // standalone text (no anchorId) writes its own world x/y and omits
@@ -1348,7 +1366,7 @@ function parseFill(raw: string | null): string | null {
  * between them, so first-pair = start, last-pair = end recovers the ends
  * exactly → idempotent re-serialize).
  */
-function arrowEndpoints(el: Element): { x1: number; y1: number; x2: number; y2: number } | null {
+function arrowEndpoints(el: SvgElLike): { x1: number; y1: number; x2: number; y2: number } | null {
   const line = el.querySelector('line');
   if (line) {
     return {
@@ -1421,7 +1439,7 @@ function sanitizeAuthorName(raw: string): string {
 }
 
 /** FigJam v3 — read the cross-tool root attrs back onto a parsed stroke. */
-function readSharedAttrs(el: Element, s: Stroke): void {
+function readSharedAttrs(el: SvgElLike, s: Stroke): void {
   const g = el.getAttribute('data-group-ids');
   if (g) {
     const ids = g.split(/\s+/).filter(Boolean);
@@ -1447,12 +1465,39 @@ function readSharedAttrs(el: Element, s: Stroke): void {
   }
 }
 
+/**
+ * The slice of the DOM `Element` API the parser reads. A browser `Element`
+ * satisfies it; so does the DOM-free tree in `annotations/legacy/mini-dom.ts`,
+ * which lets the hub (Node, no DOMParser) upconvert legacy SVG history for the
+ * annotations-v2 migration (DDR-242 §6).
+ */
+export interface SvgElLike {
+  getAttribute(name: string): string | null;
+  querySelector(selector: string): SvgElLike | null;
+  querySelectorAll(selector: string): ArrayLike<SvgElLike>;
+  readonly textContent: string | null;
+  readonly outerHTML: string;
+}
+
+export interface SvgDocLike {
+  querySelector(selector: string): SvgElLike | null;
+  querySelectorAll(selector: string): ArrayLike<SvgElLike>;
+}
+
 export function svgToStrokes(svgText: string): Stroke[] {
   const text = (svgText ?? '').trim();
   if (!text) return [];
   if (typeof DOMParser === 'undefined') return [];
   try {
-    const doc = new DOMParser().parseFromString(text, 'image/svg+xml');
+    return strokesFromDocument(new DOMParser().parseFromString(text, 'image/svg+xml'));
+  } catch {
+    return [];
+  }
+}
+
+/** The parser proper, over any document exposing `SvgDocLike`. Never throws. */
+export function strokesFromDocument(doc: SvgDocLike): Stroke[] {
+  try {
     if (doc.querySelector('parsererror')) return [];
     const out: Stroke[] = [];
     const seenContent = new Map<string, number>();
@@ -1773,6 +1818,7 @@ function pointSegmentDist(
 
 /** FigJam v3 — strokes whose `rotation` is honoured (see StrokeBase doc). */
 export function canRotate(s: Stroke): boolean {
+  if (s.tool === 'element') return false;
   if (s.tool === 'pen' || s.tool === 'arrow' || s.tool === 'section') return false;
   if (s.tool === 'text') return s.anchorId == null || s.anchorId === '';
   return true;
@@ -1840,6 +1886,9 @@ export function strokeHitTest(s: Stroke, wx: number, wy: number, tol: number): b
       wx >= bb.x - tol && wx <= bb.x + bb.w + tol && wy >= bb.y - tol && wy <= bb.y + bb.h + tol
     );
   }
+  if (s.tool === 'element') {
+    return defOf(s.el.type)?.hitTest(s.el, wx, wy, tol, WORLD_CTX) ?? false;
+  }
   if (s.tool === 'section') {
     // FigJam — a section is grabbed by its BORDER or its label chip; the
     // interior stays click-through so content on the section selects normally.
@@ -2045,6 +2094,7 @@ export function normalizeSticky(s: StickyStroke): StickyStroke {
 }
 
 export function isStrokeMeaningful(s: Stroke): boolean {
+  if (s.tool === 'element') return defOf(s.el.type)?.meaningful(s.el) ?? false;
   if (s.tool === 'pen') return s.points.length >= 2;
   if (s.tool === 'rect') return Math.abs(s.w) >= 4 && Math.abs(s.h) >= 4;
   if (s.tool === 'polygon') return Math.abs(s.w) >= 4 && Math.abs(s.h) >= 4;
@@ -2063,10 +2113,17 @@ export function isStrokeMeaningful(s: Stroke): boolean {
   return Math.hypot(s.x2 - s.x1, s.y2 - s.y1) >= 4;
 }
 
+const WORLD_CTX: GeomCtx = { origin: { x: 0, y: 0 }, resolve: () => null };
+
+function elementBox(s: ElementStroke): { x: number; y: number; w: number; h: number } | null {
+  return defOf(s.el.type)?.bounds(s.el, WORLD_CTX) ?? null;
+}
+
 export function strokeBBox(
   s: Stroke,
   anchors?: Map<string, AnchorHost>
 ): { x: number; y: number; w: number; h: number } | null {
+  if (s.tool === 'element') return elementBox(s);
   if (s.tool === 'pen') {
     if (!s.points.length) return null;
     let xMin = Number.POSITIVE_INFINITY;
@@ -2141,6 +2198,10 @@ export function strokeBBox(
 }
 
 export function translateOne(s: Stroke, dx: number, dy: number): Stroke {
+  if (s.tool === 'element') {
+    const def = defOf(s.el.type);
+    return def ? { ...s, el: { ...s.el, ...def.translate(s.el, dx, dy) } } : s;
+  }
   if (s.tool === 'pen') {
     return { ...s, points: s.points.map(([x, y]) => [x + dx, y + dy] as WorldPoint) };
   }

package/apps/studio/annotations-sync.ts

@@ -1,50 +1,7 @@
-import type * as Y from 'yjs';
-
-/** Echo identity is transport metadata, never authorization or a durable ACK. */
-export const ANNOTATION_WRITE_ID = 'writeId';
-
+/**
+ * Write/action ids travel with annotation writes as echo metadata (DDR-242:
+ * the replica's `~action`), never as authorization or a durable ACK.
+ */
 export function validAnnotationWriteId(value: unknown): value is string {
   return typeof value === 'string' && /^[a-zA-Z0-9_-]{1,96}$/.test(value);
 }
-
-/** Remember authored operations, not previously rendered content (A → B → A). */
-export function createAnnotationEchoGuard() {
-  const authored = new Map<string, string>();
-  return {
-    remember(id: string, svg: string) {
-      authored.set(id, svg);
-      if (authored.size > 64) {
-        const oldest = authored.keys().next().value;
-        if (oldest !== undefined) authored.delete(oldest);
-      }
-    },
-    forget(id: string) {
-      authored.delete(id);
-    },
-    isOwn(svg: string, id: unknown) {
-      return validAnnotationWriteId(id) && authored.get(id) === svg;
-    },
-  };
-}
-
-/** Old clients/importers may change svg without changing its old writeId. */
-export function observeAnnotationSnapshots(
-  doc: Y.Doc,
-  receive: (svg: string, writeId: unknown) => void
-): () => void {
-  const map = doc.getMap<unknown>('annotations');
-  const apply = (event?: Y.YMapEvent<unknown>) => {
-    if (event && !event.keysChanged.has('svg') && !event.keysChanged.has(ANNOTATION_WRITE_ID))
-      return;
-    const svg = map.get('svg');
-    if (typeof svg !== 'string' && !event?.keysChanged.has('svg')) return;
-    const id =
-      !event || event.keysChanged.has(ANNOTATION_WRITE_ID)
-        ? map.get(ANNOTATION_WRITE_ID)
-        : undefined;
-    receive(typeof svg === 'string' ? svg : '', id);
-  };
-  map.observe(apply);
-  apply();
-  return () => map.unobserve(apply);
-}

package/apps/studio/api.ts

@@ -14,6 +14,16 @@ import {
   stat as statp,
 } from 'node:fs/promises';
 import path from 'node:path';
+import { canonicalAnnotations } from './annotations/board-text.ts';
+import {
+  type Op as AnnotationOp,
+  type ApplyResult,
+  applyOps as applyAnnotationOpsPure,
+  diffToOps,
+} from './annotations/ops.ts';
+import './annotations/ops-merge.ts';
+import { parseBoard, serializeBoard } from './annotations/schema.ts';
+import type { AnnotationElement } from './annotations/types.ts';
 import { createAssetMirror, s3ConfigFromEnv } from './assets-s3.ts';
 import { canvasArtifacts, locatorKeyFor, relocatedName } from './canvas-artifacts.ts';
 import { renderBriefBoard, validateCanvasName, validateFolderName } from './canvas-create.ts';
@@ -23,6 +33,7 @@ import { isAnnotationId, isWorldPoint } from './comment-anchor.ts';
 import { atomicWrite } from './sync/atomic-write.ts';
 import { dedupeCommentsById } from './sync/comment-identity.ts';
 import { isRuntimeStateRel } from './sync/file-membership.ts';
+import { MAX_ANNOTATIONS_BYTES } from './sync/limits.ts';
 
 // Re-exported so existing external callers (canvas-list-watch.ts, tests) keep
 // importing it from api.ts — the actual implementation now lives in
@@ -34,7 +45,7 @@ export { canvasSlugFromRel } from './canvas-slug.ts';
  *  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;
+  if (/\.(meta\.json|annotations\.(?:svg|json)|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
   );
@@ -117,6 +128,7 @@ 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 { normalizeTreeState, type TreeState } from './tree-state.ts';
 import { isWorkspaceMode } from './workspace-mode.ts';
 
 // Directories that never hold user-facing canvases. Exported so the
@@ -324,7 +336,7 @@ export interface Comment {
    *  text is untrusted user/peer text (DDR-054) — rendered as text, never
    *  into TSX. */
   timeline?: { clipStableId?: string; frameOffset?: number; frame?: number; lane?: string };
-  /** #134/#136 — anchor on an annotation (`data-id` in `*.annotations.svg`).
+  /** #134/#136 — anchor on an annotation (an element `id` in `*.annotations.json`).
    *  Absent on element and floating comments. See comment-anchor.ts. */
   annotationId?: string;
   /** World point of the comment: the anchor of a floating comment, the last
@@ -424,6 +436,8 @@ export interface Api {
   // Canvas state
   loadCanvasState(file: string): Promise<Record<string, unknown> | null>;
   saveCanvasState(file: string, state: Record<string, unknown>): Promise<void>;
+  loadTreeState(): Promise<TreeState>;
+  saveTreeState(state: TreeState): Promise<TreeState>;
   timelineMediaLoad(key: string): Promise<Record<string, unknown> | null>;
   timelineMediaSave(key: string, data: Record<string, unknown>): Promise<boolean>;
   // Canvas meta sidecar (Phase 4 T5 — .design/ui/<slug>.meta.json)
@@ -436,11 +450,23 @@ export interface Api {
     file: string,
     patch: Record<string, unknown>
   ): Promise<Record<string, unknown> | null>;
-  // Annotations sidecar (Phase 5 — .design/<slug>.annotations.svg)
+  // Annotations board (DDR-242 — .design/<slug>.annotations.json)
+  /** Canonical board text; a not-yet-migrated legacy SVG is read through the migration. */
   loadAnnotations(file: string): Promise<string | null>;
-  saveAnnotations(file: string, svg: string, writeId?: string, base?: string): Promise<boolean>;
+  /** Strict read: an existing board that can't be read is `ok: false`, never an empty board. */
+  readBoard(
+    file: string
+  ): Promise<{ ok: true; text: string | null } | { ok: false; error: string }>;
+  /** Whole-board write (board text or legacy SVG, canonicalized). */
+  saveAnnotations(file: string, text: string, writeId?: string, base?: string): Promise<boolean>;
+  /** The canvas write path: an op batch under the DDR-242 merge rule. */
+  applyAnnotationOps(
+    file: string,
+    ops: readonly AnnotationOp[],
+    actionId?: string
+  ): Promise<AnnotationOpsResult>;
   /** Materialize a document snapshot without publishing it as another user edit. */
-  projectAnnotations(file: string, svg: string, isCurrent: () => boolean): Promise<boolean>;
+  projectAnnotations(file: string, text: 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. */
@@ -818,8 +844,22 @@ export interface ApiHooks {
    */
   /** `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, writeId?: string, base?: string) => void;
+  /**
+   * Fires after every successful annotations write with the new canonical
+   * board text, the action/write id and the board text it replaced (a merge
+   * base for accepted revisions).
+   */
+  onAnnotationsChanged?: (file: string, text: string, writeId?: string, base?: string) => void;
+  /**
+   * Apply an op batch to the canvas's LIVE collab room, when one holds the
+   * board (code review H1). `null` = no live room / accepted mode — the batch
+   * goes to disk. The room's persistence projects the result to the file.
+   */
+  applyAnnotationOpsLive?: (
+    file: string,
+    ops: readonly AnnotationOp[],
+    actionId?: string
+  ) => ApplyResult | 'too-large' | null;
   /**
    * Accepted-revisions mode (DDR-241): propose a folder operation as ONE
    * project action before touching disk. Absent, or answering `null`, means
@@ -865,8 +905,18 @@ export interface ApiHooks {
 // server modules). Re-exported here so every existing `from './api.ts'`
 // import keeps working unchanged.
 export { ASSET_IMAGE_HREF_RE, sanitizeAnnotationSvg } from './annotations-model.ts';
-
-import { sanitizeAnnotationSvg } from './annotations-model.ts';
+export type { AnnotationOp };
+/** Outcome of an annotations op batch (DDR-242 §4). */
+export interface AnnotationOpsResult {
+  ok: boolean;
+  /** Whether the board changed (false for a no-op batch). */
+  changed: boolean;
+  /** Ops the board could not take: `gone` (element deleted), `invalid`, `stale` (strict undo). */
+  rejected: Array<{ id?: string; reason: string; fields?: string[] }>;
+  error?: string;
+  /** The board on disk exists but can't be read — nothing was written (HTTP 409). */
+  unreadable?: boolean;
+}
 
 /**
  * Phase 23 — per-file ceiling for a still image. Raised 10 MB → 50 MB (still
@@ -1574,6 +1624,37 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
   }
 
+  // ---------- File-tree expansion (issue #124) ----------
+  //
+  // Which folders + sections of the Files panel the user left open. Per-user
+  // runtime state (DDR-115): it lives under `_canvas-state/` — already on every
+  // ignore list, never versioned or synced — and goes through `sessionDir`, so
+  // in a cell each member keeps their own tree. A SUBDIRECTORY, not a sibling
+  // file: `/_canvas-state` builds `<fileSlug(file)>.json` from user input with
+  // no host/origin guard, so any flat name here is reachable through it
+  // (`?file=_file-tree` hit `_file-tree.json`). A slug never contains `/`.
+  function treeStateDir(): string {
+    return path.join(sessionDir(paths.canvasStateDir), '_tree');
+  }
+  function treeStatePath(): string {
+    return path.join(treeStateDir(), 'state.json');
+  }
+
+  async function loadTreeState(): Promise<TreeState> {
+    try {
+      return normalizeTreeState(JSON.parse(await Bun.file(treeStatePath()).text()));
+    } catch {
+      return { dirs: [], sections: {} };
+    }
+  }
+
+  async function saveTreeState(state: TreeState): Promise<TreeState> {
+    const safe = normalizeTreeState(state);
+    await mkdir(treeStateDir(), { recursive: true });
+    await Bun.write(treeStatePath(), JSON.stringify(safe, null, 2));
+    return safe;
+  }
+
   // ---------- Timeline media visuals cache (enhanced-video-editing Task 7) ----
   //
   // Filmstrip dataURL strips + waveform peak arrays, keyed `<sha8>:<bucket>`,
@@ -2079,81 +2160,179 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     return await loadCanvasMeta(file);
   }
 
-  // ---------- Annotations sidecar (Phase 5) ----------
+  // ---------- Annotations sidecar (DDR-242 — annotations v2) ----------
   //
-  // Each canvas keeps a single `.annotations.svg` file under `<designRoot>/`
-  // named by the canonical `fileSlug()`. The client posts the full SVG string
-  // on every stroke commit; the server overwrites the file. SVG is bounded at
-  // 1 MB (rejects larger bodies) — well above realistic annotation sizes for
-  // hundreds of strokes but small enough that a malicious POST can't fill the
-  // disk in one round-trip.
+  // Each canvas keeps ONE `<slug>.annotations.json` board under `<designRoot>/`
+  // (canonical, one element per line — annotations/schema.ts). The canvas sends
+  // OPS (`applyAnnotationOps`), never the whole board; whole-board writes
+  // (`saveAnnotations`) remain for imports and headless writers. Every write is
+  // validated element-by-element (DDR-054 — the canvas origin and peers are
+  // untrusted) and capped at MAX_ANNOTATIONS_BYTES.
+  //
+  // A board still stored as a legacy `.annotations.svg` (not yet migrated) is
+  // READ through the v1→v2 migration; the boot migration (annotations/
+  // migrate-boot.ts) rewrites it on disk.
 
   function annotationsPath(file: string): string {
+    return path.join(paths.designRoot, `${fileSlug(file)}.annotations.json`);
+  }
+
+  function legacyAnnotationsPath(file: string): string {
     return path.join(paths.designRoot, `${fileSlug(file)}.annotations.svg`);
   }
 
-  async function loadAnnotations(file: string): Promise<string | null> {
-    try {
-      return await Bun.file(annotationsPath(file)).text();
-    } catch {
-      return null;
+  type BoardRead = { ok: true; text: string | null } | { ok: false; error: string };
+
+  /**
+   * Strict board read. `text: null` = the canvas has no annotations. A file
+   * that EXISTS but is oversized or not a board is `ok: false` — never an
+   * empty board, or the next write would silently erase it (code review H2).
+   */
+  async function readBoard(file: string): Promise<BoardRead> {
+    for (const p of [annotationsPath(file), legacyAnnotationsPath(file)]) {
+      const f = Bun.file(p);
+      if (!(await f.exists())) continue;
+      // Untrusted (peer / git) content: size gate BEFORE reading (DDR-054).
+      if (f.size > MAX_ANNOTATIONS_BYTES) {
+        return { ok: false, error: 'board file exceeds the size cap' };
+      }
+      let raw: string;
+      try {
+        raw = await f.text();
+      } catch {
+        return { ok: false, error: 'board file is unreadable' };
+      }
+      const text = canonicalAnnotations(raw);
+      return text === null
+        ? { ok: false, error: 'board file is not a valid board' }
+        : { ok: true, text };
     }
+    return { ok: true, text: null };
+  }
+
+  /** Canonical board text, or null when the canvas has no annotations (or they can't be read). */
+  async function loadAnnotations(file: string): Promise<string | null> {
+    const r = await readBoard(file);
+    return r.ok ? r.text : null;
+  }
+
+  // Read-modify-write of one board is serialized per file: two op batches
+  // landing together must not both read the same state and drop one another.
+  const annotationChains = new Map<string, Promise<unknown>>();
+  function onAnnotationChain<T>(file: string, fn: () => Promise<T>): Promise<T> {
+    const key = fileSlug(file);
+    const prev = annotationChains.get(key) ?? Promise.resolve();
+    const next = prev.then(fn, fn);
+    annotationChains.set(
+      key,
+      next.catch(() => {})
+    );
+    return next;
+  }
+
+  async function writeBoardFile(file: string, text: string): Promise<void> {
+    await Bun.write(annotationsPath(file), text);
+    // Annotations reach OTHER VIEWERS over the collab room, but the file is also
+    // a versioned, file-plane sidecar (DDR-115), and the file plane learns about
+    // a cell's own writes through exactly this event.
+    announceWritten(`${fileSlug(file)}.annotations.json`);
   }
 
+  /**
+   * Whole-board write (imports, headless writers, legacy PUT). Accepts board
+   * text or a legacy SVG (converted). `base` travels only as a merge hint for
+   * the project — bounded and canonicalized like the value, never written.
+   */
   async function saveAnnotations(
     file: string,
-    svg: string,
+    text: 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
-    // writes of arbitrary blobs through this endpoint.
-    if (!/^\s*<svg[\s>]/i.test(svg)) return false;
-    // A3 (DDR-060 F1 re-audit) — sanitize active content before persisting.
-    // This endpoint is on the canvas-origin allowlist (DDR-054 "inert collab
-    // write") and accepts ANY `file`, so a hub-pushed canvas can write a
-    // sibling's `.annotations.svg`. The persisted SVG is currently consumed only
-    // via `svgToStrokes` (DOMParser image/svg+xml → structured strokes → React
-    // re-render), so a `<script>`/`on*` payload is parsed inertly and discarded
-    // — the stored-XSS chain is LATENT today, not live. We sanitize anyway so
-    // "inert" stays true for any future raw-render consumer and for the synced
-    // file a peer/Claude-context ingests. The legit annotation vocabulary
-    // (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.
+    if (typeof text !== 'string' || text.length > MAX_ANNOTATIONS_BYTES) return false;
+    const clean = canonicalAnnotations(text);
+    if (clean === null) return false;
     const cleanBase =
-      typeof base === 'string' &&
-      base.length <= 1024 * 1024 &&
-      (base === '' || /^\s*<svg[\s>]/i.test(base))
-        ? base === ''
-          ? ''
-          : sanitizeAnnotationSvg(base)
+      typeof base === 'string' && base.length <= MAX_ANNOTATIONS_BYTES
+        ? (canonicalAnnotations(base) ?? undefined)
         : undefined;
-    await Bun.write(annotationsPath(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
-    // through exactly this event — so without it, a sticky note drawn in the
-    // cloud crossed to open browsers instantly and to a peer's DISK a quarter
-    // of an hour later.
-    announceWritten(`${fileSlug(file)}.annotations.svg`);
-    return true;
+    return onAnnotationChain(file, async () => {
+      // Never overwrite a board we can't read — it may hold work (review H2).
+      const read = await readBoard(file);
+      if (!read.ok) return false;
+      let next = clean;
+      if (cleanBase !== undefined) {
+        // With a base, the write is "what changed since base", merged onto the
+        // current board — a whole-board PUT no longer erases concurrent edits
+        // (code review M5). Same one merge rule as the op path.
+        const byId = (t: string) => new Map(parseBoard(t).elements.map((e) => [e.id, e]));
+        const ops = diffToOps(byId(cleanBase), byId(clean));
+        const live = hooks.applyAnnotationOpsLive?.(file, ops, writeId) ?? null;
+        if (live === 'too-large') return false;
+        if (live) return true;
+        const current = read.text ?? serializeBoard([]);
+        next = serializeBoard([...applyAnnotationOpsPure(byId(current), ops).state.values()]);
+        if (next.length > MAX_ANNOTATIONS_BYTES) return false;
+        if (next === current) return true;
+      }
+      await writeBoardFile(file, next);
+      onAnnotationsChanged?.(file, next, writeId, cleanBase);
+      return true;
+    });
+  }
+
+  /**
+   * The canvas write path (DDR-242 §4): apply an op batch under the one merge
+   * rule and persist the result. Ops the board can't take (gone / invalid /
+   * stale) are reported, never silently dropped.
+   */
+  async function applyAnnotationOps(
+    file: string,
+    ops: readonly AnnotationOp[],
+    actionId?: string
+  ): Promise<AnnotationOpsResult> {
+    return onAnnotationChain(file, async () => {
+      const rejectedOf = (r: ApplyResult) =>
+        r.rejected.map((x) => ({
+          id: 'id' in x.op ? x.op.id : x.op.el?.id,
+          reason: x.reason,
+          ...(x.fields ? { fields: x.fields } : {}),
+        }));
+      // A live room is ahead of the file (its flush is debounced): the batch
+      // goes to its replica, or it would revert a peer's unflushed edit (H1).
+      const live = hooks.applyAnnotationOpsLive?.(file, ops, actionId) ?? null;
+      if (live === 'too-large') {
+        return { ok: false, changed: false, rejected: [], error: 'board exceeds the size cap' };
+      }
+      if (live) return { ok: true, changed: live.touched.size > 0, rejected: rejectedOf(live) };
+      const read = await readBoard(file);
+      if (!read.ok) {
+        return { ok: false, changed: false, rejected: [], error: read.error, unreadable: true };
+      }
+      const before = read.text ? parseBoard(read.text).elements : [];
+      const beforeText = serializeBoard(before);
+      const r = applyAnnotationOpsPure(new Map(before.map((e) => [e.id, e])), ops);
+      const rejected = rejectedOf(r);
+      if (!r.touched.size) return { ok: true, changed: false, rejected };
+      const text = serializeBoard([...r.state.values()]);
+      if (text.length > MAX_ANNOTATIONS_BYTES) {
+        return { ok: false, changed: false, rejected, error: 'board exceeds the size cap' };
+      }
+      await writeBoardFile(file, text);
+      onAnnotationsChanged?.(file, text, actionId, beforeText);
+      return { ok: true, changed: true, rejected };
+    });
   }
 
   async function projectAnnotations(
     file: string,
-    svg: string,
+    text: string,
     isCurrent: () => boolean
   ): Promise<boolean> {
-    if (typeof svg !== 'string' || svg.length > 1024 * 1024 || !/^\s*<svg[\s>]/i.test(svg))
-      return false;
+    if (typeof text !== 'string' || text.length > MAX_ANNOTATIONS_BYTES) return false;
     if (!isCurrent()) return false;
-    const clean = sanitizeAnnotationSvg(svg);
+    const clean = canonicalAnnotations(text);
+    if (clean === null) return false;
     // 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.
@@ -2164,7 +2343,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       await Bun.write(temp, clean);
       if (!isCurrent()) return false;
       renameSync(temp, annotationsPath(file));
-      announceWritten(`${fileSlug(file)}.annotations.svg`);
+      announceWritten(`${fileSlug(file)}.annotations.json`);
       return true;
     } finally {
       await rm(temp, { force: true });
@@ -2982,12 +3161,9 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     }
     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()
-      );
+    const board = await loadAnnotations(rel);
+    if (board !== null) {
+      await Bun.write(path.join(paths.designRoot, `${slug}.annotations.json`), board);
     }
     ctx.bus.emit('canvas-list-update', { action: 'added', rel: toRel, slug });
     ctx.bus.emit('canvas-created', { slug });
@@ -3192,7 +3368,7 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
         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)) {
+        } else if (/\.(tsx|jsx|css|meta\.json|annotations\.(?:svg|json))$/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(() => '');
@@ -6621,13 +6797,17 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
     parseMentions,
     loadCanvasState,
     saveCanvasState,
+    loadTreeState,
+    saveTreeState,
     timelineMediaLoad,
     timelineMediaSave,
     loadCanvasMeta,
     loadCanvasSource,
     patchCanvasMeta,
     loadAnnotations,
+    readBoard,
     saveAnnotations,
+    applyAnnotationOps,
     projectAnnotations,
     saveAsset,
     listAssets,