@hyperframes/studio 0.7.102 → 0.7.104

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.102",
+  "version": "0.7.104",
   "description": "",
   "repository": {
     "type": "git",
@@ -47,11 +47,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.102",
-    "@hyperframes/parsers": "0.7.102",
-    "@hyperframes/sdk": "0.7.102",
-    "@hyperframes/player": "0.7.102",
-    "@hyperframes/studio-server": "0.7.102"
+    "@hyperframes/core": "0.7.104",
+    "@hyperframes/parsers": "0.7.104",
+    "@hyperframes/player": "0.7.104",
+    "@hyperframes/studio-server": "0.7.104",
+    "@hyperframes/sdk": "0.7.104"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -67,7 +67,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.102"
+    "@hyperframes/producer": "0.7.104"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -65,6 +65,7 @@ import {
   readStudioUrlStateFromWindow,
   resolveMasterCompositionPath,
 } from "./utils/studioUrlState";
+const getTimelineSelectionSet = () => usePlayerStore.getState().selectedElementIds;
 // fallow-ignore-next-line complexity
 export function StudioApp() {
   const { projectId, resolving, waitingForServer } = useServerConnection();
@@ -91,9 +92,9 @@ export function StudioApp() {
   const captionSync = useCaptionSync(projectId);
   const timelineElements = usePlayerStore((s) => s.elements);
   const setSelectedTimelineElementId = usePlayerStore((s) => s.setSelectedElementId);
+  const setTimelineSelectionSet = usePlayerStore((s) => s.setSelectedElementIds);
   const timelineDuration = usePlayerStore((s) => s.duration);
   const isPlaying = usePlayerStore((s) => s.isPlaying);
-  const isMasterView = !activeCompPath || activeCompPath === "index.html";
   const effectiveTimelineDuration = useMemo(() => {
     const maxEnd =
       timelineElements.length > 0
@@ -270,13 +271,14 @@ export function StudioApp() {
   const domEditSession = useDomEditSession({
     projectId,
     activeCompPath,
-    isMasterView,
     compIdToSrc,
     captionEditMode,
     compositionLoading,
     previewIframeRef,
     timelineElements,
+    getTimelineSelectionSet,
     setSelectedTimelineElementId,
+    setTimelineSelectionSet,
     setRightCollapsed: panelLayout.setRightCollapsed,
     setRightPanelTab: panelLayout.setRightPanelTab,
     showToast,
@@ -416,6 +418,8 @@ export function StudioApp() {
     rightCollapsed: panelLayout.rightCollapsed,
     activeCompPathHydrated,
     domEditSelection: domEditSession.domEditSelection,
+    domEditGroupSelections: domEditSession.domEditGroupSelections,
+    applyMarqueeSelection: domEditSession.applyMarqueeSelection,
     buildDomSelectionFromTarget: domEditSession.buildDomSelectionFromTarget,
     applyDomSelection: domEditSession.applyDomSelection,
     setRightPanelTab: panelLayout.setRightPanelTab,

package/src/captions/hooks/useCaptionSync.ts

@@ -3,6 +3,7 @@ import { useCaptionStore } from "../store";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { trackEvent } from "../../telemetry/client";
 import type { CaptionStyle } from "../types";
+import { studioWriteHeaders } from "../../utils/studioFileVersion";
 
 interface CaptionOverrideEntry {
   wordId?: string;
@@ -77,7 +78,7 @@ export function useCaptionSync(projectId: string | null) {
 
     fetch(`/api/projects/${pid}/files/${encodeURIComponent("caption-overrides.json")}`, {
       method: "PUT",
-      headers: { "Content-Type": "text/plain" },
+      headers: { "Content-Type": "text/plain", ...studioWriteHeaders() },
       body: JSON.stringify(overrides, null, 2),
     }).catch((error: unknown) => {
       // Caption auto-save is a data-loss path; surface failures via telemetry

package/src/components/editor/DomEditOverlay.test.ts

@@ -14,7 +14,10 @@ import {
   resolveDomEditRotationGesture,
 } from "./DomEditOverlay";
 import type { DomEditSelection } from "./domEditing";
-import { resolveResizeCenterAnchorOffset } from "./domEditOverlayGestures";
+import {
+  hoverCacheDescribesPoint,
+  resolveResizeCenterAnchorOffset,
+} from "./domEditOverlayGestures";
 
 // React 19 warns unless the test environment opts into act().
 globalThis.IS_REACT_ACT_ENVIRONMENT = true;
@@ -278,7 +281,9 @@ describe("DomEditOverlay", () => {
     const host = document.createElement("div");
     document.body.append(host);
     const root = createRoot(host);
-    const iframeRef = { current: document.createElement("iframe") as HTMLIFrameElement | null };
+    const iframeRef: { current: HTMLIFrameElement | null } = {
+      current: document.createElement("iframe"),
+    };
     const onCanvasMouseDown = vi.fn();
     const onMarqueeSelect = vi.fn();
 
@@ -323,6 +328,44 @@ describe("DomEditOverlay", () => {
     host.remove();
   });
 
+  it("starts a marquee from outside the composition frame", async () => {
+    const restoreRect = stubViewportRect();
+    const originalPointerCapture = HTMLDivElement.prototype.setPointerCapture;
+    const setPointerCapture = vi.fn();
+    HTMLDivElement.prototype.setPointerCapture = setPointerCapture;
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const iframeRef: { current: HTMLIFrameElement | null } = {
+      current: document.createElement("iframe"),
+    };
+
+    act(() => {
+      root.render(
+        React.createElement(DomEditOverlay, {
+          ...createOverlayProps({
+            iframeRef,
+            selection: null,
+            hoverSelection: null,
+            onSelectionChange: () => {},
+          }),
+          onMarqueeSelect: vi.fn(),
+        }),
+      );
+    });
+    await flushOverlayRaf();
+
+    // Negative x is outside the 0..800 composition frame but still reaches the
+    // overlay in a real pointer event when the user starts in the grey margin.
+    dispatchOverlayPointerDown(getOverlay(host), -40, 100);
+    expect(setPointerCapture).toHaveBeenCalledTimes(1);
+
+    act(() => root.unmount());
+    HTMLDivElement.prototype.setPointerCapture = originalPointerCapture;
+    restoreRect();
+    host.remove();
+  });
+
   it("does not start a drag from a stale hover target on canvas pointer-down", () => {
     const host = document.createElement("div");
     document.body.append(host);
@@ -628,6 +671,50 @@ describe("resolveDomEditRotationGesture", () => {
   });
 });
 
+/**
+ * Shift-click reads the hover cache instead of hit-testing, and the cache is
+ * filled asynchronously as the pointer moves. Pass over one element on the way to
+ * another and the cache still names the one you left, so the shift-click added
+ * THAT element and the click looked like it selected something at random. The
+ * guard is what makes the cache usable only when it is about the point clicked.
+ */
+describe("hoverCacheDescribesPoint", () => {
+  const doc = new Window().document;
+
+  it("rejects a cache left behind by an element the pointer passed over", () => {
+    const passedOver = doc.createElement("div");
+    const clicked = doc.createElement("div");
+    doc.body.append(passedOver, clicked);
+
+    expect(hoverCacheDescribesPoint(passedOver, clicked)).toBe(false);
+  });
+
+  it("accepts the cache when it names the element at the point", () => {
+    const clicked = doc.createElement("div");
+    doc.body.append(clicked);
+
+    expect(hoverCacheDescribesPoint(clicked, clicked)).toBe(true);
+  });
+
+  // The resolver is allowed to hand back a clip ancestor of the raw target, which
+  // still describes the same click — rejecting it would drop the fast path on
+  // every element that has children.
+  it("accepts an ancestor of the element at the point", () => {
+    const clip = doc.createElement("div");
+    const child = doc.createElement("span");
+    clip.append(child);
+    doc.body.append(clip);
+
+    expect(hoverCacheDescribesPoint(clip, child)).toBe(true);
+  });
+
+  it("rejects a missing cache or an empty point", () => {
+    const el = doc.createElement("div");
+    expect(hoverCacheDescribesPoint(null, el)).toBe(false);
+    expect(hoverCacheDescribesPoint(el, null)).toBe(false);
+  });
+});
+
 // resolveResizeCenterAnchorOffset is the UNROTATED (AABB) fallback used only when
 // the element's real transformed corners can't be measured. Center-anchored: a
 // width/height change grows the box from its top-left, drifting the center by half

package/src/components/editor/DomEditOverlay.tsx

@@ -13,6 +13,7 @@ import {
   type GestureState,
   type GroupGestureState,
   focusDomEditOverlayElement,
+  resolveShiftClickCandidate,
 } from "./domEditOverlayGestures";
 import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
 import { OffCanvasIndicators, type OffCanvasRect } from "./OffCanvasIndicators";
@@ -31,6 +32,7 @@ import { startOffCanvasIndicatorRefresh } from "./offCanvasIndicatorRefresh";
 import { CanvasContextMenu } from "./CanvasContextMenu";
 import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
 import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
+import { logSelect } from "../../utils/selectDebug";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -318,6 +320,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const handleOverlayMouseDown = (event: React.MouseEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement) return;
     if (suppressNextOverlayMouseDownRef.current) {
+      logSelect("mousedown-suppressed", { shift: event.shiftKey });
       suppressNextOverlayMouseDownRef.current = false;
       suppressNextBoxMouseDownRef.current = false;
       suppressNextBoxClickRef.current = false;
@@ -326,7 +329,9 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       return;
     }
     const target = event.target as HTMLElement | null;
-    if (target?.closest('[data-dom-edit-selection-box="true"]')) return;
+    const onBox = Boolean(target?.closest('[data-dom-edit-selection-box="true"]'));
+    logSelect("mousedown", { shift: event.shiftKey, onBox });
+    if (onBox) return;
     // Allow clicks anywhere on the overlay — GSAP-translated elements can
     // extend beyond the composition rect into the gray zone, and users need
     // to select/deselect them by clicking there.
@@ -341,8 +346,20 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const handleOverlayPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement || event.button !== 0) return;
     if (event.shiftKey) {
-      // Use the already-updated hover selection rather than re-resolving async
-      const candidate = hoverSelectionRef.current;
+      const shiftIframe = iframeRef.current;
+      const candidate = resolveShiftClickCandidate({
+        cached: hoverSelectionRef.current,
+        elementAtPoint: shiftIframe
+          ? getPreviewTargetFromPointer(
+              shiftIframe,
+              event.clientX,
+              event.clientY,
+              activeCompositionPathRef.current,
+            )
+          : null,
+      });
+      // Not confident: fall through untouched — no preventDefault, no suppression —
+      // so the mousedown path resolves this point instead of guessing here.
       if (!candidate) return;
       event.preventDefault();
       event.stopPropagation();
@@ -376,28 +393,27 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       const overlayEl = overlayRef.current;
       if (overlayEl) {
         const oRect = overlayEl.getBoundingClientRect();
+        // Anywhere empty on the overlay starts one, not just inside the frame.
+        // An element dragged past the edge sits OUT there in the grey, and a
+        // rubber band that refuses to start there cannot reach it — which left
+        // the timeline as the only way to select something you can plainly see.
+        // The hit test collects in overlay space and never clipped to the frame,
+        // so those elements were always selectable once the band could begin.
+        event.preventDefault();
+        event.stopPropagation();
+        suppressNextOverlayMouseDownRef.current = true;
+        (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
         const cx = event.clientX - oRect.left;
         const cy = event.clientY - oRect.top;
-        const inComp =
-          cx >= compRect.left &&
-          cx <= compRect.left + compRect.width &&
-          cy >= compRect.top &&
-          cy <= compRect.top + compRect.height;
-        if (inComp) {
-          event.preventDefault();
-          event.stopPropagation();
-          suppressNextOverlayMouseDownRef.current = true;
-          (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
-          marquee.marqueeRef.current = {
-            startX: cx,
-            startY: cy,
-            currentX: cx,
-            currentY: cy,
-            pointerId: event.pointerId,
-            pastThreshold: false,
-          };
-          return;
-        }
+        marquee.marqueeRef.current = {
+          startX: cx,
+          startY: cy,
+          currentX: cx,
+          currentY: cy,
+          pointerId: event.pointerId,
+          pastThreshold: false,
+        };
+        return;
       }
     }
   };
@@ -503,6 +519,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
               top: cr.top,
               width: cr.width,
               height: cr.height,
+              transform: cr.angle ? `rotate(${cr.angle}deg)` : undefined,
             }}
           />
         ))}

package/src/components/editor/domEditOverlayGeometry.test.ts

@@ -5,6 +5,7 @@ import {
   orientedGroupAwareOverlayRect,
   overlayCornersCentroid,
   selectionCacheKey,
+  orientedVisibleOverlayRect,
 } from "./domEditOverlayGeometry";
 
 describe("overlayCornersCentroid", () => {
@@ -67,6 +68,17 @@ describe("orientedOverlayRect — rotation gate (perf fix, V15 18a/18b)", () =>
         number,
       ];
     }
+    /** `this` applied outside `other`, the way an ancestor composes over a child. */
+    multiply(other: { a: number; b: number; c: number; d: number; e: number; f: number }) {
+      const out = new (this.constructor as new (init?: string) => this)();
+      out.a = this.a * other.a + this.c * other.b;
+      out.b = this.b * other.a + this.d * other.b;
+      out.c = this.a * other.c + this.c * other.d;
+      out.d = this.b * other.c + this.d * other.d;
+      out.e = this.a * other.e + this.c * other.f + this.e;
+      out.f = this.b * other.e + this.d * other.f + this.f;
+      return out;
+    }
     transformPoint(pt: { x: number; y: number }) {
       return {
         x: this.a * pt.x + this.c * pt.y + this.e,
@@ -148,6 +160,30 @@ describe("orientedOverlayRect — rotation gate (perf fix, V15 18a/18b)", () =>
     expect(rect!.angle ?? 0).toBe(0);
   });
 
+  /**
+   * A child outline is drawn ON the child, not around it. Measured axis-aligned,
+   * a text layer inside a rotated card got an upright dashed box sitting across
+   * the rotated glyphs — the parent's chrome rotated and its children's did not.
+   */
+  it("child outlines carry the element's angle, so they can co-rotate with it", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    el.style.transform = ROTATE_30DEG_MATRIX;
+    const rect = orientedVisibleOverlayRect(overlayEl, iframe, el);
+    expect(rect).not.toBeNull();
+    expect(rect!.angle).toBeCloseTo(30, 3);
+  });
+
+  it("an unrotated child outline is unchanged — no angle, same box as before", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    const rect = orientedVisibleOverlayRect(overlayEl, iframe, el);
+    expect(rect).not.toBeNull();
+    expect(rect!.angle ?? 0).toBe(0);
+    expect(rect!.left).toBeCloseTo(400, 5);
+    expect(rect!.top).toBeCloseTo(450, 5);
+    expect(rect!.width).toBeCloseTo(200, 5);
+    expect(rect!.height).toBeCloseTo(100, 5);
+  });
+
   it("rotated element takes the corner-geometry path — reports the live angle", () => {
     const { overlayEl, iframe, el } = buildHarness();
     el.style.transform = ROTATE_30DEG_MATRIX;
@@ -156,6 +192,64 @@ describe("orientedOverlayRect — rotation gate (perf fix, V15 18a/18b)", () =>
     expect(rect!.angle).toBeCloseTo(30, 3);
   });
 
+  /**
+   * The selection box is drawn at the size the element PAINTS, which is the
+   * product of every transform between it and the composition root.
+   *
+   * A text layer inside a card carrying `scale(1.2)` was drawn at 1/1.2 of the
+   * text: the top-left was right, because the caller anchors that to the real
+   * bounding rect, and the right and bottom edges fell short. The same read
+   * decides whether to draw the box rotated, so an element inside a rotated
+   * parent got an upright box.
+   */
+  const SCALE_1_2_MATRIX = "matrix(1.2, 0, 0, 1.2, 0, 0)";
+  const MIRROR_X_MATRIX = "matrix(-1, 0, 0, 1, 0, 0)";
+
+  it("sizes the box by the accumulated transform, not the element's own", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    // The element carries no transform; its parent scales it by 1.2, so it
+    // paints at 240x120 and its bounding rect says so.
+    el.parentElement!.style.transform = SCALE_1_2_MATRIX;
+    el.style.transform = ROTATE_30DEG_MATRIX;
+    stubRect(el, { left: 400, top: 450, width: 240, height: 120 });
+
+    const rect = orientedOverlayRect(overlayEl, iframe, el);
+
+    expect(rect).not.toBeNull();
+    // 200x100 local, scaled by the ancestor, then rotated: the oriented box is
+    // the scaled local box, and the AABB it is anchored to is wider again.
+    expect(rect!.width).toBeCloseTo(240, 3);
+    expect(rect!.height).toBeCloseTo(120, 3);
+    expect(rect!.angle).toBeCloseTo(30, 3);
+  });
+
+  it("takes the rotated path when only an ANCESTOR is rotated", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    el.parentElement!.style.transform = ROTATE_30DEG_MATRIX;
+
+    const rect = orientedOverlayRect(overlayEl, iframe, el);
+
+    expect(rect!.angle).toBeCloseTo(30, 3);
+  });
+
+  it("does not misread a mirrored ancestor as a 180-degree rotation", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    el.parentElement!.style.transform = MIRROR_X_MATRIX;
+
+    const rect = orientedOverlayRect(overlayEl, iframe, el);
+
+    expect(rect?.angle ?? 0).toBe(0);
+  });
+
+  it("stops transform composition at the composition root", () => {
+    const { overlayEl, iframe, el } = buildHarness();
+    iframe.contentDocument!.body.style.transform = ROTATE_30DEG_MATRIX;
+
+    const rect = orientedOverlayRect(overlayEl, iframe, el);
+
+    expect(rect?.angle ?? 0).toBe(0);
+  });
+
   it("preserves an ordinary element's rotation through the group-aware entry point", () => {
     const { overlayEl, iframe, el } = buildHarness();
     el.style.transform = ROTATE_30DEG_MATRIX;

package/src/components/editor/domEditOverlayGeometry.ts

@@ -117,6 +117,28 @@ interface ElementTransformSnapshot {
   cs: CSSStyleDeclaration;
 }
 
+/**
+ * The transform from the element's own box to the composition's, ACCUMULATED
+ * over its ancestors rather than read from the element alone.
+ *
+ * What the user sees is the product of every transform between the element and
+ * the composition root, and an element is routinely a child of something
+ * scaled or rotated. Reading only its own transform drew the selection box at
+ * the element's untransformed size: a text layer inside a card carrying
+ * `scale(1.2)` got a box at 1/1.2 of the text, with the top-left correct (the
+ * caller anchors that to the real bounding rect) and the right and bottom
+ * edges falling short. The same read decides whether to draw the box rotated,
+ * so an element inside a rotated parent got an upright box too.
+ *
+ * Only the linear part matters here. Each transform's origin contributes
+ * translation, and the caller discards translation by matching the corners'
+ * bounding box to the element's real one, so composing the matrices alone is
+ * enough and there is no per-ancestor origin to unpick.
+ *
+ * The walk stops at the composition document's root. The canvas zoom lives on
+ * the iframe element in Studio's own document and is applied separately by
+ * `computeOverlayRootScale`; including it here would count it twice.
+ */
 function readElementTransformSnapshot(
   win: Window,
   element: HTMLElement,
@@ -125,7 +147,15 @@ function readElementTransformSnapshot(
   if (!DOMMatrixCtor) return null;
   const cs = win.getComputedStyle(element);
   try {
-    const matrix = new DOMMatrixCtor(cs.transform === "none" ? "" : cs.transform);
+    let matrix = new DOMMatrixCtor();
+    for (let node: HTMLElement | null = element; node; node = node.parentElement) {
+      const transform = node === element ? cs.transform : win.getComputedStyle(node).transform;
+      if (transform && transform !== "none") {
+        // An ancestor applies outside, so it multiplies on the left.
+        matrix = new DOMMatrixCtor(transform).multiply(matrix);
+      }
+      if (node.hasAttribute("data-composition-id")) break;
+    }
     return { matrix, cs };
   } catch {
     return null;
@@ -141,7 +171,16 @@ function readElementTransformSnapshot(
 function rotationDegreesFromMatrix(matrix: DOMMatrix): number {
   const a = Number.isFinite(matrix.a) ? matrix.a : 1;
   const b = Number.isFinite(matrix.b) ? matrix.b : 0;
-  const deg = (Math.atan2(b, a) * 180) / Math.PI;
+  const c = Number.isFinite(matrix.c) ? matrix.c : 0;
+  const d = Number.isFinite(matrix.d) ? matrix.d : 1;
+  const fromX = (Math.atan2(b, a) * 180) / Math.PI;
+  const determinant = a * d - b * c;
+  // A reflection makes one basis direction read 180° away from the authored
+  // rotation. For cursor/handle orientation those directions are equivalent;
+  // choose the representative nearest zero instead of drawing a pure mirror's
+  // rotate handle on the opposite side of the element.
+  const fromY = (Math.atan2(-c, d) * 180) / Math.PI;
+  const deg = determinant < 0 && Math.abs(fromY) < Math.abs(fromX) ? fromY : fromX;
   return Number.isFinite(deg) ? deg : 0;
 }
 
@@ -391,6 +430,24 @@ export function orientedOverlayRect(
   };
 }
 
+/**
+ * `toVisibleOverlayRect`'s oriented twin: the element's crop-hugged box plus its
+ * live rotation, for chrome that has to sit on a rotated element rather than
+ * around it. Rendering the result with `transform: rotate(angle)` about its
+ * centre lands it on the element's real corners.
+ *
+ * At angle 0 `orientedOverlayRect` returns the plain AABB, so an unrotated
+ * element measures exactly as it did before.
+ */
+export function orientedVisibleOverlayRect(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  element: HTMLElement,
+): OverlayRect | null {
+  const rect = orientedOverlayRect(overlayEl, iframe, element);
+  return rect ? { ...rect, ...hugRectForElement(rect, element) } : null;
+}
+
 const OVERLAY_RECT_EPSILON_PX = 0.5;
 const OVERLAY_RECT_ANGLE_EPSILON_DEG = 0.1;
 

package/src/components/editor/domEditOverlayGestures.ts

@@ -10,6 +10,7 @@ import type { GroupOverlayItem, OverlayRect } from "./domEditOverlayGeometry";
 import type { SnapContext } from "./snapTargetCollection";
 import type { SnapGuidesState } from "./SnapGuideOverlay";
 import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
+import { logSelect } from "../../utils/selectDebug";
 
 export type GestureKind = "drag" | "resize" | "rotate";
 
@@ -112,6 +113,47 @@ export function focusDomEditOverlayElement(element: FocusableDomEditOverlay | nu
   element?.focus({ preventScroll: true });
 }
 
+/**
+ * Whether the hover cache may stand in for a hit-test at this point.
+ *
+ * The cache is filled asynchronously as the pointer moves, so it can describe an
+ * element the pointer has already left. That is harmless for drawing a hover
+ * outline and wrong for a shift-click, which would add the stale element to the
+ * selection instead of the one under the pointer. True only when the cached
+ * element IS the element at the point, or contains it — the resolver is allowed
+ * to hand back a clip ancestor of the raw target, and that still describes the
+ * same click.
+ */
+export function hoverCacheDescribesPoint(
+  cachedElement: Element | null | undefined,
+  elementAtPoint: Element | null | undefined,
+): boolean {
+  if (!cachedElement || !elementAtPoint) return false;
+  return cachedElement === elementAtPoint || cachedElement.contains(elementAtPoint);
+}
+
+/**
+ * The element a shift-click should add, or null to let the slower path resolve it.
+ *
+ * Reading the hover cache without checking is safe for a hover outline and wrong
+ * for a shift-click: the click silently adds whatever the pointer last passed
+ * over instead of the element under it, which reads as multi-select picking
+ * things at random. Returning null means "not confident", and the caller must
+ * then fall through untouched so the mousedown path resolves the point properly.
+ */
+export function resolveShiftClickCandidate<T extends { element: Element }>(input: {
+  cached: T | null;
+  elementAtPoint: Element | null;
+}): T | null {
+  const describes = hoverCacheDescribesPoint(input.cached?.element, input.elementAtPoint);
+  logSelect("shift-pointerdown", {
+    candidate: input.cached ? ((input.cached as { selector?: string }).selector ?? null) : null,
+    pointTarget: input.elementAtPoint?.id ?? input.elementAtPoint?.tagName ?? null,
+    cacheIsAboutThisPoint: describes,
+  });
+  return describes ? input.cached : null;
+}
+
 /**
  * Overlay-px translation that keeps the element's CENTER fixed while a corner
  * resizes: a CSS width/height change grows the layout box from its top-left, so

package/src/components/editor/domEditOverlayStartGesture.ts

@@ -33,6 +33,7 @@ import {
 } from "./domEditOverlayGestures";
 import { collectSnapContext, buildExcludeElements } from "./snapTargetCollection";
 import { logResize, resetResizeMoveLog } from "../../utils/resizeDebug";
+import { logDrag, readDragPositions, resetDragMoveLog } from "../../utils/dragDebug";
 
 export function startGroupDrag(
   e: React.PointerEvent<HTMLElement>,
@@ -70,6 +71,22 @@ export function startGroupDrag(
     }
     members.push(result.member);
   }
+  resetDragMoveLog();
+  logDrag("group-start", {
+    // A member whose mapping differs from its neighbours travels a different
+    // distance for the same pointer delta, which is the group coming apart.
+    members: Object.fromEntries(
+      members.map((member) => [
+        member.key,
+        {
+          map: `${member.screenToOffset.a.toFixed(3)},${member.screenToOffset.d.toFixed(3)}`,
+          base: `${Math.round(member.baseGsap.x)},${Math.round(member.baseGsap.y)}`,
+          offset: `${Math.round(member.initialOffset.x)},${Math.round(member.initialOffset.y)}`,
+        },
+      ]),
+    ),
+    at: readDragPositions(members),
+  });
 
   const overlayEl = opts.overlayRef.current;
   const iframe = opts.iframeRef.current;