@hyperframes/studio 0.8.96 → 0.8.98

package/src/components/editor/fontAssets.ts

@@ -2,6 +2,8 @@ export interface ImportedFontAsset {
   family: string;
   path: string;
   url: string;
+  weight?: string;
+  style?: "normal" | "italic";
 }
 
 const FONT_EXT_RE = /\.(eot|otf|ttc|ttf|woff2?)$/i;
@@ -9,7 +11,7 @@ const FONT_STYLE_SUFFIX_RE =
   /\s+(thin|extralight|extra light|light|regular|roman|medium|semibold|semi bold|bold|extrabold|extra bold|black|italic|oblique|variable)$/i;
 
 function cssString(value: string): string {
-  return JSON.stringify(value);
+  return JSON.stringify(value).replace(/</g, "\\3c ");
 }
 
 export function fontFamilyFromAssetPath(path: string): string {
@@ -28,5 +30,12 @@ export function fontFamilyFromAssetPath(path: string): string {
 }
 
 export function importedFontFaceCss(asset: ImportedFontAsset, url: string = asset.url): string {
-  return `@font-face { font-family: ${cssString(asset.family)}; src: url(${cssString(url)}); font-display: swap; }`;
+  const weight =
+    asset.weight && /^(?:[1-9]\d{0,2}|1000)(?: (?:[1-9]\d{0,2}|1000))?$/.test(asset.weight)
+      ? ` font-weight: ${asset.weight};`
+      : "";
+  const style = asset.style
+    ? ` font-style: ${asset.style === "italic" ? "italic" : "normal"};`
+    : "";
+  return `@font-face { font-family: ${cssString(asset.family)}; src: url(${cssString(url)});${weight}${style} font-display: swap; }`;
 }

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

@@ -2,13 +2,32 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { FontFamilyField } from "./propertyPanelFont";
+import { sortFontOptions } from "./propertyPanelHelpers";
+
+vi.mock("./propertyPanelHelpers", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./propertyPanelHelpers")>();
+  return { ...actual, sortFontOptions: vi.fn(actual.sortFontOptions) };
+});
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+// The font APIs are stubbed and every family is off the Google lists, so no test reaches the network.
+beforeEach(() => {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => ({
+      ok: true,
+      json: async () => ({ fonts: url.includes("google") ? ["Roboto Slab"] : ["Arial"] }),
+    })),
+  );
+});
+
 afterEach(() => {
   document.body.innerHTML = "";
+  document.head.innerHTML = "";
+  vi.unstubAllGlobals();
 });
 
 describe("FontFamilyField flat trigger", () => {
@@ -17,14 +36,38 @@ describe("FontFamilyField flat trigger", () => {
     document.body.append(host);
     const root = createRoot(host);
     act(() => {
-      root.render(
-        <FontFamilyField flat value="JetBrains Mono" importedFonts={[]} onCommit={vi.fn()} />,
-      );
+      root.render(<FontFamilyField flat value="Georgia" importedFonts={[]} onCommit={vi.fn()} />);
     });
     const trigger = host.querySelector<HTMLButtonElement>('[data-flat-font-trigger="true"]');
     expect(trigger).not.toBeNull();
     expect(trigger?.className).not.toContain("border-neutral-800");
-    expect(host.textContent).toContain("JetBrains Mono");
+    expect(host.textContent).toContain("Georgia");
     act(() => root.unmount());
   });
 });
+
+describe("FontFamilyField font list", () => {
+  it("builds the list only while the dropdown is open", async () => {
+    vi.mocked(sortFontOptions).mockClear();
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const render = (value: string) =>
+      root.render(<FontFamilyField flat value={value} importedFonts={[]} onCommit={vi.fn()} />);
+    try {
+      await act(async () => render("Arial"));
+      // The font lists arrive and the value changes while the dropdown is closed, as during a drag.
+      await act(async () => render("Georgia"));
+      expect(sortFontOptions).not.toHaveBeenCalled();
+
+      const trigger = host.querySelector<HTMLButtonElement>('[data-flat-font-trigger="true"]');
+      await act(async () => trigger?.click());
+      expect(sortFontOptions).toHaveBeenCalledTimes(1);
+      expect(host.textContent).toContain("Roboto Slab");
+      expect(document.head.querySelector('link[href*="fonts.googleapis.com"]')).toBeNull();
+    } finally {
+      act(() => root.unmount());
+      host.remove();
+    }
+  });
+});

package/src/components/editor/propertyPanelFont.tsx

@@ -276,6 +276,7 @@ export function FontFamilyField({
   );
 
   const options = useMemo(() => {
+    if (!open) return [];
     const documentFonts = collectDocumentFontFamilies();
     const googleSet = new Set(googleFonts.map((f) => f.toLowerCase()));
     const taggedLocal = localFonts.map(
@@ -294,7 +295,7 @@ export function FontFamilyField({
         ...DEFAULT_FONT_FAMILIES.map((f): FontOption => ({ family: f, source: "System" })),
       ]),
     );
-  }, [currentFamily, googleFonts, localFonts, projectFontAssets]);
+  }, [open, currentFamily, googleFonts, localFonts, projectFontAssets]);
 
   const filteredOptions = useMemo(() => {
     const matches = options.filter((o) => fontMatchesQuery(o.family, query));

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

@@ -193,7 +193,6 @@ describe("a shift press on a selected box starts the drag", () => {
         selectionKey="box"
         groupSelectionCount={0}
         gestures={spies as never}
-        onBoxMouseDown={vi.fn()}
         onBoxClick={vi.fn()}
       />
     ));
@@ -207,7 +206,6 @@ describe("a shift press on a selected box starts the drag", () => {
         allowBodyDrag
         groupCanMove={groupCanMove}
         gestures={spies as never}
-        onBoxMouseDown={vi.fn()}
         onBoxClick={vi.fn()}
       />
     ));

package/src/components/nle/TimelinePane.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import { Timeline } from "../../player";
 import type { TimelineElement, TimelineTimeRange } from "../../player";
+import type { TimelineProps } from "../../player/components/TimelineTypes";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
 import { AudioMeterStrip } from "./AudioMeterStrip";
 import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
@@ -45,6 +46,7 @@ export interface TimelinePaneProps {
   onPasteClip?: () => Promise<void>;
   onDuplicateClip?: () => Promise<boolean>;
   canPasteClip?: () => boolean;
+  clipMenuItems?: TimelineProps["clipMenuItems"];
 }
 
 export function TimelinePane({
@@ -64,6 +66,7 @@ export function TimelinePane({
   onPasteClip,
   onDuplicateClip,
   canPasteClip,
+  clipMenuItems,
 }: TimelinePaneProps) {
   const {
     seek,
@@ -119,6 +122,7 @@ export function TimelinePane({
               onPasteClip={onPasteClip}
               onDuplicateClip={onDuplicateClip}
               canPasteClip={canPasteClip}
+              clipMenuItems={clipMenuItems}
             />
           </div>
           <AudioMeterStrip />

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 });

package/src/hooks/domStyleCommit.fonts.test.ts

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+import { expect, it } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { ImportedFontAsset } from "../components/editor/fontAssets";
+import { commitDomStyles, type DomStyleCommitContext } from "./domStyleCommit";
+
+const selection = (id: string): DomEditSelection =>
+  ({
+    id,
+    selector: `#${id}`,
+    label: id,
+    tagName: "p",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    textFields: [],
+    inlineStyles: {},
+    computedStyles: {},
+    dataAttributes: {},
+    capabilities: { canSelect: true, canEditStyles: true },
+  }) as unknown as DomEditSelection;
+
+const poppins = (file: string, weight: string): ImportedFontAsset => ({
+  family: "Poppins",
+  path: `assets/fonts/Poppins/${file}`,
+  url: `/preview/assets/fonts/Poppins/${file}`,
+  weight,
+  style: "normal",
+});
+
+it("each font a host hands over is saved as its own face, with the weight and style it draws", async () => {
+  let html = '<html><head></head><body><h1 id="title"></h1><p id="subtitle"></p></body></html>';
+  let listed: ImportedFontAsset | null = null;
+  const context: DomStyleCommitContext = {
+    activeCompPath: "index.html",
+    previewIframeRef: { current: null },
+    showToast: () => undefined,
+    versions: new Map(),
+    resolveImportedFontAsset: () => listed,
+    persistDomEditOperations: (async (
+      _selection: DomEditSelection,
+      _operations: unknown,
+      options?: { prepareContent?: (html: string, sourceFile: string) => string },
+    ) => {
+      html = options?.prepareContent?.(html, "index.html") ?? html;
+    }) as unknown as DomStyleCommitContext["persistDomEditOperations"],
+  };
+  listed = poppins("Poppins-SemiBold.ttf", "600");
+  await commitDomStyles(context, selection("title"), { "font-family": "Poppins" });
+  listed = poppins("Poppins-Regular.ttf", "400");
+  await commitDomStyles(context, selection("subtitle"), { "font-family": "Poppins" });
+  const faces = html.match(/@font-face[^}]*}/g) ?? [];
+  expect(faces).toHaveLength(2);
+  expect(faces[0]).toContain('Poppins-SemiBold.ttf"); font-weight: 600; font-style: normal;');
+  expect(faces[1]).toContain('Poppins-Regular.ttf"); font-weight: 400; font-style: normal;');
+});

package/src/hooks/useAppHotkeys.test.ts

@@ -65,13 +65,14 @@ describe("dispatchPlainKey — select leftward / rightward", () => {
     { ...bgmElement, id: "early", key: "early", start: 0, track: 0 },
     { ...bgmElement, id: "at", key: "at", start: 4, track: 1 },
     { ...bgmElement, id: "late", key: "late", start: 7, track: 2 },
+    { ...bgmElement, id: "gone", key: "gone", start: 0, duration: 2, track: 3 },
   ];
   beforeEach(() => usePlayerStore.setState({ elements: clips, currentTime: 4 }));
 
-  it("[ selects every clip starting before the playhead, on every track", () => {
+  it("[ selects every clip that started before the playhead, crossing clips included", () => {
     const event = press("[");
     dispatchPlainKey(event, "[", callbacks());
-    expect([...usePlayerStore.getState().selectedElementIds]).toEqual(["early"]);
+    expect([...usePlayerStore.getState().selectedElementIds].sort()).toEqual(["early", "gone"]);
     expect(usePlayerStore.getState().selectedElementId).toBe("early");
     expect(event.defaultPrevented).toBe(true);
   });
@@ -84,6 +85,7 @@ describe("dispatchPlainKey — select leftward / rightward", () => {
       expect([...usePlayerStore.getState().selectedElementIds].sort()).toEqual([
         "at",
         "early",
+        "gone",
         "late",
       ]);
     } finally {
@@ -98,11 +100,11 @@ describe("dispatchPlainKey — select leftward / rightward", () => {
     expect(usePlayerStore.getState().activeKeyframePct).toBeNull();
   });
 
-  it("] selects every clip starting at or after the playhead, on every track", () => {
+  it("] selects every clip still running at or after the playhead, crossing clips included", () => {
     dispatchPlainKey(press("]"), "]", callbacks());
     const { selectedElementIds, selectedElementId } = usePlayerStore.getState();
-    expect([...selectedElementIds].sort()).toEqual(["at", "late"]);
-    expect(selectedElementId).toBe("at");
+    expect([...selectedElementIds].sort()).toEqual(["at", "early", "late"]);
+    expect(selectedElementId).toBe("early");
   });
 
   it("selects nothing when no clip is on that side", () => {

package/src/hooks/useClipboard.ts

@@ -11,6 +11,7 @@ import {
   deduplicateIds,
   insertAsSibling,
 } from "../utils/clipboardPayload";
+import { carryLook, renamedIds } from "../utils/clipboardLook";
 import { collectHtmlIds } from "../utils/studioHelpers";
 import { insertTimelineAssetIntoSource } from "../utils/timelineAssetDrop";
 import { extendRootDurationInSource } from "../utils/rootDuration";
@@ -165,15 +166,16 @@ export function pasteElementHtml(
   return insertAsSibling(content, deduped, payload.originSelector, payload.originSelectorIndex);
 }
 
-/** Shared insertion path for paste and duplicate, anchored at the playhead or
- *  the selection's end respectively. Returns the final ids so the caller can
- *  select what it just placed, and the furthest end any clip lands at so the
- *  caller can grow the root composition's duration to cover it. */
+/** Shared insertion path for paste and duplicate, anchored at the playhead or the selection's end. Returns the
+ *  final ids so the caller can select what it placed, and the furthest end any clip lands at so it can grow the
+ *  root duration to cover it. `fromThisFile`: the clips came from `content`, so a renamed copy takes its
+ *  original's look. */
 export function pasteTimelineClips(
   content: string,
   clips: readonly TimelineClipboardClip[],
   anchorTime: number,
   liveElements: readonly TimelineElement[],
+  fromThisFile = false,
 ): { content: string; ids: string[]; requiredEnd: number } {
   const groupMinStart = Math.min(...clips.map((c) => c.start));
   let existingIds = collectHtmlIds(content);
@@ -209,6 +211,11 @@ export function pasteTimelineClips(
       .replace(/data-track-index="[^"]*"/, `data-track-index="${newTrack}"`);
     const withPatched = patchedRootTag + deduped.slice(rootTagEnd + 1);
     result = insertTimelineAssetIntoSource(result, withPatched);
+    if (fromThisFile) {
+      const authored = Number(rootTag.match(/data-start="([^"]*)"/)?.[1]);
+      const authoredStart = Number.isFinite(authored) ? authored : clip.start;
+      result = carryLook(result, renamedIds(reminted, deduped), newStart - authoredStart);
+    }
 
     const id = patchedRootTag.match(ID_ATTR_RE)?.[1];
     if (id) ids.push(id);
@@ -294,7 +301,12 @@ export function useClipboard({
     const sourceFile = targets.elements[0]?.sourceFile || activeCompPath || "index.html";
     return readClips(targets).then((clips) => {
       showToast(clips.length > 1 ? `Copied ${clips.length} clips` : "Copied clip", "info");
-      return { kind: "timeline-clip", clips, sourceFile };
+      return {
+        kind: "timeline-clip",
+        clips,
+        sourceFile,
+        projectId: projectIdRef.current ?? undefined,
+      };
     });
   }, [activeCompPath, findSelectedClips, readClips, showToast]);
 
@@ -364,7 +376,13 @@ export function useClipboard({
       const paste = (originalContent: string) => {
         if (payload.kind !== "timeline-clip") return pasteElementHtml(originalContent, payload);
         const { currentTime, elements } = usePlayerStore.getState();
-        const pasted = pasteTimelineClips(originalContent, payload.clips, currentTime, elements);
+        const pasted = pasteTimelineClips(
+          originalContent,
+          payload.clips,
+          currentTime,
+          elements,
+          payload.sourceFile === targetPath && payload.projectId === pid,
+        );
         pastedIds = pasted.ids;
         // A clip pasted past the current composition end would exist in the
         // file but never appear on the timeline or in playback/export (the
@@ -433,7 +451,7 @@ export function useClipboard({
           .getState()
           .elements.filter((el) => pathOf(el) === targetPath)
           .map((el) => ({ ...el, start: toAuthoredStart(el, el.start) }));
-        const pasted = pasteTimelineClips(originalContent, clips, anchorTime, liveElements);
+        const pasted = pasteTimelineClips(originalContent, clips, anchorTime, liveElements, true);
         ids = pasted.ids;
         return extendRootDurationInSource(pasted.content, pasted.requiredEnd);
       };

package/src/hooks/useCommitPreflightCapabilities.ts

@@ -5,10 +5,8 @@ import { dragEditOutcome, preflightGsapRotationIntercept } from "./gsapRuntimeBr
 import { preflightGsapResizeIntercept } from "./gsapResizePreflight";
 import { GSAP_EDIT_BLOCK_COPY, type GsapEditOutcome } from "./gsapEditOutcome";
 import { fetchParsedAnimations, parseCacheKey } from "./keyframeCacheAstLoad";
-import {
-  gsapSourceFileForSelection,
-  selectElementAnimationsOrRetry,
-} from "./useGsapAnimationFetchFallback";
+import { getAnimationsForElement } from "./gsapElementMatch";
+import { gsapSourceFileForSelection } from "./useGsapAnimationFetchFallback";
 
 interface CommitPreflight {
   offset: GsapEditOutcome;
@@ -23,13 +21,7 @@ function runCommitPreflights(
   group: boolean,
 ): CommitPreflight {
   const target = { id: selection.id ?? null, selector: selection.selector ?? null };
-  const matched = selectElementAnimationsOrRetry(
-    { animations: fileAnimations },
-    target,
-    selection.element,
-  );
-  // A file the server parsed with no tweens at all is a definitive answer here.
-  const animations = matched.kind === "resolved" ? matched.animations : [];
+  const animations = getAnimationsForElement(fileAnimations, target, selection.element);
   return {
     offset: dragEditOutcome(selection, animations, iframe, [], group),
     size: preflightGsapResizeIntercept(selection, animations, iframe),

package/src/hooks/useDomSelection.test.ts

@@ -29,9 +29,13 @@ function renderHarness(
   cleanup: () => void;
   timeline: TimelineSpies;
 } {
+  // Reads back what was last published, as the timeline store does.
+  let publishedSet: ReadonlySet<string> = new Set();
   const timeline: TimelineSpies = {
     setSelectedTimelineElementId: vi.fn(),
-    setTimelineSelectionSet: vi.fn(),
+    setTimelineSelectionSet: vi.fn((ids: Set<string>) => {
+      publishedSet = ids;
+    }),
   };
   const host = document.createElement("div");
   document.body.append(host);
@@ -47,7 +51,7 @@ function renderHarness(
       captionEditMode: false,
       previewIframeRef: { current: null },
       timelineElements: options.timelineElements ?? [],
-      getTimelineSelectionSet: () => new Set(),
+      getTimelineSelectionSet: () => publishedSet,
       setSelectedTimelineElementId: timeline.setSelectedTimelineElementId,
       setTimelineSelectionSet: timeline.setTimelineSelectionSet,
       setRightCollapsed: vi.fn(),
@@ -107,6 +111,17 @@ function timelineElement(domId: string): TimelineElement {
   } as TimelineElement;
 }
 
+function renderCardAndChip() {
+  const card = makeSelection("Card", Object.assign(document.createElement("div"), { id: "card" }));
+  const chip = makeSelection("Chip", Object.assign(document.createElement("div"), { id: "chip" }));
+  document.body.append(card.element, chip.element);
+  const harness = renderHarness(
+    { activeCompPath: "index.html", projectId: "project-1", refreshKey: 0 },
+    { timelineElements: [timelineElement("card"), timelineElement("chip")] },
+  );
+  return { harness, card, chip };
+}
+
 /**
  * A marquee builds the group correctly and then used to lose it: it announced only
  * the primary to the timeline, the timeline is the source of truth for what is
@@ -116,24 +131,9 @@ function timelineElement(domId: string): TimelineElement {
  */
 describe("useDomSelection marquee", () => {
   it("announces every marquee'd element to the timeline, anchored on the primary", () => {
-    const first = document.createElement("div");
-    first.id = "card";
-    const second = document.createElement("div");
-    second.id = "chip";
-    document.body.append(first, second);
-    const harness = renderHarness(
-      { activeCompPath: "index.html", projectId: "project-1", refreshKey: 0 },
-      { timelineElements: [timelineElement("card"), timelineElement("chip")] },
-    );
+    const { harness, card, chip } = renderCardAndChip();
 
-    act(() =>
-      harness
-        .current()
-        .applyMarqueeSelection(
-          [makeSelection("Card", first), makeSelection("Chip", second)],
-          false,
-        ),
-    );
+    act(() => harness.current().applyMarqueeSelection([card, chip], false));
 
     expect(harness.current().domEditGroupSelections).toHaveLength(2);
     expect(harness.timeline.setTimelineSelectionSet).toHaveBeenCalledWith(
@@ -181,20 +181,10 @@ describe("useDomSelection marquee", () => {
  */
 describe("useDomSelection additive", () => {
   it("announces both members when a second element joins the selection", () => {
-    const first = document.createElement("div");
-    first.id = "card";
-    const second = document.createElement("div");
-    second.id = "chip";
-    document.body.append(first, second);
-    const harness = renderHarness(
-      { activeCompPath: "index.html", projectId: "project-1", refreshKey: 0 },
-      { timelineElements: [timelineElement("card"), timelineElement("chip")] },
-    );
+    const { harness, card, chip } = renderCardAndChip();
 
-    act(() => harness.current().applyDomSelection(makeSelection("Card", first)));
-    act(() =>
-      harness.current().applyDomSelection(makeSelection("Chip", second), { additive: true }),
-    );
+    act(() => harness.current().applyDomSelection(card));
+    act(() => harness.current().applyDomSelection(chip, { additive: true }));
 
     expect(harness.current().domEditGroupSelections).toHaveLength(2);
     expect(harness.timeline.setTimelineSelectionSet).toHaveBeenLastCalledWith(
@@ -205,6 +195,40 @@ describe("useDomSelection additive", () => {
     });
     harness.cleanup();
   });
+
+  // The timeline syncs its set back onto the canvas, so a set left at two re-adds the member.
+  it.each([
+    ["shift+click removes a member", "toggle"],
+    ["a marquee catches one member of a live group", "marquee"],
+  ] as const)("publishes the smaller set when %s", (_, shrink) => {
+    const { harness, card, chip } = renderCardAndChip();
+
+    act(() => harness.current().applyMarqueeSelection([card, chip], false));
+    act(() =>
+      shrink === "toggle"
+        ? harness.current().applyDomSelection(chip, { additive: true })
+        : harness.current().applyMarqueeSelection([card], false),
+    );
+
+    expect(harness.current().domEditGroupSelections).toHaveLength(1);
+    expect(harness.timeline.setTimelineSelectionSet).toHaveBeenLastCalledWith(new Set(["card"]));
+    expect(harness.timeline.setSelectedTimelineElementId).toHaveBeenLastCalledWith("card", {
+      preserveSet: true,
+    });
+    harness.cleanup();
+  });
+
+  it("keeps the live set when a single member is re-announced", () => {
+    const { harness, card, chip } = renderCardAndChip();
+
+    act(() => harness.current().applyMarqueeSelection([card, chip], false));
+    act(() => harness.current().applyDomSelection(chip));
+
+    expect(harness.timeline.setTimelineSelectionSet).toHaveBeenLastCalledWith(
+      new Set(["card", "chip"]),
+    );
+    harness.cleanup();
+  });
 });
 
 describe("useDomSelection", () => {

package/src/hooks/useDomSelection.ts

@@ -83,7 +83,7 @@ export function useDomSelection({
   // ── Callbacks ──
 
   const announceTimelineSelection = useCallback(
-    (group: DomEditSelection[], primary: DomEditSelection | null) =>
+    (group: DomEditSelection[], primary: DomEditSelection | null, replaceSet?: boolean) =>
       announceSelectionToTimeline(
         {
           timelineElements,
@@ -93,6 +93,7 @@ export function useDomSelection({
         },
         group,
         primary,
+        replaceSet,
       ),
     [
       getTimelineSelectionSet,
@@ -179,7 +180,7 @@ export function useDomSelection({
             setRightPanelTab("design");
           }
         }
-        announceTimelineSelection(nextGroup, nextSelection);
+        announceTimelineSelection(nextGroup, nextSelection, isAdditiveSelection);
         return;
       }
 
@@ -510,7 +511,7 @@ export function useDomSelection({
       domEditGroupSelectionsRef.current = nextGroup;
       setDomEditSelection(nextSelection);
       setDomEditGroupSelections(nextGroup);
-      announceTimelineSelection(nextGroup, nextSelection);
+      announceTimelineSelection(nextGroup, nextSelection, true);
     },
     [applyDomSelection, announceTimelineSelection],
   );