@1agh/maude 1.4.6 → 1.5.0

package/apps/studio/collab/index.ts

@@ -4,6 +4,9 @@
 import { readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 
+import { canonicalAnnotations } from '../annotations/board-text.ts';
+import { diffToOps } from '../annotations/ops.ts';
+import { parseBoard } from '../annotations/schema.ts';
 import type { Api } from '../api.ts';
 import type { Context } from '../context.ts';
 
@@ -59,10 +62,27 @@ export function createCollab(ctx: Context, api: Api): Collab {
   // (the predicate is only consulted at room-seed time, after `registry` is
   // assigned). Flag-OFF → predicate returns true → seed unchanged.
   let registryRef: Registry | null = null;
+  // Board texts this process's rooms projected to disk and whose watcher echo
+  // hasn't come back yet (a few per slug: flushes can outrun the watcher).
+  const ownProjections = new Map<string, string[]>();
+  // The board as disk last held it while the room agreed with it (the room's
+  // own projection, or an external write it imported). An external write is
+  // applied as the CHANGE from this base, never as a replacement: a room edit
+  // not yet flushed (a delete, a move) survives a writer that didn't know it.
+  const diskBase = new Map<string, string>();
   const persistence = createPersistence({
     ctx,
     api,
     fileForSlug,
+    onAnnotationsProjected: (slug, board) => {
+      const list = ownProjections.get(slug) ?? [];
+      list.push(board);
+      ownProjections.set(slug, list.slice(-4));
+      diskBase.set(slug, board);
+    },
+    onAnnotationsSeeded: (slug, board) => {
+      diskBase.set(slug, board);
+    },
     shouldSeed: (slug) => !(ctx.sharedDoc && registryRef?.isPinned(slug)),
     // Issue #133 — record comment ids as synced only once the hub holds them,
     // and only for the room that IS the hub's doc (pinned). No hub linked:
@@ -88,9 +108,9 @@ export function createCollab(ctx: Context, api: Api): Collab {
       };
       const file = await fileForSlug(slug);
       if (!file) return;
-      if (newerThanCache(path.join(ctx.paths.designRoot, `${slug}.annotations.svg`))) {
-        const svg = await api.loadAnnotations(file);
-        if (svg) applyAnnotationsToDoc(doc, svg, 'seed');
+      if (newerThanCache(path.join(ctx.paths.designRoot, `${slug}.annotations.json`))) {
+        const board = await api.loadAnnotations(file);
+        if (board) applyAnnotationsToDoc(doc, board, 'seed');
       }
       if (newerThanCache(path.join(ctx.paths.commentsDir, `${slug}.json`))) {
         applyCommentsToDoc(doc, await api.loadCommentsForFile(file), 'seed');
@@ -124,7 +144,9 @@ export function createCollab(ctx: Context, api: Api): Collab {
     registry.peek(slug) !== null && !registry.isPinned(slug);
   const reseedFromDisk = async (rel: string): Promise<void> => {
     const cm = /^_comments\/(.+)\.json$/.exec(rel);
-    const am = /^(.+)\.annotations\.svg$/.exec(rel);
+    // DDR-242 — the board file. A legacy `.annotations.svg` reappearing on disk
+    // is NOT a board write (the boot migration quarantines it).
+    const am = /^(.+)\.annotations\.json$/.exec(rel);
     const slug = cm?.[1] ?? am?.[1];
     if (!slug) return;
     const abs = path.join(ctx.paths.designRoot, rel);
@@ -149,7 +171,29 @@ export function createCollab(ctx: Context, api: Api): Collab {
         if (ownsRoomFromDisk(slug)) registry.syncRoomFromComments(slug, parsed);
         if (file) ctx.bus.emit('comments', { file, comments: parsed });
       } else if (ownsRoomFromDisk(slug)) {
-        registry.syncRoomFromAnnotations(slug, readFileSync(abs, 'utf8'));
+        const text = readFileSync(abs, 'utf8');
+        // The room's own projection coming back: the room is at or AHEAD of
+        // it (an op may have landed since), so re-seeding from it would revert
+        // that op. Consumed once, so a later external write of the same bytes
+        // still re-seeds.
+        const own = ownProjections.get(slug);
+        const at = own ? own.indexOf(canonicalAnnotations(text) ?? '') : -1;
+        if (own && at >= 0) {
+          own.splice(0, at + 1);
+          return;
+        }
+        const next = canonicalAnnotations(text);
+        const base = diskBase.get(slug);
+        if (next !== null && base !== undefined) {
+          const toMap = (t: string) => new Map(parseBoard(t).elements.map((e) => [e.id, e]));
+          const ops = diffToOps(toMap(base), toMap(next));
+          diskBase.set(slug, next);
+          if (!ops.length) return;
+          const applied = registry.applyOpsToRoom(slug, ops);
+          if (applied !== null && applied !== 'too-large') return;
+        }
+        if (next !== null) diskBase.set(slug, next);
+        registry.syncRoomFromAnnotations(slug, text);
       }
     } catch {
       /* file vanished mid-flight or unreadable — leave state as-is */

package/apps/studio/collab/persistence.ts

@@ -1,11 +1,13 @@
 // DDR-051 persistence wiring — bridges Room callbacks to the existing JSON
-// snapshots (Phase 6 _comments/<slug>.json) + Phase 5 annotations.svg + the
+// snapshots (Phase 6 _comments/<slug>.json) + the annotations board (DDR-242) + the
 // new `.ydoc.bin` cache under _state/<slug>.ydoc.bin.
 
 import path from 'node:path';
 
 import * as Y from 'yjs';
 
+import { noteAnnotationsOnDisk, replicaBoardText, writeReplica } from '../annotations/replica.ts';
+import { parseBoard } from '../annotations/schema.ts';
 import type { Api } from '../api.ts';
 import type { Context } from '../context.ts';
 // From the LEAF, never from `sync/codec.ts` — codec imports `Y_TYPES` from this
@@ -23,6 +25,8 @@ import { ensureStateDir, type RoomCallbacks } from './room.ts';
  */
 export const Y_TYPES = {
   comments: 'comments',
+  /** v1 annotations map (`svg` key) — read only for lazy migration; the v2
+   *  replica lives in 'annotations2' (annotations/replica.ts, DDR-242). */
   annotations: 'annotations',
   presentation: 'presentation',
 } as const;
@@ -61,6 +65,16 @@ export interface PersistenceDeps {
    * seed). Absent → cache-only restore, the previous behavior.
    */
   reconcileAfterCache?: (slug: string, doc: Y.Doc, cachedAtMs: number) => Promise<void>;
+  /**
+   * Called with the board text a flush just projected to
+   * `<slug>.annotations.json`. The disk→room re-seed uses it to recognise the
+   * room's OWN write coming back through the file watcher: by then the room
+   * may be ahead (a later op), and re-seeding it from that echo reverted the
+   * later edit.
+   */
+  onAnnotationsProjected?: (slug: string, board: string) => void;
+  /** The board a room was seeded from — the disk state it starts out agreeing with. */
+  onAnnotationsSeeded?: (slug: string, board: string) => void;
   /**
    * Issue #133 — which comment ids this machine synced before (see
    * sync/comment-ledger.ts). Defaults to the process-wide ledger for the design
@@ -286,10 +300,12 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
         if (missing.length > 0) arr.push(missing);
       }
       if (svg && typeof svg === 'string') {
-        const map = doc.getMap<string>(Y_TYPES.annotations);
-        map.set('svg', svg);
+        // DDR-242 — `loadAnnotations` returns canonical board text (a legacy
+        // sidecar arrives already migrated); the replica takes it per element.
+        writeReplica(doc, parseBoard(svg).elements, 'seed');
       }
     }, 'seed');
+    if (svg && typeof svg === 'string') deps.onAnnotationsSeeded?.(slug, svg);
   }
 
   async function persistJson(slug: string, doc: Y.Doc): Promise<void> {
@@ -339,16 +355,21 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
       }
     }
 
-    // Annotations — Y.Map.svg → annotations.svg file. Task 5.
-    const map = doc.getMap<unknown>(Y_TYPES.annotations);
-    const svg = map.get('svg');
-    if (typeof svg === 'string' && svg) {
-      if (withinCap(slug, 'annotations', svg, MAX_ANNOTATIONS_BYTES)) {
+    // Annotations — the replica → `<slug>.annotations.json` (DDR-242). A doc
+    // that was never populated (null) writes nothing, so a cold room can't
+    // clobber the file with emptiness (DDR-223).
+    const board = replicaBoardText(doc);
+    if (board !== null) {
+      if (withinCap(slug, 'annotations', board, MAX_ANNOTATIONS_BYTES)) {
         // Projection must never re-enter onAnnotationsChanged: an old flush
-        // finishing after a new edit otherwise republishes the old SVG and
+        // finishing after a new edit otherwise republishes the old board and
         // rolls back every peer. The API checks freshness after async IO and
         // before its atomic rename; a later doc update schedules a new flush.
-        await api.projectAnnotations(file, svg, () => map.get('svg') === svg);
+        // Recorded BEFORE the write: the watcher event may be delivered before
+        // this await resumes.
+        deps.onAnnotationsProjected?.(slug, board);
+        noteAnnotationsOnDisk(doc, board);
+        await api.projectAnnotations(file, board, () => replicaBoardText(doc) === board);
       }
     }
   }

package/apps/studio/collab/registry.ts

@@ -9,10 +9,13 @@
 import type { Awareness } from 'y-protocols/awareness';
 import type * as Y from 'yjs';
 
-import { ANNOTATION_WRITE_ID, validAnnotationWriteId } from '../annotations-sync.ts';
-import { applyCommentsToDoc } from '../sync/codec.ts';
+import { canonicalAnnotations } from '../annotations/board-text.ts';
+import { type ApplyResult, applyOps, type Op } from '../annotations/ops.ts';
+import { readReplica, validActionId, writeReplica } from '../annotations/replica.ts';
+import { parseBoard, serializeBoard } from '../annotations/schema.ts';
+import { applyCommentsToDoc, stampAnnotationsEdit } from '../sync/codec.ts';
+import { MAX_ANNOTATIONS_BYTES } from '../sync/limits.ts';
 import { bridgeAwareness } from './awareness-bridge.ts';
-import { Y_TYPES } from './persistence.ts';
 import type { Room, RoomCallbacks } from './room.ts';
 import { createRoom } from './room.ts';
 
@@ -49,12 +52,23 @@ export interface Registry {
    */
   syncRoomFromComments(slug: string, comments: readonly unknown[]): void;
   /**
-   * Phase 8 Task 5 bridge — same shape as syncRoomFromComments but for the
-   * `annotations` Y.Map. The PUT /_api/annotations endpoint passes the
-   * post-write SVG; the room replaces `Y.Map.svg` so collab peers see the
-   * updated stroke set without waiting for a cold-open re-seed.
+   * Same shape as syncRoomFromComments but for the annotations replica
+   * (DDR-242). Every annotations write passes the post-write board; the room's
+   * replica is diffed to it, so collab peers receive only the changed elements.
    */
-  syncRoomFromAnnotations(slug: string, svg: string, writeId?: string): void;
+  syncRoomFromAnnotations(slug: string, text: string, actionId?: string): void;
+  /**
+   * The canvas op path while a room is live (code review H1): apply the batch
+   * to the room's replica — the freshest state, ahead of a debounced flush —
+   * instead of to disk, where a peer's not-yet-flushed edit would be reverted.
+   * `null` when no room (or a never-populated one) is live; `'too-large'` when
+   * the result would exceed the board cap (nothing written).
+   */
+  applyOpsToRoom(
+    slug: string,
+    ops: readonly Op[],
+    actionId?: string
+  ): ApplyResult | 'too-large' | null;
   /**
    * Phase 30 — project agent editing-presence onto a slug's room awareness so
    * it crosses the hub (the loopback `ai-activity` bus event does not). `null`
@@ -110,27 +124,24 @@ export interface Registry {
 }
 
 /**
- * Replace a doc's annotation SVG — the one write shape shared by the live
- * disk→room bridge and the cache-restore reconcile (`collab/index.ts`).
- * Identical disk notifications stay no-ops (no update → no persist loop); a UI
- * operation may deliberately restore identical content under a new write id.
- * Returns whether the doc changed.
+ * Make a doc's annotations replica hold `text` (canonical board JSON, or a
+ * legacy SVG that is converted) — the one write shape shared by the live
+ * disk→room bridge and the cache-restore reconcile (`collab/index.ts`). Only the
+ * elements / fields that differ become Yjs updates (DDR-242 §5); identical
+ * content is a no-op (no update → no persist loop). `actionId` lets the author's
+ * canvas recognise its own echo. Returns whether the doc changed.
  */
 export function applyAnnotationsToDoc(
   doc: Y.Doc,
-  svg: string,
+  text: string,
   origin: unknown,
-  writeId?: string
+  actionId?: string
 ): boolean {
-  const map = doc.getMap<string>(Y_TYPES.annotations);
-  const id = validAnnotationWriteId(writeId) ? writeId : undefined;
-  if (map.get('svg') === svg && (!id || map.get(ANNOTATION_WRITE_ID) === id)) return false;
-  doc.transact(() => {
-    map.set('svg', svg);
-    if (id) map.set(ANNOTATION_WRITE_ID, id);
-    else map.delete(ANNOTATION_WRITE_ID);
-  }, origin);
-  return true;
+  const board = canonicalAnnotations(text);
+  if (board === null) return false;
+  return writeReplica(doc, parseBoard(board).elements, origin, {
+    ...(validActionId(actionId) ? { actionId } : {}),
+  });
 }
 
 export function createRegistry(callbacks: RoomCallbacks): Registry {
@@ -218,10 +229,35 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     applyCommentsToDoc(room.doc, comments as unknown[], 'inspector-write');
   }
 
-  function syncRoomFromAnnotations(slug: string, svg: string, writeId?: string): void {
+  function syncRoomFromAnnotations(slug: string, text: string, actionId?: string): void {
     const room = rooms.get(slug);
     if (!room) return;
-    applyAnnotationsToDoc(room.doc, svg, 'inspector-write', writeId);
+    applyAnnotationsToDoc(room.doc, text, 'inspector-write', actionId);
+  }
+
+  function applyOpsToRoom(
+    slug: string,
+    ops: readonly Op[],
+    actionId?: string
+  ): ApplyResult | 'too-large' | null {
+    const room = rooms.get(slug);
+    // A replica that was never populated is not the board's truth — the
+    // caller takes the disk path instead (DDR-223: no value ≠ empty).
+    const cur = room ? readReplica(room.doc) : null;
+    if (!room || cur === null) return null;
+    const r = applyOps(new Map(cur.elements.map((e) => [e.id, e])), ops);
+    if (!r.touched.size) return r;
+    const next = [...r.state.values()];
+    if (serializeBoard(next).length > MAX_ANNOTATIONS_BYTES) return 'too-large';
+    // One transaction with the lane's newest-wins stamp, so peers get ONE
+    // update and the room's persistence projects it to disk.
+    room.doc.transact(() => {
+      writeReplica(room.doc, next, 'inspector-write', {
+        ...(validActionId(actionId) ? { actionId } : {}),
+      });
+      stampAnnotationsEdit(room.doc, 'inspector-write');
+    }, 'inspector-write');
+    return r;
   }
 
   function setAgentEditing(slug: string, state: { name: string; since: number } | null): void {
@@ -275,6 +311,7 @@ export function createRegistry(callbacks: RoomCallbacks): Registry {
     getDoc,
     syncRoomFromComments,
     syncRoomFromAnnotations,
+    applyOpsToRoom,
     setAgentEditing,
     attachHubAwareness,
     pin,

package/apps/studio/commands/annotation-ops-command.ts

@@ -0,0 +1,72 @@
+/**
+ * @file       commands/annotation-ops-command.ts — undo entry for an annotation op batch
+ * @scope      apps/studio/commands/annotation-ops-command.ts
+ * @purpose    DDR-242 AD4 (Task 26): one user gesture is one op batch and one
+ *             undo record; undo is the batch's INVERSE (from `applyOps`),
+ *             which is peer-safe at field granularity — it reverts only the
+ *             fields this action set and only while they still hold its value.
+ *             Nothing here replays a snapshot of the whole board.
+ *
+ *             Rebuilt per iframe mount from a serializable record (DDR-050), so
+ *             the stack survives canvas switches; the side effect (apply
+ *             locally + send) is the layer's `annotationOpsFn` sink.
+ */
+
+import type { Op } from '../annotations/ops.ts';
+import type { CommandRecord, EditCommand } from '../undo-stack.ts';
+import { registerCommand } from '../undo-stack.ts';
+
+export const ANNOTATION_OPS_KIND = 'annotation-ops';
+
+export interface AnnotationOpsPayload {
+  ops: readonly Op[];
+  inverse: readonly Op[];
+  /**
+   * The canvas the batch belongs to. The stack's records live in origin-wide
+   * sessionStorage, so the layer replays only its own canvas's (security
+   * review A5 — another canvas must not steer this one's undo).
+   */
+  file?: string;
+}
+
+/** Applies a batch locally and sends it; returns the batch's own inverse. */
+export type AnnotationOpsFn = (ops: readonly Op[], file?: string) => readonly Op[] | void;
+
+export function buildAnnotationOpsRecord(opts: {
+  ops: readonly Op[];
+  inverse: readonly Op[];
+  label: string;
+  file?: string;
+}): CommandRecord<AnnotationOpsPayload> {
+  return {
+    kind: ANNOTATION_OPS_KIND,
+    label: opts.label,
+    payload: {
+      ops: structuredClone(opts.ops),
+      inverse: structuredClone(opts.inverse),
+      ...(opts.file ? { file: opts.file } : {}),
+    },
+  };
+}
+
+export function createAnnotationOpsCommand(
+  record: CommandRecord<AnnotationOpsPayload>,
+  fn: AnnotationOpsFn
+): EditCommand {
+  return {
+    kind: ANNOTATION_OPS_KIND,
+    label: record.label,
+    async do() {
+      fn(record.payload.ops, record.payload.file);
+    },
+    async undo() {
+      fn(record.payload.inverse, record.payload.file);
+    },
+  };
+}
+
+registerCommand<AnnotationOpsPayload>(ANNOTATION_OPS_KIND, (record, sinks) => {
+  const fn = sinks.annotationOpsFn as AnnotationOpsFn | undefined;
+  if (!fn) return null;
+  return createAnnotationOpsCommand(record, fn);
+});

package/apps/studio/cursors-overlay.tsx

@@ -20,8 +20,14 @@
 import type { JSX } from 'react';
 import { memo, useEffect, useState } from 'react';
 
+import { REPLICA_TYPE } from './annotations/replica.ts';
 import { useLiveViewport } from './canvas-lib.tsx';
-import { type ForeignAwareness, useCollab, useForeignAwareness } from './use-collab.tsx';
+import {
+  type AnnotationGesture,
+  type ForeignAwareness,
+  useCollab,
+  useForeignAwareness,
+} from './use-collab.tsx';
 
 const CURSOR_CSS = `
 .dc-cursor-overlay {
@@ -77,6 +83,23 @@ const CURSOR_CSS = `
   box-sizing: border-box;
   will-change: transform, width, height;
 }
+.dc-peer-gesture {
+  position: absolute;
+  top: 0;
+  left: 0;
+  pointer-events: none;
+  border: 1.5px dashed;
+  border-radius: 3px;
+  box-sizing: border-box;
+}
+.dc-peer-gesture-ink {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+  pointer-events: none;
+}
 .dc-peer-selection__label {
   position: absolute;
   top: -18px;
@@ -269,6 +292,132 @@ export const PeerAnnotationSelection = memo(
     sameIds(a.peer.annotationSelection, b.peer.annotationSelection)
 );
 
+/**
+ * Task 22 (DDR-242 AD5) — a peer's annotation gesture while it is in flight:
+ * the elements they drag, the box they resize or draw, the ink of a pen stroke
+ * — so peers watch it move instead of seeing it jump at the commit. Awareness
+ * only (sanitized in use-collab); nothing here reads or writes the board. A
+ * gesture that stops updating (a peer who vanished mid-drag) fades after
+ * GESTURE_STALE_MS even before awareness garbage-collects the peer.
+ */
+const GESTURE_STALE_MS = 3000;
+const MAX_GHOSTS = 64;
+
+function sameGesture(
+  a: AnnotationGesture | null | undefined,
+  b: AnnotationGesture | null | undefined
+): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return (
+    a.kind === b.kind &&
+    a.dx === b.dx &&
+    a.dy === b.dy &&
+    sameIds(a.ids, b.ids) &&
+    a.box?.x === b.box?.x &&
+    a.box?.y === b.box?.y &&
+    a.box?.w === b.box?.w &&
+    a.box?.h === b.box?.h &&
+    (a.points?.length ?? 0) === (b.points?.length ?? 0) &&
+    a.points?.[a.points.length - 1] === b.points?.[b.points.length - 1]
+  );
+}
+
+interface PeerAnnotationGestureProps {
+  peer: ForeignAwareness;
+  viewport: ViewportSnapshot;
+}
+
+export const PeerAnnotationGesture = memo(
+  function PeerAnnotationGesture({
+    peer,
+    viewport,
+  }: PeerAnnotationGestureProps): JSX.Element | null {
+    const g = peer.annotationGesture;
+    const [stale, setStale] = useState(false);
+    useEffect(() => {
+      setStale(false);
+      if (!g) return;
+      const t = setTimeout(() => setStale(true), GESTURE_STALE_MS);
+      return () => clearTimeout(t);
+    }, [g]);
+    if (!g || stale || typeof document === 'undefined') return null;
+    const z = viewport.zoom || 1;
+    const toScreen = (x: number, y: number) => [x * z + viewport.x, y * z + viewport.y] as const;
+    const boxes: Array<{ key: string; x: number; y: number; w: number; h: number }> = [];
+    if (g.kind === 'move' && g.dx !== undefined && g.dy !== undefined) {
+      for (const id of g.ids.slice(0, MAX_GHOSTS)) {
+        try {
+          const el = document.querySelector(`.dc-annot-scene [data-id="${CSS.escape(id)}"]`);
+          if (!el) continue;
+          const r = el.getBoundingClientRect();
+          if (r.width <= 0 && r.height <= 0) continue;
+          boxes.push({
+            key: id,
+            x: r.left + g.dx * z,
+            y: r.top + g.dy * z,
+            w: r.width,
+            h: r.height,
+          });
+        } catch {
+          /* invalid id token — skip */
+        }
+      }
+    } else if (g.box) {
+      const [x, y] = toScreen(g.box.x, g.box.y);
+      boxes.push({ key: 'box', x, y, w: g.box.w * z, h: g.box.h * z });
+    }
+    let ink: string | null = null;
+    if (g.kind === 'draw' && g.points && g.points.length >= 4) {
+      const pts: string[] = [];
+      for (let i = 0; i + 1 < g.points.length; i += 2) {
+        const [sx, sy] = toScreen(g.points[i] as number, g.points[i + 1] as number);
+        pts.push(`${sx},${sy}`);
+      }
+      ink = pts.join(' ');
+    }
+    if (!boxes.length && !ink) return null;
+    return (
+      <>
+        {boxes.map((b, i) => (
+          <div
+            key={`g-${b.key}`}
+            className="dc-peer-gesture"
+            data-peer-gesture={g.kind}
+            style={{
+              transform: `translate(${b.x}px, ${b.y}px)`,
+              width: b.w,
+              height: b.h,
+              borderColor: peer.color,
+            }}
+          >
+            {i === 0 && (
+              <div className="dc-peer-selection__label" style={{ background: peer.color }}>
+                {peer.name}
+              </div>
+            )}
+          </div>
+        ))}
+        {ink ? (
+          <svg className="dc-peer-gesture-ink" data-peer-gesture="draw" aria-hidden="true">
+            <polyline
+              points={ink}
+              fill="none"
+              stroke={peer.color}
+              strokeWidth={2}
+              strokeOpacity={0.7}
+            />
+          </svg>
+        ) : null}
+      </>
+    );
+  },
+  (a, b) =>
+    sameViewport(a.viewport, b.viewport) &&
+    sameLabel(a.peer, b.peer) &&
+    sameGesture(a.peer.annotationGesture, b.peer.annotationGesture)
+);
+
 /**
  * Foreign-selection halo for canvas-shell elements (cdId-based selSet).
  * The peer publishes selection.cssPath; we re-resolve in the local DOM
@@ -355,12 +504,14 @@ export function CursorsOverlay(): JSX.Element {
   const [tick, bumpTick] = useState(0);
   useEffect(() => {
     if (!collab) return;
-    const map = collab.doc.getMap('annotations');
+    // The v2 replica (DDR-242): element records are nested maps, so a field
+    // edit only reaches a deep observer.
+    const map = collab.doc.getMap(REPLICA_TYPE);
     const onChange = () => bumpTick((n) => n + 1);
-    map.observe(onChange);
+    map.observeDeep(onChange);
     return () => {
       try {
-        map.unobserve(onChange);
+        map.unobserveDeep(onChange);
       } catch {
         /* doc destroyed */
       }
@@ -390,6 +541,9 @@ export function CursorsOverlay(): JSX.Element {
           tick={tick}
         />
       ))}
+      {peers.map((peer) => (
+        <PeerAnnotationGesture key={`gest-${peer.clientID}`} peer={peer} viewport={vp} />
+      ))}
       {peers.map((peer) => (
         <Cursor key={peer.clientID} peer={peer} viewport={vp} />
       ))}