@1agh/maude 1.4.5 → 1.5.0

package/apps/studio/client/tree-expansion.js

@@ -0,0 +1,217 @@
+// tree-expansion.js — which folders + sections of the Files panel are open
+// (issue #124).
+//
+// Before this, every folder row owned its own `useState(defaultOpen=true)`:
+// the tree started fully expanded and forgot every collapse the moment the row
+// unmounted — a dock-tab switch, a section toggle, a reload. The state now
+// lives ONCE at App level (so it outlives the rows) and is persisted per
+// project through `/_api/tree-state` (so it outlives the app).
+//
+// Rule: anything not recorded is CLOSED — folders and sections alike. Nothing
+// expands itself on boot; only the user does (a click, or explicitly opening a
+// canvas, which reveals its row). Search force-opens without recording.
+//
+// The helpers below are pure (state in → state out) so they are unit-testable
+// without a DOM; `useTreeExpansion` is the thin React wrapper App uses.
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export const EMPTY_TREE_STATE = Object.freeze({ dirs: [], sections: {} });
+
+// Pre-#124 section overrides lived only in origin-scoped localStorage. Read
+// once as a seed so an existing user's choices survive the move to disk.
+export const LEGACY_SECTIONS_STORE = 'mdcc-sections-expanded';
+
+const PERSIST_DEBOUNCE_MS = 250;
+const HYDRATE_TIMEOUT_MS = 3000;
+
+export function isDirOpen(state, dirPath) {
+  return !!dirPath && state.dirs.includes(dirPath);
+}
+
+export function isSectionOpen(state, label) {
+  return state.sections[label] === true;
+}
+
+export function setDirOpen(state, dirPath, open) {
+  if (!dirPath) return state;
+  const has = state.dirs.includes(dirPath);
+  if (has === !!open) return state;
+  const dirs = open ? [...state.dirs, dirPath].sort() : state.dirs.filter((d) => d !== dirPath);
+  return { ...state, dirs };
+}
+
+export function toggleDir(state, dirPath) {
+  return setDirOpen(state, dirPath, !isDirOpen(state, dirPath));
+}
+
+export function setSectionOpen(state, label, open) {
+  if (!label || state.sections[label] === !!open) return state;
+  return { ...state, sections: { ...state.sections, [label]: !!open } };
+}
+
+export function toggleSection(state, label) {
+  return setSectionOpen(state, label, !isSectionOpen(state, label));
+}
+
+/** The group (section) a repo-relative path lives in — longest `fullPath` wins. */
+export function groupForPath(groups, path) {
+  let best = null;
+  for (const g of groups || []) {
+    const root = g.fullPath;
+    if (!root || !(path === root || path.startsWith(root + '/'))) continue;
+    if (!best || root.length > best.fullPath.length) best = g;
+  }
+  return best;
+}
+
+/**
+ * Open everything needed to SEE `path`: its section, and every folder between
+ * the section root and the path. `includeSelf` also opens `path` itself (for a
+ * folder target — a new folder's parent, a move destination).
+ */
+export function revealPath(state, groups, path, { includeSelf = false } = {}) {
+  if (!path) return state;
+  const g = groupForPath(groups, path);
+  if (!g) return state;
+  let next = setSectionOpen(state, g.label, true);
+  const rest = path.slice(g.fullPath.length + 1);
+  if (!rest) return next;
+  const parts = rest.split('/');
+  const upto = includeSelf ? parts.length : parts.length - 1;
+  let cur = g.fullPath;
+  for (let i = 0; i < upto; i++) {
+    cur = `${cur}/${parts[i]}`;
+    next = setDirOpen(next, cur, true);
+  }
+  return next;
+}
+
+/** A folder moved/renamed `from` → `to`: carry its (and its subfolders') keys. */
+export function remapDirPrefix(state, from, to) {
+  if (!from || !to || from === to) return state;
+  let changed = false;
+  const dirs = state.dirs.map((d) => {
+    if (d === from) {
+      changed = true;
+      return to;
+    }
+    if (d.startsWith(from + '/')) {
+      changed = true;
+      return to + d.slice(from.length);
+    }
+    return d;
+  });
+  return changed ? { ...state, dirs: [...new Set(dirs)].sort() } : state;
+}
+
+/** Every folder path present in the loaded groups' trees. */
+export function collectDirPaths(groups) {
+  const out = new Set();
+  const walk = (node, base) => {
+    for (const k of Object.keys(node || {})) {
+      if (k === '_files') continue;
+      const p = `${base}/${k}`;
+      out.add(p);
+      walk(node[k], p);
+    }
+  };
+  for (const g of groups || []) if (g.fullPath) walk(g.tree, g.fullPath);
+  return out;
+}
+
+/** Drop keys for folders that no longer exist (deleted, moved outside Maude). */
+export function pruneDirs(state, known) {
+  const dirs = state.dirs.filter((d) => known.has(d));
+  return dirs.length === state.dirs.length ? state : { ...state, dirs };
+}
+
+export function normalizeClientState(raw) {
+  const o = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  const dirs = Array.isArray(o.dirs) ? [...new Set(o.dirs.filter((d) => typeof d === 'string' && d))].sort() : [];
+  const sections = {};
+  if (o.sections && typeof o.sections === 'object' && !Array.isArray(o.sections)) {
+    for (const [k, v] of Object.entries(o.sections)) if (typeof v === 'boolean') sections[k] = v;
+  }
+  return { dirs, sections };
+}
+
+function readLegacySections() {
+  try {
+    const v = JSON.parse(localStorage.getItem(LEGACY_SECTIONS_STORE) || 'null');
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * App-level owner of the tree state. `ready` flips once the stored state has
+ * been read (or the read failed) — App holds the tree back until then so the
+ * first paint is the remembered tree, not an all-closed flash. Writes are
+ * debounced and only start after hydration, so the initial empty state can
+ * never overwrite what is on disk.
+ */
+export function useTreeExpansion({ fetchImpl } = {}) {
+  const [state, setState] = useState(EMPTY_TREE_STATE);
+  const [ready, setReady] = useState(false);
+  const doFetch = fetchImpl || ((...a) => fetch(...a));
+  const fetchRef = useRef(doFetch);
+  fetchRef.current = doFetch;
+
+  useEffect(() => {
+    let cancelled = false;
+    // A stalled read (cell cold start, a hung proxy) must not keep the Files
+    // panel empty: after HYDRATE_TIMEOUT_MS the tree renders all-closed.
+    const ctrl = typeof AbortController === 'function' ? new AbortController() : null;
+    const timer = setTimeout(() => ctrl?.abort(), HYDRATE_TIMEOUT_MS);
+    fetchRef
+      .current('/_api/tree-state', ctrl ? { signal: ctrl.signal } : undefined)
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`HTTP ${r.status}`))))
+      .then((raw) => {
+        if (cancelled) return;
+        let next = normalizeClientState(raw);
+        const stored = raw && typeof raw === 'object' && raw.sections && Object.keys(raw.sections).length;
+        if (!stored) {
+          const legacy = readLegacySections();
+          if (legacy) next = normalizeClientState({ ...next, sections: legacy });
+        }
+        setState(next);
+      })
+      .catch(() => {})
+      .finally(() => {
+        clearTimeout(timer);
+        if (!cancelled) setReady(true);
+      });
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+    };
+  }, []);
+
+  const skipFirst = useRef(true);
+  useEffect(() => {
+    if (!ready) return;
+    // The hydrating setState lands in the same commit as `ready`; that value
+    // came FROM disk, so writing it back is pointless.
+    if (skipFirst.current) {
+      skipFirst.current = false;
+      return;
+    }
+    const t = setTimeout(() => {
+      try {
+        fetchRef
+          .current('/_api/tree-state', {
+            method: 'POST',
+            headers: { 'content-type': 'text/plain' },
+            body: JSON.stringify(state),
+          })
+          .catch(() => {});
+      } catch {}
+    }, PERSIST_DEBOUNCE_MS);
+    return () => clearTimeout(t);
+  }, [ready, state]);
+
+  const update = useCallback((fn) => setState((s) => fn(s)), []);
+  return { state, ready, update };
+}

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,11 +62,37 @@ 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:
+    // nothing is "synced" — recording then would label local comments with
+    // the last hub's identity and a relink would drop them (security review
+    // F1a). Linked but the runtime is not up yet: not confirmed.
+    commentsConfirmed: (slug) => {
+      if (!ctx.cfg?.linkedHub || !registryRef?.isPinned(slug)) return false;
+      return ctx.syncControl?.current?.()?.commentsConfirmedOnHub?.(slug) === true;
+    },
     // A room restored from its own `.ydoc.bin` must not outrank a sidecar the
     // hub (or an editor) wrote after that cache — see `reconcileAfterCache`.
     // Only for rooms no hub provider owns: a pinned doc is the hub's replica
@@ -79,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');
@@ -115,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);
@@ -140,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,16 +1,19 @@
 // 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
 // file, so reaching for it here would close a cycle (see sync/limits.ts).
 import { commentKey } from '../sync/comment-identity.ts';
+import { type CommentLedger, commentLedgerFor } from '../sync/comment-ledger.ts';
 import { MAX_ANNOTATIONS_BYTES, MAX_COMMENTS_BYTES, withinByteCap } from '../sync/limits.ts';
 import { ensureStateDir, type RoomCallbacks } from './room.ts';
 
@@ -22,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;
@@ -60,6 +65,29 @@ 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
+   * root; tests inject a fresh one per simulated launch.
+   */
+  commentLedger?: CommentLedger;
+  /**
+   * May the ledger record `slug`'s projected comments as synced? Only when the
+   * hub is known to hold them (see `commentsConfirmedOnHub`, sync/index.ts). A
+   * projection of a comment added offline would otherwise read as "synced" and
+   * the next cold start would drop it. Absent → always (tests, local projects).
+   */
+  commentsConfirmed?: (slug: string) => boolean;
 }
 
 /**
@@ -93,6 +121,7 @@ function withinCap(slug: string, lane: string, value: string, max: number): bool
 export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
   const { ctx, api, fileForSlug } = deps;
   const stateDir = ensureStateDir(ctx.paths.designRoot);
+  const ledger = deps.commentLedger ?? commentLedgerFor(ctx.paths.designRoot);
 
   // Per-slug: every comment identity this doc has EVER carried (issue #111).
   //
@@ -180,6 +209,27 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
     return ids;
   }
 
+  // Issue #133 (plan Task 8) — a comment that stays on this disk and out of the
+  // shared document is invisible to every other peer, and nothing said so: the
+  // report behind #133 had to be reconstructed from code. Say it once per
+  // change of the count, in the server log (which the in-app bug report
+  // attaches), and say when it clears.
+  const localOnlyBySlug = new Map<string, number>();
+  function reportLocalOnly(slug: string, n: number): void {
+    const prev = localOnlyBySlug.get(slug) ?? 0;
+    if (n === prev) return;
+    localOnlyBySlug.set(slug, n);
+    if (n > 0) {
+      console.warn(
+        `[collab/${slug}] comments: ${n} on this disk ${n === 1 ? 'is' : 'are'} not in the shared document yet — kept, not overwritten; other peers do not see ${n === 1 ? 'it' : 'them'} until ${n === 1 ? 'it arrives' : 'they arrive'}.`
+      );
+    } else {
+      console.log(
+        `[collab/${slug}] comments: every comment on this disk is in the shared document again.`
+      );
+    }
+  }
+
   function ydocBinPath(slug: string): string {
     return path.join(stateDir, `${slug}.ydoc.bin`);
   }
@@ -250,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> {
@@ -284,23 +336,40 @@ export function createPersistence(deps: PersistenceDeps): RoomCallbacks {
       // brings that id into the doc is itself a doc update, which re-arms the
       // flush, and the next pass writes the merged state. A delete still
       // materializes — its id IS in `everSeen`, so the write proceeds.
+      //
+      // Issue #133 — `everSeen` starts empty on every launch, so an id deleted
+      // by a peer while this machine was closed also reads as "never carried"
+      // and froze the file for good. The ledger knows it was synced from here
+      // before: an id in the ledger and absent from the doc is a delete.
       const onDisk = await api.loadCommentsForFile(file);
-      const behind = onDisk.some((c) => !everSeen.has(commentKey(c)));
+      const synced = ledger.get(slug);
+      const localOnly = onDisk.filter((c) => {
+        const k = commentKey(c);
+        return !everSeen.has(k) && !synced.has(k);
+      }).length;
+      const behind = localOnly > 0;
+      reportLocalOnly(slug, localOnly);
       if (!behind && withinCap(slug, 'comments', JSON.stringify(list), MAX_COMMENTS_BYTES)) {
         await api.saveCommentsForFile(file, list);
+        if (deps.commentsConfirmed?.(slug) ?? true) ledger.record(slug, list.map(commentKey));
       }
     }
 
-    // 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,