@1agh/maude 1.4.5 → 1.5.0

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

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

package/apps/studio/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;
+}

package/apps/studio/comments-overlay.tsx

@@ -33,9 +33,13 @@
  * trade-off), which can silently reanchor a comment to the wrong element or to
  * nothing. `resolveCommentTarget` tries the stored selector first, falls back
  * to a structural match via `resolveByDomPath` (dom-selection.ts) when the
- * direct hit is missing or looks like the wrong element (tag mismatch), and —
- * per DDR-034's deferred future-work item — `CommentPin` auto-deletes a
- * comment whose target stays unresolvable past a short grace window.
+ * direct hit is missing or looks like the wrong element (tag mismatch). A
+ * comment whose target stays unresolvable past a short grace window is
+ * DETACHED — kept, shown at its last known place, and marked — never deleted:
+ * software deleting a comment is how #134/#136 lost every comment placed on a
+ * sticky or on empty canvas, and how one peer's missing element deleted a
+ * comment for everyone. Only a person deletes a comment. Comments on
+ * annotations and on empty canvas anchor through `comment-anchor.ts`.
  *
  * Popup placement — `CommentComposer` / `CommentThread` pick a side
  * (left/right, above/below the anchor) that actually fits the viewport via
@@ -49,6 +53,13 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
+import {
+  annotationElement,
+  isAnnotationId,
+  isWorldPoint,
+  type WorldPoint,
+  worldToClient,
+} from './comment-anchor.ts';
 import { resolveByDomPath } from './dom-selection.ts';
 import { isReadOnlyCanvas } from './read-only-mode.ts';
 import { useCollab } from './use-collab.tsx';
@@ -84,6 +95,10 @@ interface ComposeSelection {
   dom_path: string[];
   bounds: OverlayBounds | null;
   html: string;
+  /** Set when the click landed on an annotation (comment-anchor.ts). */
+  annotationId?: string;
+  /** World point of the click, when the canvas has a world plane. */
+  world?: WorldPoint;
 }
 
 interface ComposerState {
@@ -121,6 +136,11 @@ export interface OverlayComment {
   tag?: string;
   classes?: string;
   dom_path?: string[];
+  /** Anchor on an annotation (sticky, shape, stroke…) — see comment-anchor.ts. */
+  annotationId?: string;
+  /** World point of the comment — the anchor of a floating comment, and the
+   * last known place of an anchored one whose target is gone. */
+  world?: WorldPoint;
   // html_excerpt unused at overlay layer; kept off the type to keep the
   // surface tight.
 }
@@ -176,6 +196,7 @@ export interface TargetRef {
   tag?: string;
   classes?: string;
   dom_path?: string[];
+  annotationId?: string;
 }
 
 /**
@@ -187,6 +208,9 @@ export interface TargetRef {
  * match via `resolveByDomPath`.
  */
 export function resolveCommentTarget(target: TargetRef): HTMLElement | null {
+  if (isAnnotationId(target.annotationId)) {
+    return annotationElement(target.annotationId) as HTMLElement | null;
+  }
   if (!target.selector) return null;
   let el: HTMLElement | null = null;
   try {
@@ -426,6 +450,8 @@ export function CommentsOverlay(): React.ReactNode {
         classes: sel.classes,
         bounds: sel.bounds,
         html_excerpt: sel.html,
+        ...(sel.annotationId ? { annotationId: sel.annotationId } : {}),
+        ...(sel.world ? { world: sel.world } : {}),
         text,
       };
       if (typeof window === 'undefined') return;
@@ -547,7 +573,6 @@ export function CommentsOverlay(): React.ReactNode {
             sequence={n}
             focused={focusedId === c.id}
             onClick={handlePinClick}
-            onOrphaned={handleDelete}
           />
         );
       })}
@@ -836,28 +861,54 @@ function MentionAwareTextarea({
 // reflow, font load). Falls back to the stored `bounds` when the target is
 // gone from the DOM.
 
-// How long a pin is allowed to stay unresolvable (no live target AND no
-// structural-fallback match) before its comment is presumed orphaned and
-// auto-deleted. Long enough to ride out a canvas HMR remount; short enough
-// that a genuinely deleted element's comment doesn't linger.
-const ORPHAN_GRACE_MS = 3000;
+// How long a pin may stay unresolvable before it is shown as DETACHED. Long
+// enough to ride out a canvas HMR remount. Detached is a view of this client's
+// DOM, never a fact written back: another peer may still resolve the target.
+const DETACH_GRACE_MS = 3000;
+
+/** The pin box for a client point — the pin centres on the point. */
+function pointBox(p: { x: number; y: number }): OverlayBounds {
+  return { x: p.x - 12, y: p.y - 12, w: 24, h: 24 };
+}
+
+/**
+ * Where a comment's pin goes this frame, and whether its target is missing.
+ *
+ *   - anchored (element selector or annotation id) and resolved → on the target;
+ *   - anchored but unresolved → last known place (world point, else the
+ *     create-time screen bounds), `missing: true`;
+ *   - floating (no anchor) → its world point, else legacy screen bounds.
+ */
+export function locateComment(comment: OverlayComment): {
+  pos: OverlayBounds | null;
+  missing: boolean;
+} {
+  const anchored = !!comment.selector || isAnnotationId(comment.annotationId);
+  if (anchored) {
+    const live = screenRectFor(comment);
+    if (live) return { pos: live, missing: false };
+  }
+  const at = isWorldPoint(comment.world) ? worldToClient(comment.world) : null;
+  const pos = at ? pointBox(at) : (comment.bounds ?? null);
+  return { pos, missing: anchored };
+}
 
 function CommentPin({
   comment,
   sequence,
   focused,
   onClick,
-  onOrphaned,
 }: {
   comment: OverlayComment;
   sequence: number;
   focused: boolean;
   onClick: (id: string) => void;
-  onOrphaned: (id: string) => void;
 }) {
   const ref = useRef<HTMLButtonElement | null>(null);
   const rafRef = useRef<number | null>(null);
-  const unresolvedSinceRef = useRef<number | null>(null);
+  const missingSinceRef = useRef<number | null>(null);
+  const [detached, setDetached] = useState(false);
+  const detachedRef = useRef(false);
 
   useEffect(() => {
     const tick = () => {
@@ -865,27 +916,18 @@ function CommentPin({
       const pin = ref.current;
       if (!pin) return;
 
-      // Live screen-coord lookup mirrors SelectionHalos in canvas-shell.tsx
-      // (resolveCommentTarget tries the stored selector, then a structural
-      // fallback). Falls back to stored bounds (a screen-coord capture at
-      // create time) when neither resolves — better than vanishing entirely.
-      let pos = screenRectFor(comment);
-      if (pos) {
-        unresolvedSinceRef.current = null;
+      // Live screen-coord lookup mirrors SelectionHalos in canvas-shell.tsx.
+      const { pos, missing } = locateComment(comment);
+      let nowDetached = false;
+      if (missing) {
+        if (missingSinceRef.current == null) missingSinceRef.current = Date.now();
+        nowDetached = Date.now() - missingSinceRef.current > DETACH_GRACE_MS;
       } else {
-        if (unresolvedSinceRef.current == null) {
-          unresolvedSinceRef.current = Date.now();
-        } else if (Date.now() - unresolvedSinceRef.current > ORPHAN_GRACE_MS) {
-          onOrphaned(comment.id);
-        }
-        if (comment.bounds) {
-          pos = {
-            x: comment.bounds.x,
-            y: comment.bounds.y,
-            w: comment.bounds.w,
-            h: comment.bounds.h,
-          };
-        }
+        missingSinceRef.current = null;
+      }
+      if (nowDetached !== detachedRef.current) {
+        detachedRef.current = nowDetached;
+        setDetached(nowDetached);
       }
       if (!pos) {
         pin.style.display = 'none';
@@ -905,10 +947,10 @@ function CommentPin({
     return () => {
       if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
     };
-  }, [comment, onOrphaned]);
+  }, [comment]);
 
   const author = comment.author?.trim() || 'unknown';
-  const label = `Comment ${sequence} by ${author}`;
+  const label = `Comment ${sequence} by ${author}${detached ? ' (detached: its target is gone)' : ''}`;
 
   return (
     <button
@@ -917,6 +959,7 @@ function CommentPin({
       className="cm-pin"
       data-resolved={comment.status === 'resolved' ? 'true' : 'false'}
       data-focused={focused ? 'true' : 'false'}
+      data-detached={detached ? 'true' : 'false'}
       data-comment-pin={comment.id}
       aria-label={label}
       aria-expanded={focused}
@@ -1002,7 +1045,7 @@ function CommentComposer({
   // tight inside the 300px card.
   const selectorChip = useMemo(() => {
     const s = state.selection.selector || '';
-    if (!s) return state.selection.tag || 'canvas';
+    if (!s) return state.selection.tag || (state.selection.annotationId ? 'annotation' : 'canvas');
     // [data-cd-id="…"] → cd:<id> · keeps the chip readable when stable ids
     // are present.
     const cd = s.match(/data-cd-id="([^"]+)"/);

package/apps/studio/context.ts

@@ -274,6 +274,7 @@ export interface Context {
           | { op: 'dir.move'; from: string; to: string }
       ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean }> | null;
       acceptedMode?(): boolean;
+      commentsConfirmedOnHub?(slug: string): boolean;
       acceptedHistory?(q: {
         limit?: number;
         before?: number | null;