@1agh/maude 1.4.5 → 1.5.0

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

@@ -18,16 +18,38 @@
 // A canvas the project does not know yet is proposed as `doc.create` with all
 // of its lanes, so it arrives on every peer as ONE action.
 //
-// Comments and annotations are never re-proposed from disk here: every change
-// the studio made to them went through the durable outbox (drained before any
-// cold start), so a difference on disk is an older accepted state the room had
-// not re-projected — the accepted value wins, and the local file is kept in a
+// Annotations are never re-proposed from disk here: every change the studio
+// made to them went through the durable outbox (drained before any cold start),
+// so a difference on disk is an older accepted state the room had not
+// re-projected — the accepted value wins, and the local file is kept in a
 // recovery slot in case a raw edit made while the studio was down lived there.
+//
+// Comments had the same rule, and the premise did not hold for them (issue
+// #133, reproduced end-to-end): a comment added while the sync runtime was not
+// up yet (`proposeLane` unavailable, server.ts) went to the local room and disk
+// only, never into the outbox — so the web never saw it, and the file then
+// froze behind it. Comments carry stable ids, so the difference is decidable:
+// an id on disk that the accepted state lacks and that the comment ledger says
+// was never synced from here is a local comment still owed to the project; it
+// is proposed, as the accepted list plus those comments (a three-way id merge
+// on the hub). Ids the ledger knows were synced are deletions made while this
+// machine was away and are not proposed back. With no ledger record for the
+// canvas (first launch after upgrading) nothing is decidable: the old rule —
+// accepted wins, local kept in recovery — stands.
 
 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';
 import type { SyncJournal } from './journal.ts';
 import type { DocProjection, ProjectionPaths, ProposalLane } from './projection.ts';
@@ -53,6 +75,38 @@ function readText(p: string | undefined): string | null {
   }
 }
 
+function parseList(v: string): unknown[] {
+  if (!v) return [];
+  try {
+    const parsed = JSON.parse(v) as unknown;
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The comments list to propose at cold start — the accepted list plus the local
+ * comments never synced from here — or null when there is nothing owed (or no
+ * ledger record to decide by). See the header.
+ */
+export function commentsOwedToProject(
+  local: string,
+  accepted: string,
+  slug: string,
+  ledger: CommentLedger | undefined
+): string | null {
+  if (!ledger?.known(slug)) return null;
+  const acceptedList = parseList(accepted);
+  const inProject = new Set(acceptedList.map(commentKey));
+  const synced = ledger.get(slug);
+  const owed = parseList(local).filter((c) => {
+    const k = commentKey(c);
+    return !inProject.has(k) && !synced.has(k);
+  });
+  return owed.length > 0 ? JSON.stringify([...acceptedList, ...owed]) : null;
+}
+
 /**
  * Pure decision for the source lanes. `knownBase` is the last value disk and
  * the accepted replica agreed on (recovery slot), `baseHash` the journal's
@@ -92,6 +146,8 @@ export interface AcceptedColdStartInput {
   projection: DocProjection;
   historyDir?: string;
   journal?: SyncJournal;
+  /** Issue #133 — comment ids synced from here before (see the header). */
+  commentLedger?: CommentLedger;
   /**
    * This disk's own html proposal a previous run left unanswered, which the
    * outbox drain has just had accepted. The disk was saved on top of it, so it
@@ -131,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;
@@ -218,13 +275,20 @@ 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) {
       verdicts.push({ lane, decision: local === null ? 'materialize' : 'agreed' });
       continue;
     }
+    if (lane === 'comments') {
+      const owed = commentsOwedToProject(local, accepted, i.slug, i.commentLedger);
+      if (owed) {
+        verdicts.push({ lane, decision: 'propose', base: accepted, local: owed });
+        continue;
+      }
+    }
     if (i.historyDir && text) {
       try {
         saveRecoveryBody(i.historyDir, p, 'local', text);

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,
@@ -67,7 +70,8 @@ import {
   unionCommentsById,
 } from './cold-start.ts';
 import { applyColdStart, type ColdStartSnapshotReason } from './cold-start-apply.ts';
-import { dedupeCommentsById, hasDuplicateComments } from './comment-identity.ts';
+import { commentKey, dedupeCommentsById, hasDuplicateComments } from './comment-identity.ts';
+import { type CommentLedger, withoutRemotelyDeleted } from './comment-ledger.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import { rememberSeed, repairSeedDuplication } from './seed-repair.ts';
@@ -87,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)
@@ -119,6 +123,20 @@ export interface CanvasSyncAgentOptions {
    * without it simply degrade to the conservative conflict path.
    */
   journal?: SyncJournal;
+  /**
+   * Issue #133 — comment ids synced from this machine before
+   * (sync/comment-ledger.ts). The cold-start union drops a local comment the
+   * ledger knows and the hub's doc no longer holds: that is a delete made
+   * while this machine was away, not a local-only comment. Optional — absent,
+   * the union keeps everything, as before.
+   */
+  commentLedger?: CommentLedger;
+  /**
+   * Does the hub hold this doc's current state (nothing unacknowledged)? The
+   * ledger records comment ids as synced only then — see
+   * `commentsConfirmedOnHub` in sync/index.ts. Absent → never records.
+   */
+  commentsConfirmed?: () => boolean;
   /**
    * Snapshot writer (DDR-102 conflict protocol) — persists a body version to
    * `_history/<slug>/` and resolves with the snapshot's ISO ts (null on
@@ -339,6 +357,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     echoGuard.record(paths.comments, hash);
     writer(paths.comments, serialized);
     lastComments = serialized;
+    if (opts.commentsConfirmed?.()) opts.commentLedger?.record(slug, next.map(commentKey));
   }
 
   function writeAnnotationsIfChanged(): void {
@@ -352,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;
   }
@@ -411,6 +431,8 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
       if (parsed === null) return false;
       const changed = applyCommentsToDoc(doc, parsed, origin);
       if (changed) lastComments = str;
+      if (opts.commentsConfirmed?.())
+        opts.commentLedger?.record(slug, commentsFromDoc(doc).map(commentKey));
       return changed;
     }
     if (evt.path === paths.annotations) {
@@ -420,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;
@@ -452,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;
 
@@ -562,7 +584,13 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
     const bodyWinner = applied.bodyWinner;
 
     // ---- comments: id-union merge (DDR-102 — union loses nothing) ----------
-    const localParsedComments = localComments !== null ? tryParseJsonArray(localComments) : null;
+    const localParsed = localComments !== null ? tryParseJsonArray(localComments) : null;
+    // Issue #133 — a local comment that was synced from here before and that
+    // the hub's doc no longer holds was deleted while this machine was away.
+    // Unioning it back resurrected it for everyone.
+    const localParsedComments = localParsed
+      ? withoutRemotelyDeleted(localParsed, docComments, opts.commentLedger?.get(slug))
+      : null;
     if (localParsedComments !== null && localParsedComments.length > 0) {
       const merged = unionCommentsById(docComments, localParsedComments);
       const mergedStr = merged.length > 0 ? `${JSON.stringify(merged, null, 2)}\n` : '';
@@ -573,6 +601,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
         writer(paths.comments, mergedStr);
       }
       lastComments = mergedStr;
+      if (opts.commentsConfirmed?.()) opts.commentLedger?.record(slug, merged.map(commentKey));
     } else {
       // No (parseable) local comments — hub state materializes as before.
       lastComments = docCommentsStr;
@@ -581,6 +610,7 @@ export function createCanvasSyncAgent(opts: CanvasSyncAgentOptions): CanvasSyncA
         echoGuard.record(paths.comments, hash);
         writer(paths.comments, docCommentsStr);
       }
+      if (opts.commentsConfirmed?.()) opts.commentLedger?.record(slug, docComments.map(commentKey));
     }
 
     // ---- annotations: PER-LANE newest-wins (the 2026-08-14 eraser fix) -----

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,17 @@ 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 {
+  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 +304,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 +391,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 +483,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 +506,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) : '';
 }