@1agh/maude 0.19.0 → 0.20.0

package/plugins/design/dev-server/annotations-layer.tsx

@@ -35,10 +35,14 @@ import { createPortal } from 'react-dom';
 
 import { AnnotationContextToolbar } from './annotations-context-toolbar.tsx';
 import { useViewportControllerContext, useWorldRefContext } from './canvas-lib.tsx';
+import { buildAnnotationStrokesRecord } from './commands/annotation-strokes-command.ts';
+import { crossedDragThreshold } from './input-router.tsx';
+import { AnnotationResizeOverlay } from './use-annotation-resize.tsx';
 import { useAnnotationSelectionOptional } from './use-annotation-selection.tsx';
 import { useAnnotationsVisibility } from './use-annotations-visibility.tsx';
 import { useSelectionSetOptional } from './use-selection-set.tsx';
 import { useToolMode } from './use-tool-mode.tsx';
+import { useUndoSinks, useUndoStackOptional } from './use-undo-stack.tsx';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -114,7 +118,7 @@ const FILL_PALETTE = [
   '#f4f1ee', // paper
 ] as const;
 
-const STROKE_WIDTH_THIN = 2;
+const STROKE_WIDTH_THIN = 3;
 const STROKE_WIDTH_THICK = 6;
 type Thickness = typeof STROKE_WIDTH_THIN | typeof STROKE_WIDTH_THICK;
 
@@ -457,15 +461,15 @@ const ANNOT_CSS = `
   display: flex;
   align-items: center;
   gap: 8px;
-  background: var(--u-bg-2, var(--bg-1, rgba(255,255,255,0.98)));
+  background: var(--u-bg-0, var(--bg-0, rgba(255,255,255,0.98)));
   border: 1px solid var(--u-fg-0, #1c1917);
-  border-radius: 0;
+  border-radius: 8px;
   padding: 6px 10px;
   font-family: var(--u-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
   color: var(--u-fg-0, rgba(40,30,20,0.85));
   z-index: 6;
-  box-shadow: 4px 4px 0 var(--u-fg-0, #1c1917);
+  box-shadow: 0 6px 24px color-mix(in oklab, var(--u-fg-0, #1c1917) 10%, transparent);
   user-select: none;
 }
 .dc-annot-chrome .dc-annot-swatches { display: flex; gap: 4px; }
@@ -608,6 +612,23 @@ function translateOne(s: Stroke, dx: number, dy: number): Stroke {
   return s; // text inherits its host's bbox
 }
 
+/**
+ * Reference-equal stroke comparison — true when the two arrays carry the same
+ * stroke object references in the same order. Used by the annotation drag
+ * onPointerUp to skip pushing an undo record when the gesture didn't actually
+ * move anything (zero movement OR snapshot mapped through a no-op translate
+ * back to the original references — `translateOne` short-circuits when dx=dy=0
+ * because new objects are still created, so we compare references defensively).
+ */
+export function strokesShallowEqual(a: readonly Stroke[], b: readonly Stroke[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
 // Annotations visibility now lives in use-annotations-visibility.tsx so the
 // ToolPalette (a sibling under CanvasRouter, not a descendant of this layer)
 // can read the same state. Re-exported here for back-compat.
@@ -618,7 +639,7 @@ export { useAnnotationsVisibility } from './use-annotations-visibility.tsx';
 
 export function AnnotationsLayer() {
   ensureAnnotStyles();
-  const { tool } = useToolMode();
+  const { tool, setTool, sticky } = useToolMode();
   const controller = useViewportControllerContext();
   const vp = controller?.viewport ?? null;
   const worldRef = useWorldRefContext();
@@ -649,11 +670,22 @@ export function AnnotationsLayer() {
   const saveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const drawingRef = useRef<Stroke | null>(null);
   drawingRef.current = drawing;
+  /**
+   * Phase 20 — latest strokes mirror so command builders can read the
+   * pre-mutation snapshot synchronously (React state isn't refreshed
+   * between rapid taps in the same tick).
+   */
+  const strokesRef = useRef<Stroke[]>(strokes);
+  strokesRef.current = strokes;
 
   const isDraw = tool === 'pen' || tool === 'rect' || tool === 'arrow' || tool === 'ellipse';
   const isErase = tool === 'eraser';
   const isActive = isDraw || isErase;
-  const supportsThickness = tool === 'pen' || tool === 'arrow';
+  // T20 — rect + ellipse expose stroke weight too (FigJam ships thickness on
+  // every shape). The annotation toolbar reads supportsThickness to decide
+  // whether to render the Thin / Thick chips.
+  const supportsThickness =
+    tool === 'pen' || tool === 'arrow' || tool === 'rect' || tool === 'ellipse';
   const supportsFill = tool === 'rect' || tool === 'ellipse';
 
   // Load existing annotations on mount.
@@ -679,56 +711,100 @@ export function AnnotationsLayer() {
     };
   }, []);
 
-  const scheduleSave = useCallback((next: readonly Stroke[]) => {
+  const undoStack = useUndoStackOptional();
+  const undoSinks = useUndoSinks();
+  const undoStackRef = useRef(undoStack);
+  undoStackRef.current = undoStack;
+
+  /**
+   * Apply a `Stroke[]` snapshot: update local React state AND fire-and-forget
+   * PUT to the server. Used as the `putFn` injected into the
+   * `AnnotationStrokesCommand` — both the initial push AND every undo/redo
+   * replay route through here, so the iframe's `strokes` state always
+   * tracks the server. (Without the setStrokesState here, Cmd+Z would
+   * silently PUT the prior SVG but the canvas would keep painting the
+   * post-edit strokes until the user reloaded.)
+   *
+   * The 200 ms scheduled-save debounce (legacy path) is cleared the moment
+   * we push a command, so the server only sees one PUT per edit instead
+   * of two-step racing.
+   */
+  const putStrokes = useCallback((next: readonly Stroke[]) => {
+    setStrokesState(next as Stroke[]);
     const file = fileRef.current;
-    if (!file) return;
-    if (saveTimerRef.current) clearTimeout(saveTimerRef.current);
-    saveTimerRef.current = setTimeout(() => {
-      saveTimerRef.current = null;
-      const svg = strokesToSvg(next);
-      void fetch('/_api/annotations', {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ file, svg }),
-      }).catch(() => {
-        /* swallow — the user will see uncommitted state until the next stroke */
+    if (!file) return Promise.resolve();
+    const svg = strokesToSvg(next);
+    return fetch('/_api/annotations', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ file, svg }),
+    })
+      .then(() => undefined)
+      .catch(() => {
+        /* swallow — user sees uncommitted state until the next stroke */
       });
-    }, 200);
   }, []);
 
+  // Register the strokes put sink with the undo provider so the rebuilt
+  // AnnotationStrokesCommand (after a canvas switch + return) routes through
+  // THIS iframe's React state, not the gone iframe's stale closures.
+  useEffect(() => {
+    undoSinks.setSink('strokesPutFn', putStrokes);
+    return () => undoSinks.setSink('strokesPutFn', undefined);
+  }, [undoSinks, putStrokes]);
+
+  /**
+   * Single entry point for every stroke mutation. Builds an undo record
+   * and pushes onto the stack — `push()` rebuilds the command via the
+   * registered `strokesPutFn` sink and calls `cmd.do() = putStrokes(next)`,
+   * which both updates local state and PUTs. Cancels any pending debounced
+   * save first — DDR-050 gotcha: a queued auto-save flushing AFTER our PUT
+   * would race the stack into a stale state.
+   */
+  const commitStrokes = useCallback(
+    (prev: readonly Stroke[], next: readonly Stroke[], label?: string) => {
+      if (saveTimerRef.current) {
+        clearTimeout(saveTimerRef.current);
+        saveTimerRef.current = null;
+      }
+      const record = buildAnnotationStrokesRecord({
+        before: prev,
+        after: next,
+        ...(label ? { label } : {}),
+      });
+      void undoStackRef.current.push(record);
+    },
+    []
+  );
+
   const setStrokes = useCallback(
     (next: Stroke[]) => {
-      setStrokesState(next);
-      scheduleSave(next);
+      const prev = strokesRef.current;
+      commitStrokes(prev, next);
     },
-    [scheduleSave]
+    [commitStrokes]
   );
 
   const strokesStore = useMemo<StrokesStoreValue>(() => {
     const updateStroke = (id: string, patch: Partial<Stroke>): void => {
-      setStrokesState((prev) => {
-        const next = prev.map((s) => (s.id === id ? ({ ...s, ...patch } as Stroke) : s));
-        scheduleSave(next);
-        return next;
-      });
+      const prev = strokesRef.current;
+      const next = prev.map((s) => (s.id === id ? ({ ...s, ...patch } as Stroke) : s));
+      commitStrokes(prev, next);
     };
     const deleteStrokes = (ids: string[]): void => {
       const set = new Set(ids);
-      setStrokesState((prev) => {
-        const next = prev.filter(
-          (s) => !set.has(s.id) && !(s.tool === 'text' && set.has(s.anchorId))
-        );
-        scheduleSave(next);
-        return next;
-      });
+      const prev = strokesRef.current;
+      const next = prev.filter(
+        (s) => !set.has(s.id) && !(s.tool === 'text' && set.has(s.anchorId))
+      );
+      if (next.length === prev.length) return;
+      commitStrokes(prev, next);
     };
     const translateStrokes = (ids: string[], dx: number, dy: number): void => {
       const set = new Set(ids);
-      setStrokesState((prev) => {
-        const next = prev.map((s) => (set.has(s.id) ? translateOne(s, dx, dy) : s));
-        scheduleSave(next);
-        return next;
-      });
+      const prev = strokesRef.current;
+      const next = prev.map((s) => (set.has(s.id) ? translateOne(s, dx, dy) : s));
+      commitStrokes(prev, next, `move ${ids.length} stroke${ids.length === 1 ? '' : 's'}`);
     };
     return {
       strokes,
@@ -737,7 +813,7 @@ export function AnnotationsLayer() {
       deleteStrokes,
       translateStrokes,
     };
-  }, [strokes, setStrokes, scheduleSave]);
+  }, [strokes, setStrokes, commitStrokes]);
 
   // Menubar bridge (Phase 5.1 Task 10) — listen for postMessages from the
   // dev-server shell. `selection-clear` + `tool-set` live in canvas-shell
@@ -789,23 +865,21 @@ export function AnnotationsLayer() {
     (wx: number, wy: number) => {
       const zoom = vp?.zoom || 1;
       const tol = 8 / zoom;
-      setStrokesState((prev) => {
-        for (let i = prev.length - 1; i >= 0; i--) {
-          const candidate = prev[i];
-          if (candidate && strokeHitTest(candidate, wx, wy, tol)) {
-            const removedId = candidate.id;
-            const next = prev
-              .slice(0, i)
-              .concat(prev.slice(i + 1))
-              .filter((s) => !(s.tool === 'text' && s.anchorId === removedId));
-            scheduleSave(next);
-            return next;
-          }
+      const prev = strokesRef.current;
+      for (let i = prev.length - 1; i >= 0; i--) {
+        const candidate = prev[i];
+        if (candidate && strokeHitTest(candidate, wx, wy, tol)) {
+          const removedId = candidate.id;
+          const next = prev
+            .slice(0, i)
+            .concat(prev.slice(i + 1))
+            .filter((s) => !(s.tool === 'text' && s.anchorId === removedId));
+          commitStrokes(prev, next, 'erase 1 stroke');
+          return;
         }
-        return prev;
-      });
+      }
     },
-    [vp, scheduleSave]
+    [vp, commitStrokes]
   );
 
   const beginStroke = useCallback(
@@ -839,7 +913,7 @@ export function AnnotationsLayer() {
           id,
           tool: 'rect',
           color,
-          width: STROKE_WIDTH_THIN,
+          width,
           x: wx,
           y: wy,
           w: 0,
@@ -851,7 +925,7 @@ export function AnnotationsLayer() {
           id,
           tool: 'ellipse',
           color,
-          width: STROKE_WIDTH_THIN,
+          width,
           cx: wx,
           cy: wy,
           rx: 0,
@@ -930,14 +1004,41 @@ export function AnnotationsLayer() {
     if (final && !isStrokeMeaningful(final)) final = null;
     if (final) {
       const committed = final;
-      setStrokesState((prev) => {
-        const next = [...prev, committed];
-        scheduleSave(next);
-        return next;
-      });
+      const prev = strokesRef.current;
+      const next = [...prev, committed];
+      commitStrokes(prev, next, `draw ${committed.tool}`);
+      // T18 — auto-select the freshly drawn shape so the user can immediately
+      // see + adjust it. annotSel is optional (some test harnesses mount
+      // AnnotationsLayer without the provider), so guard the call.
+      if (annotSel) annotSel.replace(committed.id);
+    }
+    // T18 / T19 — flip the tool back to Move after every commit UNLESS sticky
+    // mode is locked on this tool. Sticky lets the user draw many shapes in a
+    // row (canonical pattern: tldraw double-click to lock). Eraser stays
+    // armed by default — that tool is destructive, not constructive.
+    const toolJustUsed = cur.tool;
+    if (toolJustUsed !== 'eraser') {
+      const stickyOnThis = sticky.locked && sticky.tool === toolJustUsed;
+      if (!stickyOnThis) setTool('move');
     }
     setDrawing(null);
-  }, [isActive, isErase, visible, scheduleSave]);
+  }, [isActive, isErase, visible, commitStrokes, annotSel, setTool, sticky]);
+
+  // T21 — abort a mid-stroke draw without committing. Dispatched by the
+  // canvas-shell Esc handler (`maude:cancel-stroke`). Safe to call when
+  // nothing is being drawn — the early-return on drawingRef keeps it
+  // a no-op.
+  const cancelStroke = useCallback(() => {
+    if (!drawingRef.current) return;
+    setDrawing(null);
+  }, []);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const onCancel = () => cancelStroke();
+    document.addEventListener('maude:cancel-stroke', onCancel);
+    return () => document.removeEventListener('maude:cancel-stroke', onCancel);
+  }, [cancelStroke]);
 
   const renderStrokes = useMemo(
     () => (drawing ? [...strokes, drawing] : strokes),
@@ -966,11 +1067,19 @@ export function AnnotationsLayer() {
   //   - Cmd / Cmd+Shift falls through to element-selection (we bail).
   // Once a stroke is selected, clicking inside its bbox starts a drag.
 
+  /**
+   * Annotation drag state. Snapshot of strokes captured at pointerdown so the
+   * whole gesture (pointermove × N → pointerup) commits as ONE undo record at
+   * release time. Without the snapshot, each pointermove tick became its own
+   * `translateStrokes` call and each call became its own undo record — Cmd+Z
+   * had to be pressed dozens of times to walk back a single drag.
+   */
   const dragStateRef = useRef<{
     pointerId: number;
     startWX: number;
     startWY: number;
     movedIds: string[];
+    snapshot: Stroke[];
   } | null>(null);
 
   // Drag-select marquee state. World-coord rectangle (anchor + cursor); the
@@ -982,6 +1091,7 @@ export function AnnotationsLayer() {
     by: number;
   } | null>(null);
 
+  // biome-ignore lint/correctness/useExhaustiveDependencies: commitStrokes/strokesStore are stable refs from parent context; manual dep list reflects effect-trigger semantics, not internal callbacks
   useEffect(() => {
     if (typeof document === 'undefined') return;
     if (tool !== 'move') return;
@@ -1005,7 +1115,7 @@ export function AnnotationsLayer() {
     // the main tool palette, the in-canvas draw chrome, the minimap, and the
     // right-click menu. Clicks on these route to their own handlers.
     const CHROME_SELECTOR =
-      '.dc-annot-ctx, .dc-tool-palette, .dc-annot-chrome, .dc-mm, .dc-context-menu, .dc-tp-popover';
+      '.dc-annot-ctx, .dc-tool-palette, .dc-annot-chrome, .dc-mm, .dc-context-menu, .dc-tp-popover, .dc-multi-artboard-tb, .dc-elem-ctx-tb, .dc-cv-eq-spacing-layer, .cm-composer, .cm-thread, .cm-mention-popup, .cm-pin, .dc-annot-resize-handle';
 
     const onDown = (e: PointerEvent) => {
       if (e.button !== 0) return;
@@ -1013,6 +1123,11 @@ export function AnnotationsLayer() {
       const target = e.target as Element | null;
       if (target?.closest?.(CHROME_SELECTOR)) return; // chrome owns its clicks
       const strokeId = findStrokeId(target);
+      // When pointerdown lands inside an artboard but not on a stroke, the
+      // gesture belongs to artboard-drag / element-marquee — not the
+      // annotation marquee. Bailing here keeps the annotation marquee from
+      // racing the artboard drag (post-Wave-3 user grievance G5).
+      if (!strokeId && target?.closest?.('[data-dc-screen]')) return;
       const [wx, wy] = screenToWorld(e.clientX, e.clientY);
       const startClientX = e.clientX;
       const startClientY = e.clientY;
@@ -1034,29 +1149,51 @@ export function AnnotationsLayer() {
           annotSel.replace(strokeId);
           ids = [strokeId];
         }
+        // Capture a snapshot of all strokes at drag start. Every pointermove
+        // re-translates FROM the snapshot using the cumulative cursor delta
+        // (NOT a delta-from-last-frame mutation), so dragging back to origin
+        // restores positions exactly. Optimistic state-only updates during
+        // the move; ONE undo record + ONE server PUT fires on pointerup.
+        const dragSnapshot = strokesRef.current.slice();
         dragStateRef.current = {
           pointerId: e.pointerId,
           startWX: wx,
           startWY: wy,
           movedIds: ids,
+          snapshot: dragSnapshot,
         };
+        const movedSet = new Set(ids);
         const onMove = (mv: PointerEvent) => {
           const st = dragStateRef.current;
           if (!st || mv.pointerId !== st.pointerId) return;
           const [cwx, cwy] = screenToWorld(mv.clientX, mv.clientY);
           const dx = cwx - st.startWX;
           const dy = cwy - st.startWY;
-          if (dx === 0 && dy === 0) return;
-          strokesStore.translateStrokes(st.movedIds, dx, dy);
-          st.startWX = cwx;
-          st.startWY = cwy;
+          // Drag-back-to-origin: restore exact references so the pointerup
+          // shallow-equality check skips committing a no-op record.
+          const next =
+            dx === 0 && dy === 0
+              ? st.snapshot
+              : st.snapshot.map((s) => (movedSet.has(s.id) ? translateOne(s, dx, dy) : s));
+          // Local React state only. No commitStrokes — no PUT, no undo push.
+          setStrokesState(next);
         };
         const onUp = (up: PointerEvent) => {
-          if (up.pointerId !== dragStateRef.current?.pointerId) return;
+          const st = dragStateRef.current;
+          if (!st || up.pointerId !== st.pointerId) return;
           dragStateRef.current = null;
           document.removeEventListener('pointermove', onMove, true);
           document.removeEventListener('pointerup', onUp, true);
           document.removeEventListener('pointercancel', onUp, true);
+          // Commit the gesture as ONE record. Skip on zero-movement
+          // (click without drag past threshold or drag back to origin).
+          const final = strokesRef.current;
+          if (strokesShallowEqual(st.snapshot, final)) return;
+          commitStrokes(
+            st.snapshot,
+            final,
+            `move ${st.movedIds.length} stroke${st.movedIds.length === 1 ? '' : 's'}`
+          );
         };
         document.addEventListener('pointermove', onMove, true);
         document.addEventListener('pointerup', onUp, true);
@@ -1064,13 +1201,15 @@ export function AnnotationsLayer() {
         return;
       }
 
-      // Empty world — start a drag-select gesture. A small movement falls
-      // back to a "click on empty world → clear selection" (Figma-style).
+      // Empty world — start a drag-select gesture. A bare click without
+      // moving clears annotation selection (post-Wave-3 feedback: click-to-
+      // deselect is back; Esc also still works).
       const addToSelection = e.shiftKey;
       let moved = false;
       const onMove = (mv: PointerEvent) => {
-        const distSq = (mv.clientX - startClientX) ** 2 + (mv.clientY - startClientY) ** 2;
-        if (!moved && distSq < 16) return; // 4 px threshold
+        if (!moved && !crossedDragThreshold(startClientX, startClientY, mv.clientX, mv.clientY)) {
+          return;
+        }
         moved = true;
         const [cwx, cwy] = screenToWorld(mv.clientX, mv.clientY);
         setMarquee({ ax: wx, ay: wy, bx: cwx, by: cwy });
@@ -1080,8 +1219,10 @@ export function AnnotationsLayer() {
         document.removeEventListener('pointerup', onUp, true);
         document.removeEventListener('pointercancel', onUp, true);
         if (!moved) {
-          // True click on empty world → clear (unless modifier add-mode).
-          if (!addToSelection && annotSel.selectedIds.length > 0) annotSel.clear();
+          // Click without movement on empty world → clear annotation
+          // selection (post-Wave-3 user feedback). Shift-click preserves
+          // existing selection for additive-mode workflows.
+          if (!addToSelection) annotSel.clear();
           return;
         }
         const final = marqueeRef.current;
@@ -1100,13 +1241,10 @@ export function AnnotationsLayer() {
             hits.push(s.id);
           }
         }
-        if (addToSelection) {
-          annotSel.add(hits);
-        } else if (hits.length === 0) {
-          annotSel.clear();
-        } else {
-          annotSel.replace(hits);
-        }
+        // Marquee that captured no strokes — preserve existing selection.
+        if (hits.length === 0) return;
+        if (addToSelection) annotSel.add(hits);
+        else annotSel.replace(hits);
       };
       document.addEventListener('pointermove', onMove, true);
       document.addEventListener('pointerup', onUp, true);
@@ -1146,33 +1284,36 @@ export function AnnotationsLayer() {
   const commitText = useCallback(
     (anchorId: string, text: string) => {
       const trimmed = text.trim();
-      setStrokesState((prev) => {
-        const existing = prev.find((s) => s.tool === 'text' && s.anchorId === anchorId) as
-          | TextStroke
-          | undefined;
-        let next: Stroke[];
-        if (trimmed.length === 0) {
-          next = existing ? prev.filter((s) => s.id !== existing.id) : prev;
-        } else if (existing) {
-          next = prev.map((s) => (s.id === existing.id ? { ...existing, text: trimmed } : s));
-        } else {
-          next = [
-            ...prev,
-            {
-              id: rid(),
-              tool: 'text',
-              color: '#1a1a1a',
-              fontSize: DEFAULT_FONT_SIZE,
-              text: trimmed,
-              anchorId,
-            } as TextStroke,
-          ];
-        }
-        scheduleSave(next);
-        return next;
-      });
+      const prev = strokesRef.current;
+      const existing = prev.find((s) => s.tool === 'text' && s.anchorId === anchorId) as
+        | TextStroke
+        | undefined;
+      let next: Stroke[];
+      let label = 'edit text';
+      if (trimmed.length === 0) {
+        if (!existing) return; // nothing to do
+        next = prev.filter((s) => s.id !== existing.id);
+        label = 'delete text';
+      } else if (existing) {
+        if (existing.text === trimmed) return; // identity edit
+        next = prev.map((s) => (s.id === existing.id ? { ...existing, text: trimmed } : s));
+      } else {
+        next = [
+          ...prev,
+          {
+            id: rid(),
+            tool: 'text',
+            color: '#1a1a1a',
+            fontSize: DEFAULT_FONT_SIZE,
+            text: trimmed,
+            anchorId,
+          } as TextStroke,
+        ];
+        label = 'add text';
+      }
+      commitStrokes(prev, next, label);
     },
-    [scheduleSave]
+    [commitStrokes]
   );
 
   // Keyboard: arrow nudge + Backspace/Delete remove selected strokes.
@@ -1257,6 +1398,7 @@ export function AnnotationsLayer() {
           />
         ) : null}
         <AnnotationContextToolbar />
+        {visible && tool === 'move' ? <AnnotationResizeOverlay store={strokesStore} /> : null}
         {isActive ? (
           <AnnotationsChrome
             color={color}
@@ -1382,8 +1524,14 @@ function AnnotationsSvg({
         <StrokeNode key={s.id} stroke={s} anchorsById={anchorsById} interactive={selectMode} />
       ))}
       {selectedStrokes.map((s) => (
-        <SelectionHalo key={`halo-${s.id}`} stroke={s} anchorsById={anchorsById} />
+        <SelectionHalo
+          key={`halo-${s.id}`}
+          stroke={s}
+          anchorsById={anchorsById}
+          multi={selectedStrokes.length > 1}
+        />
       ))}
+      <AnnotGroupBbox selectedStrokes={selectedStrokes} anchorsById={anchorsById} />
       {marquee ? (
         <rect
           className="dc-annot-marquee"
@@ -1507,12 +1655,26 @@ function TextEditor({
 function SelectionHalo({
   stroke,
   anchorsById,
+  multi,
 }: {
   stroke: Stroke;
   anchorsById: Map<string, RectStroke | EllipseStroke>;
+  multi: boolean;
 }) {
   const bbox = strokeBBox(stroke, anchorsById);
   if (!bbox) return null;
+  // T17 + post-Wave-2 fix — annotation halo idioms:
+  //   * Single select → 2 px solid border, NO ring, NO corner ticks.
+  //     The resize overlay (T23) renders the corner handles in screen-space,
+  //     so painting SVG ticks here too would duplicate them. The element
+  //     halo uses CSS box-shadow for the 18% ring; the SVG equivalent (a
+  //     second outline rect) reads as "double frame" rather than a halo —
+  //     user feedback flagged this immediately. Solid 2 px is enough signal
+  //     once the resize handles claim the corners.
+  //   * Multi member → 1.5 px solid full accent, no ring, no ticks (group
+  //     bbox above carries the container affordance).
+  // Marquee STAYS dashed (drawn elsewhere) — dashed is reserved for the
+  // ambient group-container + active-gesture idioms per DDR-046 rev 2.
   const pad = 4;
   return (
     <rect
@@ -1522,8 +1684,7 @@ function SelectionHalo({
       height={bbox.h + pad * 2}
       fill="none"
       stroke="var(--accent, #d63b1f)"
-      strokeWidth={1.5}
-      strokeDasharray="4 3"
+      strokeWidth={multi ? 1.5 : 2}
       vectorEffect="non-scaling-stroke"
       pointerEvents="none"
       rx={2}
@@ -1531,6 +1692,76 @@ function SelectionHalo({
   );
 }
 
+// T17 — group bbox dashed rect for multi-stroke annotation selection. Mirrors
+// the element-side GroupBbox idiom (1 px dashed accent + 6 × 6 corner handles).
+function AnnotGroupBbox({
+  selectedStrokes,
+  anchorsById,
+}: {
+  selectedStrokes: readonly Stroke[];
+  anchorsById: Map<string, RectStroke | EllipseStroke>;
+}) {
+  if (selectedStrokes.length < 2) return null;
+  let xMin = Number.POSITIVE_INFINITY;
+  let yMin = Number.POSITIVE_INFINITY;
+  let xMax = Number.NEGATIVE_INFINITY;
+  let yMax = Number.NEGATIVE_INFINITY;
+  let any = false;
+  for (const s of selectedStrokes) {
+    const b = strokeBBox(s, anchorsById);
+    if (!b) continue;
+    any = true;
+    if (b.x < xMin) xMin = b.x;
+    if (b.y < yMin) yMin = b.y;
+    if (b.x + b.w > xMax) xMax = b.x + b.w;
+    if (b.y + b.h > yMax) yMax = b.y + b.h;
+  }
+  if (!any) return null;
+  const pad = 6;
+  const x = xMin - pad;
+  const y = yMin - pad;
+  const w = xMax - xMin + pad * 2;
+  const h = yMax - yMin + pad * 2;
+  const handle = 6;
+  const inset = 3;
+  const handles = [
+    { corner: 'nw', x: x - inset, y: y - inset },
+    { corner: 'ne', x: x + w - handle + inset, y: y - inset },
+    { corner: 'sw', x: x - inset, y: y + h - handle + inset },
+    { corner: 'se', x: x + w - handle + inset, y: y + h - handle + inset },
+  ];
+  return (
+    <g pointerEvents="none">
+      <rect
+        x={x}
+        y={y}
+        width={w}
+        height={h}
+        fill="none"
+        stroke="var(--accent, #d63b1f)"
+        strokeWidth={1}
+        strokeDasharray="4 3"
+        vectorEffect="non-scaling-stroke"
+        rx={2}
+      />
+      {handles.map((c) => (
+        <rect
+          key={c.corner}
+          x={c.x}
+          y={c.y}
+          width={handle}
+          height={handle}
+          fill="var(--accent, #d63b1f)"
+          stroke="var(--bg-0, #ffffff)"
+          strokeWidth={1}
+          vectorEffect="non-scaling-stroke"
+          rx={1}
+        />
+      ))}
+    </g>
+  );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Stroke renderer
 
@@ -1694,7 +1925,7 @@ function AnnotationsChrome({
             type="button"
             className="dc-annot-btn"
             aria-pressed={thickness === STROKE_WIDTH_THIN}
-            title="Thin (2px)"
+            title="Thin (3px)"
             onClick={() => setThickness(STROKE_WIDTH_THIN)}
           >
             Thin