@1agh/maude 1.4.6 → 1.5.1

package/apps/studio/server.ts

@@ -18,6 +18,7 @@ import path from 'node:path';
 import { createAcp } from './acp/index.ts';
 import { cancelInstall, cancelSignin } from './acp/login-state.ts';
 import { createActivity } from './activity.ts';
+import { migrateAnnotationsV2 } from './annotations/migrate-boot.ts';
 import { ASSET_MAX_VIDEO_BYTES, createApi } from './api.ts';
 import { bootSelfHeal } from './boot-self-heal.ts';
 import { isSandboxArmed } from './canvas-build-sandbox.ts';
@@ -129,6 +130,13 @@ const api = createApi(ctx, {
       collab.registry.syncRoomFromAnnotations(api.fileSlug(file), svg, writeId);
     }
   },
+  // Code review H1 — the canvas op path goes to a live room's replica, not to a
+  // file its debounced flush hasn't caught up with. Accepted mode keeps the
+  // disk + proposeLane path: there the hub kernel merges against the base.
+  applyAnnotationOpsLive: (file, ops, actionId) => {
+    if (ctx.syncControl?.current?.()?.acceptedMode?.()) return null;
+    return collab?.registry.applyOpsToRoom(api.fileSlug(file), ops, actionId) ?? null;
+  },
   // feature-file-tree-drag-drop-folders (Task 3) — moveCanvas's collab guard
   // + `_active.json` retarget, bridged the same forward-declared way as the
   // comments/annotations hooks above.
@@ -182,6 +190,13 @@ ctx.bus.on('canvas-list-update', (change) => {
   }
 });
 
+// DDR-242 — convert legacy `<slug>.annotations.svg` boards to
+// `.annotations.json` BEFORE any room seeds or sync scan reads them. Skipped in
+// a cloud workspace: the hub owns that checkout (its workspace agent migrates).
+if (process.env.MAUDE_WORKSPACE_MODE !== '1') {
+  migrateAnnotationsV2({ designRoot: ctx.paths.designRoot });
+}
+
 collab = createCollab(ctx, api);
 const aiActivity = createAiActivity(ctx);
 
@@ -518,6 +533,7 @@ function startCanvasServer(port: number): BunServer {
       '/_api/git-user': http.routes['/_api/git-user'],
       '/_api/canvas-meta': http.routes['/_api/canvas-meta'],
       '/_api/annotations': http.routes['/_api/annotations'],
+      '/_api/annotations/ops': http.routes['/_api/annotations/ops'],
       // Phase 23 — capped binary image upload (magic-byte sniff + category cap +
       // content-addressed name + traversal guard + no-SVG, in api.saveAsset).
       // Bun matches `routes` BEFORE `fetch`, so the route must be listed here

package/apps/studio/sync/accepted-cold-start.ts

@@ -40,7 +40,14 @@
 import { existsSync, readFileSync } from 'node:fs';
 import type * as Y from 'yjs';
 
-import { cssFromDoc, htmlFromDoc, laneValueFromFile, readLaneFromDoc } from './codec.ts';
+import {
+  cssFromDoc,
+  htmlFromDoc,
+  isEmptyAnnotationsSvg,
+  laneValueFromFile,
+  readLaneFromDoc,
+  readLocalAnnotations,
+} from './codec.ts';
 import { commentKey } from './comment-identity.ts';
 import type { CommentLedger } from './comment-ledger.ts';
 import { hashBytes } from './echo-guard.ts';
@@ -180,8 +187,9 @@ export async function acceptedColdStart(
     const metaText = readText(i.paths.meta);
     const meta = metaText === null ? null : laneValueFromFile('meta', metaText);
     if (meta && meta !== '{}') lanes.meta = meta;
-    const ann = readText(i.paths.annotations);
-    if (ann) lanes.annotations = ann;
+    // DDR-242 — canonical board text; a legacy sidecar arrives migrated.
+    const ann = readLocalAnnotations(i.paths.annotations, readText);
+    if (ann && !isEmptyAnnotationsSvg(ann)) lanes.annotations = ann;
     const commentsText = readText(i.paths.comments);
     const comments = commentsText === null ? null : laneValueFromFile('comments', commentsText);
     if (comments) lanes.comments = comments;
@@ -267,7 +275,7 @@ export async function acceptedColdStart(
   // ---- comments / annotations — the accepted value wins (see header)
   for (const lane of ['comments', 'annotations'] as const) {
     const p = lane === 'comments' ? i.paths.comments : i.paths.annotations;
-    const text = readText(p);
+    const text = lane === 'annotations' ? readLocalAnnotations(p, readText) : readText(p);
     const local = text === null ? null : laneValueFromFile(lane, text);
     const accepted = readLaneFromDoc(i.doc, lane);
     if (local === null || local === accepted) {

package/apps/studio/sync/agent.ts

@@ -5,7 +5,7 @@
 //
 //   `.design/<slug>.html`           ←→ Y.Text  (Y_SYNC_TYPES.html)
 //   `.design/_comments/<slug>.json` ←→ Y.Array (Y_TYPES.comments)
-//   `.design/<slug>.annotations.svg`←→ Y.Map.svg (Y_TYPES.annotations)
+//   `.design/<slug>.annotations.json`←→ 'annotations2' replica (DDR-242)
 //
 // Provider is INJECTED — the agent doesn't import @hocuspocus/provider. This
 // keeps the orchestration testable with an in-memory pair of Y.Docs (no hub
@@ -51,10 +51,13 @@ import {
   commentsFromDoc,
   cssFromDoc,
   htmlFromDoc,
+  importAnnotationsFromDisk,
   isEmptyAnnotationsSvg,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
   movedToFromDoc,
+  noteAnnotationsOnDisk,
+  readLocalAnnotations,
   repairSharedMeta,
   stampAnnotationsEdit,
   stampBodyEdit,
@@ -88,7 +91,7 @@ export interface CanvasSyncPaths {
   html: string;
   /** Absolute path to <designRoot>/_comments/<slug>.json. */
   comments: string;
-  /** Absolute path to <designRoot>/<slug>.annotations.svg. */
+  /** Absolute path to <designRoot>/<slug>.annotations.json (DDR-242). */
   annotations: string;
   /** Absolute path to the canvas `.meta.json` (sibling of the body). Optional:
    *  when set (always, in production wiring), shared meta keys (layout/artboards)
@@ -368,6 +371,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     }
     const hash = hashBytes(value);
     echoGuard.record(paths.annotations, hash);
+    noteAnnotationsOnDisk(doc, value);
     writer(paths.annotations, value);
     lastAnnotations = value;
   }
@@ -438,7 +442,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       // wrapper written by saveAnnotations) cold-start-safe on other peers.
       let changed = false;
       doc.transact(() => {
-        changed = applyAnnotationsToDoc(doc, str, origin);
+        changed = importAnnotationsFromDisk(doc, str, origin, lastAnnotations);
         if (changed) stampAnnotationsEdit(doc, origin);
       }, origin);
       if (changed) lastAnnotations = str;
@@ -470,7 +474,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     if (movedToFromDoc(doc) !== null) return;
     const localHtml = readLocal(paths.html);
     const localComments = readLocal(paths.comments);
-    const localAnnotations = readLocal(paths.annotations);
+    const localAnnotations = readLocalAnnotations(paths.annotations, readLocal);
     const localMeta = paths.meta ? readLocal(paths.meta) : null;
     const localCss = paths.css ? readLocal(paths.css) : null;
 

package/apps/studio/sync/codec.ts

@@ -1,4 +1,3 @@
-import { ANNOTATION_WRITE_ID } from '../annotations-sync.ts';
 // Y.Doc ↔ disk codecs for the bidirectional file sync agent (Phase 9 Task 4).
 //
 // The agent shuttles three classes of files between disk and the Y.Doc the
@@ -6,7 +5,8 @@ import { ANNOTATION_WRITE_ID } from '../annotations-sync.ts';
 //
 //   `.design/<canvas>.html`             -> Y.Text     (Y_SYNC_TYPES.html)
 //   `.design/_comments/<slug>.json`     -> Y.Array    (Y_TYPES.comments  — Phase 6)
-//   `.design/<slug>.annotations.svg`    -> Y.Map.svg  (Y_TYPES.annotations — Phase 5)
+//   `.design/<slug>.annotations.json`   -> Y.Map      ('annotations2' — DDR-242; per-element replica,
+//                                                   see annotations/replica.ts)
 //
 // v1.1 design decision (plan §"Key insight"): HTML body is treated as opaque
 // Y.Text rather than structured Y.XmlFragment. Round-trip drift would
@@ -26,6 +26,18 @@ import { hostname } from 'node:os';
 import { diffChars } from 'diff';
 import type * as Y from 'yjs';
 
+import { annotationsLaneValue, canonicalAnnotations } from '../annotations/board-text.ts';
+import { applyOps, diffToOps } from '../annotations/ops.ts';
+import '../annotations/ops-merge.ts';
+import {
+  annotationsOnDiskOf,
+  isEmptyBoardText,
+  noteAnnotationsOnDisk,
+  readReplica,
+  replicaBoardText,
+  writeReplica,
+} from '../annotations/replica.ts';
+import { parseBoard, serializeBoard } from '../annotations/schema.ts';
 import { Y_TYPES } from '../collab/persistence.ts';
 import { commentKey, dedupeCommentsById } from './comment-identity.ts';
 import {
@@ -293,30 +305,84 @@ export function applyCommentsToDoc(doc: Y.Doc, next: CommentsSnapshot, origin?:
 
 /* ---------------------------------------------------------------- annotations */
 
-/** Returns the annotations SVG string, or null if unset. */
+export { canonicalAnnotations };
+
+/**
+ * The local board (canonical text) at `jsonPath`, falling back to a not-yet-
+ * migrated legacy `.annotations.svg` sibling — so a cold start that races the
+ * boot migration still sees the local strokes instead of "no local" (which lets
+ * the hub win by default: the DDR-223 eraser shape). null = neither exists.
+ */
+export function readLocalAnnotations(
+  jsonPath: string,
+  read: (abs: string) => string | null
+): string | null {
+  const local = read(jsonPath);
+  if (local !== null) return canonicalAnnotations(local) ?? local;
+  const legacy = read(jsonPath.replace(/\.json$/, '.svg'));
+  return legacy === null ? null : canonicalAnnotations(legacy);
+}
+
+/** The board held by the doc as canonical text, or null if never populated. */
 export function annotationsFromDoc(doc: Y.Doc): string | null {
-  const map = doc.getMap<unknown>(Y_TYPES.annotations);
-  const svg = map.get('svg');
-  return typeof svg === 'string' ? svg : null;
+  return replicaBoardText(doc);
 }
 
 /**
- * True when an annotations value carries ZERO strokes: null, `''`, or the bare
- * serialized wrapper `<svg …></svg>` with no child elements (what
- * `strokesToSvg([])` emits — 72 bytes, constant across peers).
+ * True when an annotations value carries ZERO elements: null, `''`, an empty
+ * board, or the bare legacy wrapper `<svg …></svg>`.
  *
- * This distinction is load-bearing for cold start (the 2026-08-14 annotations
- * eraser): the wrapper is a non-empty STRING, so every `!== ''` emptiness
- * guard let a stale hub wrapper overwrite a peer's real strokes — and with the
- * strokes went the `assets/<sha8>` references the asset lane pulled by, so
- * freshly dropped images never crossed machines. Live delete-all still materializes
- * the wrapper through `writeAnnotationsIfChanged` (deletes must propagate);
- * only COLD-START decisions treat it as emptiness.
+ * Load-bearing for cold start (the 2026-08-14 annotations eraser, DDR-223): the
+ * legacy wrapper was a non-empty STRING, so every `!== ''` guard let a stale hub
+ * wrapper overwrite a peer's real strokes. Emptiness is "zero elements", never a
+ * byte heuristic. Live delete-all still materializes; only COLD-START decisions
+ * treat this as emptiness.
+ */
+export function isEmptyAnnotationsSvg(text: string | null): boolean {
+  return isEmptyBoardText(text);
+}
+
+/**
+ * Make the doc's replica hold `next` (board text or legacy SVG), writing only
+ * the elements / fields that differ. `null` / `''` → an empty board. A
+ * filesystem import is a new operation, never the previous UI author's echo:
+ * `writeReplica` clears '~action' on any change made without an action id.
+ */
+/**
+ * A disk change to the board, imported into the doc as the CHANGE it made —
+ * the ops from what disk last held to what it holds now — never as a
+ * replacement. A projection written a moment before a newer edit, whose file
+ * event arrives after it, would otherwise put the older values back (the
+ * multiplayer rig's lost toolbar edits and deletes). Without a known base
+ * (first sight of the file) it is a full apply. Returns whether the doc changed.
  */
-export function isEmptyAnnotationsSvg(svg: string | null): boolean {
-  if (svg === null) return true;
-  if (svg.trim() === '') return true;
-  return /^\s*<svg\b[^>]*>\s*<\/svg>\s*$/i.test(svg);
+export { noteAnnotationsOnDisk };
+
+export function importAnnotationsFromDisk(
+  doc: Y.Doc,
+  next: string | null,
+  origin?: unknown,
+  fallbackBase?: string | null
+): boolean {
+  const text = next === null ? serializeBoard([]) : canonicalAnnotations(next);
+  if (text === null || byteLengthUtf8(text) > MAX_ANNOTATIONS_BYTES) {
+    return applyAnnotationsToDoc(doc, next, origin);
+  }
+  const known = annotationsOnDiskOf(doc);
+  const base =
+    (known !== undefined ? canonicalAnnotations(known) : null) ??
+    (fallbackBase ? canonicalAnnotations(fallbackBase) : null);
+  const cur = readReplica(doc);
+  noteAnnotationsOnDisk(doc, text);
+  if (base === null || cur === null) {
+    return applyAnnotationsToDoc(doc, text, origin);
+  }
+  const toMap = (t: string) => new Map(parseBoard(t).elements.map((e) => [e.id, e]));
+  const ops = diffToOps(toMap(base), toMap(text));
+  if (!ops.length) return false;
+  const r = applyOps(new Map(cur.elements.map((e) => [e.id, e])), ops);
+  if (!r.touched.size) return false;
+  return writeReplica(doc, [...r.state.values()], origin);
 }
 
 export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?: unknown): boolean {
@@ -326,21 +392,13 @@ export function applyAnnotationsToDoc(doc: Y.Doc, next: string | null, origin?:
     );
     return false;
   }
-  const map = doc.getMap<unknown>(Y_TYPES.annotations);
-  const current = map.get('svg');
-  const currentStr = typeof current === 'string' ? current : null;
-  if (currentStr === next) return false;
-
-  doc.transact(() => {
-    // A filesystem import is a new operation, never the previous UI author's echo.
-    map.delete(ANNOTATION_WRITE_ID);
-    if (next === null || next === '') {
-      map.delete('svg');
-    } else {
-      map.set('svg', next);
-    }
-  }, origin);
-  return true;
+  const text = next === null ? serializeBoard([]) : canonicalAnnotations(next);
+  if (text === null) {
+    console.warn('[sync/codec] refusing annotations apply: not a board document');
+    return false;
+  }
+  if (readReplica(doc) !== null && replicaBoardText(doc) === text) return false;
+  return writeReplica(doc, parseBoard(text).elements, origin);
 }
 
 /* ---------------------------------------------------------------- meta */
@@ -426,7 +484,8 @@ export function laneValueFromFile(
   lane: 'html' | 'css' | 'meta' | 'annotations' | 'comments',
   text: string
 ): string | null {
-  if (lane === 'html' || lane === 'css' || lane === 'annotations') return text;
+  if (lane === 'html' || lane === 'css') return text;
+  if (lane === 'annotations') return annotationsLaneValue(text);
   let parsed: unknown;
   try {
     parsed = parseJsonSafe(text);
@@ -448,10 +507,7 @@ export function readLaneFromDoc(
   lane: 'html' | 'css' | 'meta' | 'annotations' | 'comments'
 ): string {
   if (lane === 'html' || lane === 'css' || lane === 'meta') return doc.getText(lane).toString();
-  if (lane === 'annotations') {
-    const svg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
-    return typeof svg === 'string' ? svg : '';
-  }
+  if (lane === 'annotations') return annotationsLaneValue(replicaBoardText(doc) ?? '') ?? '';
   const list = doc.getArray<unknown>(Y_TYPES.comments).toArray();
   return list.length ? JSON.stringify(list) : '';
 }

package/apps/studio/sync/file-membership.ts

@@ -199,6 +199,16 @@ export interface ClassifyOptions {
  * `node_modules`, directory segments start alphanumeric, the final segment
  * may start with `_`.
  */
+/**
+ * The annotations board (DDR-242: `<slug>.annotations.json`) and its legacy v1
+ * form (`<slug>.annotations.svg`). BOTH stay canvas-owned: the board is the doc
+ * lane's, and a stale legacy sidecar must never ride the file plane between
+ * machines (the boot migration quarantines it locally).
+ */
+function isAnnotationsSidecar(lowerName: string): boolean {
+  return lowerName.endsWith('.annotations.json') || lowerName.endsWith('.annotations.svg');
+}
+
 export function classifyProjectFile(rel: string, opts: ClassifyOptions = {}): FileClass {
   const parts = relShape(rel);
   if (parts === null) return 'never';
@@ -219,7 +229,7 @@ export function classifyProjectFile(rel: string, opts: ClassifyOptions = {}): Fi
     // The canvas body and its NAMED sidecars — Plane A's, by construction.
     if (lowerLast.endsWith('.tsx')) return 'canvas-owned';
     if (lowerLast.endsWith('.meta.json')) return 'canvas-owned';
-    if (lowerLast.endsWith('.annotations.svg')) return 'canvas-owned';
+    if (isAnnotationsSidecar(lowerLast)) return 'canvas-owned';
     if (lowerLast.endsWith('.css') && opts.hasFile) {
       const sibling = `${rel.slice(0, -'.css'.length)}.tsx`;
       if (opts.hasFile(sibling)) return 'canvas-owned';
@@ -238,7 +248,7 @@ export function classifyProjectFile(rel: string, opts: ClassifyOptions = {}): Fi
   // pushed over them at 10:50:33). The annotations lane's own stamped
   // newest-wins protection never saw it coming — it guards the DOC lane, and
   // this was the file plane acting alone. One owner: the canvas.
-  if (parts.length === 1 && lowerLast.endsWith('.annotations.svg')) return 'canvas-owned';
+  if (parts.length === 1 && isAnnotationsSidecar(lowerLast)) return 'canvas-owned';
 
   if (COMPANION_SIDECAR_SUFFIXES.some((s) => lowerLast.endsWith(s))) return 'companion-text';
 

package/apps/studio/sync/file-plane.ts

@@ -2397,7 +2397,7 @@ function holdOversized(out: FilePlaneResult, ledger: FileLedger, file: Oversized
 function referencedAssetNames(designRoot: string): Set<string> {
   const out = new Set<string>();
   const RE = /assets\/([A-Za-z0-9._-]+\.[A-Za-z0-9]+)/g;
-  const SCANNED = /\.(?:annotations\.svg|tsx|jsx|css|meta\.json)$/i;
+  const SCANNED = /\.(?:annotations\.(?:svg|json)|tsx|jsx|css|meta\.json)$/i;
   const walk = (dir: string, depth: number): void => {
     if (depth > MAX_WALK_DEPTH) return;
     let entries: Dirent[];

package/apps/studio/sync/index.ts

@@ -33,6 +33,8 @@ import { hostname } from 'node:os';
 import path from 'node:path';
 import type { Awareness } from 'y-protocols/awareness';
 import * as Y from 'yjs';
+import { migrateAnnotationsV2 } from '../annotations/migrate-boot.ts';
+import { REPLICA_TYPE, replicaBoardText } from '../annotations/replica.ts';
 import { renewHubCredential } from '../cloud/renew.ts';
 import { Y_TYPES } from '../collab/persistence.ts';
 import type { Context, LinkedHub } from '../context.ts';
@@ -71,13 +73,14 @@ import { createFsReader, type FsReader } from './fs-mirror.ts';
 import { type HubDocRow, hubHolds, indexHubDocs } from './hub-listing.ts';
 import { getHubRecord } from './hubs-config.ts';
 import { loadJournal, type SyncJournal } from './journal.ts';
-import { hasLedger, hubCapabilities } from './journal-client.ts';
+import { hasAnnotationsV2, hasLedger, hubCapabilities } from './journal-client.ts';
 import { isLoopbackHost } from './loopback.ts';
 import { migrateFlatFallback } from './migrate-flat-fallback.ts';
 import { migrateSeed } from './migrate-seed.ts';
 import { ORIGINS } from './origins.ts';
 import { createDocProjection, type DocProjection } from './projection.ts';
 import {
+  acceptedListing,
   describeRemoteDiff,
   diffRemoteDocs,
   fetchRemoteListing,
@@ -2070,12 +2073,10 @@ export function createSyncRuntime(
     // connect before doc.create commits; pulling that empty room would lock
     // the receiver onto a lossy slug-derived path before the real path arrives.
     // The accepted manifest alone names live canvases, including successors
-    // of retired documents whose transport rows may still linger.
-    const bytesByName = new Map((listing?.documents ?? []).map((d) => [d.name, d.bytes]));
-    const documents = manifest.docs
-      .filter((d) => !d.retired)
-      .map((d) => ({ name: d.doc, bytes: bytesByName.get(d.doc) ?? 1 }));
-    return { ...(listing ?? { tombstones: [] }), documents, tombstones: listing?.tombstones ?? [] };
+    // of retired documents whose transport rows may still linger — and a
+    // legacy tombstone for a name the manifest lists live no longer buries it
+    // (see `acceptedListing`).
+    return { ...(listing ?? {}), ...acceptedListing(listing, manifest.docs) };
   }
 
   /**
@@ -2242,6 +2243,9 @@ export function createSyncRuntime(
         designRoot: ctx.paths.designRoot,
         designRel: ctx.paths.designRel,
       });
+      // DDR-242 — idempotent; also covers a runtime cycled after boot (a
+      // project linked from the cloud panel) whose tree gained a v1 board.
+      migrateAnnotationsV2({ designRoot: ctx.paths.designRoot });
     }
 
     const scan = opts.canvases ? { canvases: opts.canvases, tsxCount: 0 } : await scanCanvases(ctx);
@@ -2382,18 +2386,23 @@ export function createSyncRuntime(
       path.sep,
       { ...pathOpts, realpath: realpathOfDeepestExisting, pathFor: manifestPathFor }
     );
-    const pullNote = describeRemoteDiff(remoteDiff);
+    // Named as it will actually happen: a canvas the project deleted is listed
+    // for a tick after its tombstone and is not pulled, so it is not announced.
+    const pullNote = describeRemoteDiff({
+      ...remoteDiff,
+      hubOnly: remoteDiff.hubOnly.filter((d) => !tombstoned.has(slugFromDocName(d.name) ?? '')),
+    });
     if (pullNote) console.log(`[sync] ${pullNote}`);
     /** Descriptor paths for one slug at one body path. The sidecar rules live
      *  here, once: `.meta.json`/`.css` are SIBLINGS of the body, while
-     *  `.annotations.svg` is keyed by the flat slug at the design root — the
+     *  `.annotations.json` is keyed by the flat slug at the design root — the
      *  asymmetry `workspace-files.mjs` documents, and which moving the body
      *  must not quietly change. */
     const descriptorFor = (slug: string, bodyAbs: string): CanvasDescriptor => ({
       slug,
       html: bodyAbs,
       comments: path.join(ctx.paths.commentsDir, `${slug}.json`),
-      annotations: path.join(ctx.paths.designRoot, `${slug}.annotations.svg`),
+      annotations: path.join(ctx.paths.designRoot, `${slug}.annotations.json`),
       meta: bodyAbs.replace(/\.tsx$/i, '.meta.json'),
       css: bodyAbs.replace(/\.tsx$/i, '.css'),
     });
@@ -3892,21 +3901,23 @@ export function createSyncRuntime(
               const agentOrigin = agent.origin;
               const slug = canvas.slug;
               const provComments = provider.document.getArray(Y_TYPES.comments);
-              const provAnn = provider.document.getMap(Y_TYPES.annotations);
+              // DDR-242 — the annotations replica: relay the board, the room
+              // diffs it per element (writeReplica), so only changes cross.
+              const provAnn = provider.document.getMap(REPLICA_TYPE);
               const onComments = (_e: unknown, tx: { origin: unknown }) => {
                 if (tx.origin === agentOrigin) return;
                 reg.syncRoomFromComments?.(slug, provComments.toArray());
               };
               const onAnn = (_e: unknown, tx: { origin: unknown }) => {
                 if (tx.origin === agentOrigin) return;
-                const svg = provAnn.get('svg');
-                if (typeof svg === 'string') reg.syncRoomFromAnnotations?.(slug, svg);
+                const board = replicaBoardText(provider.document);
+                if (board !== null) reg.syncRoomFromAnnotations?.(slug, board);
               };
               provComments.observe(onComments);
-              provAnn.observe(onAnn);
+              provAnn.observeDeep(onAnn);
               noteDetach(statusDetaches, canvas.slug, () => {
                 provComments.unobserve(onComments);
-                provAnn.unobserve(onAnn);
+                provAnn.unobserveDeep(onAnn);
               });
             }
           },
@@ -4646,6 +4657,17 @@ export function createSyncRuntime(
       void hubCapabilities({ hubUrl: linkedHub.url, signal: fileEventsProbe.signal })
         .then((caps) => {
           if (stopped) return;
+          // DDR-242 — a hub that predates the annotations-v2 model still keeps
+          // boards as SVG: its workspace checkout and kernel would not carry
+          // this studio's `.annotations.json` edits. Say so loudly; the
+          // annotations themselves stay safe (a v1 hub never writes the v2
+          // replica, and this studio never reads its SVG as authoritative).
+          if (caps !== null && !hasAnnotationsV2(caps)) {
+            console.warn(
+              `[sync] ${linkedHub.url} does not advertise annotations-v2 — update the hub; ` +
+                'whiteboard edits will not reach its checkout until it is'
+            );
+          }
           if (!hasLedger(caps)) {
             // No journal on this hub ⇒ the legacy client carries the upward
             // lane, exactly as the pre-v2 desktop did (Open decision 4).
@@ -5355,7 +5377,7 @@ async function walk(
       slug,
       html: abs,
       comments: path.join(commentsDir, `${slug}.json`),
-      annotations: path.join(designRoot, `${slug}.annotations.svg`),
+      annotations: path.join(designRoot, `${slug}.annotations.json`),
       // The `.meta.json` sidecar sits next to the body: `Foo.tsx` → `Foo.meta.json`.
       meta: abs.replace(/\.(tsx|html)$/i, '.meta.json'),
       // The `.css` sibling: `Foo.tsx` → `Foo.css` (absent for inline-CSS canvases).

package/apps/studio/sync/journal-client.ts

@@ -212,6 +212,11 @@ export async function hubCapabilities(opts: {
   }
 }
 
+/** Does this hub keep annotations as the v2 element model (DDR-242)? */
+export function hasAnnotationsV2(capabilities: string[] | null): boolean {
+  return Array.isArray(capabilities) && capabilities.includes('annotations-v2');
+}
+
 /** Does this hub carry the journal file plane? */
 export function hasLedger(capabilities: string[] | null): boolean {
   return Array.isArray(capabilities) && capabilities.includes('ledger');

package/apps/studio/sync/limits.ts

@@ -15,8 +15,13 @@
 export const MAX_HTML_BYTES = 4 * 1024 * 1024;
 /** `_comments/<slug>.json`, serialized. */
 export const MAX_COMMENTS_BYTES = 1 * 1024 * 1024;
-/** `<slug>.annotations.svg`. */
-export const MAX_ANNOTATIONS_BYTES = 1 * 1024 * 1024;
+/**
+ * `<slug>.annotations.json` (DDR-242). Must equal `MAX_BOARD_BYTES` in
+ * annotations/constants.ts — annotations-v2-replica.test.ts pins the pair.
+ * Raised from v1's 1 MB: the v1 cap bit at ~3.7k elements, and the v2 board is
+ * ~3× more compact, so 4 MB is ≈ 20k typical elements (the element-count cap).
+ */
+export const MAX_ANNOTATIONS_BYTES = 4 * 1024 * 1024;
 /** The shared subset of a canvas `.meta.json`. */
 export const MAX_META_BYTES = 1 * 1024 * 1024;
 /** The canvas's sibling stylesheet. */

package/apps/studio/sync/migrate-seed.ts

@@ -34,10 +34,12 @@ import path from 'node:path';
 
 import type * as Y from 'yjs';
 
+import { readReplica } from '../annotations/replica.ts';
 import { Y_TYPES } from '../collab/persistence.ts';
 import { atomicWrite } from './atomic-write.ts';
 import {
   annotationsEditAtFromDoc,
+  annotationsFromDoc,
   applyAnnotationsToDoc,
   applyCommentsToDoc,
   applyCssToDoc,
@@ -45,6 +47,7 @@ import {
   applyMetaToDoc,
   bodyEditAtFromDoc,
   isEmptyAnnotationsSvg,
+  readLocalAnnotations,
   stampAnnotationsEdit,
   stampBodyEdit,
   Y_SYNC_TYPES,
@@ -155,8 +158,9 @@ export function docIsEmpty(doc: Y.Doc): boolean {
   if (doc.getText(Y_SYNC_TYPES.css).length > 0) return false;
   if (doc.getText(Y_SYNC_TYPES.meta).length > 0) return false;
   if (doc.getArray(Y_TYPES.comments).length > 0) return false;
-  const svg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
-  if (typeof svg === 'string' && svg.length > 0) return false;
+  // DDR-242 — the annotations replica (or a legacy v1 value read through the
+  // migration): content means at least one element.
+  if ((readReplica(doc)?.elements.length ?? 0) > 0) return false;
   return true;
 }
 
@@ -174,7 +178,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   const localHtml =
     diskHtml !== null && sourceError(paths.html, diskHtml) === null ? diskHtml : null;
   const localComments = readLocal(paths.comments);
-  const localAnnotations = readLocal(paths.annotations);
+  const localAnnotations = readLocalAnnotations(paths.annotations, readLocal);
   const localMeta = paths.meta ? readLocal(paths.meta) : null;
   const readCss = paths.css ? readLocal(paths.css) : null;
   const localCss = readCss === null ? null : (collapseRepeatedText(readCss)?.unit ?? readCss);
@@ -355,8 +359,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   // right after this seed ran. Resolve the lane here, before the room
   // materializes: unstamped emptiness never beats content.
   {
-    const docSvg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
-    const docAnnotations = typeof docSvg === 'string' ? docSvg : '';
+    const docAnnotations = annotationsFromDoc(doc) ?? '';
     const annDecision = decideAnnotationsColdStart({
       local: localAnnotations,
       doc: docAnnotations,

package/apps/studio/sync/projection.ts

@@ -37,10 +37,12 @@ import {
   applyMetaToDoc,
   cssFromDoc,
   htmlFromDoc,
+  importAnnotationsFromDisk,
   laneValueFromFile,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
   movedToFromDoc,
+  noteAnnotationsOnDisk,
   readLaneFromDoc,
   stampAnnotationsEdit,
   stampBodyEdit,
@@ -84,7 +86,7 @@ export interface ProjectionPaths {
   html: string;
   /** Absolute path to `_comments/<slug>.json`. */
   comments: string;
-  /** Absolute path to `<slug>.annotations.svg`. */
+  /** Absolute path to `<slug>.annotations.json` (DDR-242). */
   annotations: string;
   /** Absolute path to the canvas `.meta.json` sibling (optional). */
   meta?: string;
@@ -449,6 +451,9 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
    * fire must never cost the write that already succeeded.
    */
   function writeAndAnnounce(path: string, value: string): void {
+    // The board disk holds from here on — the base a later file event is
+    // imported against (codec importAnnotationsFromDisk).
+    if (path === paths.annotations) noteAnnotationsOnDisk(doc, value);
     if (readLocal(path) === value) return;
     writer(path, value);
     try {
@@ -1159,7 +1164,7 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
       // survives cold start on other peers (the 2026-08-14 eraser fix).
       let changed = false;
       doc.transact(() => {
-        changed = applyAnnotationsToDoc(doc, str, importOrigin);
+        changed = importAnnotationsFromDisk(doc, str, importOrigin);
         if (changed) stampAnnotationsEdit(doc, importOrigin);
       }, importOrigin);
       return changed;