@hyperframes/studio 0.8.114 → 0.8.115

package/src/hooks/keyframeCacheAstLoad.ts

@@ -81,9 +81,9 @@ async function requestParsedAnimations(
   try {
     const res = await fetch(
       `/api/projects/${encodeURIComponent(projectId)}/gsap-animations/${encodeURIComponent(sourceFile)}`,
-      // Always re-read the freshly-parsed source; no per-call timestamp (which
-      // would defeat caching forever and is a deterministic-render no-no).
-      { cache: "no-store" },
+      // Always revalidate; an unchanged file answers 304. No per-call timestamp
+      // (a deterministic-render no-no).
+      { cache: "no-cache" },
     );
     if (!res.ok) return null;
     const parsed: unknown = await res.json();
@@ -106,9 +106,9 @@ export async function populateKeyframeCacheFromAst(
   projectId: string,
   sf: string,
   doc: Document | null | undefined,
-): Promise<void> {
+): Promise<boolean> {
   const parsed = await fetchParsedAnimations(projectId, sf);
-  if (!parsed) return;
+  if (!parsed) return false;
   const { elements, domClipChildren } = usePlayerStore.getState();
   const mergedByElement = new Map<string, GsapKeyframesData<MergeableKeyframe>>();
   const sourceByElement = new Map<string, GsapAnimation[]>();
@@ -136,4 +136,5 @@ export async function populateKeyframeCacheFromAst(
     }
   }
   replaceKeyframeCacheForFile(sf, mergedByElement, sourceByElement);
+  return true;
 }

package/src/hooks/plainRotation.ts

@@ -1,3 +1,4 @@
+import type { DomEditPersistOutcome } from "./domEditCommitTypes";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { captureStudioRotation, clearStudioRotation } from "../components/editor/manualEdits";
 import { buildClearRotationPatches } from "../components/editor/manualEditsDomPatches";
@@ -17,8 +18,8 @@ export function savePlainRotation(
   { commitPositionPatchToHtml, readOnlyPreview }: Omit<ElementOffsetStagerDeps, "showToast">,
   selection: DomEditSelection,
   next: RotationCommit,
-): Promise<void> {
-  if (readOnlyPreview) return Promise.resolve();
+): Promise<DomEditPersistOutcome | undefined> {
+  if (readOnlyPreview) return Promise.resolve(undefined);
   const { element } = selection;
   const before = captureStudioRotation(element);
   // Legacy marks go in the same write, or a seek puts their angle back; clearing them voids the press read.

package/src/hooks/previewPromotionSelection.test.tsx

@@ -101,7 +101,7 @@ describe("a shadow reload promoted without a host re-render", () => {
       });
       expect(overlayNode).toBe(selection.element);
 
-      const commitPositionPatchToHtml = vi.fn(async () => {});
+      const commitPositionPatchToHtml = vi.fn(async () => undefined);
       await savePlainRotation({ commitPositionPatchToHtml }, selection, { angle: 30 });
       await stageElementOffset(
         { commitPositionPatchToHtml, showToast: vi.fn() },

package/src/hooks/refreshTimelineRowText.test.ts

@@ -0,0 +1,65 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it } from "vitest";
+import { usePlayerStore, type TimelineElement } from "../player/store/playerStore";
+import { refreshTimelineRowText } from "./refreshTimelineRowText";
+
+afterEach(() => {
+  usePlayerStore.getState().reset();
+  document.body.innerHTML = "";
+});
+
+const row = (key: string, selector: string, sourceFile?: string): TimelineElement => ({
+  id: key.split("#").pop()!,
+  key,
+  tag: "p",
+  start: 0,
+  duration: 2,
+  track: 0,
+  selector,
+  selectorIndex: 0,
+  sourceFile,
+  text: { value: "Old" },
+});
+
+describe("refreshTimelineRowText", () => {
+  it("gives the edited layer's row, addressed by its store key, its new words", () => {
+    document.body.innerHTML = `<h1 id="title">New words</h1>`;
+    usePlayerStore.getState().setElements([row("index.html#title", "#title")]);
+
+    refreshTimelineRowText(document.getElementById("title")!);
+
+    expect(usePlayerStore.getState().elements[0]?.text?.value).toBe("New words");
+  });
+
+  it("finds a row known only by its data-hf-id", () => {
+    document.body.innerHTML = `<p data-hf-id="caption-a">New</p>`;
+    usePlayerStore
+      .getState()
+      .setElements([
+        { ...row("index.html#caption-a", ""), selector: undefined, hfId: "caption-a" },
+      ]);
+
+    refreshTimelineRowText(document.querySelector("p")!);
+
+    expect(usePlayerStore.getState().elements[0]?.text?.value).toBe("New");
+  });
+
+  it("finds the row in the edited layer's own composition when two share a selector", () => {
+    document.body.innerHTML = `
+      <div data-composition-id="a" data-composition-file="a.html"><p class="caption">A</p></div>
+      <div data-composition-id="b" data-composition-file="b.html"><p class="caption">B new</p></div>`;
+    usePlayerStore
+      .getState()
+      .setElements([
+        row("a.html#a-caption", ".caption", "a.html"),
+        row("b.html#b-caption", ".caption", "b.html"),
+      ]);
+
+    refreshTimelineRowText(document.querySelectorAll<HTMLElement>(".caption")[1]!);
+
+    expect(usePlayerStore.getState().elements.map((element) => element.text?.value)).toEqual([
+      "Old",
+      "B new",
+    ]);
+  });
+});

package/src/hooks/refreshTimelineRowText.ts

@@ -0,0 +1,29 @@
+import {
+  getTimelineElementIdentity,
+  getTimelineElementSelector,
+  getTimelineElementSelectorIndex,
+  getTimelineElementSourceFile,
+} from "../player/lib/timelineElementHelpers";
+import { readTimelineText } from "../player/lib/timelineText";
+import { usePlayerStore } from "../player/store/playerStore";
+
+/** A text commit skips the preview reload, so the edited layer's row re-reads its words here. */
+export function refreshTimelineRowText(el: HTMLElement): void {
+  const sourceFile = getTimelineElementSourceFile(el);
+  const hfId = el.getAttribute("data-hf-id");
+  const selector = getTimelineElementSelector(el);
+  const selectorIndex = selector
+    ? (getTimelineElementSelectorIndex(el.ownerDocument, el, selector) ?? 0)
+    : 0;
+  const { elements, updateElement } = usePlayerStore.getState();
+  const row = elements.find(
+    (candidate) =>
+      candidate.sourceFile === sourceFile &&
+      (hfId
+        ? candidate.hfId === hfId
+        : !!selector &&
+          candidate.selector === selector &&
+          (candidate.selectorIndex ?? 0) === selectorIndex),
+  );
+  if (row) updateElement(getTimelineElementIdentity(row), { text: readTimelineText(el) });
+}

package/src/hooks/useAnimatedPropertyCommit.test.tsx

@@ -2,17 +2,22 @@
 
 import React, { act } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { parseGsapScript, type GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
 import { mountReactHarness, withInlineLayoutBox } from "./domSelectionTestHarness";
 import { writeSizeWithCrop } from "../components/editor/cropResize";
-import type { CommitMutation } from "./gsapScriptCommitTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
+import type { CommitMutationOptions, CommitMutation } from "./gsapScriptCommitTypes";
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
 afterEach(() => {
+  vi.clearAllMocks();
   document.body.innerHTML = "";
   usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 0 });
 });
@@ -43,7 +48,11 @@ type Commit = (
 /** Renders the hook and hands its commit function to the caller via a ref callback. */
 function renderHookWith(
   animations: GsapAnimation[],
-  onMutation: (mutation: Record<string, unknown>, label: string) => unknown | Promise<unknown>,
+  onMutation: (
+    mutation: Record<string, unknown>,
+    label: string,
+    options: CommitMutationOptions,
+  ) => unknown | Promise<unknown>,
   onReady: (commit: Commit) => void,
   bumpGsapCache = vi.fn(),
   onBatch?: (
@@ -56,9 +65,9 @@ function renderHookWith(
       async (
         _sel: DomEditSelection,
         mutation: Record<string, unknown>,
-        options: { label: string },
+        options: CommitMutationOptions,
       ) => {
-        await onMutation(mutation, options.label);
+        await onMutation(mutation, options.label, options);
       },
       onBatch
         ? {
@@ -401,3 +410,35 @@ describe("useAnimatedPropertyCommit — a size write and its crop are one undo s
     act(() => root.unmount());
   });
 });
+
+it("counts one add when an inspector edit first converts a flat animation", async () => {
+  usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 1 });
+  const flat = parseGsapScript(
+    'const tl = gsap.timeline(); tl.to("#box", { rotationX: 0, duration: 2 }, 0);',
+  ).animations[0]!;
+  const mutations: Record<string, unknown>[] = [];
+  let commit!: Commit;
+  const root = renderHookWith(
+    [flat, keyframedAnim],
+    (mutation, _label, options) => {
+      mutations.push(mutation);
+      trackKeyframeCommit([mutation], { ok: true, changed: true }, options);
+    },
+    (value) => {
+      commit = value;
+    },
+  );
+  try {
+    await act(async () => {
+      await commit(selection, { rotationX: 20 });
+    });
+    expect(mutations.map((mutation) => mutation.type)).toEqual([
+      "convert-to-keyframes",
+      "add-keyframe",
+    ]);
+    expect(trackStudioEvent).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+  } finally {
+    act(() => root.unmount());
+  }
+});

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -333,7 +333,7 @@ async function commitKeyframeProps(
     await commit(
       selection,
       { type: "convert-to-keyframes", animationId: anim.id },
-      { label: "Convert to keyframes", skipReload: true },
+      { label: "Convert to keyframes", keyframeTelemetry: false, skipReload: true },
     );
   }
   const ct = usePlayerStore.getState().currentTime;
@@ -389,7 +389,7 @@ async function commitKeyframeProps(
         duration: roundTo3(newDuration),
         keyframes: remapped,
       },
-      { label: `Edit ${primaryProp} (extended keyframe)`, softReload: true },
+      { label: `Edit ${primaryProp} (extended keyframe)`, keyframeAction: "add", softReload: true },
     );
     return;
   }

package/src/hooks/useBlockedTimelineEditToast.ts

@@ -8,19 +8,28 @@
 
 import { useCallback, useRef } from "react";
 import type { TimelineElement } from "../player";
+import {
+  MAX_HAND_EDIT_CLIPS,
+  type BlockedTimelineEditIntent,
+} from "../player/components/timelineEditing";
 
 const BLOCKED_TOAST_INTERVAL_MS = 1500;
 
 export function useBlockedTimelineEditToast(
   showToast: (message: string, tone?: "info" | "error") => void,
-): (element: TimelineElement) => void {
+): (element: TimelineElement, intent: BlockedTimelineEditIntent) => void {
   const lastAtRef = useRef(0);
   return useCallback(
-    (_element: TimelineElement) => {
+    (_element: TimelineElement, intent: BlockedTimelineEditIntent) => {
       const now = Date.now();
       if (now - lastAtRef.current < BLOCKED_TOAST_INTERVAL_MS) return;
       lastAtRef.current = now;
-      showToast("This clip can't be moved or resized from the timeline yet.", "info");
+      showToast(
+        intent === "edit-many"
+          ? `Select ${MAX_HAND_EDIT_CLIPS} or fewer clips to move or resize by hand, or describe the change.`
+          : "This clip can't be moved or resized from the timeline yet.",
+        "info",
+      );
     },
     [showToast],
   );

package/src/hooks/useDomEditPositionPatchCommit.ts

@@ -33,30 +33,25 @@ export function useDomEditPositionPatchCommit({
         coalesceMs: options.coalesceMs,
         skipRefresh: options.skipRefresh ?? true,
         deferRender: options.deferRender,
-      })
-        .then(() => undefined)
-        .catch((error) => {
-          // A paused save queue is not worth a toast: the paused-save banner is
-          // already on screen, and one toast per blocked edit is what this branch
-          // exists to prevent. It still has to REJECT, though. Swallowing it
-          // resolved the commit, which skipped the caller's revert, so the element
-          // stayed where the drag put it while nothing reached the file.
-          if (error instanceof DomEditSaveQueueOpenError) throw error;
-          if (!wasAlreadyToasted(error)) {
-            showToast(error instanceof Error ? error.message : "Failed to save position");
-          }
-          trackStudioSaveFailure({
-            source: "dom_edit",
-            error,
-            filePath: selection.sourceFile ?? activeCompPath ?? "index.html",
-            mutationType: "position",
-            label: options.label,
-            targetId: selection.id,
-            targetSelector: selection.selector,
-            targetSourceFile: selection.sourceFile,
-          });
-          throw error;
+      }).catch((error) => {
+        // The paused-save banner already explains this refusal. Rethrow so the
+        // caller reverts the preview instead of treating an unsaved edit as committed.
+        if (error instanceof DomEditSaveQueueOpenError) throw error;
+        if (!wasAlreadyToasted(error)) {
+          showToast(error instanceof Error ? error.message : "Failed to save position");
+        }
+        trackStudioSaveFailure({
+          source: "dom_edit",
+          error,
+          filePath: selection.sourceFile ?? activeCompPath ?? "index.html",
+          mutationType: "position",
+          label: options.label,
+          targetId: selection.id,
+          targetSelector: selection.selector,
+          targetSourceFile: selection.sourceFile,
         });
+        throw error;
+      });
     },
     [activeCompPath, persistDomEditOperations, showToast],
   );

package/src/hooks/useDomEditTextCommits.test.tsx

@@ -160,6 +160,21 @@ describe("useDomEditTextCommits", () => {
     };
   }
 
+  it.each([true, false])(
+    "counts in-place text only after a changed write (%s)",
+    async (changed) => {
+      vi.mocked(trackStudioEvent).mockClear();
+      const { persist, save } = richTextProbe();
+      persist.mockResolvedValue({ changed, sourceFile: "private.html", version: "v2" });
+      await save();
+      expect(vi.mocked(trackStudioEvent).mock.calls).toEqual(
+        changed
+          ? [["feature_used", { feature: "text_edit", surface: "preview", method: "field" }]]
+          : [],
+      );
+    },
+  );
+
   it("saves in-place text while the preview is editable, and refreshes the selection it edited", async () => {
     const applyDomSelection = vi.fn();
     const { persist, element, save } = richTextProbe(undefined, () => ({ applyDomSelection }));
@@ -464,3 +479,6 @@ describe("useDomEditTextCommits", () => {
     expect(agentElement.textContent).toBe("Edited");
   });
 });
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+import { trackStudioEvent } from "../utils/studioTelemetry";

package/src/hooks/useDomEditTextCommits.ts

@@ -1,4 +1,6 @@
+import { trackPreviewFeatureUsed } from "../utils/previewFeatureUsage";
 import { useCallback, useRef } from "react";
+import { refreshTimelineRowText } from "./refreshTimelineRowText";
 import { normalizeDomEditStyleValue } from "../utils/studioHelpers";
 import { injectPreviewGoogleFont, injectPreviewImportedFont } from "../utils/studioFontHelpers";
 import {
@@ -63,6 +65,7 @@ async function resyncDomTextSelectionFromPreview(
   if (!doc) return;
   const refreshed = findElementForSelection(doc, selection, activeCompPath);
   if (!refreshed) return;
+  refreshTimelineRowText(refreshed);
   const nextSelection = await buildDomSelectionFromTarget(refreshed);
   if (!nextSelection) return;
   applyDomSelection(nextSelection, { revealPanel: false, preserveGroup: true });
@@ -272,11 +275,12 @@ export function useDomEditTextCommits({
           appliedHtml = element.innerHTML;
         },
         persist: async () => {
-          await persistDomEditOperations(selection, operations, {
+          const result = await persistDomEditOperations(selection, operations, {
             label: "Edit text",
             skipRefresh: true,
             shouldSave: isLatestTextCommit,
           });
+          if (result?.changed) trackPreviewFeatureUsed("text_edit", "field");
         },
         shouldRevert: () => isLatestTextCommit(),
         revert: () => {

package/src/hooks/useDomEditWiring.ts

@@ -104,8 +104,10 @@ export interface UseDomEditWiringParams {
     animId: string,
     resolvedFromValues?: Record<string, number | string>,
   ) => Promise<void>;
-  removeAllKeyframes: (sel: DomEditSelection, animId: string) => Promise<void>;
-  handleDomManualEditsReset: (sel: DomEditSelection) => Promise<void>;
+  removeAllKeyframes: Parameters<typeof useGsapSelectionHandlers>[0]["removeAllKeyframes"];
+  handleDomManualEditsReset: (
+    sel: DomEditSelection,
+  ) => Promise<void | import("./domEditCommitTypes").DomEditPersistOutcome>;
 }
 
 // fallow-ignore-next-line complexity

package/src/hooks/useDomGeometryCommit.test.tsx

@@ -127,7 +127,7 @@ describe("useDomGeometryCommit, from the package entry", () => {
       y: 20,
     });
 
-    expect(outcome).toEqual({ ok: true });
+    expect(outcome).toEqual({ ok: true, changed: true });
     expect(mutations).toEqual([
       expect.objectContaining({ type: "add", targetSelector: "#card", method: "set" }),
     ]);
@@ -146,7 +146,14 @@ describe("useDomGeometryCommit, from the package entry", () => {
         const url = String(input instanceof Request ? input.url : input);
         calls.urls.push(url);
         if (url.includes("/patch-element/")) calls.patches.push(JSON.parse(String(init?.body)));
-        const saved = { ok: true, changed: true, matched: true, content: "AFTER", version: "v2" };
+        const saved = {
+          ok: true,
+          changed: true,
+          matched: true,
+          path: "index.html",
+          content: "AFTER",
+          version: "v2",
+        };
         const body = url.includes("/files/") ? { content: SOURCE } : saved;
         const status = url.includes("/patch-element/") ? patchStatus : 200;
         return new Response(JSON.stringify(body), {
@@ -163,7 +170,10 @@ describe("useDomGeometryCommit, from the package entry", () => {
     const { element, recordEdit, hook, unmount } = renderHost();
 
     const card = makeSelection("card", element);
-    await expect(hook().commitPathOffset(card, { x: 130.5, y: 90 })).resolves.toEqual({ ok: true });
+    await expect(hook().commitPathOffset(card, { x: 130.5, y: 90 })).resolves.toEqual({
+      ok: true,
+      changed: true,
+    });
 
     expect(element.style.getPropertyValue("translate")).toBe("130.5px 90px");
     expect(calls.patches).toEqual([
@@ -185,7 +195,7 @@ describe("useDomGeometryCommit, from the package entry", () => {
 
     await expect(
       hook().commitBoxSize(makeSelection("card", element), { width: 300, height: 90 }),
-    ).resolves.toEqual({ ok: true });
+    ).resolves.toEqual({ ok: true, changed: true });
 
     expect(element.style.getPropertyValue("width")).toBe("300px");
     expect(calls.patches).toEqual([
@@ -247,7 +257,7 @@ describe("useDomGeometryCommit, from the package entry", () => {
         { x: 1, y: 2 },
         { plainTranslate: true },
       ),
-    ).resolves.toEqual({ ok: true });
+    ).resolves.toEqual({ ok: true, changed: true });
     expect(calls.patches).toHaveLength(1);
     unmount();
   });
@@ -396,7 +406,14 @@ describe("useDomGeometryCommit, one word of a staggered phrase", () => {
               headers: { "content-type": "application/json" },
             });
           }
-          return json({ ok: true, changed: true, matched: true, content: "AFTER", version: "v2" });
+          return json({
+            ok: true,
+            changed: true,
+            matched: true,
+            path: "index.html",
+            content: "AFTER",
+            version: "v2",
+          });
         }
         if (url.includes("/api/projects/p1/gsap-mutations/")) {
           calls.gsapMutations.push(JSON.parse(String(init?.body)));
@@ -426,6 +443,7 @@ describe("useDomGeometryCommit, one word of a staggered phrase", () => {
 
     await expect(hook().commitPathOffset(selection, { x: 40, y: 20 })).resolves.toEqual({
       ok: true,
+      changed: true,
     });
 
     expect(calls.gsapMutations).toHaveLength(0);
@@ -455,6 +473,7 @@ describe("useDomGeometryCommit, one word of a staggered phrase", () => {
     ]);
     await expect(hook().commitPathOffset(selection, { x: 40, y: 20 })).resolves.toEqual({
       ok: true,
+      changed: true,
     });
 
     expect(calls.patches).toHaveLength(2);

package/src/hooks/useDomGeometryCommit.ts

@@ -1,3 +1,4 @@
+import type { GeometryCommitResult } from "../utils/previewFeatureUsage";
 import type { RotationCommit } from "../components/editor/rotationDraft";
 import { useCallback, useMemo, useRef, useState } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
@@ -67,7 +68,7 @@ export function useDomGeometryCommit({
 }: UseDomGeometryCommitOptions): DomGeometryCommits {
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
-  const pending = useRef(new Set<Promise<void>>()).current;
+  const pending = useRef(new Set<Promise<GeometryCommitResult | undefined>>()).current;
   const editHistory = useMemo(() => ({ recordEdit }), [recordEdit]);
   const reload = useCallback(
     () => (reloadPreview ? reloadPreview() : iframeRef.current?.contentWindow?.location.reload()),
@@ -142,7 +143,10 @@ export function useDomGeometryCommit({
     updateArcSegment: gsap.updateArcSegment,
   });
   const saved = useCallback(
-    async (commit: () => Promise<void>, restore = noop): Promise<DomEditCommitOutcome> => {
+    async (
+      commit: () => Promise<GeometryCommitResult | undefined>,
+      restore = noop,
+    ): Promise<DomEditCommitOutcome> => {
       const refusal = !projectIdRef.current
         ? "No project is open"
         : !isPreviewBooted(projectIdRef.current)
@@ -156,11 +160,10 @@ export function useDomGeometryCommit({
       const run = commit();
       pending.add(run);
       try {
-        await run;
+        return { ok: true, changed: (await run)?.changed === true };
       } finally {
         pending.delete(run);
       }
-      return { ok: true };
     },
     [pending, showToast],
   );

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -305,6 +305,7 @@ describe("Reset after a plain move puts the author's translate back", () => {
       async (_selection, patches) => {
         project.history.push(project.file);
         project.file = patches.reduce((html, op) => applyPatch(html, "layer", op), project.file);
+        return undefined;
       },
     );
     const selection = { id: "layer", selector: "#layer", element } as unknown as DomEditSelection;

package/src/hooks/useDomGeometryCommits.ts

@@ -1,3 +1,4 @@
+import type { DomEditPersistOutcome } from "./domEditCommitTypes";
 import type { RotationCommit } from "../components/editor/rotationDraft";
 import { useCallback } from "react";
 import { getDomEditTargetKey, type DomEditSelection } from "../components/editor/domEditing";
@@ -39,7 +40,7 @@ export interface UseDomGeometryCommitsParams {
       skipRefresh?: boolean;
       deferRender?: boolean;
     },
-  ) => Promise<void>;
+  ) => Promise<DomEditPersistOutcome | undefined>;
   readOnlyPreview: boolean;
 }
 
@@ -73,7 +74,7 @@ export function useDomGeometryCommits({
       restore?: () => void,
       undoKey?: string,
     ) => {
-      if (readOnlyPreview) return Promise.resolve();
+      if (readOnlyPreview) return Promise.resolve(undefined);
       const element = selection.element;
       const beforeSize = captureStudioBoxSize(element);
       const beforeOffset = captureStudioPathOffset(element);

package/src/hooks/useDomSelection.test.ts

@@ -334,3 +334,29 @@ describe("useDomSelection", () => {
     harness.cleanup();
   });
 });
+
+it("reports unchanged marquee membership and one new additive member", () => {
+  const { harness, card, chip } = renderCardAndChip();
+  try {
+    act(() => harness.current().applyDomSelection(card));
+    let receipt!: ReturnType<ReturnType<typeof useDomSelection>["applyMarqueeSelection"]>;
+    act(() => {
+      receipt = harness.current().applyMarqueeSelection([chip], true);
+    });
+    expect(receipt).toEqual({ changed: true, count: 2 });
+    act(() => {
+      receipt = harness.current().applyMarqueeSelection([card, chip], true);
+    });
+    expect(receipt).toEqual({ changed: false, count: 2 });
+    act(() => {
+      receipt = harness.current().applyMarqueeSelection([], true);
+    });
+    expect(receipt).toEqual({ changed: false, count: 2 });
+    act(() => {
+      receipt = harness.current().applyMarqueeSelection([], false);
+    });
+    expect(receipt).toEqual({ changed: true, count: 0 });
+  } finally {
+    harness.cleanup();
+  }
+});

package/src/hooks/useDomSelection.ts

@@ -487,12 +487,13 @@ export function useDomSelection({
     // fallow-ignore-next-line complexity
     (selections: DomEditSelection[], additive: boolean) => {
       logSelect("marquee", { hits: selections.length, additive });
+      const current = domEditSelectionRef.current;
+      const currentGroup = domEditGroupSelectionsRef.current;
       if (selections.length === 0) {
+        const count = seedDomEditGroupWithSelection(currentGroup, current).length;
         if (!additive) applyDomSelection(null, { revealPanel: false });
-        return;
+        return { changed: !additive && count > 0, count: additive ? count : 0 };
       }
-      const current = domEditSelectionRef.current;
-      const currentGroup = domEditGroupSelectionsRef.current;
       let nextGroup: DomEditSelection[];
       if (additive) {
         nextGroup = seedDomEditGroupWithSelection(currentGroup, current);
@@ -507,11 +508,17 @@ export function useDomSelection({
         }
       }
       const nextSelection = additive && current ? current : selections[0];
+      const previous = seedDomEditGroupWithSelection(currentGroup, current);
+      const changed =
+        previous.length !== nextGroup.length ||
+        nextGroup.some((selection) => !domEditSelectionInGroup(previous, selection)) ||
+        !domEditSelectionsTargetSame(current, nextSelection);
       domEditSelectionRef.current = nextSelection;
       domEditGroupSelectionsRef.current = nextGroup;
       setDomEditSelection(nextSelection);
       setDomEditGroupSelections(nextGroup);
       announceTimelineSelection(nextGroup, nextSelection, true);
+      return { changed, count: nextGroup.length };
     },
     [applyDomSelection, announceTimelineSelection],
   );

package/src/hooks/useDomSelectionTypes.ts

@@ -3,6 +3,11 @@ import type { DomEditSelection } from "../components/editor/domEditing";
 import type { SelectElementOptions, TimelineElement } from "../player";
 import type { RightPanelTab } from "../utils/studioHelpers";
 
+export interface DomSelectionResult {
+  changed: boolean;
+  count: number;
+}
+
 export interface ApplyDomSelectionOptions {
   revealPanel?: boolean;
   additive?: boolean;
@@ -85,5 +90,5 @@ export interface UseDomSelectionReturn {
   handleTimelineElementSelect: (element: TimelineElement | null) => Promise<void>;
   refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => Promise<void>;
   refreshDomEditGroupSelectionsFromPreview: (selections: DomEditSelection[]) => Promise<void>;
-  applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => void;
+  applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => DomSelectionResult;
 }