@1agh/maude 1.4.5 → 1.4.6

package/apps/studio/annotations-model.ts

@@ -654,6 +654,37 @@ export function rid(): string {
   return `s_${Math.random().toString(36).slice(2, 10)}`;
 }
 
+/**
+ * The id of an annotation element that was written WITHOUT a `data-id` (a
+ * hand-edited or externally generated SVG). It used to be `rid()` — a new
+ * random id on every parse — so the same element had a different id in every
+ * tab, on every peer and after every reload, and nothing could point at it: a
+ * comment anchored to it (#134/#136), a peer's selection halo, an agent's
+ * `annotate update`. Now it is derived from the element's own markup, plus its
+ * occurrence among identical elements, so every parse of the same SVG gives
+ * every element the same id everywhere. The first edit writes it back as a real
+ * `data-id` (strokesToSvg always emits one), after which it never changes.
+ *
+ * Contract for the annotations-v2 element model
+ * (.ai/plans/feature-annotations-v2-element-model.md): an annotation's id is
+ * stable for the life of the element — across edits, moves, undo/redo, sync
+ * and reload — and is what external references (comments' `annotationId`)
+ * hold. A migration must carry ids over unchanged.
+ */
+export function stableAnnotationId(el: Element, seen: Map<string, number>): string {
+  const content = el.outerHTML;
+  const n = seen.get(content) ?? 0;
+  seen.set(content, n + 1);
+  // FNV-1a, 32-bit — deterministic, dependency-free, plenty for a per-board id.
+  let h = 0x811c9dc5;
+  const key = `${content}#${n}`;
+  for (let i = 0; i < key.length; i++) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return `s_h${h.toString(36)}`;
+}
+
 /** FigJam v3 — group ids mirror the stroke id scheme (`g_` prefix). */
 export function gid(): string {
   return `g_${Math.random().toString(36).slice(2, 10)}`;
@@ -1424,9 +1455,10 @@ export function svgToStrokes(svgText: string): Stroke[] {
     const doc = new DOMParser().parseFromString(text, 'image/svg+xml');
     if (doc.querySelector('parsererror')) return [];
     const out: Stroke[] = [];
+    const seenContent = new Map<string, number>();
     for (const el of Array.from(doc.querySelectorAll('[data-tool]'))) {
       const tool = el.getAttribute('data-tool');
-      const id = el.getAttribute('data-id') || rid();
+      const id = el.getAttribute('data-id') || stableAnnotationId(el, seenContent);
       const color = el.getAttribute('stroke') || el.getAttribute('fill') || DEFAULT_COLOR;
       const width = Number.parseFloat(el.getAttribute('stroke-width') || '2') || 2;
       // FigJam v3 — every branch funnels through push() so the shared attrs

package/apps/studio/api.ts

@@ -19,6 +19,7 @@ import { canvasArtifacts, locatorKeyFor, relocatedName } from './canvas-artifact
 import { renderBriefBoard, validateCanvasName, validateFolderName } from './canvas-create.ts';
 import { rewriteRelativeImports } from './canvas-imports.ts';
 import { canvasSlugFromRel } from './canvas-slug.ts';
+import { isAnnotationId, isWorldPoint } from './comment-anchor.ts';
 import { atomicWrite } from './sync/atomic-write.ts';
 import { dedupeCommentsById } from './sync/comment-identity.ts';
 import { isRuntimeStateRel } from './sync/file-membership.ts';
@@ -323,6 +324,12 @@ export interface Comment {
    *  text is untrusted user/peer text (DDR-054) — rendered as text, never
    *  into TSX. */
   timeline?: { clipStableId?: string; frameOffset?: number; frame?: number; lane?: string };
+  /** #134/#136 — anchor on an annotation (`data-id` in `*.annotations.svg`).
+   *  Absent on element and floating comments. See comment-anchor.ts. */
+  annotationId?: string;
+  /** World point of the comment: the anchor of a floating comment, the last
+   *  known place of an anchored one. Absent on legacy comments. */
+  world?: { x: number; y: number };
 }
 
 export interface GitCommitter {
@@ -1247,6 +1254,11 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       thread: Array.isArray(c.thread) ? c.thread : [],
       mentions: Array.isArray(c.mentions) ? c.mentions : [],
       ...(timeline ? { timeline } : { timeline: undefined }),
+      // Same trust boundary for the #134/#136 anchors: a peer-synced comment
+      // never passed commentsAdd, so an anchor that fails its shape is dropped
+      // (the comment then renders from `bounds`, detached — never deleted).
+      annotationId: isAnnotationId(c.annotationId) ? c.annotationId : undefined,
+      world: isWorldPoint(c.world) ? { x: c.world.x, y: c.world.y } : undefined,
     };
   }
 
@@ -1462,6 +1474,9 @@ export function createApi(ctx: Context, hooks: ApiHooks): Api {
       }
       if (anchor.clipStableId != null || anchor.frame != null) c.timeline = anchor;
     }
+    // #134/#136 — annotation / world anchors (peer-supplied: shape-checked).
+    if (isAnnotationId(payload.annotationId)) c.annotationId = payload.annotationId;
+    if (isWorldPoint(payload.world)) c.world = { x: payload.world.x, y: payload.world.y };
     list.push(c);
     await publishComments(payload.file, list, base);
     return c;

package/apps/studio/canvas-comment-mount.tsx

@@ -39,6 +39,7 @@ import {
 } from 'react';
 import { createRoot } from 'react-dom/client';
 
+import { annotationElement, annotationIdAt, clientToWorld } from './comment-anchor.ts';
 import { CommentsOverlay } from './comments-overlay.tsx';
 import { deriveFile, hoverTargetToSelection } from './dom-selection.ts';
 import {
@@ -394,6 +395,36 @@ function dropComment(
   file: string | undefined
 ): void {
   if (typeof document === 'undefined') return;
+  const world = clientToWorld(clientX, clientY) ?? undefined;
+
+  // A click on an annotation (sticky, shape, stroke, image, link, media card)
+  // anchors to it (#134/#136). Checked first: annotations draw above the
+  // artboards, so what the user clicked is the annotation, not the element
+  // underneath it.
+  const annotationId = annotationIdAt(clientX, clientY);
+  if (annotationId) {
+    const el = annotationElement(annotationId);
+    const r = el?.getBoundingClientRect();
+    const annotationSel: Selection = {
+      file,
+      id: undefined,
+      selector: '',
+      artboardId: null,
+      tag: el?.getAttribute('data-tool') ?? 'annotation',
+      classes: '',
+      text: '',
+      dom_path: [],
+      bounds: r
+        ? { x: r.left, y: r.top, w: r.width, h: r.height }
+        : { x: clientX - 12, y: clientY - 12, w: 24, h: 24 },
+      html: '',
+      annotationId,
+      ...(world ? { world } : {}),
+    };
+    openComposer(annotationSel, clientX, clientY);
+    return;
+  }
+
   let target = resolveHoverTarget(document, clientX, clientY, { deep: true });
   if (!target) target = resolveHoverTarget(document, clientX, clientY, { deep: false });
   // UI-canvas recovery — when both passes bail on a `pointer-events: none`
@@ -428,8 +459,9 @@ function dropComment(
 
   if (!target) {
     // Floating comment — no element anchor, just the click point (e.g. a click
-    // on empty canvas/specimen dead space). The overlay renders a pin at the
-    // stored bounds.
+    // on empty canvas/specimen dead space). The overlay renders the pin at the
+    // WORLD point, so it stays put through pan and zoom; `bounds` is the
+    // screen-space fallback for surfaces without a world plane (specimens).
     const floatingSel: Selection = {
       file,
       id: undefined,
@@ -441,6 +473,7 @@ function dropComment(
       dom_path: [],
       bounds: { x: clientX - 12, y: clientY - 12, w: 24, h: 24 },
       html: '',
+      ...(world ? { world } : {}),
     };
     openComposer(floatingSel, clientX, clientY);
     return;

package/apps/studio/canvas-lib.tsx

@@ -2869,11 +2869,16 @@ function buildCanvasRectsManifest(): CanvasRectsManifest {
 declare global {
   interface Window {
     __maudeCanvasRects?: () => CanvasRectsManifest;
+    /** The live camera, for layers built in another bundle (the comment
+     *  overlay mounts from canvas-comment-mount, which gets its own copy of
+     *  this module's state) — see comment-anchor.ts. */
+    __maudeViewport?: () => ViewportState | null;
   }
 }
 
 if (typeof window !== 'undefined') {
   window.__maudeCanvasRects = buildCanvasRectsManifest;
+  window.__maudeViewport = getLiveViewport;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/apps/studio/canvas-shell.tsx

@@ -1130,9 +1130,52 @@ interface DsThemeSupport {
 }
 
 let _dsThemeSupport: DsThemeSupport | null = null;
+// A NEGATIVE answer is cached too (#131). The probe below appends DOM to
+// <body> and reads getComputedStyle for every candidate, which forces a style
+// recalc of the whole document. Only a positive answer was cached, so on a
+// canvas whose DS has a single theme it re-ran on EVERY call — and the element
+// toolbar's menu asks on every render, i.e. every frame of a pan with something
+// selected. On a 160-board canvas in Safari that alone held pan at ~1.3 fps
+// (hundreds of ms per probe, two per frame). The reason a negative answer was
+// not cached — a DS stylesheet that parses after first paint — is honoured
+// precisely instead: the negative answer holds until a stylesheet is added to
+// or finishes loading in the document, then the next call probes again.
+let _dsThemeUnsupported = false;
+let _dsThemeWatch = false;
+const _unsupported: DsThemeSupport = { supported: false, wrapperClass: '' };
+
+function watchStylesheetsOnce(): void {
+  if (_dsThemeWatch || typeof document === 'undefined') return;
+  _dsThemeWatch = true;
+  const invalidate = (): void => {
+    _dsThemeUnsupported = false;
+  };
+  try {
+    new MutationObserver((records) => {
+      for (const r of records) {
+        for (const n of Array.from(r.addedNodes)) {
+          const tag = (n as Element).tagName;
+          if (tag === 'STYLE' || tag === 'LINK') return invalidate();
+        }
+      }
+    }).observe(document.head ?? document.documentElement, { childList: true, subtree: true });
+    // A <link> that was already in the DOM finishing its load (capture: load
+    // does not bubble).
+    document.addEventListener(
+      'load',
+      (e) => {
+        if ((e.target as Element | null)?.tagName === 'LINK') invalidate();
+      },
+      true
+    );
+  } catch {
+    _dsThemeWatch = false;
+  }
+}
 
-function detectDsThemeSupport(): DsThemeSupport {
+export function detectDsThemeSupport(): DsThemeSupport {
   if (_dsThemeSupport) return _dsThemeSupport;
+  if (_dsThemeUnsupported) return _unsupported;
   const fallback: DsThemeSupport = { supported: false, wrapperClass: '' };
   if (typeof document === 'undefined' || !document.body) return fallback;
   try {
@@ -1181,6 +1224,10 @@ function detectDsThemeSupport(): DsThemeSupport {
     // unsupported. Caching that would permanently disable theming; instead
     // re-probe until support is confirmed (or the DS genuinely has one theme).
     if (found.supported) _dsThemeSupport = found;
+    else {
+      _dsThemeUnsupported = true;
+      watchStylesheetsOnce();
+    }
     return found;
   } catch {
     return fallback;

package/apps/studio/client/app.jsx

@@ -13711,6 +13711,9 @@ function App() {
               classes: p.classes,
               bounds: p.bounds,
               html_excerpt: p.html_excerpt,
+              // #134/#136 anchors — shape-checked server-side (api.ts commentsAdd).
+              annotationId: p.annotationId,
+              world: p.world,
               text: txt,
             },
           });

package/apps/studio/client/comments-overlay.css

@@ -65,6 +65,16 @@
   opacity: 0.6;
 }
 
+/* Detached — the comment's element or annotation is gone from this canvas. The
+   comment is kept at its last known place (never deleted by software, #134/#136).
+   A hollow, dashed pin: the state reads from the shape, not from colour alone,
+   and the number keeps full contrast. The aria-label says "detached" too. */
+.cm-pin[data-detached='true'] {
+  background: var(--maude-chrome-bg-1, #faf6ef);
+  color: var(--maude-chrome-fg-0, #2a2520);
+  border: 1.5px dashed var(--maude-hud-accent, #6f63ef);
+}
+
 .cm-pin[data-focused='true'] {
   /* Subtle ring — DS hard-edges discipline: no glow, just a hairline outline. */
   outline: 1px solid var(--maude-chrome-fg-0, #2a2520);

package/apps/studio/collab/index.ts

@@ -64,6 +64,15 @@ export function createCollab(ctx: Context, api: Api): Collab {
     api,
     fileForSlug,
     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

package/apps/studio/collab/persistence.ts

@@ -11,6 +11,7 @@ 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';
 
@@ -60,6 +61,19 @@ export interface PersistenceDeps {
    * seed). Absent → cache-only restore, the previous behavior.
    */
   reconcileAfterCache?: (slug: string, doc: Y.Doc, cachedAtMs: number) => Promise<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 +107,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 +195,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`);
   }
@@ -284,10 +320,22 @@ 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));
       }
     }
 

package/apps/studio/comment-anchor.ts

@@ -0,0 +1,116 @@
+/**
+ * @file       comment-anchor.ts — where a comment lives when it is not on an element
+ * @scope      apps/studio/comment-anchor.ts
+ * @purpose    Two anchors besides the `data-cd-id` element selector (#134/#136):
+ *
+ *   - `annotationId` — a comment placed on a sticky, shape, pen stroke, image,
+ *     link or media card anchors to that annotation's `data-id`. Annotation ids
+ *     are persisted in `*.annotations.svg` and stable across edits, undo and
+ *     sync (see `stableAnnotationId` in annotations-model.ts for the one case
+ *     they were not). The pin follows the annotation; a deleted annotation
+ *     DETACHES the comment, it never deletes it.
+ *   - `world` — a comment placed on empty canvas holds a WORLD point, so it stays
+ *     put through pan and zoom. The legacy screen `bounds` captured at create
+ *     time only matched the camera of that moment.
+ *
+ * Runs inside the canvas iframe, in both the canvas bundle and the separate
+ * comment-mount bundle — so the camera is read through `window.__maudeViewport`
+ * (canvas-lib.tsx), not through a module import that would be another copy.
+ * Annotation ids are peer-supplied (DDR-054): every id is validated before it
+ * reaches a selector.
+ */
+
+export interface WorldPoint {
+  x: number;
+  y: number;
+}
+
+interface Viewport {
+  x: number;
+  y: number;
+  zoom: number;
+}
+
+/** Shape rule for an annotation id — the `s_…` scheme plus imported ids. */
+const ANNOTATION_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/** World coordinates beyond this are garbage, not a place on the board. */
+const MAX_WORLD = 10_000_000;
+
+export function isAnnotationId(v: unknown): v is string {
+  return typeof v === 'string' && ANNOTATION_ID_RE.test(v);
+}
+
+export function isWorldPoint(v: unknown): v is WorldPoint {
+  if (!v || typeof v !== 'object') return false;
+  const { x, y } = v as { x?: unknown; y?: unknown };
+  return (
+    typeof x === 'number' &&
+    typeof y === 'number' &&
+    Number.isFinite(x) &&
+    Number.isFinite(y) &&
+    Math.abs(x) <= MAX_WORLD &&
+    Math.abs(y) <= MAX_WORLD
+  );
+}
+
+function liveCamera(): { vp: Viewport; left: number; top: number } | null {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return null;
+  const vp = window.__maudeViewport?.() ?? null;
+  if (!vp || !(vp.zoom > 0)) return null;
+  const host = document.querySelector('.dc-canvas');
+  if (!host) return null;
+  const r = host.getBoundingClientRect();
+  return { vp, left: r.left, top: r.top };
+}
+
+/** Client (iframe viewport) point → world point, or null with no world plane. */
+export function clientToWorld(clientX: number, clientY: number): WorldPoint | null {
+  const cam = liveCamera();
+  if (!cam) return null;
+  const { vp } = cam;
+  return {
+    x: (clientX - cam.left - vp.x) / vp.zoom,
+    y: (clientY - cam.top - vp.y) / vp.zoom,
+  };
+}
+
+/** World point → client point, or null with no world plane. */
+export function worldToClient(p: WorldPoint): { x: number; y: number } | null {
+  const cam = liveCamera();
+  if (!cam) return null;
+  const { vp } = cam;
+  return { x: cam.left + vp.x + p.x * vp.zoom, y: cam.top + vp.y + p.y * vp.zoom };
+}
+
+/** The live element of an annotation, or null. */
+export function annotationElement(id: string): Element | null {
+  if (typeof document === 'undefined' || !isAnnotationId(id)) return null;
+  // The id is already restricted to [A-Za-z0-9_-]; no escaping needed.
+  return document.querySelector(`[data-id="${id}"][data-tool]`);
+}
+
+/**
+ * The annotation under a client point, if any. Geometric rather than
+ * `elementFromPoint`: in comment mode the annotation layer is not the hit
+ * target (its pointer events belong to the draw tools), which is exactly why a
+ * click on a sticky used to fall through to a floating comment.
+ *
+ * The smallest containing box wins, so a sticky inside a section anchors to
+ * the sticky. Sections are skipped: they frame artboards and other elements,
+ * and "a comment somewhere inside this section" is a floating comment.
+ */
+export function annotationIdAt(clientX: number, clientY: number): string | null {
+  if (typeof document === 'undefined') return null;
+  let best: { id: string; area: number } | null = null;
+  for (const el of Array.from(document.querySelectorAll('[data-id][data-tool]'))) {
+    if (el.getAttribute('data-tool') === 'section') continue;
+    const id = el.getAttribute('data-id');
+    if (!isAnnotationId(id)) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 && r.height <= 0) continue;
+    if (clientX < r.left || clientX > r.right || clientY < r.top || clientY > r.bottom) continue;
+    const area = Math.max(1, r.width) * Math.max(1, r.height);
+    if (!best || area <= best.area) best = { id, area };
+  }
+  return best?.id ?? null;
+}