@1agh/maude 0.19.0 → 0.20.0

package/plugins/design/dev-server/use-annotation-resize.tsx

@@ -0,0 +1,295 @@
+/**
+ * @file       use-annotation-resize.tsx — Task 23 (Wave 2, G4)
+ * @scope      plugins/design/dev-server/use-annotation-resize.tsx
+ * @purpose    Screen-space corner / endpoint handles for the selected
+ *             annotation. Per-tool resize math; modifier semantics (Shift
+ *             aspect-lock, Alt scale-from-center) are deferred to a follow-up.
+ *
+ *             Handles are `position: fixed` DOM siblings of the canvas (the
+ *             same pattern element selection uses) — they stay 8 × 8 CSS px
+ *             at any zoom and never get caught in the SVG `vector-effect`
+ *             gymnastics.
+ *
+ *             Mounts the overlay element exactly once via `AnnotationResizeOverlay`.
+ *             The hook does the math + persistence; the overlay component
+ *             owns the rAF loop that follows pan/zoom + pointer drags.
+ */
+
+import { type ReactNode, useCallback, useEffect, useMemo, useRef } from 'react';
+
+import {
+  type ArrowStroke,
+  type EllipseStroke,
+  type PenStroke,
+  type RectStroke,
+  type Stroke,
+  type StrokesStoreValue,
+  strokeBBox,
+} from './annotations-layer.tsx';
+import { useViewportControllerContext } from './canvas-lib.tsx';
+import { useAnnotationSelection } from './use-annotation-selection.tsx';
+
+const RESIZE_CSS = `
+.dc-annot-resize-handle {
+  position: fixed;
+  width: 8px;
+  height: 8px;
+  background: var(--accent, #d63b1f);
+  border: 1px solid var(--bg-0, #ffffff);
+  border-radius: 1px;
+  box-shadow: 0 0 0 0.5px color-mix(in oklab, var(--fg-0, #1c1917) 30%, transparent);
+  z-index: 6;
+  pointer-events: auto;
+  touch-action: none;
+}
+.dc-annot-resize-handle[data-corner="nw"], .dc-annot-resize-handle[data-corner="se"] { cursor: nwse-resize; }
+.dc-annot-resize-handle[data-corner="ne"], .dc-annot-resize-handle[data-corner="sw"] { cursor: nesw-resize; }
+.dc-annot-resize-handle[data-corner="ep1"], .dc-annot-resize-handle[data-corner="ep2"] { cursor: move; }
+`.trim();
+
+function ensureResizeStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-annot-resize-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-annot-resize-css';
+  s.textContent = RESIZE_CSS;
+  document.head.appendChild(s);
+}
+
+type Corner = 'nw' | 'ne' | 'sw' | 'se' | 'ep1' | 'ep2';
+
+/** Stroke types that expose resize handles in v1. Text inherits anchor bbox. */
+function isResizable(s: Stroke): s is RectStroke | EllipseStroke | ArrowStroke | PenStroke {
+  return s.tool === 'rect' || s.tool === 'ellipse' || s.tool === 'arrow' || s.tool === 'pen';
+}
+
+/**
+ * Per-tool resize math. Given a stroke + the moved corner + the new world
+ * coords for that corner, returns a patched stroke. `start` is the stroke at
+ * the moment the drag began (used as the source-of-truth for scaling math —
+ * avoids drift from rounding successive deltas).
+ */
+function resizeStroke(
+  start: Stroke,
+  corner: Corner,
+  wx: number,
+  wy: number
+): Partial<Stroke> | null {
+  if (start.tool === 'rect') {
+    const bbox = { x: start.x, y: start.y, w: start.w, h: start.h };
+    const left = corner === 'nw' || corner === 'sw' ? wx : bbox.x;
+    const right = corner === 'ne' || corner === 'se' ? wx : bbox.x + bbox.w;
+    const top = corner === 'nw' || corner === 'ne' ? wy : bbox.y;
+    const bottom = corner === 'sw' || corner === 'se' ? wy : bbox.y + bbox.h;
+    return {
+      x: Math.min(left, right),
+      y: Math.min(top, bottom),
+      w: Math.abs(right - left),
+      h: Math.abs(bottom - top),
+    } as Partial<RectStroke>;
+  }
+  if (start.tool === 'ellipse') {
+    // Treat the four corners as the bbox of the ellipse. Drag any corner →
+    // recompute the AABB and derive cx/cy/rx/ry from the diagonal anchor.
+    const bbox = {
+      x: start.cx - start.rx,
+      y: start.cy - start.ry,
+      w: start.rx * 2,
+      h: start.ry * 2,
+    };
+    const left = corner === 'nw' || corner === 'sw' ? wx : bbox.x;
+    const right = corner === 'ne' || corner === 'se' ? wx : bbox.x + bbox.w;
+    const top = corner === 'nw' || corner === 'ne' ? wy : bbox.y;
+    const bottom = corner === 'sw' || corner === 'se' ? wy : bbox.y + bbox.h;
+    const nx = Math.min(left, right);
+    const ny = Math.min(top, bottom);
+    const nw = Math.abs(right - left);
+    const nh = Math.abs(bottom - top);
+    return {
+      cx: nx + nw / 2,
+      cy: ny + nh / 2,
+      rx: Math.max(1, nw / 2),
+      ry: Math.max(1, nh / 2),
+    } as Partial<EllipseStroke>;
+  }
+  if (start.tool === 'arrow') {
+    if (corner === 'ep1') return { x1: wx, y1: wy } as Partial<ArrowStroke>;
+    if (corner === 'ep2') return { x2: wx, y2: wy } as Partial<ArrowStroke>;
+    return null;
+  }
+  if (start.tool === 'pen') {
+    // Scale all points by (newW / oldW, newH / oldH) around the opposite
+    // corner anchor. When the drag-start bbox has 0 width/height on an axis
+    // (single-point pen stroke) we skip that axis to avoid div-by-zero.
+    const bb = strokeBBox(start);
+    if (!bb) return null;
+    const anchorX = corner === 'nw' || corner === 'sw' ? bb.x + bb.w : bb.x;
+    const anchorY = corner === 'nw' || corner === 'ne' ? bb.y + bb.h : bb.y;
+    const newLeft = corner === 'nw' || corner === 'sw' ? wx : bb.x;
+    const newTop = corner === 'nw' || corner === 'ne' ? wy : bb.y;
+    const newRight = corner === 'ne' || corner === 'se' ? wx : bb.x + bb.w;
+    const newBottom = corner === 'sw' || corner === 'se' ? wy : bb.y + bb.h;
+    const sx = bb.w === 0 ? 1 : (newRight - newLeft) / bb.w;
+    const sy = bb.h === 0 ? 1 : (newBottom - newTop) / bb.h;
+    const scaled = start.points.map(
+      ([px, py]) =>
+        [anchorX + (px - anchorX) * sx, anchorY + (py - anchorY) * sy] as [number, number]
+    );
+    return { points: scaled } as Partial<PenStroke>;
+  }
+  return null;
+}
+
+/**
+ * Returns the four corners (or two endpoints, for arrow) of the selected
+ * stroke in world coordinates. Used by the overlay component to position
+ * the screen-space handle divs each rAF tick.
+ */
+function handlePositions(s: Stroke): Array<{ corner: Corner; x: number; y: number }> {
+  if (s.tool === 'arrow') {
+    return [
+      { corner: 'ep1', x: s.x1, y: s.y1 },
+      { corner: 'ep2', x: s.x2, y: s.y2 },
+    ];
+  }
+  const bb = strokeBBox(s);
+  if (!bb) return [];
+  return [
+    { corner: 'nw', x: bb.x, y: bb.y },
+    { corner: 'ne', x: bb.x + bb.w, y: bb.y },
+    { corner: 'sw', x: bb.x, y: bb.y + bb.h },
+    { corner: 'se', x: bb.x + bb.w, y: bb.y + bb.h },
+  ];
+}
+
+export function AnnotationResizeOverlay({
+  store,
+}: {
+  store: StrokesStoreValue | null;
+}): ReactNode {
+  ensureResizeStyles();
+  const annotSel = useAnnotationSelection();
+  const controller = useViewportControllerContext();
+  const vp = controller?.viewport ?? null;
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const rafRef = useRef<number | null>(null);
+  const dragRef = useRef<{
+    pointerId: number;
+    startStroke: Stroke;
+    corner: Corner;
+  } | null>(null);
+
+  const selectedId = annotSel.selectedIds.length === 1 ? (annotSel.selectedIds[0] ?? null) : null;
+  const selectedStroke: Stroke | null = useMemo(() => {
+    if (!selectedId || !store) return null;
+    return store.strokes.find((s) => s.id === selectedId) ?? null;
+  }, [selectedId, store]);
+
+  const screenToWorld = useCallback(
+    (cx: number, cy: number): [number, number] => {
+      const v = vp ?? { x: 0, y: 0, zoom: 1 };
+      const z = v.zoom || 1;
+      return [(cx - v.x) / z, (cy - v.y) / z];
+    },
+    [vp]
+  );
+
+  // rAF loop — repositions handles on every frame while a single resizable
+  // stroke is selected. Cheaper than wiring pan/zoom observers because the
+  // halo overlays already follow the same pattern.
+  useEffect(() => {
+    if (!selectedStroke || !isResizable(selectedStroke)) {
+      const c = containerRef.current;
+      if (c) {
+        for (const child of Array.from(c.children)) {
+          (child as HTMLElement).style.display = 'none';
+        }
+      }
+      return;
+    }
+    const tick = () => {
+      rafRef.current = null;
+      const c = containerRef.current;
+      if (!c) return;
+      const positions = handlePositions(selectedStroke);
+      const v = vp ?? { x: 0, y: 0, zoom: 1 };
+      const z = v.zoom || 1;
+      // Ensure enough handle children exist (each corner = one absolutely-
+      // positioned div). 4 for rect/ellipse/pen; 2 for arrow.
+      while (c.children.length < positions.length) {
+        const handle = document.createElement('div');
+        handle.className = 'dc-annot-resize-handle';
+        c.appendChild(handle);
+      }
+      while (c.children.length > positions.length) {
+        c.lastChild && c.removeChild(c.lastChild);
+      }
+      for (let i = 0; i < positions.length; i++) {
+        const pos = positions[i];
+        const handle = c.children[i] as HTMLElement | undefined;
+        if (!pos || !handle) continue;
+        const sx = pos.x * z + v.x;
+        const sy = pos.y * z + v.y;
+        handle.style.display = 'block';
+        handle.style.left = `${Math.round(sx - 4)}px`;
+        handle.style.top = `${Math.round(sy - 4)}px`;
+        handle.dataset.corner = pos.corner;
+      }
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+    };
+  }, [selectedStroke, vp]);
+
+  // Pointer handling — pointerdown on a handle starts a drag; pointermove
+  // patches the stroke via `store.updateStroke`; pointerup commits.
+  useEffect(() => {
+    const c = containerRef.current;
+    if (!c) return;
+    const onDown = (e: PointerEvent) => {
+      const t = e.target as HTMLElement | null;
+      if (!t?.classList.contains('dc-annot-resize-handle')) return;
+      if (!selectedStroke || !store) return;
+      const corner = t.dataset.corner as Corner | undefined;
+      if (!corner) return;
+      e.preventDefault();
+      e.stopPropagation();
+      dragRef.current = { pointerId: e.pointerId, startStroke: selectedStroke, corner };
+      try {
+        t.setPointerCapture(e.pointerId);
+      } catch {
+        /* some browsers reject capture on synthetic events */
+      }
+    };
+    const onMove = (e: PointerEvent) => {
+      const d = dragRef.current;
+      if (!d || e.pointerId !== d.pointerId) return;
+      if (!store) return;
+      const [wx, wy] = screenToWorld(e.clientX, e.clientY);
+      const patch = resizeStroke(d.startStroke, d.corner, wx, wy);
+      if (patch) store.updateStroke(d.startStroke.id, patch);
+    };
+    const onUp = (e: PointerEvent) => {
+      const d = dragRef.current;
+      if (!d || e.pointerId !== d.pointerId) return;
+      dragRef.current = null;
+    };
+    c.addEventListener('pointerdown', onDown);
+    document.addEventListener('pointermove', onMove);
+    document.addEventListener('pointerup', onUp);
+    document.addEventListener('pointercancel', onUp);
+    return () => {
+      c.removeEventListener('pointerdown', onDown);
+      document.removeEventListener('pointermove', onMove);
+      document.removeEventListener('pointerup', onUp);
+      document.removeEventListener('pointercancel', onUp);
+    };
+  }, [selectedStroke, store, screenToWorld]);
+
+  // Only render when there's exactly one resizable stroke selected. Multi
+  // resize is undefined for v1 (no canonical UX); text inherits anchor bbox.
+  if (!selectedStroke || !isResizable(selectedStroke)) return null;
+  return <div ref={containerRef} aria-hidden="true" />;
+}

package/plugins/design/dev-server/use-artboard-drag.tsx

@@ -36,14 +36,17 @@ import {
   useState,
 } from 'react';
 
+import { DRAG_THRESHOLD_PX as INPUT_DRAG_THRESHOLD_PX } from './input-router.tsx';
 import type { Selection } from './use-selection-set.tsx';
 import { type Rect, type SnapResult, computeSnap } from './use-snap-guides.tsx';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
 
-/** Screen-pixel distance the cursor must travel before pending → dragging. */
-export const DRAG_THRESHOLD_PX = 4;
+/** Screen-pixel distance the cursor must travel before pending → dragging.
+ *  Re-export from `input-router` so artboard-drag, marquees, and annotation
+ *  drag-vs-tap share the same canonical value (T25). */
+export const DRAG_THRESHOLD_PX = INPUT_DRAG_THRESHOLD_PX;
 
 /** Default grid + tolerance (world units). Documented in DDR-028. */
 export const DEFAULT_GRID_SIZE = 40;
@@ -136,7 +139,7 @@ export function dragReducer(state: DragState, ev: DragEvent): DragState {
       const dxClient = ev.clientX - state.startClientX;
       const dyClient = ev.clientY - state.startClientY;
       if (state.kind === 'pending') {
-        if (Math.abs(dxClient) < DRAG_THRESHOLD_PX && Math.abs(dyClient) < DRAG_THRESHOLD_PX) {
+        if (Math.hypot(dxClient, dyClient) < DRAG_THRESHOLD_PX) {
           return state;
         }
       }

package/plugins/design/dev-server/use-cursor-modifiers.tsx

@@ -0,0 +1,122 @@
+/**
+ * @file       use-cursor-modifiers.tsx — T28 (Wave 3)
+ * @scope      plugins/design/dev-server/use-cursor-modifiers.tsx
+ * @purpose    Modifier-aware cursor state machine. Tracks Alt / Shift / Meta
+ *             modifier state globally and reflects it as `data-mod-*`
+ *             attributes on `.dc-canvas`. CSS rules consume those attrs to
+ *             flip cursors live:
+ *
+ *               • Alt-held over a `[data-cd-id]` in Move tool → cursor: copy
+ *                 (preview of "Alt-drag duplicates this element").
+ *               • Shift-held in Move tool over empty body padding → crosshair
+ *                 (preview of "marquee add mode").
+ *
+ *             Per the research finding (Excalidraw #250): cursor changes on
+ *             HOVER, not on drag-start. We track modifier state at the
+ *             document level so the cursor updates the moment the user
+ *             presses/releases without waiting for a pointermove.
+ *
+ *             Resize-handle cursors (nw / ne / ns / ew) live next to the
+ *             handle DOM in `use-annotation-resize.tsx` — those don't need
+ *             modifier coupling; they fire on hover via their own CSS rules.
+ */
+
+import { type RefObject, useEffect } from 'react';
+
+const STYLES = `
+/* Alt + cd-id in move tool → copy cursor. The Alt-drag-duplicates affordance
+   is partial in v1 (no drag handler yet) — paint the cursor anyway so the
+   user discovers the gesture, and a future wave wires the actual duplication. */
+.dc-canvas[data-active-tool="move"][data-mod-alt="true"] [data-cd-id],
+.dc-canvas[data-active-tool="move"][data-mod-alt="true"] [data-dc-screen] {
+  cursor: copy !important;
+}
+
+/* Shift over empty body padding in move tool → crosshair (marquee add mode
+   preview). Body padding = the .dc-artboard-body direct background, not
+   user content. */
+.dc-canvas[data-active-tool="move"][data-mod-shift="true"] .dc-artboard-body {
+  cursor: crosshair;
+}
+`.trim();
+
+function ensureStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-cv-cursor-modifiers-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-cv-cursor-modifiers-css';
+  s.textContent = STYLES;
+  document.head.appendChild(s);
+}
+
+export interface ModifierState {
+  alt: boolean;
+  shift: boolean;
+  meta: boolean;
+}
+
+/**
+ * Reduce a key event into the modifier slice. Pulled out for unit tests —
+ * the actual hook is DOM-bound and harder to test directly.
+ */
+export function reduceModifiers(
+  prev: ModifierState,
+  e: { altKey: boolean; shiftKey: boolean; metaKey: boolean; ctrlKey: boolean }
+): ModifierState {
+  // Treat Ctrl as Meta on non-mac so the cursor preview stays consistent with
+  // the input-router's `metaOrCtrl` gate.
+  const meta = e.metaKey || e.ctrlKey;
+  if (prev.alt === e.altKey && prev.shift === e.shiftKey && prev.meta === meta) {
+    return prev;
+  }
+  return { alt: e.altKey, shift: e.shiftKey, meta };
+}
+
+/**
+ * Attach modifier tracking to the canvas host element. Reflects the modifier
+ * state as `data-mod-alt` / `data-mod-shift` / `data-mod-meta` so cursor CSS
+ * rules can act on combinations without re-rendering React.
+ *
+ * Cleans up on unmount + on window blur (so leaving the tab with Alt held
+ * doesn't strand the cursor in copy mode).
+ */
+export function useCursorModifiers(hostRef: RefObject<HTMLElement | null>): void {
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const host = hostRef.current;
+    if (!host) return;
+    ensureStyles();
+
+    let state: ModifierState = { alt: false, shift: false, meta: false };
+
+    const apply = (next: ModifierState) => {
+      if (next === state) return;
+      state = next;
+      host.setAttribute('data-mod-alt', next.alt ? 'true' : 'false');
+      host.setAttribute('data-mod-shift', next.shift ? 'true' : 'false');
+      host.setAttribute('data-mod-meta', next.meta ? 'true' : 'false');
+    };
+
+    const onKeyChange = (e: KeyboardEvent) => apply(reduceModifiers(state, e));
+    const onBlur = () => apply({ alt: false, shift: false, meta: false });
+    // pointermove carries the modifier state too — handles the case where
+    // the user presses a modifier outside the focused window and then mouses
+    // back in (keydown/keyup never fires for the press).
+    const onPointer = (e: PointerEvent) => apply(reduceModifiers(state, e));
+
+    document.addEventListener('keydown', onKeyChange, true);
+    document.addEventListener('keyup', onKeyChange, true);
+    document.addEventListener('pointermove', onPointer, { passive: true });
+    window.addEventListener('blur', onBlur);
+
+    return () => {
+      document.removeEventListener('keydown', onKeyChange, true);
+      document.removeEventListener('keyup', onKeyChange, true);
+      document.removeEventListener('pointermove', onPointer);
+      window.removeEventListener('blur', onBlur);
+      host.removeAttribute('data-mod-alt');
+      host.removeAttribute('data-mod-shift');
+      host.removeAttribute('data-mod-meta');
+    };
+  }, [hostRef]);
+}

package/plugins/design/dev-server/use-keyboard-discipline.tsx

@@ -0,0 +1,125 @@
+/**
+ * @file       use-keyboard-discipline.tsx — T29 (Wave 3)
+ * @scope      plugins/design/dev-server/use-keyboard-discipline.tsx
+ * @purpose    Keyboard nudge + Cmd+A select-all-in-artboard. Bail when focus
+ *             is inside an input / textarea / contenteditable so typing
+ *             into the dev-server's own inputs (file tree filter, etc.)
+ *             never collides.
+ *
+ *             Scope decision — arrow nudge applies to **artboards** only.
+ *             User content inside artboards has no live-position channel
+ *             (canvas surface is HTML; element positions are CSS-derived
+ *             from the compiled JSX, not directly manipulable). Element
+ *             nudge would require either an ephemeral CSS-transform overlay
+ *             (cleaner) or a TSX rewrite channel (heavier). Out of scope
+ *             for this wave — the artboard channel + dragBus.commitPositions
+ *             already exists, so we leverage that and document the
+ *             limitation here.
+ *
+ *             Cmd+D duplicate is also deferred — same architectural reason
+ *             (no duplicate channel). Esc is owned by the input-router's
+ *             onEscape callback, so we don't duplicate it here.
+ *
+ *             Distance:
+ *               • Arrow      → 1 world-unit step (DDR-028 world units, not
+ *                              screen px).
+ *               • Shift+Arrow → 10 world-unit step.
+ */
+
+import { useEffect } from 'react';
+
+import { useArtboardsContext, useDragStateContext } from './canvas-lib.tsx';
+import { isEditableTarget } from './input-router.tsx';
+import { type Selection, useSelectionSet } from './use-selection-set.tsx';
+
+const STEP_SMALL = 1;
+const STEP_LARGE = 10;
+
+export interface NudgeInput {
+  key: string;
+  shift: boolean;
+}
+
+/**
+ * Map a keyboard event into a (dx, dy) delta in world units. Returns null
+ * when the key isn't an arrow. Exported for unit tests.
+ */
+export function nudgeDelta(input: NudgeInput): { dx: number; dy: number } | null {
+  const step = input.shift ? STEP_LARGE : STEP_SMALL;
+  switch (input.key) {
+    case 'ArrowLeft':
+      return { dx: -step, dy: 0 };
+    case 'ArrowRight':
+      return { dx: step, dy: 0 };
+    case 'ArrowUp':
+      return { dx: 0, dy: -step };
+    case 'ArrowDown':
+      return { dx: 0, dy: step };
+    default:
+      return null;
+  }
+}
+
+export function useKeyboardDiscipline(): void {
+  const selSet = useSelectionSet();
+  const artboardsCtx = useArtboardsContext();
+  const dragBus = useDragStateContext();
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (isEditableTarget(e.target)) return;
+
+      // Cmd+A → select all stamped elements in the active artboard.
+      const isMeta = e.metaKey || e.ctrlKey;
+      if (isMeta && e.key.toLowerCase() === 'a') {
+        if (!artboardsCtx) return;
+        const id = artboardsCtx.activeArtboardId;
+        if (!id) return;
+        const root = document.querySelector(`[data-dc-screen="${id}"] .dc-artboard-body`);
+        if (!root) return;
+        const stamped = root.querySelectorAll('[data-cd-id]');
+        if (stamped.length === 0) return;
+        const hits: Selection[] = [];
+        for (const el of stamped) {
+          const cdId = el.getAttribute('data-cd-id');
+          if (!cdId) continue;
+          hits.push({
+            id: cdId,
+            selector: `[data-cd-id="${cdId}"]`,
+            artboardId: id,
+            tag: el.tagName.toLowerCase(),
+          });
+        }
+        if (hits.length === 0) return;
+        e.preventDefault();
+        selSet.replace(hits);
+        return;
+      }
+
+      // Arrow nudge — artboards only (see file header for the why).
+      const delta = nudgeDelta({ key: e.key, shift: e.shiftKey });
+      if (!delta) return;
+      if (isMeta || e.altKey) return; // modifier combos reserved for future
+      if (!artboardsCtx || !dragBus) return;
+
+      const artboardSelections = selSet.selected.filter((s) => !!s.artboardId && !s.id);
+      if (artboardSelections.length === 0) return;
+      const ids = new Set(artboardSelections.map((s) => s.artboardId as string));
+      const targets = artboardsCtx.artboards.filter((r) => ids.has(r.id));
+      if (targets.length === 0) return;
+
+      e.preventDefault();
+      const moved = targets.map((r) => ({
+        id: r.id,
+        x: Math.round(r.x + delta.dx),
+        y: Math.round(r.y + delta.dy),
+      }));
+      dragBus.commitPositions(moved);
+    };
+
+    document.addEventListener('keydown', onKeyDown, true);
+    return () => document.removeEventListener('keydown', onKeyDown, true);
+  }, [selSet, artboardsCtx, dragBus]);
+}

package/plugins/design/dev-server/use-snap-guides.tsx

@@ -40,6 +40,13 @@ export interface Rect {
 
 export type SnapAxis = 'x' | 'y';
 
+/** DDR-046 — `kind` lets SnapGuideOverlay route grid vs sibling guides to
+ *  different visual treatments (grid = lighter gray fallback; sibling = full
+ *  magenta confidence). `delta` is the signed correction the snap applied;
+ *  the overlay renders a `Δ{Math.round(delta)}` pill mid-span when |delta| > 0
+ *  and the guide span > 60 px. */
+export type SnapKind = 'grid' | 'sibling';
+
 export interface SnapGuide {
   /** `"x"` → vertical line (snapping X coord). Line sits at `pos` on X,
    *  spans `from..to` on Y. `"y"` is the dual: horizontal line at `pos` on Y,
@@ -48,6 +55,12 @@ export interface SnapGuide {
   pos: number;
   from: number;
   to: number;
+  /** Signed pixel delta the snap corrected (additive: `proposed + delta`).
+   *  Optional for back-compat with pre-DDR-046 readers. */
+  delta?: number;
+  /** Whether the winning candidate came from the grid pass or a sibling edge.
+   *  Optional for back-compat. */
+  kind?: SnapKind;
 }
 
 export interface SnapResult {
@@ -76,6 +89,8 @@ interface AxisCandidate {
   /** Perpendicular extent — `from..to` of the would-be guide. */
   from: number;
   to: number;
+  /** Whether this candidate came from the grid pass or the sibling pass. */
+  kind: SnapKind;
 }
 
 function nearestGridDelta(coord: number, gridSize: number, tolerance: number): number | null {
@@ -108,12 +123,17 @@ function pickClosest(cands: AxisCandidate[]): AxisCandidate | null {
 function mergeAtPos(axis: SnapAxis, winner: AxisCandidate, cands: AxisCandidate[]): SnapGuide {
   let from = winner.from;
   let to = winner.to;
+  let worstDelta = winner.delta;
   for (const c of cands) {
     if (Math.abs(c.pos - winner.pos) > 0.001) continue;
     if (c.from < from) from = c.from;
     if (c.to > to) to = c.to;
+    // Distance pill shows the worst-case correction among merged candidates,
+    // not the average (per DDR-046 — "render the pixels the user actually
+    // had to be corrected by").
+    if (Math.abs(c.delta) > Math.abs(worstDelta)) worstDelta = c.delta;
   }
-  return { axis, pos: winner.pos, from, to };
+  return { axis, pos: winner.pos, from, to, delta: worstDelta, kind: winner.kind };
 }
 
 export function computeSnap(proposed: Rect, others: Rect[], opts: SnapOptions): SnapResult {
@@ -140,6 +160,7 @@ export function computeSnap(proposed: Rect, others: Rect[], opts: SnapOptions):
       pos: propLeft + gridX,
       from: propTop,
       to: propBottom,
+      kind: 'grid',
     });
   }
   const gridY = nearestGridDelta(propTop, gridSize, tolerance);
@@ -149,6 +170,7 @@ export function computeSnap(proposed: Rect, others: Rect[], opts: SnapOptions):
       pos: propTop + gridY,
       from: propLeft,
       to: propRight,
+      kind: 'grid',
     });
   }
 
@@ -177,6 +199,7 @@ export function computeSnap(proposed: Rect, others: Rect[], opts: SnapOptions):
         pos: otherCoord,
         from: Math.min(propTop, oTop),
         to: Math.max(propBottom, oBottom),
+        kind: 'sibling',
       });
     }
 
@@ -196,6 +219,7 @@ export function computeSnap(proposed: Rect, others: Rect[], opts: SnapOptions):
         pos: otherCoord,
         from: Math.min(propLeft, oLeft),
         to: Math.max(propRight, oRight),
+        kind: 'sibling',
       });
     }
   }