@hyperframes/studio 0.8.95 → 0.8.97

package/src/components/editor/manualOffsetDrag.ts

@@ -514,6 +514,7 @@ export function applyManualOffsetNudgeCommit(
 
 function restoreManualOffsetDragMember(member: ManualOffsetDragMember): void {
   restoreStudioPathOffset(member.element, member.initialPathOffset);
+  getOffsetDragGsap(member.element)?.set(member.element, { ...member.baseGsap });
   endStudioManualEditGesture(member.element, member.gestureToken);
 }
 
@@ -525,6 +526,18 @@ export function restoreManualOffsetDragMembers(members: ManualOffsetDragMember[]
   }
 }
 
+// Drop the draft's `translate: none` so the soft reload starts clean (#1673). When GSAP owns
+// the position it folded any translate into its transform, so one still showing applies twice.
+function settleDraftTranslate(element: HTMLElement, gsapOwnsPosition: boolean): void {
+  if (element.style.getPropertyValue("translate") === "none") {
+    element.style.removeProperty("translate");
+  }
+  if (!gsapOwnsPosition) return;
+  const view = element.ownerDocument.defaultView;
+  const underneath = view?.getComputedStyle(element).getPropertyValue("translate");
+  if (underneath && underneath !== "none") element.style.setProperty("translate", "none");
+}
+
 /** Teardown after a COMMITTED drag. */
 export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): void {
   for (const member of members) {
@@ -533,23 +546,17 @@ export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): v
     member.element.removeAttribute("data-hf-drag-initial-offset-y");
     member.element.removeAttribute("data-hf-drag-gsap-base-x");
     member.element.removeAttribute("data-hf-drag-gsap-base-y");
-    // Clear the draft's `translate: none` so the soft reload starts clean —
-    // otherwise button-less pointermoves after the reload compute deltas
-    // from a stale base and fling the element off-screen (#1673).
     // Do NOT clearProps:"transform" — that nukes the committed GSAP position
     // and causes a visual snap-back before the soft reload re-applies it.
-    if (member.element.style.getPropertyValue("translate") === "none") {
-      member.element.style.removeProperty("translate");
-    }
+    const gsapOwnsPosition = Boolean(getOffsetDragGsap(member.element));
     // Migration: when GSAP owns the position (the committed value lives in the
     // GSAP transform), the legacy `--hf-studio-offset` CSS channel is obsolete.
     // Clear it on the LIVE element — otherwise the leftover `translate:
     // var(--hf-studio-offset)` composes with the GSAP transform and the element
     // renders offset by the stale value until a full page reload (the source is
     // already stripped). clearStudioPathOffset leaves `transform` untouched.
-    if (getOffsetDragGsap(member.element)) {
-      clearStudioPathOffset(member.element);
-    }
+    if (gsapOwnsPosition) clearStudioPathOffset(member.element);
+    settleDraftTranslate(member.element, gsapOwnsPosition);
     resumeGsapTimelines(member.element);
   }
 }

package/src/components/editor/shiftDragAxisLock.test.tsx

@@ -0,0 +1,358 @@
+// @vitest-environment happy-dom
+import React, { act, createRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import type { GestureState, GroupGestureState } from "./domEditOverlayGestures";
+import { DomEditGroupChrome, DomEditSelectionChrome } from "./DomEditSelectionChrome";
+import { createManualOffsetDragMember } from "./manualOffsetDrag";
+import { resolveSnapAdjustment } from "./snapEngine";
+import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function gestureHarness(gesture: Partial<GestureState> | null, group: GroupGestureState | null) {
+  const opts = {
+    gestureRef: { current: gesture },
+    groupGestureRef: { current: group },
+    selectionRef: { current: null },
+    hoverSelectionRef: { current: null },
+    boxRef: { current: null },
+    blockedMoveRef: { current: null },
+    rafPausedRef: { current: false },
+    suppressNextBoxClickRef: { current: false },
+    snapGuidesRef: { current: null },
+    setOverlayRect: vi.fn(),
+    setGroupOverlayItems: vi.fn(),
+    onCanvasMouseDown: vi.fn(),
+    onCanvasPointerMoveRef: { current: vi.fn() },
+    onPathOffsetCommitRef: { current: vi.fn() },
+    onGroupPathOffsetCommitRef: { current: vi.fn() },
+  };
+  const handlers = createDomEditOverlayGestureHandlers(opts as never);
+  const pointer = (clientX: number, clientY: number, shiftKey: boolean) =>
+    ({ clientX, clientY, shiftKey, altKey: false }) as never;
+  return { opts, handlers, pointer };
+}
+
+function singleDrag() {
+  const element = document.createElement("div");
+  return gestureHarness(
+    {
+      kind: "drag",
+      mode: "path-offset",
+      selection: { element } as unknown as DomEditSelection,
+      startX: 100,
+      startY: 100,
+      originLeft: 10,
+      originTop: 20,
+      originWidth: 50,
+      originHeight: 40,
+      editScaleX: 1,
+      editScaleY: 1,
+      actualRotation: 0,
+    },
+    null,
+  );
+}
+
+const groupGesture = () =>
+  ({ startX: 100, startY: 100, originItems: [], members: [] }) as unknown as GroupGestureState;
+
+describe("shift+drag locks a move to the axis the pointer travels further on", () => {
+  it("keeps a mostly horizontal single drag on its row", () => {
+    const { opts, handlers, pointer } = singleDrag();
+    handlers.onPointerMove(pointer(130, 108, true));
+    expect(opts.setOverlayRect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ left: 40, top: 20 }),
+    );
+  });
+
+  it("keeps a mostly vertical single drag on its column", () => {
+    const { opts, handlers, pointer } = singleDrag();
+    handlers.onPointerMove(pointer(95, 160, true));
+    expect(opts.setOverlayRect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ left: 10, top: 80 }),
+    );
+  });
+
+  it("frees the drag on the next move once shift is released, and locks again when pressed", () => {
+    const { opts, handlers, pointer } = singleDrag();
+    handlers.onPointerMove(pointer(130, 108, false));
+    expect(opts.setOverlayRect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ left: 40, top: 28 }),
+    );
+    handlers.onPointerMove(pointer(140, 110, true));
+    expect(opts.setOverlayRect).toHaveBeenLastCalledWith(
+      expect.objectContaining({ left: 50, top: 20 }),
+    );
+  });
+
+  it("locks a group drag the same way", () => {
+    const group = groupGesture();
+    const { handlers, pointer } = gestureHarness(null, group);
+    handlers.onPointerMove(pointer(130, 108, true));
+    expect([group.lastSnappedDx, group.lastSnappedDy]).toEqual([30, 0]);
+  });
+
+  it("snaps a locked drag only along its free axis", () => {
+    const target = {
+      id: "t",
+      left: 0,
+      top: 203,
+      right: 400,
+      bottom: 303,
+      centerX: 200,
+      centerY: 253,
+    };
+    const snap = (lockedAxis?: "x" | "y") =>
+      resolveSnapAdjustment({
+        movingRect: { left: 0, top: 0, width: 50, height: 200 },
+        proposedDx: 97,
+        proposedDy: 0,
+        targets: [target],
+        threshold: 6,
+        disabled: false,
+        lockedAxis,
+      } as never);
+    expect(snap().dy).toBe(3);
+    const locked = snap("y");
+    expect(locked.dy).toBe(0);
+    expect(locked.guides.every((guide) => guide.axis === "x")).toBe(true);
+  });
+});
+
+describe("shift+click on a selected box still toggles the element under the pointer", () => {
+  it.each([
+    ["group", () => gestureHarness(null, groupGesture())],
+    ["single", () => singleMemberDrag()],
+  ])(
+    "hands a %s shift press that never travelled to the canvas as an additive click",
+    (_, make) => {
+      const { opts, handlers, pointer } = make();
+      handlers.onPointerUp(pointer(101, 100, true));
+      expect(opts.onCanvasMouseDown).toHaveBeenCalledWith(
+        expect.objectContaining({ shiftKey: true }),
+        expect.objectContaining({ preferClipAncestor: false }),
+      );
+      expect(opts.suppressNextBoxClickRef.current).toBe(true);
+    },
+  );
+
+  it("leaves a plain press on the group box alone", () => {
+    const { opts, handlers, pointer } = gestureHarness(null, groupGesture());
+    handlers.onPointerUp(pointer(101, 100, false));
+    expect(opts.onCanvasMouseDown).not.toHaveBeenCalled();
+  });
+});
+
+describe("a shift press on a selected box starts the drag", () => {
+  const rect = { left: 10, top: 10, width: 200, height: 100, editScaleX: 1, editScaleY: 1 };
+  const gestures = () => ({
+    startGesture: vi.fn(),
+    startGroupDrag: vi.fn(),
+    startBlockedMove: vi.fn(),
+  });
+  const shiftPress = (el: Element) =>
+    act(() => {
+      el.dispatchEvent(
+        new PointerEvent("pointerdown", {
+          bubbles: true,
+          cancelable: true,
+          shiftKey: true,
+          pointerId: 1,
+        }),
+      );
+    });
+
+  function mount(node: (spies: ReturnType<typeof gestures>) => React.ReactNode) {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const spies = gestures();
+    act(() => root.render(node(spies)));
+    const box = host.querySelector<HTMLElement>('[data-dom-edit-selection-box="true"]')!;
+    return { spies, box, unmount: () => act(() => root.unmount()) };
+  }
+
+  const single = (canMove: boolean) =>
+    mount((spies) => (
+      <DomEditSelectionChrome
+        selection={
+          {
+            element: document.createElement("div"),
+            capabilities: { canApplyManualOffset: canMove },
+          } as unknown as DomEditSelection
+        }
+        overlayRect={rect}
+        allowCanvasMovement
+        allowBodyDrag
+        boxRef={createRef()}
+        boxChromeClass=""
+        boxClipPath={undefined}
+        selectionKey="box"
+        groupSelectionCount={0}
+        gestures={spies as never}
+        onBoxMouseDown={vi.fn()}
+        onBoxClick={vi.fn()}
+      />
+    ));
+
+  const group = (groupCanMove: boolean) =>
+    mount((spies) => (
+      <DomEditGroupChrome
+        groupOverlayItems={[]}
+        groupBounds={rect}
+        allowCanvasMovement
+        allowBodyDrag
+        groupCanMove={groupCanMove}
+        gestures={spies as never}
+        onBoxMouseDown={vi.fn()}
+        onBoxClick={vi.fn()}
+      />
+    ));
+
+  it("drags a single selection", () => {
+    const { spies, box, unmount } = single(true);
+    shiftPress(box);
+    expect(spies.startGesture).toHaveBeenCalledWith("drag", expect.anything());
+    unmount();
+  });
+
+  it("drags a group selection", () => {
+    const { spies, box, unmount } = group(true);
+    shiftPress(box);
+    expect(spies.startGroupDrag).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+
+  it("leaves a shift press on a box that cannot move to the multi-select toggle", () => {
+    const one = single(false);
+    shiftPress(one.box);
+    expect(one.spies.startBlockedMove).not.toHaveBeenCalled();
+    one.unmount();
+    const many = group(false);
+    shiftPress(many.box);
+    expect(many.spies.startGroupDrag).not.toHaveBeenCalled();
+    many.unmount();
+  });
+});
+
+type GsapStub = {
+  set: (el: Element, vars: object) => void;
+  getProperty: (el: Element, p: string) => number;
+};
+
+function previewGsap(): GsapStub {
+  const win = window as unknown as { gsap?: GsapStub };
+  if (win.gsap) return win.gsap;
+  const positions = new WeakMap<Element, Record<string, number>>();
+  win.gsap = {
+    set: (el, vars) => positions.set(el, { ...positions.get(el), ...vars }),
+    getProperty: (el, prop) => positions.get(el)?.[prop] ?? 0,
+  };
+  return win.gsap;
+}
+
+function draggableMember(key: string) {
+  const gsap = previewGsap();
+  const element = document.createElement("div");
+  document.body.append(element);
+  gsap.set(element, { x: 10, y: -10 });
+  const selection = {
+    element,
+    capabilities: { canApplyManualOffset: true },
+  } as unknown as DomEditSelection;
+  const result = createManualOffsetDragMember({
+    key,
+    selection,
+    element,
+    rect: { left: 0, top: 0, width: 50, height: 40, editScaleX: 1, editScaleY: 1 },
+  } as never);
+  if (!result.ok) throw new Error(result.reason);
+  const at = () => [gsap.getProperty(element, "x"), gsap.getProperty(element, "y")];
+  return { member: result.member, selection, at };
+}
+
+function singleMemberDrag() {
+  const { member, selection, at } = draggableMember("single");
+  const harness = gestureHarness(
+    {
+      kind: "drag",
+      mode: "path-offset",
+      selection,
+      startX: 100,
+      startY: 100,
+      originLeft: 0,
+      originTop: 0,
+      originWidth: 50,
+      originHeight: 40,
+      editScaleX: 1,
+      editScaleY: 1,
+      actualRotation: 0,
+      pathOffsetMember: member,
+      initialPathOffset: member.initialPathOffset,
+      manualEditDragToken: member.gestureToken,
+    },
+    null,
+  );
+  return { ...harness, at };
+}
+
+function groupMemberDrag() {
+  const a = draggableMember("a");
+  const b = draggableMember("b");
+  const group = { startX: 100, startY: 100, originItems: [], members: [a.member, b.member] };
+  const harness = gestureHarness(null, group as unknown as GroupGestureState);
+  return { ...harness, at: () => [a.at(), b.at()] };
+}
+
+afterEach(() => {
+  delete (window as unknown as { gsap?: GsapStub }).gsap;
+});
+
+describe("a press that stays under the drag threshold puts the preview back where it started", () => {
+  it.each([true, false])("single, shift %s", (shift) => {
+    const { handlers, pointer, at } = singleMemberDrag();
+    handlers.onPointerMove(pointer(102, 100, shift));
+    expect(at()).toEqual([12, -10]);
+    handlers.onPointerUp(pointer(102, 100, shift));
+    expect(at()).toEqual([10, -10]);
+  });
+
+  it.each([true, false])("group, shift %s", (shift) => {
+    const { handlers, pointer, at } = groupMemberDrag();
+    handlers.onPointerMove(pointer(102, 100, shift));
+    handlers.onPointerUp(pointer(102, 100, shift));
+    expect(at()).toEqual([
+      [10, -10],
+      [10, -10],
+    ]);
+  });
+});
+
+describe("a drag that travelled is not a click, even when it ends near its start", () => {
+  it.each([
+    ["single", singleMemberDrag, "onPathOffsetCommitRef"],
+    ["group", groupMemberDrag, "onGroupPathOffsetCommitRef"],
+  ] as const)("commits a %s shift drag instead of toggling", (_, make, commit) => {
+    const { opts, handlers, pointer } = make();
+    handlers.onPointerMove(pointer(180, 100, true));
+    handlers.onPointerMove(pointer(101, 100, true));
+    handlers.onPointerUp(pointer(101, 100, true));
+    expect(opts.onCanvasMouseDown).not.toHaveBeenCalled();
+    expect(opts[commit].current).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("a cancelled drag puts the preview back where it started", () => {
+  it("returns a single drag that travelled to its start and saves nothing", () => {
+    const { opts, handlers, pointer, at } = singleMemberDrag();
+    handlers.onPointerMove(pointer(140, 100, false));
+    expect(at()).toEqual([50, -10]);
+    handlers.clearPointerState({ current: null });
+    expect(at()).toEqual([10, -10]);
+    expect(opts.gestureRef.current).toBeNull();
+    expect(opts.onPathOffsetCommitRef.current).not.toHaveBeenCalled();
+  });
+});

package/src/components/editor/snapEngine.ts

@@ -379,6 +379,7 @@ export function resolveSnapAdjustment(input: {
   disabled: boolean;
   /** Set when the gesture has not travelled far enough for snapping yet. */
   disabledForTravel?: boolean;
+  lockedAxis?: "x" | "y";
 }): SnapResult {
   if (input.disabled || input.disabledForTravel || input.threshold <= 0) {
     return DISABLED_RESULT(input.proposedDx, input.proposedDy);
@@ -407,8 +408,8 @@ export function resolveSnapAdjustment(input: {
     input.threshold,
   );
 
-  const bestX = pickBest(xCandidates);
-  const bestY = pickBest(yCandidates);
+  const bestX = input.lockedAxis === "x" ? null : pickBest(xCandidates);
+  const bestY = input.lockedAxis === "y" ? null : pickBest(yCandidates);
   const adjustedDx = input.proposedDx + (bestX?.adjustment ?? 0);
   const adjustedDy = input.proposedDy + (bestY?.adjustment ?? 0);
 

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -12,7 +12,6 @@ import {
   applyRotationDraftViaGsap,
   endManualOffsetDragMembers,
   restoreManualOffsetDragMembers,
-  resumeGsapTimelines,
 } from "./manualOffsetDrag";
 import {
   applyStudioBoxSize,
@@ -40,6 +39,7 @@ import {
   type UseDomEditOverlayGesturesOptions,
   ROTATED_SNAP_BYPASS_DEGREES,
   hasDomEditRotationChanged,
+  lockDragToDominantAxis,
   resolveDomEditRotationGesture,
 } from "./domEditOverlayGestures";
 import { resolveCenterResizeSize } from "./domEditResizeLocal";
@@ -61,6 +61,13 @@ import { logDrag, logDragSettle, readDragPositions } from "../../utils/dragDebug
 import { createGroupDragMover } from "./groupDragMove";
 import { DomEditSaveQueueOpenError } from "../../utils/domEditSaveQueue";
 
+function isTap(g: { startX: number; startY: number; travelled?: boolean }, e: React.PointerEvent) {
+  return (
+    !g.travelled &&
+    Math.hypot(e.clientX - g.startX, e.clientY - g.startY) < BLOCKED_MOVE_THRESHOLD_PX
+  );
+}
+
 function logGestureCommitFailure(message: string, error: unknown): void {
   if (error instanceof DomEditSaveQueueOpenError) return;
   console.error(message, error);
@@ -136,11 +143,13 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (groupG) {
+      if (!isTap(groupG, e)) groupG.travelled = true;
       moveGroupDrag(groupG, e);
       return;
     }
 
     if (!g || !sel) return;
+    if (!isTap(g, e)) g.travelled = true;
     let dx = e.clientX - g.startX;
     let dy = e.clientY - g.startY;
 
@@ -164,6 +173,9 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (g.kind === "drag") {
+      const lock = lockDragToDominantAxis(dx, dy, e.shiftKey);
+      dx = lock.dx;
+      dy = lock.dy;
       const sc = g.snapContext;
       // Bypass edge-snapping for rotated elements — the snap targets and the
       // snapped rect are axis-aligned, so snapping a rotated box's AABB shifts it
@@ -196,6 +208,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
           gridEdges: sc.gridEdges ?? undefined,
           threshold: SNAP_THRESHOLD_PX,
           disabled: e.altKey,
+          lockedAxis: lock.lockedAxis,
         });
         dx = snap.dx;
         dy = snap.dy;
@@ -302,8 +315,14 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       // ordinary click — which lands between the members, resolves to nothing,
       // and deselects the group the drag just moved.
       opts.suppressNextBoxClickRef.current = true;
-      if (Math.hypot(rawDx, rawDy) < BLOCKED_MOVE_THRESHOLD_PX) {
+      if (isTap(groupG, e)) {
         restoreGroupPathOffsets(groupG);
+        if (e.shiftKey) {
+          opts.onCanvasMouseDown(e as unknown as React.MouseEvent<HTMLDivElement>, {
+            preferClipAncestor: false,
+            hoverSelection: opts.hoverSelectionRef.current,
+          });
+        }
         return;
       }
       const dx = groupG.lastSnappedDx ?? rawDx;
@@ -360,10 +379,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     opts.rafPausedRef.current = false;
     const movedDistance = Math.hypot(e.clientX - g.startX, e.clientY - g.startY);
 
-    if (g.kind === "drag" && movedDistance < BLOCKED_MOVE_THRESHOLD_PX) {
-      restoreStudioPathOffset(sel.element, g.initialPathOffset);
-      endStudioManualEditGesture(sel.element, g.manualEditDragToken);
-      resumeGsapTimelines(sel.element);
+    if (g.kind === "drag" && isTap(g, e)) {
+      if (g.pathOffsetMember) restoreManualOffsetDragMembers([g.pathOffsetMember]);
       if (box) {
         box.style.left = `${g.originLeft}px`;
         box.style.top = `${g.originTop}px`;
@@ -525,9 +542,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     const g = opts.gestureRef.current;
     const sel = g?.selection ?? selectionRef.current;
     if (g?.mode === "path-offset" && sel) {
-      restoreStudioPathOffset(sel.element, g.initialPathOffset);
-      endStudioManualEditGesture(sel.element, g.manualEditDragToken);
-      resumeGsapTimelines(sel.element);
+      if (g.pathOffsetMember) restoreManualOffsetDragMembers([g.pathOffsetMember]);
       restoreGestureOverlayRect(g);
     }
     if (g?.mode === "box-size" && sel) {

package/src/components/ui/Menu.test.tsx

@@ -298,6 +298,27 @@ describe("Popover", () => {
     expect(document.activeElement).toBe(input);
     expect(document.querySelector('[role="menu"]')).toBeNull();
   });
+
+  it("points at its trigger only when asked", async () => {
+    const renderOpen = (arrow: boolean) => {
+      render(
+        <Popover trigger={<button data-testid="trigger">Speed</button>} arrow={arrow} defaultOpen>
+          <span>1x</span>
+        </Popover>,
+      );
+    };
+    renderOpen(false);
+    await settle();
+    expect(one("[role=dialog]", "popup").querySelector("svg")).toBeNull();
+    act(() => mounted?.root.unmount());
+    mounted?.host.remove();
+    mounted = null;
+
+    renderOpen(true);
+    await settle();
+    const arrow = one("[role=dialog] svg", "arrow").parentElement!;
+    expect(arrow.getAttribute("data-side")).toBe("bottom");
+  });
 });
 
 describe("hotkey classification", () => {

package/src/components/ui/Popover.tsx

@@ -14,6 +14,15 @@ type PortalContainer = ComponentPropsWithoutRef<typeof BasePopover.Portal>["cont
 const SIDE_OFFSET = 6;
 const VIEWPORT_MARGIN = 8;
 
+/** The arrow's 14x8 box overlaps the popup's border by 1px, so its fill hides the border where it meets the popup. */
+const ARROW_PX = 7;
+const ARROW_CORNER_CLEARANCE = 10;
+const arrowPlace = cn(
+  "data-[side=bottom]:-top-[7px] data-[side=top]:-bottom-[7px] data-[side=top]:rotate-180",
+  "data-[side=left]:-right-[10px] data-[side=left]:rotate-90",
+  "data-[side=right]:-left-[10px] data-[side=right]:-rotate-90",
+);
+
 interface PopoverProps extends Omit<ComponentPropsWithoutRef<typeof BasePopover.Root>, "children"> {
   /** A single element. It becomes the trigger; no wrapper is added around it. */
   trigger: ReactElement;
@@ -22,6 +31,8 @@ interface PopoverProps extends Omit<ComponentPropsWithoutRef<typeof BasePopover.
   side?: "top" | "bottom" | "left" | "right";
   align?: "start" | "center" | "end";
   sideOffset?: number;
+  /** Points the popup at its trigger. Off by default; the default gap from the trigger grows by the arrow's height. */
+  arrow?: boolean;
   /** Portal target. Pass the shadow root when the trigger lives in one. */
   container?: PortalContainer;
   /** Names the popup for assistive tech. */
@@ -40,7 +51,8 @@ export function Popover({
   children,
   side = "bottom",
   align = "center",
-  sideOffset = SIDE_OFFSET,
+  arrow = false,
+  sideOffset = arrow ? SIDE_OFFSET + ARROW_PX : SIDE_OFFSET,
   container,
   className,
   initialFocus,
@@ -57,6 +69,7 @@ export function Popover({
           align={align}
           sideOffset={sideOffset}
           collisionPadding={VIEWPORT_MARGIN}
+          arrowPadding={ARROW_CORNER_CLEARANCE}
           className="z-200"
         >
           <BasePopover.Popup
@@ -65,6 +78,13 @@ export function Popover({
             data-preview-state={previewState}
             className={cn(popupSurface, "p-3 text-step-11 text-text-1 shadow-popover", className)}
           >
+            {arrow && (
+              <BasePopover.Arrow className={arrowPlace}>
+                <svg width="14" height="8" viewBox="0 0 14 8" aria-hidden="true" className="block">
+                  <path d="M0 8 L7 1 L14 8" className="fill-surface stroke-border-input" />
+                </svg>
+              </BasePopover.Arrow>
+            )}
             {children}
           </BasePopover.Popup>
         </BasePopover.Positioner>

package/src/hooks/domSelectionTimelineMirror.ts

@@ -28,6 +28,7 @@ export function announceTimelineSelection(
   deps: TimelineMirrorDeps,
   group: DomEditSelection[],
   primary: DomEditSelection | null,
+  replaceSet = false,
 ): void {
   const {
     timelineElements,
@@ -72,10 +73,10 @@ export function announceTimelineSelection(
     }
     return;
   }
-  // A late async primary that already belongs to the live set must preserve the
-  // group. A fresh single click does not belong to it, so publish the singleton
-  // first; otherwise `preserveSet` clears the set and sync wipes the canvas.
-  if (group.length > 1 || !getTimelineSelectionSet().has(timelineAnchor)) {
+  // A late async primary inside the live set keeps the group. A click outside it, or a
+  // group the caller states in full (`replaceSet`: shift toggle, marquee, timeline sync), is published
+  // first; otherwise `preserveSet` clears or keeps a stale set and sync undoes the canvas.
+  if (replaceSet || group.length > 1 || !getTimelineSelectionSet().has(timelineAnchor)) {
     setTimelineSelectionSet(publishedMembers);
   }
   setSelectedTimelineElementId(timelineAnchor, { preserveSet: true });