@1agh/maude 0.22.0 → 0.23.0

package/plugins/design/dev-server/test/comment-mount.test.ts

@@ -0,0 +1,87 @@
+// comment-mount — shell-owned comment layer. Covers provider dedup (the
+// Maybe* wrappers consume an outer instance instead of double-mounting) and
+// the bundle scope-guard (react/react-dom externalized to the importmap so the
+// comment layer shares the canvas's single React singleton).
+
+import { describe, expect, test } from 'bun:test';
+import { join } from 'node:path';
+
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import {
+  MaybeSelectionSetProvider,
+  SelectionSetProvider,
+  useSelectionSetOptional,
+} from '../use-selection-set.tsx';
+import { MaybeToolProvider, ToolProvider, useToolMode } from '../use-tool-mode.tsx';
+
+describe('comment-mount / MaybeToolProvider dedup', () => {
+  function ToolReader() {
+    const { tool } = useToolMode();
+    return createElement('span', { 'data-tool': tool });
+  }
+
+  test('consumes an OUTER ToolProvider instead of double-mounting', () => {
+    // Outer provider seeds tool='comment'. If MaybeToolProvider mounted a
+    // fresh provider, the reader would see the default 'move' instead.
+    const html = renderToStaticMarkup(
+      createElement(
+        ToolProvider,
+        { initial: 'comment' },
+        createElement(MaybeToolProvider, null, createElement(ToolReader))
+      )
+    );
+    expect(html).toContain('data-tool="comment"');
+  });
+
+  test('mounts its OWN ToolProvider when none exists above', () => {
+    const html = renderToStaticMarkup(
+      createElement(MaybeToolProvider, null, createElement(ToolReader))
+    );
+    expect(html).toContain('data-tool="move"');
+  });
+});
+
+describe('comment-mount / MaybeSelectionSetProvider dedup', () => {
+  function SelReader() {
+    const ctx = useSelectionSetOptional();
+    // Tag identity so we can assert a single context instance is shared.
+    return createElement('span', { 'data-has-ctx': ctx ? 'yes' : 'no' });
+  }
+
+  test('provides a SelectionSet when none exists above', () => {
+    const html = renderToStaticMarkup(
+      createElement(MaybeSelectionSetProvider, null, createElement(SelReader))
+    );
+    expect(html).toContain('data-has-ctx="yes"');
+  });
+
+  test('does not throw when nested inside an existing SelectionSetProvider', () => {
+    expect(() =>
+      renderToStaticMarkup(
+        createElement(
+          SelectionSetProvider,
+          { postTarget: null },
+          createElement(MaybeSelectionSetProvider, null, createElement(SelReader))
+        )
+      )
+    ).not.toThrow();
+  });
+});
+
+describe('comment-mount / bundle scope-guard', () => {
+  test('dist/comment-mount.js externalizes react + exports mountCanvas', async () => {
+    const here = join(import.meta.dir, '..');
+    const bundle = Bun.file(join(here, 'dist', 'comment-mount.js'));
+    expect(await bundle.exists()).toBe(true);
+    const src = await bundle.text();
+    // mountCanvas is the public entry the shell calls.
+    expect(src.includes('mountCanvas')).toBe(true);
+    // React must be a BARE import (resolved by _shell.html's importmap), not
+    // inlined — a second React instance would break hooks ("invalid hook
+    // call") across the canvas module and the comment layer.
+    expect(/import[^;]*["']react-dom\/client["']/.test(src)).toBe(true);
+    expect(/import[^;]*["']react["']/.test(src)).toBe(true);
+  });
+});

package/plugins/design/dev-server/test/hmr-classify.test.ts

@@ -0,0 +1,70 @@
+// Unit test for hmr-broadcast.ts classifyChange().
+//
+// The load-bearing case: a canvas/specimen sibling stylesheet (e.g. motion.css
+// next to motion.tsx) is INLINED into the built module — there is no <link> for
+// the iframe css-swap to target, so it must route to a module reload keyed on
+// the sibling .tsx. Link-mounted CSS (tokens / _components / _layout — no
+// sibling .tsx) keeps the fast css swap. Regression guard for the silent-drop
+// bug (see .ai/logs/rca/hmr-inlined-css-dropped.md).
+
+import { describe, expect, test } from 'bun:test';
+
+import { classifyChange } from '../hmr-broadcast.ts';
+
+describe('classifyChange', () => {
+  const noSibling = () => false;
+  const hasSibling = () => true;
+
+  test('sibling-tsx CSS → module reload keyed on the .tsx', () => {
+    const msg = classifyChange(
+      'system/x/preview/motion.css',
+      (cssRel) => cssRel === 'system/x/preview/motion.css'
+    );
+    expect(msg?.mode).toBe('module');
+    expect(msg?.file).toBe('system/x/preview/motion.tsx');
+    expect(msg?.scope).toBe('canvas');
+  });
+
+  test('link-mounted partial CSS (no sibling .tsx) → css swap', () => {
+    expect(classifyChange('system/x/preview/_components.css', noSibling)?.mode).toBe('css');
+    expect(classifyChange('system/x/preview/_layout.css', noSibling)?.mode).toBe('css');
+    expect(classifyChange('system/x/colors_and_type.css', noSibling)?.mode).toBe('css');
+  });
+
+  test('css mode echoes the changed file path', () => {
+    const msg = classifyChange('system/x/colors_and_type.css', noSibling);
+    expect(msg?.mode).toBe('css');
+    expect(msg?.file).toBe('system/x/colors_and_type.css');
+  });
+
+  test('_lib/** → hard reload (no file)', () => {
+    const msg = classifyChange('_lib/canvas-lib.tsx', hasSibling);
+    expect(msg?.mode).toBe('hard');
+    expect(msg?.scope).toBe('lib');
+    expect(msg?.file).toBeUndefined();
+  });
+
+  test('.tsx / .jsx / .ts / .js → module reload', () => {
+    for (const f of ['ui/Foo.tsx', 'ui/Foo.jsx', 'ui/Foo.ts', 'ui/Foo.js']) {
+      expect(classifyChange(f, noSibling)?.mode).toBe('module');
+      expect(classifyChange(f, noSibling)?.file).toBe(f);
+    }
+  });
+
+  test('.meta.json → meta (not treated as a .json no-op)', () => {
+    const msg = classifyChange('ui/Foo.meta.json', noSibling);
+    expect(msg?.mode).toBe('meta');
+    expect(msg?.file).toBe('ui/Foo.meta.json');
+  });
+
+  test('unrelated extensions → null', () => {
+    expect(classifyChange('ui/notes.md', noSibling)).toBeNull();
+    expect(classifyChange('assets/logo.svg', noSibling)).toBeNull();
+  });
+
+  test('backslash paths are normalised before classification', () => {
+    const msg = classifyChange('system\\x\\preview\\motion.css', () => true);
+    expect(msg?.mode).toBe('module');
+    expect(msg?.file).toBe('system/x/preview/motion.tsx');
+  });
+});

package/plugins/design/dev-server/test/sync-agent.test.ts

@@ -0,0 +1,278 @@
+// Sync-agent integration tests — Phase 9 Task 4.
+//
+// Uses an in-memory pair of Y.Docs cross-linked via Y.applyUpdate as a stand-in
+// for HocuspocusProvider's transport. The agent under test owns docB; docA
+// represents "another peer talking to the hub". Updates flow:
+//
+//   docA → encode → applyUpdate(docB) → agent observes → write to disk
+//   disk → onRead → applyFromFs → applyHtmlToDoc(docB) → encode → docA
+//
+// This lets us validate the whole bidi loop, echo prevention, and the
+// 100-event stress scenario from the plan without booting a real hub.
+
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+
+import { type CanvasSyncAgent, createCanvasSyncAgent } from '../sync/agent.ts';
+import { Y_SYNC_TYPES, applyHtmlToDoc, htmlFromDoc } from '../sync/codec.ts';
+import { createEchoGuard, hashBytes } from '../sync/echo-guard.ts';
+import { createFsReader } from '../sync/fs-mirror.ts';
+
+let dir: string;
+let agent: CanvasSyncAgent;
+let docA: Y.Doc;
+let docB: Y.Doc;
+
+function paths() {
+  return {
+    html: join(dir, 'screen.html'),
+    comments: join(dir, '_comments', 'screen.json'),
+    annotations: join(dir, 'screen.annotations.svg'),
+  };
+}
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'sync-agent-'));
+  docA = new Y.Doc();
+  docB = new Y.Doc();
+  // Mirror docA→docB and docB→docA, ignoring transient origin objects from
+  // the transport itself (we use a symbol).
+  const TRANSPORT = Symbol('transport');
+  docA.on('update', (update: Uint8Array, origin: unknown) => {
+    if (origin === TRANSPORT) return;
+    Y.applyUpdate(docB, update, TRANSPORT);
+  });
+  docB.on('update', (update: Uint8Array, origin: unknown) => {
+    if (origin === TRANSPORT) return;
+    Y.applyUpdate(docA, update, TRANSPORT);
+  });
+});
+
+afterEach(() => {
+  agent?.stop();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function makeAgent(extra: { adopt?: boolean; flushMs?: number } = {}): CanvasSyncAgent {
+  const a = createCanvasSyncAgent({
+    slug: 'screen',
+    doc: docB,
+    paths: paths(),
+    echoGuard: createEchoGuard(),
+    flushMs: 0, // synchronous flush; the agent uses queueMicrotask
+    ...extra,
+  });
+  a.start();
+  return a;
+}
+
+describe('CanvasSyncAgent — hub → disk (Flow B)', () => {
+  test('writes HTML to disk when other peer mutates the doc', async () => {
+    agent = makeAgent();
+    // Other peer types into docA — propagates to docB via the in-memory
+    // transport, which our agent observes.
+    applyHtmlToDoc(docA, '<button>v1</button>');
+    await agent.flush();
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>v1</button>');
+  });
+
+  test('debounces multiple rapid peer edits into one disk write', async () => {
+    agent = makeAgent({ flushMs: 30 });
+    for (let i = 0; i < 10; i++) {
+      applyHtmlToDoc(docA, `<button>v${i}</button>`);
+    }
+    await new Promise((res) => setTimeout(res, 80));
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<button>v9</button>');
+  });
+
+  test('writes comments JSON when Y.Array changes', async () => {
+    agent = makeAgent();
+    docA.transact(() => {
+      docA.getArray('comments').push([{ id: 'c1', body: 'hello' }]);
+    });
+    await agent.flush();
+
+    const written = JSON.parse(readFileSync(paths().comments, 'utf8'));
+    expect(written).toEqual([{ id: 'c1', body: 'hello' }]);
+  });
+
+  test('writes annotations SVG when Y.Map.svg changes', async () => {
+    agent = makeAgent();
+    docA.transact(() => {
+      docA.getMap('annotations').set('svg', '<svg>annot</svg>');
+    });
+    await agent.flush();
+
+    expect(readFileSync(paths().annotations, 'utf8')).toBe('<svg>annot</svg>');
+  });
+});
+
+describe('CanvasSyncAgent — disk → hub (Flow A)', () => {
+  test('applies disk HTML to doc when applyFromFs is called', () => {
+    agent = makeAgent();
+    const bytes = new TextEncoder().encode('<div>local-edit</div>');
+    const changed = agent.applyFromFs({
+      path: paths().html,
+      bytes,
+      hash: hashBytes(bytes),
+    });
+    expect(changed).toBe(true);
+    expect(htmlFromDoc(docA)).toBe('<div>local-edit</div>');
+  });
+
+  test('parses + applies comments JSON from disk', () => {
+    agent = makeAgent();
+    const snap = [{ id: 'c2' }];
+    const str = `${JSON.stringify(snap, null, 2)}\n`;
+    const bytes = new TextEncoder().encode(str);
+    agent.applyFromFs({ path: paths().comments, bytes, hash: hashBytes(bytes) });
+    expect(docA.getArray('comments').toArray()).toEqual(snap);
+  });
+
+  test('applies annotations SVG from disk', () => {
+    agent = makeAgent();
+    const bytes = new TextEncoder().encode('<svg>x</svg>');
+    agent.applyFromFs({ path: paths().annotations, bytes, hash: hashBytes(bytes) });
+    expect(docA.getMap<string>('annotations').get('svg')).toBe('<svg>x</svg>');
+  });
+
+  test('drops the fs-watch echo of its own atomic write', async () => {
+    agent = makeAgent();
+    // Peer edits → agent writes to disk → echo guard recorded.
+    applyHtmlToDoc(docA, '<button>hi</button>');
+    await agent.flush();
+
+    // Simulate the fs.watch firing for the path we just wrote.
+    const bytes = readFileSync(paths().html);
+    const u8 = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const changed = agent.applyFromFs({
+      path: paths().html,
+      bytes: u8,
+      hash: hashBytes(u8),
+    });
+
+    expect(changed).toBe(false);
+  });
+});
+
+describe('CanvasSyncAgent — cold start reconciliation', () => {
+  test('hub-wins (default): overwrites disk when doc differs', async () => {
+    // Local disk has stale content.
+    writeFileSync(paths().html, '<old>');
+    // Hub state arrives via docA (propagated to docB before reconcile runs).
+    applyHtmlToDoc(docA, '<new>');
+
+    agent = makeAgent();
+    await agent.reconcile();
+
+    expect(readFileSync(paths().html, 'utf8')).toBe('<new>');
+  });
+
+  test('adopt mode: pushes local disk state up to the doc', async () => {
+    writeFileSync(paths().html, '<button>local</button>');
+    // Hub has stale content.
+    applyHtmlToDoc(docA, '<old-hub>');
+
+    agent = makeAgent({ adopt: true });
+    await agent.reconcile();
+
+    expect(htmlFromDoc(docA)).toBe('<button>local</button>');
+    expect(htmlFromDoc(docB)).toBe('<button>local</button>');
+  });
+
+  test('adopt mode is one-shot — second reconcile is hub-wins', async () => {
+    writeFileSync(paths().html, '<button>local-v1</button>');
+    agent = makeAgent({ adopt: true });
+    await agent.reconcile();
+
+    // Hub changes the value.
+    applyHtmlToDoc(docA, '<button>hub-v2</button>');
+
+    // Disk reverts to a stale local-only state.
+    writeFileSync(paths().html, '<button>local-v3</button>');
+    await agent.reconcile();
+
+    // Hub state won this time.
+    expect(htmlFromDoc(docB)).toBe('<button>hub-v2</button>');
+  });
+
+  test('identical disk + doc states: no disk write', async () => {
+    writeFileSync(paths().html, '<button>same</button>');
+    applyHtmlToDoc(docA, '<button>same</button>');
+
+    agent = makeAgent();
+    let writes = 0;
+    const customAgent = createCanvasSyncAgent({
+      slug: 'screen',
+      doc: docB,
+      paths: paths(),
+      echoGuard: createEchoGuard(),
+      flushMs: 0,
+      writer: () => {
+        writes++;
+      },
+    });
+    customAgent.start();
+    await customAgent.reconcile();
+    customAgent.stop();
+
+    expect(writes).toBe(0);
+  });
+});
+
+describe('CanvasSyncAgent — stress: 100 rapid disk writes converge with no echo loop', () => {
+  test('100-event scenario from plan validate', async () => {
+    // Wire up fs-mirror against the temp dir so this looks like the production
+    // flow: file writes → fs.watch → fs-mirror debounce → agent.applyFromFs.
+    agent = makeAgent({ flushMs: 20 });
+
+    const reader = createFsReader({
+      rootDir: dir,
+      quietMs: 15,
+      accept: (p) => p.endsWith('.html'),
+      onRead: async (evt) => {
+        agent.applyFromFs({
+          path: join(dir, evt.path),
+          bytes: evt.bytes,
+          hash: evt.hash,
+        });
+      },
+    });
+
+    // Track how many times the doc transitioned — should be bounded, no echo
+    // loop multiplying it.
+    let docUpdates = 0;
+    docB.on('update', () => {
+      docUpdates++;
+    });
+
+    for (let i = 0; i < 100; i++) {
+      writeFileSync(paths().html, `<button>${i}</button>`);
+      reader.notify('screen.html');
+    }
+
+    // Let everything settle: reader quiet (15ms), agent flush (20ms) + slack.
+    await new Promise((res) => setTimeout(res, 200));
+    await reader.flush();
+    await agent.flush();
+    reader.stop();
+
+    // Doc + disk + peer all converge on the last write.
+    const last = '<button>99</button>';
+    expect(htmlFromDoc(docB)).toBe(last);
+    expect(htmlFromDoc(docA)).toBe(last);
+    expect(readFileSync(paths().html, 'utf8')).toBe(last);
+
+    // Update count must be bounded — strictly < 100 transitions (debounce did
+    // its job) AND < 200 (no echo loop running 2x amplification).
+    expect(docUpdates).toBeLessThan(200);
+    // Also: it should be > 0 — we DID see real syncs.
+    expect(docUpdates).toBeGreaterThan(0);
+  });
+});

package/plugins/design/dev-server/test/sync-atomic-write.test.ts

@@ -0,0 +1,63 @@
+// Atomic-write unit tests — Phase 9 Task 4.
+
+import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { atomicWrite } from '../sync/atomic-write.ts';
+
+let dir: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'atomic-write-'));
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('atomicWrite', () => {
+  test('writes UTF-8 string to a new path', () => {
+    const p = join(dir, 'a.html');
+    atomicWrite(p, '<button>hi</button>');
+    expect(readFileSync(p, 'utf8')).toBe('<button>hi</button>');
+  });
+
+  test('writes Uint8Array bytes verbatim', () => {
+    const p = join(dir, 'b.html');
+    const bytes = new TextEncoder().encode('<div>x</div>');
+    atomicWrite(p, bytes);
+    expect(readFileSync(p, 'utf8')).toBe('<div>x</div>');
+  });
+
+  test('overwrites existing files atomically (no partial-write window)', () => {
+    const p = join(dir, 'c.html');
+    writeFileSync(p, 'old');
+    atomicWrite(p, 'new');
+    expect(readFileSync(p, 'utf8')).toBe('new');
+  });
+
+  test('cleans up the .tmp sidecar after a successful write', () => {
+    const p = join(dir, 'd.html');
+    atomicWrite(p, 'final');
+    const leftovers = readdirSync(dir).filter((f) => f.startsWith('d.html.tmp.'));
+    expect(leftovers).toEqual([]);
+  });
+
+  test('rapid sequential writes converge on the last value', () => {
+    const p = join(dir, 'e.html');
+    for (let i = 0; i < 50; i++) {
+      atomicWrite(p, `v${i}`);
+    }
+    expect(readFileSync(p, 'utf8')).toBe('v49');
+    const leftovers = readdirSync(dir).filter((f) => f.startsWith('e.html.tmp.'));
+    expect(leftovers).toEqual([]);
+  });
+
+  test('returns the path it wrote', () => {
+    const p = join(dir, 'f.html');
+    expect(atomicWrite(p, 'x')).toBe(p);
+  });
+});

package/plugins/design/dev-server/test/sync-codec.test.ts

@@ -0,0 +1,165 @@
+// Codec unit tests — Phase 9 Task 4.
+//
+// Verify Y.Doc <-> disk round-trips for the three classes of files the sync
+// agent shuttles: HTML body, comments JSON, annotations SVG.
+
+import { describe, expect, test } from 'bun:test';
+import * as Y from 'yjs';
+
+import { Y_TYPES } from '../collab/persistence.ts';
+import {
+  Y_SYNC_TYPES,
+  annotationsFromDoc,
+  applyAnnotationsToDoc,
+  applyCommentsToDoc,
+  applyHtmlToDoc,
+  commentsFromDoc,
+  htmlFromDoc,
+} from '../sync/codec.ts';
+
+describe('HTML codec', () => {
+  test('htmlFromDoc returns empty string for a fresh doc', () => {
+    const doc = new Y.Doc();
+    expect(htmlFromDoc(doc)).toBe('');
+  });
+
+  test('applyHtmlToDoc → htmlFromDoc round-trip', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, '<button>hello</button>');
+    expect(htmlFromDoc(doc)).toBe('<button>hello</button>');
+  });
+
+  test('applyHtmlToDoc with identical content is a no-op', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, '<button>hi</button>');
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const changed = applyHtmlToDoc(doc, '<button>hi</button>');
+    expect(changed).toBe(false);
+    expect(updates).toBe(0);
+  });
+
+  test('applyHtmlToDoc emits a minimal op via common prefix + suffix', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, '<button class="cta">Click</button>');
+
+    // Yjs requires `event.changes.delta` to be read inside the observer.
+    let inserts = '';
+    let deletes = 0;
+    const yText = doc.getText(Y_SYNC_TYPES.html);
+    yText.observe((evt) => {
+      for (const d of evt.changes.delta) {
+        if (typeof d.insert === 'string') inserts += d.insert;
+        if (typeof d.delete === 'number') deletes += d.delete;
+      }
+    });
+
+    applyHtmlToDoc(doc, '<button class="cta">Tap</button>');
+    expect(htmlFromDoc(doc)).toBe('<button class="cta">Tap</button>');
+
+    // The change is "Click" → "Tap". With shared prefix
+    // `<button class="cta">` and shared suffix `</button>`, the delta should
+    // only touch the middle.
+    expect(inserts).toBe('Tap');
+    expect(deletes).toBe('Click'.length);
+  });
+
+  test('applyHtmlToDoc handles complete replace (no shared prefix)', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, 'aaaa');
+    applyHtmlToDoc(doc, 'bbbb');
+    expect(htmlFromDoc(doc)).toBe('bbbb');
+  });
+
+  test('applyHtmlToDoc tags transaction with origin', () => {
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, 'seed');
+
+    let observedOrigin: unknown = 'unset';
+    doc.on('update', (_update: Uint8Array, origin: unknown) => {
+      observedOrigin = origin;
+    });
+
+    const myOrigin = { id: 'sync-agent' };
+    applyHtmlToDoc(doc, 'changed', myOrigin);
+    expect(observedOrigin).toBe(myOrigin);
+  });
+});
+
+describe('Comments codec', () => {
+  test('commentsFromDoc returns empty array for a fresh doc', () => {
+    expect(commentsFromDoc(new Y.Doc())).toEqual([]);
+  });
+
+  test('applyCommentsToDoc → commentsFromDoc round-trip', () => {
+    const doc = new Y.Doc();
+    const snap = [{ id: 'c1', body: 'hi' }];
+    applyCommentsToDoc(doc, snap);
+    expect(commentsFromDoc(doc)).toEqual(snap);
+  });
+
+  test('applyCommentsToDoc with identical content is a no-op', () => {
+    const doc = new Y.Doc();
+    applyCommentsToDoc(doc, [{ id: 'c1' }]);
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const changed = applyCommentsToDoc(doc, [{ id: 'c1' }]);
+    expect(changed).toBe(false);
+    expect(updates).toBe(0);
+  });
+
+  test('applyCommentsToDoc replaces existing entries on disk-wins update', () => {
+    const doc = new Y.Doc();
+    applyCommentsToDoc(doc, [{ id: 'c1' }, { id: 'c2' }]);
+    applyCommentsToDoc(doc, [{ id: 'c3' }]);
+    expect(commentsFromDoc(doc)).toEqual([{ id: 'c3' }]);
+  });
+
+  test('comments share Y_TYPES.comments name with Phase 6 persistence', () => {
+    const doc = new Y.Doc();
+    applyCommentsToDoc(doc, [{ id: 'c1' }]);
+    // The Phase 6 persistence layer reads from this name directly.
+    expect(doc.getArray(Y_TYPES.comments).toArray()).toEqual([{ id: 'c1' }]);
+  });
+});
+
+describe('Annotations codec', () => {
+  test('annotationsFromDoc returns null for a fresh doc', () => {
+    expect(annotationsFromDoc(new Y.Doc())).toBeNull();
+  });
+
+  test('applyAnnotationsToDoc → annotationsFromDoc round-trip', () => {
+    const doc = new Y.Doc();
+    applyAnnotationsToDoc(doc, '<svg></svg>');
+    expect(annotationsFromDoc(doc)).toBe('<svg></svg>');
+  });
+
+  test('applyAnnotationsToDoc with null clears the entry', () => {
+    const doc = new Y.Doc();
+    applyAnnotationsToDoc(doc, '<svg></svg>');
+    applyAnnotationsToDoc(doc, null);
+    expect(annotationsFromDoc(doc)).toBeNull();
+  });
+
+  test('applyAnnotationsToDoc with identical content is a no-op', () => {
+    const doc = new Y.Doc();
+    applyAnnotationsToDoc(doc, '<svg></svg>');
+    let updates = 0;
+    doc.on('update', () => {
+      updates++;
+    });
+    const changed = applyAnnotationsToDoc(doc, '<svg></svg>');
+    expect(changed).toBe(false);
+    expect(updates).toBe(0);
+  });
+
+  test('annotations share Y_TYPES.annotations name with Phase 5 persistence', () => {
+    const doc = new Y.Doc();
+    applyAnnotationsToDoc(doc, '<svg>x</svg>');
+    expect(doc.getMap<string>(Y_TYPES.annotations).get('svg')).toBe('<svg>x</svg>');
+  });
+});