@1agh/maude 1.4.5 → 1.5.0

package/apps/studio/sync/migrate-seed.ts

@@ -34,10 +34,12 @@ import path from 'node:path';
 
 import type * as Y from 'yjs';
 
+import { readReplica } from '../annotations/replica.ts';
 import { Y_TYPES } from '../collab/persistence.ts';
 import { atomicWrite } from './atomic-write.ts';
 import {
   annotationsEditAtFromDoc,
+  annotationsFromDoc,
   applyAnnotationsToDoc,
   applyCommentsToDoc,
   applyCssToDoc,
@@ -45,6 +47,7 @@ import {
   applyMetaToDoc,
   bodyEditAtFromDoc,
   isEmptyAnnotationsSvg,
+  readLocalAnnotations,
   stampAnnotationsEdit,
   stampBodyEdit,
   Y_SYNC_TYPES,
@@ -58,6 +61,7 @@ import {
   unionCommentsById,
 } from './cold-start.ts';
 import { applyColdStart, type ColdStartSnapshotReason } from './cold-start-apply.ts';
+import { type CommentLedger, withoutRemotelyDeleted } from './comment-ledger.ts';
 import { hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import { ORIGINS } from './origins.ts';
@@ -85,6 +89,8 @@ export interface MigrateSeedOptions {
   historyDir?: string;
   /** DDR-102 — per-machine journal; gates fast-forward vs conflict. */
   journal?: SyncJournal;
+  /** Issue #133 — comment ids synced from here before (sync/comment-ledger.ts). */
+  commentLedger?: CommentLedger;
   /** DDR-102 — body snapshot writer (history.ts), same contract as the agent's. */
   snapshot?: (content: string, reason: ColdStartSnapshotReason) => Promise<string | null>;
   /**
@@ -152,8 +158,9 @@ export function docIsEmpty(doc: Y.Doc): boolean {
   if (doc.getText(Y_SYNC_TYPES.css).length > 0) return false;
   if (doc.getText(Y_SYNC_TYPES.meta).length > 0) return false;
   if (doc.getArray(Y_TYPES.comments).length > 0) return false;
-  const svg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
-  if (typeof svg === 'string' && svg.length > 0) return false;
+  // DDR-242 — the annotations replica (or a legacy v1 value read through the
+  // migration): content means at least one element.
+  if ((readReplica(doc)?.elements.length ?? 0) > 0) return false;
   return true;
 }
 
@@ -171,7 +178,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   const localHtml =
     diskHtml !== null && sourceError(paths.html, diskHtml) === null ? diskHtml : null;
   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 readCss = paths.css ? readLocal(paths.css) : null;
   const localCss = readCss === null ? null : (collapseRepeatedText(readCss)?.unit ?? readCss);
@@ -352,8 +359,7 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   // right after this seed ran. Resolve the lane here, before the room
   // materializes: unstamped emptiness never beats content.
   {
-    const docSvg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
-    const docAnnotations = typeof docSvg === 'string' ? docSvg : '';
+    const docAnnotations = annotationsFromDoc(doc) ?? '';
     const annDecision = decideAnnotationsColdStart({
       local: localAnnotations,
       doc: docAnnotations,
@@ -414,9 +420,13 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
   // delete-then-insert codec — same-id entries keep the doc's version, so the
   // duplication trap stays closed; local-only comments survive.
   if (localComments) {
-    const parsed = tryParseJsonArray(localComments);
+    const docList = doc.getArray(Y_TYPES.comments).toArray();
+    const read = tryParseJsonArray(localComments);
+    // Issue #133 — never union back a comment a peer deleted while we were away.
+    const parsed = read
+      ? withoutRemotelyDeleted(read, docList, opts.commentLedger?.get(slug))
+      : null;
     if (parsed && parsed.length > 0) {
-      const docList = doc.getArray(Y_TYPES.comments).toArray();
       const merged = unionCommentsById(docList, parsed);
       if (merged.length !== docList.length) {
         doc.transact(() => {

package/apps/studio/sync/projection.ts

@@ -37,10 +37,12 @@ import {
   applyMetaToDoc,
   cssFromDoc,
   htmlFromDoc,
+  importAnnotationsFromDisk,
   laneValueFromFile,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
   movedToFromDoc,
+  noteAnnotationsOnDisk,
   readLaneFromDoc,
   stampAnnotationsEdit,
   stampBodyEdit,
@@ -84,7 +86,7 @@ export interface ProjectionPaths {
   html: string;
   /** Absolute path to `_comments/<slug>.json`. */
   comments: string;
-  /** Absolute path to `<slug>.annotations.svg`. */
+  /** Absolute path to `<slug>.annotations.json` (DDR-242). */
   annotations: string;
   /** Absolute path to the canvas `.meta.json` sibling (optional). */
   meta?: string;
@@ -449,6 +451,9 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
    * fire must never cost the write that already succeeded.
    */
   function writeAndAnnounce(path: string, value: string): void {
+    // The board disk holds from here on — the base a later file event is
+    // imported against (codec importAnnotationsFromDisk).
+    if (path === paths.annotations) noteAnnotationsOnDisk(doc, value);
     if (readLocal(path) === value) return;
     writer(path, value);
     try {
@@ -1159,7 +1164,7 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
       // survives cold start on other peers (the 2026-08-14 eraser fix).
       let changed = false;
       doc.transact(() => {
-        changed = applyAnnotationsToDoc(doc, str, importOrigin);
+        changed = importAnnotationsFromDisk(doc, str, importOrigin);
         if (changed) stampAnnotationsEdit(doc, importOrigin);
       }, importOrigin);
       return changed;

package/apps/studio/sync/remote-docs.ts

@@ -391,3 +391,37 @@ export function resolvePulledTarget(args: {
   }
   return { bodyAbs, fromPath };
 }
+
+/**
+ * The listing as an accepted-revisions project states it.
+ *
+ * In accepted mode the MANIFEST names the live canvases: an open Yjs room is
+ * not necessarily an accepted canvas (its author can connect before
+ * `doc.create` commits), so the documents come from the manifest, with the
+ * transport listing's byte counts where it has them.
+ *
+ * The same holds for DELETIONS. The transport's tombstones outlive the legacy
+ * era: a canvas deleted then and later re-created under the same name through
+ * `doc.create` stays tombstoned in the document store while the manifest lists
+ * it live — and every peer that honoured the tombstone skipped a live canvas
+ * (the web showed it, the desktop never pulled it). A tombstone for a name the
+ * manifest lists live is stale and dropped; one for a name the manifest
+ * retired, or does not carry, still stands. A peer's OWN just-made deletion is
+ * not affected: it is remembered locally and never passes through here.
+ */
+export function acceptedListing(
+  listing: RemoteListing | null,
+  manifestDocs: readonly { doc: string; retired: boolean }[]
+): RemoteListing {
+  const bytesByName = new Map((listing?.documents ?? []).map((d) => [d.name, d.bytes]));
+  const documents = manifestDocs
+    .filter((d) => !d.retired)
+    .map((d) => ({ name: d.doc, bytes: bytesByName.get(d.doc) ?? 1 }));
+  const live = new Set(
+    manifestDocs.filter((d) => !d.retired).map((d) => slugFromDocName(d.doc) ?? d.doc)
+  );
+  const tombstones = (listing?.tombstones ?? []).filter(
+    (t) => !live.has(slugFromDocName(t.name) ?? t.name)
+  );
+  return { documents, tombstones };
+}

package/apps/studio/sync/writer-registry.ts

@@ -79,6 +79,15 @@ export const WRITER_REGISTRY: Record<string, WriterEntry> = {
     via: 'onAnnotationsChanged hook → annotations lane.replace with the base the layer sent',
     test: 'test/sync-accepted-projection.test.ts',
   },
+  // DDR-242 §4 — the canvas's op batches. Same lane, same hook: the api applies
+  // the ops to the board, then fires onAnnotationsChanged with the pre-batch
+  // board as base (the kernel's `annotations.apply` replaces this in Task 12).
+  '/_api/annotations/ops': {
+    class: 'lane',
+    rows: 'S23',
+    via: 'onAnnotationsChanged hook → annotations lane.replace with the pre-batch board as base',
+    test: 'test/sync-accepted-projection.test.ts',
+  },
   // --- accepted history (T27/T28)
   '/_api/project/history': { class: 'read' },
   '/_api/project/restore': {
@@ -230,6 +239,7 @@ export const WRITER_REGISTRY: Record<string, WriterEntry> = {
   '/_api/sync/settings': { class: 'local' },
   '/_api/sync/trash': { class: 'local', rows: 'X15 (restore re-enters through cold start)' },
   '/_api/timeline-media': { class: 'local' },
+  '/_api/tree-state': { class: 'local' },
   '/_api/ui-prefs': { class: 'local' },
   '/_api/workspace/disclosure': { class: 'local' },
   '/_api/workspace/sign-in': { class: 'local' },

package/apps/studio/text-caret.ts

@@ -146,7 +146,7 @@ interface CaretRect {
  * should hide (no collapsed selection inside the editable / editable not
  * focused / a range selection is active, where the native highlight is the
  * affordance). */
-function caretRectFor(editable: HTMLElement, win: Window): CaretRect | null {
+function caretRectFor(editable: HTMLElement, win: Window): CaretRect | 'native' | null {
   const doc = editable.ownerDocument;
   const active = doc.activeElement;
   if (active !== editable && !editable.contains(active)) return null;
@@ -165,6 +165,13 @@ function caretRectFor(editable: HTMLElement, win: Window): CaretRect | null {
     if (br && br.height > 0) r = br;
   }
   if (r && r.height > 0) return { x: r.left, y: r.top, h: r.height };
+  // A caret on a line with no text box yet — Shift+Enter's "\n" puts it at
+  // the start of an empty last line — has no client rect in Chromium or
+  // WebKit. Guessing a position from the editable's box painted it back at
+  // the top-left of line ONE (the "Shift+Enter throws the cursor somewhere
+  // weird" report). Only the engine knows where that caret is, so hand the
+  // caret back to it: the native caret shows until a rect exists again.
+  if ((editable.textContent ?? '').replace(/\u200b/g, '') !== '') return 'native';
   // Empty editable — no rect exists anywhere. Derive a caret box from the
   // editable's padding box + line metrics. (The annotation editors avoid this
   // path by mounting with a zero-width-space JUMP_SENTINEL, but the artboard
@@ -221,7 +228,9 @@ export function mountCaret(editable: HTMLElement, win: Window): () => void {
 
   const position = (): void => {
     const rc = caretRectFor(editable, win);
-    if (!rc) {
+    // The engine's own caret, while ours can't be placed (see caretRectFor).
+    editable.style.caretColor = rc === 'native' ? prevCaretColor || 'auto' : 'transparent';
+    if (!rc || rc === 'native') {
       if (shown) {
         caret.style.display = 'none';
         shown = false;

package/apps/studio/tree-state.ts

@@ -0,0 +1,45 @@
+// tree-state.ts — the Files panel's remembered disclosure (issue #124).
+//
+// `dirs` are the repo-relative folder paths the user left expanded (the same
+// `dirPath` the tree rows carry); `sections` maps a section label (PROJECT /
+// UI CANVASES / …) to open/closed. Anything absent is CLOSED — that default is
+// the point of the issue. Stored per project + per member by api.ts under
+// `_canvas-state/`; this module only owns the shape and its bounds, so a
+// hostile or corrupt body can neither grow the file without limit nor smuggle
+// a non-string into a path the client later splits.
+
+export interface TreeState {
+  dirs: string[];
+  sections: Record<string, boolean>;
+}
+
+export const TREE_STATE_MAX_DIRS = 2000;
+export const TREE_STATE_MAX_PATH = 1024;
+export const TREE_STATE_MAX_SECTIONS = 64;
+const MAX_LABEL = 128;
+
+/** Coerce anything into a bounded, de-duplicated TreeState. Never throws. */
+export function normalizeTreeState(raw: unknown): TreeState {
+  const o =
+    raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+  const dirs = new Set<string>();
+  if (Array.isArray(o.dirs)) {
+    for (const d of o.dirs) {
+      if (dirs.size >= TREE_STATE_MAX_DIRS) break;
+      if (typeof d !== 'string' || !d || d.length > TREE_STATE_MAX_PATH || d.includes('\0'))
+        continue;
+      dirs.add(d);
+    }
+  }
+  const sections: Record<string, boolean> = {};
+  if (o.sections && typeof o.sections === 'object' && !Array.isArray(o.sections)) {
+    let n = 0;
+    for (const [k, v] of Object.entries(o.sections as Record<string, unknown>)) {
+      if (n >= TREE_STATE_MAX_SECTIONS) break;
+      if (typeof v !== 'boolean' || !k || k.length > MAX_LABEL || k === '__proto__') continue;
+      sections[k] = v;
+      n++;
+    }
+  }
+  return { dirs: [...dirs].sort(), sections };
+}

package/apps/studio/undo-stack.ts

@@ -69,8 +69,8 @@ export interface CommandRecord<P = unknown> {
 export interface CommandSinks {
   /** Wired by canvas-lib `DesignCanvasInner`. */
   layoutPatchFn?: unknown;
-  /** Wired by `AnnotationsLayer`. */
-  strokesPutFn?: unknown;
+  /** Wired by `AnnotationsLayer` (DDR-242): apply + send an annotation op batch. */
+  annotationOpsFn?: unknown;
   /**
    * Wired by `CanvasShell` (canvas-shell.tsx). Applies a single inline source
    * edit (CSS / text / attr) by posting `dgn:'apply-edit'` to the parent shell,

package/apps/studio/use-annotation-resize.tsx

@@ -18,10 +18,13 @@
  */
 
 import { type ReactNode, useCallback, useEffect, useMemo, useRef } from 'react';
+import { defOf } from './annotations/registry.ts';
+import { useAnnotationPipeline } from './annotations/ui/pipeline-context.ts';
 import { anchorPoint, BIND_THRESHOLD_PX, bindCandidate } from './annotations-bindings.ts';
 import {
   type ArrowStroke,
   canRotate,
+  type ElementStroke,
   type EllipseStroke,
   HALO_PAD_PX,
   type ImageStroke,
@@ -141,6 +144,7 @@ export const padDY = (c: Corner): number =>
 function isResizable(
   s: Stroke
 ): s is
+  | ElementStroke
   | RectStroke
   | EllipseStroke
   | PolygonStroke
@@ -150,6 +154,10 @@ function isResizable(
   | ImageStroke
   | LinkStroke
   | SectionStroke {
+  if (s.tool === 'element') {
+    const caps = defOf(s.el.type)?.caps;
+    return !!caps?.box && caps.resizable;
+  }
   return (
     s.tool === 'rect' ||
     s.tool === 'ellipse' ||
@@ -386,6 +394,15 @@ export function resizeStroke(
     const box = bboxResizeRotAware(start, b0, corner, wx, wy, mods, start.tool === 'sticky');
     return box as Partial<RectStroke | StickyStroke | PolygonStroke | LinkStroke>;
   }
+  if (start.tool === 'element') {
+    // A registry type: fit its box, the fields come from its definition.
+    const def = defOf(start.el.type);
+    const b0 = strokeBBox(start);
+    if (!def || !b0) return null;
+    const box = bboxResize(b0, corner, wx, wy, mods, !!def.caps.aspectLock);
+    const ctx = { origin: { x: 0, y: 0 }, resolve: () => null };
+    return { el: { ...start.el, ...def.resize(start.el, box, ctx) } } as Partial<Stroke>;
+  }
   if (start.tool === 'image') {
     // Phase 23 — images aspect-LOCK by default and free-resize with Shift held
     // (the inverse of the shape tools — Figma/FigJam image behaviour). Invert
@@ -560,6 +577,7 @@ export function AnnotationResizeOverlay({ store }: { store: StrokesStoreValue |
   const annotSel = useAnnotationSelection();
   const controller = useViewportControllerContext();
   const vp = controller?.viewport ?? null;
+  const pipeline = useAnnotationPipeline();
   const containerRef = useRef<HTMLDivElement | null>(null);
   const rafRef = useRef<number | null>(null);
   const dragRef = useRef<{
@@ -725,6 +743,17 @@ export function AnnotationResizeOverlay({ store }: { store: StrokesStoreValue |
       } catch {
         /* some browsers reject capture on synthetic events */
       }
+      // The layer's pointer pipeline owns the moves and the release (Task 21);
+      // mounted without a layer (tests), the overlay listens itself.
+      if (pipeline) {
+        const pointerId = e.pointerId;
+        pipeline.begin(pointerId, {
+          kind: isRotCorner(corner) ? 'rotating' : 'resizing',
+          move: onMove,
+          up: onUp,
+          cancel: (ev) => onUp(ev ?? ({ pointerId } as PointerEvent)),
+        });
+      }
     };
     const applyResize = (
       clientX: number,
@@ -810,19 +839,15 @@ export function AnnotationResizeOverlay({ store }: { store: StrokesStoreValue |
             matchIds.push(bestH.id);
           }
         }
-        document.dispatchEvent(
-          new CustomEvent('maude:resize-info', {
-            detail: {
-              box: { x: patch.x, y: patch.y, w: patch.w, h: patch.h },
-              matchIds,
-            },
-          })
-        );
+        store.setResizeInfo?.({
+          box: { x: patch.x, y: patch.y, w: patch.w, h: patch.h },
+          matchIds,
+        });
       }
       // FigJam v3 — dragging an arrow ENDPOINT re-anchors its bind: within the
       // magnet threshold of a bindable host the endpoint snaps + binds; free
       // space (or ⌘ held — Figma "suppress snap") clears the bind. The layer
-      // paints the candidate halo via the maude:bind-hint broadcast.
+      // paints the candidate halo (store.setBindHint).
       if (d.startStroke.tool === 'arrow' && (d.corner === 'ep1' || d.corner === 'ep2')) {
         const zoom = vp?.zoom || 1;
         const cand = suppressBind
@@ -852,9 +877,7 @@ export function AnnotationResizeOverlay({ store }: { store: StrokesStoreValue |
             [d.corner === 'ep1' ? 'startBind' : 'endBind']: undefined,
           } as Partial<Stroke>;
         }
-        document.dispatchEvent(
-          new CustomEvent('maude:bind-hint', { detail: { hostId: cand?.hostId ?? null } })
-        );
+        store.setBindHint?.(cand?.hostId ?? null);
       }
       // Wave H — transient preview tick: no undo record, no PUT. The gesture
       // commits ONCE on pointerup (undo used to walk every resize pixel).
@@ -898,26 +921,28 @@ export function AnnotationResizeOverlay({ store }: { store: StrokesStoreValue |
       );
       // Clear the bind-hint halo + size label regardless of what was dragged
       // (no-ops when nothing was hinted).
-      document.dispatchEvent(new CustomEvent('maude:bind-hint', { detail: { hostId: null } }));
-      document.dispatchEvent(
-        new CustomEvent('maude:resize-info', { detail: { box: null, matchIds: [] } })
-      );
+      store?.setBindHint?.(null);
+      store?.setResizeInfo?.(null);
     };
     c.addEventListener('pointerdown', onDown);
-    document.addEventListener('pointermove', onMove);
-    document.addEventListener('pointerup', onUp);
-    document.addEventListener('pointercancel', onUp);
+    if (!pipeline) {
+      document.addEventListener('pointermove', onMove);
+      document.addEventListener('pointerup', onUp);
+      document.addEventListener('pointercancel', onUp);
+    }
     document.addEventListener('keydown', onKey, true);
     document.addEventListener('keyup', onKey, true);
     return () => {
       c.removeEventListener('pointerdown', onDown);
-      document.removeEventListener('pointermove', onMove);
-      document.removeEventListener('pointerup', onUp);
-      document.removeEventListener('pointercancel', onUp);
+      if (!pipeline) {
+        document.removeEventListener('pointermove', onMove);
+        document.removeEventListener('pointerup', onUp);
+        document.removeEventListener('pointercancel', onUp);
+      }
       document.removeEventListener('keydown', onKey, true);
       document.removeEventListener('keyup', onKey, true);
     };
-  }, [selectedStroke, store, screenToWorld, vp]);
+  }, [selectedStroke, store, screenToWorld, vp, pipeline]);
 
   // Only render when there's exactly one resizable stroke selected. Multi
   // resize is undefined for v1 (no canonical UX); text inherits anchor bbox.

package/apps/studio/use-annotation-selection.tsx

@@ -24,6 +24,8 @@ export interface AnnotationSelectionValue {
   selectedIds: string[];
   replace: (id: string | string[]) => void;
   add: (id: string | string[]) => void;
+  /** Drop ids from the selection (shift-click on a selected element). */
+  remove: (id: string | string[]) => void;
   toggle: (id: string) => void;
   clear: () => void;
   contains: (id: string) => boolean;
@@ -55,6 +57,11 @@ export function AnnotationSelectionProvider({ children }: { children: ReactNode
     setSelectedIds((prev) => dedupe([...prev, ...incoming]));
   }, []);
 
+  const remove = useCallback((id: string | string[]) => {
+    const drop = new Set(Array.isArray(id) ? id : [id]);
+    setSelectedIds((prev) => prev.filter((x) => !drop.has(x)));
+  }, []);
+
   const toggle = useCallback((id: string) => {
     setSelectedIds((prev) => (prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id]));
   }, []);
@@ -76,8 +83,8 @@ export function AnnotationSelectionProvider({ children }: { children: ReactNode
   const contains = useCallback((id: string) => containsRef.current.includes(id), []);
 
   const value = useMemo<AnnotationSelectionValue>(
-    () => ({ selectedIds, replace, add, toggle, clear, contains }),
-    [selectedIds, replace, add, toggle, clear, contains]
+    () => ({ selectedIds, replace, add, remove, toggle, clear, contains }),
+    [selectedIds, replace, add, remove, toggle, clear, contains]
   );
 
   return (

package/apps/studio/use-collab.tsx

@@ -106,6 +106,12 @@ export interface CollabAwarenessState {
    * annotation-shaped is selected.
    */
   annotationSelection: string[];
+  /**
+   * DDR-242 AD5 / Task 22 — an annotation gesture in flight (drag, resize,
+   * draw), so peers see it move live. It never touches storage: the op
+   * commits once at gesture end, and this goes back to null.
+   */
+  annotationGesture?: AnnotationGesture | null;
   viewport: { x: number; y: number; zoom: number };
   /**
    * Soft editing-presence (Phase 30). Set while THIS peer (a human editing via
@@ -130,6 +136,20 @@ export interface CollabAwarenessState {
 
 export type ForeignAwareness = Omit<CollabAwarenessState, '__connId'> & { clientID: number };
 
+/** A live annotation gesture, in WORLD coordinates. */
+export interface AnnotationGesture {
+  kind: 'move' | 'resize' | 'draw';
+  /** Elements the gesture moves / resizes (empty while drawing a new one). */
+  ids: string[];
+  /** move: the drag offset. */
+  dx?: number;
+  dy?: number;
+  /** resize: the box being dragged out; draw: a shape / sticky / section being drawn. */
+  box?: { x: number; y: number; w: number; h: number };
+  /** draw: pen ink so far, flat [x0,y0,x1,y1,…] (the latest part, capped). */
+  points?: number[];
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Untrusted-input sanitization at the awareness trust boundary.
 //
@@ -214,6 +234,58 @@ function sanitizeCursor(raw: unknown): { x: number; y: number } | null {
   return isFiniteNum(c.x) && isFiniteNum(c.y) ? { x: c.x, y: c.y } : null;
 }
 
+const GESTURE_KINDS = new Set(['move', 'resize', 'draw']);
+const MAX_GESTURE_POINTS = 512; // numbers, i.e. 256 points
+const GESTURE_COORD_LIMIT = 1e6;
+
+function gestureNum(v: unknown): number | undefined {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return undefined;
+  return Math.max(-GESTURE_COORD_LIMIT, Math.min(GESTURE_COORD_LIMIT, v));
+}
+
+/**
+ * Task 22 — a peer's gesture preview is untrusted like every other awareness
+ * field: kind allowlisted, ids through the same token + count gate as the
+ * selection, every number finite and clamped, pen points capped.
+ */
+export function sanitizeAnnotationGesture(raw: unknown): AnnotationGesture | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const g = raw as Record<string, unknown>;
+  if (typeof g.kind !== 'string' || !GESTURE_KINDS.has(g.kind)) return null;
+  const out: AnnotationGesture = {
+    kind: g.kind as AnnotationGesture['kind'],
+    ids: sanitizeAnnotationSelection(g.ids),
+  };
+  const dx = gestureNum(g.dx);
+  const dy = gestureNum(g.dy);
+  if (dx !== undefined && dy !== undefined) {
+    out.dx = dx;
+    out.dy = dy;
+  }
+  const b = g.box as Record<string, unknown> | undefined;
+  if (b && typeof b === 'object') {
+    const x = gestureNum(b.x);
+    const y = gestureNum(b.y);
+    const w = gestureNum(b.w);
+    const h = gestureNum(b.h);
+    if (x !== undefined && y !== undefined && w !== undefined && h !== undefined) {
+      out.box = { x, y, w: Math.abs(w), h: Math.abs(h) };
+    }
+  }
+  if (Array.isArray(g.points)) {
+    const pts: number[] = [];
+    const src = g.points.slice(-MAX_GESTURE_POINTS);
+    for (const v of src) {
+      const n = gestureNum(v);
+      if (n === undefined) break;
+      pts.push(n);
+    }
+    if (pts.length % 2 === 1) pts.pop();
+    if (pts.length) out.points = pts;
+  }
+  return out;
+}
+
 function sanitizeViewport(raw: unknown): { x: number; y: number; zoom: number } {
   const fallback = { x: 0, y: 0, zoom: 1 };
   if (!raw || typeof raw !== 'object') return fallback;
@@ -284,6 +356,7 @@ export function sanitizeForeignState(clientID: number, state: unknown): ForeignA
     cursor: sanitizeCursor(s.cursor),
     selection: sanitizeSelection(s.selection),
     annotationSelection: sanitizeAnnotationSelection(s.annotationSelection),
+    annotationGesture: sanitizeAnnotationGesture(s.annotationGesture),
     viewport: sanitizeViewport(s.viewport),
     editing: sanitizeEditingState(s.editing),
   };
@@ -323,6 +396,27 @@ export function useCollab(): CollabValue | null {
 // ─────────────────────────────────────────────────────────────────────────────
 // Hook: foreign awareness peers (the cursor overlay subscribes to this).
 
+export interface AwarenessChanges {
+  added: number[];
+  updated: number[];
+  removed: number[];
+}
+
+/**
+ * Could this awareness `change` alter the foreign peers we show? False only
+ * when every touched client is the local one (our own cursor publish — #131).
+ * Unknown shape → true, the safe direction.
+ */
+export function touchesForeignClient(changes: AwarenessChanges | undefined, myId: number): boolean {
+  if (!changes) return true;
+  const touched = [
+    ...(changes.added ?? []),
+    ...(changes.updated ?? []),
+    ...(changes.removed ?? []),
+  ];
+  return touched.length === 0 || touched.some((id) => id !== myId);
+}
+
 /**
  * Returns the current set of foreign peers (excludes the local client). The
  * returned array is stable-reference between awareness updates — useful for
@@ -351,7 +445,13 @@ export function useForeignAwareness(): ForeignAwareness[] {
       return out;
     }
     setPeers(compute());
-    const onChange = () => setPeers(compute());
+    // Issue #131 — `change` fires for OUR OWN publishes too (the 30 Hz cursor),
+    // and each one rebuilt every peer object and re-rendered every consumer.
+    // Only a change that touches another client can change what we show.
+    const onChange = (changes?: AwarenessChanges) => {
+      if (!touchesForeignClient(changes, awareness.clientID)) return;
+      setPeers(compute());
+    };
     awareness.on('change', onChange);
     return () => {
       awareness.off('change', onChange);
@@ -559,6 +659,7 @@ function createSession(slug: string): CollabSession {
       cursor: cur.cursor ?? null,
       selection: cur.selection ?? null,
       annotationSelection: cur.annotationSelection ?? [],
+      annotationGesture: null,
       viewport: cur.viewport ?? { x: 0, y: 0, zoom: 1 },
       editing: cur.editing ?? null,
       __connId: connId,
@@ -867,6 +968,8 @@ export function CollabProvider({ slug, children }: CollabProviderProps): JSX.Ele
           cursor: current.cursor ?? null,
           selection: current.selection ?? null,
           annotationSelection: current.annotationSelection ?? [],
+          // Kept across other fields' publishes (a cursor move mid-drag).
+          annotationGesture: current.annotationGesture ?? null,
           viewport: current.viewport ?? { x: 0, y: 0, zoom: 1 },
           editing: current.editing ?? null,
           __connId: myConnId,

package/apps/studio/use-selection-set.tsx

@@ -67,6 +67,10 @@ export interface Selection {
   worldW?: number;
   worldH?: number;
   html?: string;
+  /** Comment drops only — the annotation the click landed on, and the click's
+   *  world point (comment-anchor.ts). */
+  annotationId?: string;
+  world?: { x: number; y: number };
   /** Phase 12.2 — authored inline-style values (knob pre-fill) + resolved computed (placeholder hint). */
   authored?: Record<string, string>;
   computed?: Record<string, string>;