@hyperframes/studio 0.8.114 → 0.8.116

package/src/hooks/gsapDragPositionCommit.ts

@@ -1,8 +1,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { PROPERTY_GROUPS } from "@hyperframes/parsers/gsap-constants";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import { resolveTweenStart } from "../utils/globalTimeCompiler";
 import { KEYFRAME_PCT_MATCH, resolveEditableTweenDuration } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
@@ -10,8 +9,9 @@ import {
   type GsapDragCommitCallbacks,
   computeCurrentPercentage,
   parkPlayheadOnKeyframe,
-  materializeIfDynamic,
 } from "./gsapDragCommit";
+import type { GsapEditOutcome } from "./gsapEditOutcome";
+import { commitValueAtPlayhead, planValueEdit } from "./gsapValueAtPlayhead";
 
 /**
  * The tween's keyframes with one inserted at `percentage`. Any existing keyframe
@@ -38,232 +38,26 @@ export function buildTemporalArcKeyframes(
   ].sort((a, b) => a.percentage - b.percentage);
 }
 
-async function extendTweenAndAddKeyframe(
+/** commitGsapPositionFromDrag's refusal, decided without writing. */
+export function gsapPositionFromDragOutcome(
   selection: DomEditSelection,
   anim: GsapAnimation,
-  properties: Record<string, number>,
-  targetTime: number,
-  tweenStart: number,
-  tweenDuration: number,
-  callbacks: GsapDragCommitCallbacks,
-  beforeReload?: () => void,
-  backfillDefaults?: Record<string, number>,
-): Promise<void> {
-  const tweenEnd = tweenStart + tweenDuration;
-  const newStart = Math.min(targetTime, tweenStart);
-  const newEnd = Math.max(targetTime, tweenEnd);
-  const newDuration = Math.max(0.01, newEnd - newStart);
-  const existingKfs = anim.keyframes?.keyframes ?? [];
-  const remappedKfs: Array<{ percentage: number; properties: Record<string, number | string> }> =
-    [];
-  for (const kf of existingKfs) {
-    const absTime = tweenStart + (kf.percentage / 100) * tweenDuration;
-    const newPct = Math.round(((absTime - newStart) / newDuration) * 1000) / 10;
-    const props: Record<string, number | string> = { ...kf.properties };
-    for (const k of Object.keys(properties)) {
-      if (!(k in props) && backfillDefaults?.[k] != null) props[k] = backfillDefaults[k];
-    }
-    remappedKfs.push({ percentage: newPct, properties: props });
-  }
-
-  const targetPct = Math.round(((targetTime - newStart) / newDuration) * 1000) / 10;
-  remappedKfs.push({ percentage: targetPct, properties });
-
-  remappedKfs.sort((a, b) => a.percentage - b.percentage);
-
-  await callbacks.commitMutation(
-    selection,
-    {
-      type: "replace-with-keyframes",
-      animationId: anim.id,
-      targetSelector: anim.targetSelector,
-      position: roundTo3(newStart),
-      duration: roundTo3(newDuration),
-      keyframes: remappedKfs,
-    },
-    { label: `Move layer (extended keyframe)`, softReload: true, beforeReload },
-  );
-}
-
-// fallow-ignore-next-line complexity
-async function commitKeyframedPosition(
-  selection: DomEditSelection,
-  anim: GsapAnimation,
-  properties: Record<string, number>,
-  callbacks: GsapDragCommitCallbacks,
-  beforeReload?: () => void,
-  backfillDefaults?: Record<string, number>,
-): Promise<void> {
-  const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
-  const computedPct = computeCurrentPercentage(selection, anim);
-  const pct = activeKeyframePct ?? computedPct;
-  await callbacks.commitMutation(
-    selection,
-    {
-      type: "add-keyframe",
-      animationId: anim.id,
-      percentage: pct,
-      properties,
-      ...(backfillDefaults ? { backfillDefaults } : {}),
-    },
-    { label: `Move layer (keyframe ${pct}%)`, softReload: true, beforeReload },
-  );
-  if (activeKeyframePct != null) {
-    setActiveKeyframePct(null);
-    parkPlayheadOnKeyframe(anim, pct);
-  }
-}
-
-interface DragRuntimeGsap {
-  getProperty: (target: Element, key: string) => unknown;
-  set: (target: Element, vars: Record<string, unknown>) => void;
-}
-interface DragRuntimeTimeline {
-  seek: (time: number) => void;
-}
-interface DragRuntime {
-  gsapLib: DragRuntimeGsap;
-  el: Element;
-  mainTl: DragRuntimeTimeline;
-}
-
-function resolveDragRuntime(
-  iframe: HTMLIFrameElement | null | undefined,
-  selector: string | undefined,
-): DragRuntime | null {
-  if (!iframe || !selector) return null;
-  const win = iframe.contentWindow as
-    | (Window & {
-        gsap?: Partial<DragRuntimeGsap>;
-        __timelines?: Record<string, Partial<DragRuntimeTimeline>>;
-      })
-    | null;
-  const gsap = win?.gsap;
-  if (typeof gsap?.getProperty !== "function" || typeof gsap.set !== "function") return null;
-  let el: Element | null = null;
-  try {
-    el = iframe.contentDocument?.querySelector(selector) ?? null;
-  } catch {
-    return null;
-  }
-  if (!el) return null;
-  const timelines = win?.__timelines;
-  const mainTl = timelines ? Object.values(timelines)[0] : undefined;
-  if (typeof mainTl?.seek !== "function") return null;
-  return {
-    gsapLib: gsap as DragRuntimeGsap,
-    el,
-    mainTl: mainTl as DragRuntimeTimeline,
-  };
-}
-
-// fallow-ignore-next-line complexity
-async function commitFlatViaKeyframes(
-  selection: DomEditSelection,
-  anim: GsapAnimation,
-  properties: Record<string, number>,
-  callbacks: GsapDragCommitCallbacks,
-  beforeReload?: () => void,
-  iframe?: HTMLIFrameElement | null,
-  selector?: string,
-  backfillDefaults?: Record<string, number>,
-): Promise<void> {
-  const ct = usePlayerStore.getState().currentTime;
-  const ts = resolveTweenStart(anim);
-  const td = resolveEditableTweenDuration(anim, selection);
-  const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
-  const outsideRange =
-    activeKeyframePct == null && ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
-
-  const resolvedFromValues: Record<string, number | string> = {};
-  const runtime = resolveDragRuntime(iframe, selector);
-  if (runtime && ts !== null) {
-    const { gsapLib, el, mainTl } = runtime;
-    const draggedValues: Record<string, number> = {};
-    const channelsTheClearWipes = new Set([
-      ...Object.keys(properties),
-      ...PROPERTY_GROUPS.position,
-    ]);
-    for (const key of channelsTheClearWipes) {
-      const v = Number(gsapLib.getProperty(el, key));
-      if (Number.isFinite(v)) draggedValues[key] = v;
-    }
-    try {
-      gsapLib.set(el, { clearProps: Object.keys(properties).join(",") });
-      mainTl.seek(ts);
-      for (const key of Object.keys(properties)) {
-        const v = Number(gsapLib.getProperty(el, key));
-        if (Number.isFinite(v)) resolvedFromValues[key] = roundTo3(v);
-      }
-      mainTl.seek(ct);
-    } catch {
-      for (const key of Object.keys(resolvedFromValues)) delete resolvedFromValues[key];
-    } finally {
-      if (Object.keys(draggedValues).length > 0) gsapLib.set(el, draggedValues);
-    }
-  }
-
-  if (outsideRange && ts !== null) {
-    const coalesceKey = `gsap:convert-drag:${anim.id}`;
-    await callbacks.commitMutation(
-      selection,
-      {
-        type: "convert-to-keyframes",
-        animationId: anim.id,
-        ...(Object.keys(resolvedFromValues).length > 0 ? { resolvedFromValues } : {}),
-      },
-      { label: "Convert to keyframes for drag", skipReload: true, coalesceKey },
-    );
-    const fresh = callbacks.fetchAnimations ? await callbacks.fetchAnimations() : [];
-    // By id first: a target with several tweens (two `to`s on the same selector)
-    // matches the selector lookup on whichever one happens to be first, and the
-    // extend-and-add below would then rewrite a tween the drag never touched.
-    const converted =
-      fresh.find((a) => a.id === anim.id && a.keyframes) ??
-      fresh.find((a) => a.targetSelector === anim.targetSelector && a.keyframes) ??
-      anim;
-    const convertedStart = resolveTweenStart(converted) ?? ts;
-    const convertedDur = resolveTweenDuration(converted) || td;
-    await extendTweenAndAddKeyframe(
-      selection,
-      converted,
-      properties,
-      ct,
-      convertedStart,
-      convertedDur,
-      callbacks,
-      beforeReload,
-    );
-    return;
-  }
-
-  const coalesceKey = `gsap:convert-drag:${anim.id}`;
-  // fallow-ignore-next-line code-duplication
-  await callbacks.commitMutation(
-    selection,
-    {
-      type: "convert-to-keyframes",
-      animationId: anim.id,
-      ...(Object.keys(resolvedFromValues).length > 0 ? { resolvedFromValues } : {}),
-    },
-    { label: "Convert to keyframes for drag", skipReload: true, coalesceKey },
-  );
-  const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
-  const editedSelected = activeKeyframePct != null;
-  if (editedSelected) setActiveKeyframePct(null);
-
-  await callbacks.commitMutation(
-    selection,
-    {
-      type: "add-keyframe",
-      animationId: anim.id,
-      percentage: pct,
-      properties,
-      ...(backfillDefaults ? { backfillDefaults } : {}),
-    },
-    { label: `Move layer (keyframe ${pct}%)`, softReload: true, beforeReload, coalesceKey },
+  studioOffset: { x: number; y: number },
+  gsapPos: { x: number; y: number },
+  iframe: HTMLIFrameElement | null,
+): GsapEditOutcome {
+  if (anim.arcPath?.enabled) return { status: "persisted" };
+  const { newX, newY, baseGsapX, baseGsapY } = computeDraggedGsapPosition(
+    selection.element,
+    studioOffset,
+    gsapPos,
   );
-  if (editedSelected) parkPlayheadOnKeyframe(anim, pct);
+  const plan = planValueEdit(selection, anim, { x: newX, y: newY }, iframe, {
+    backfill: { x: baseGsapX, y: baseGsapY },
+  });
+  return plan.ok
+    ? { status: "persisted" }
+    : { status: "blocked", reason: "keyframes-uneditable", detail: plan.reason };
 }
 
 // fallow-ignore-next-line code-duplication
@@ -274,9 +68,8 @@ export async function commitGsapPositionFromDrag(
   studioOffset: { x: number; y: number },
   gsapPos: { x: number; y: number },
   iframe: HTMLIFrameElement | null,
-  selector: string,
   callbacks: GsapDragCommitCallbacks,
-): Promise<void> {
+): Promise<GsapEditOutcome> {
   const el = selection.element;
   // fallow-ignore-next-line code-duplication
   const { newX, newY, baseGsapX, baseGsapY } = computeDraggedGsapPosition(
@@ -293,8 +86,6 @@ export async function commitGsapPositionFromDrag(
     el.removeAttribute("data-hf-drag-initial-offset-y");
   };
 
-  const backfillDefaults: Record<string, number> = { x: baseGsapX, y: baseGsapY };
-  const ct = usePlayerStore.getState().currentTime;
   if (anim.arcPath?.enabled) {
     const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
     const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
@@ -319,14 +110,15 @@ export async function commitGsapPositionFromDrag(
       );
       setActiveKeyframePct(null);
       parkPlayheadOnKeyframe(anim, pct);
-      return;
+      return { status: "persisted" };
     }
 
     const tweenStart = resolveTweenStart(anim);
     // Clip-wide, same as applyArcKeyframeAtPlayhead: authoring GSAP's 0.5s
     // default here would collapse a duration-less arc's window on drag.
     const tweenDuration = resolveEditableTweenDuration(anim, selection);
-    if (tweenStart === null || tweenDuration <= 0 || keyframes.length < 2) return;
+    if (tweenStart === null || tweenDuration <= 0 || keyframes.length < 2)
+      return { status: "persisted" };
     const temporalKeyframes = buildTemporalArcKeyframes(anim, pct, { x: newX, y: newY });
     await callbacks.commitMutation(
       selection,
@@ -339,158 +131,18 @@ export async function commitGsapPositionFromDrag(
         keyframes: temporalKeyframes,
         ease: "none",
       },
-      { label: "Move layer (new keyframe)", softReload: true, beforeReload: restoreOffset },
-    );
-    return;
-  }
-  if (anim.keyframes) {
-    const newId = await materializeIfDynamic(anim, iframe, callbacks.commitMutation, selection);
-    const effectiveAnim = newId ? { ...anim, id: newId } : anim;
-    const dragProps: Record<string, number> = { x: newX, y: newY };
-
-    const ts = resolveTweenStart(effectiveAnim);
-    const td = resolveEditableTweenDuration(effectiveAnim, selection);
-    const outsideRange = ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
-    const hasSelectedKeyframe = usePlayerStore.getState().activeKeyframePct != null;
-    if (outsideRange && !hasSelectedKeyframe) {
-      await extendTweenAndAddKeyframe(
-        selection,
-        effectiveAnim,
-        dragProps,
-        ct,
-        ts,
-        td,
-        callbacks,
-        restoreOffset,
-        backfillDefaults,
-      );
-    } else {
-      await commitKeyframedPosition(
-        selection,
-        effectiveAnim,
-        dragProps,
-        callbacks,
-        restoreOffset,
-        backfillDefaults,
-      );
-    }
-  } else if (anim.method === "from" || anim.method === "fromTo") {
-    const ct = usePlayerStore.getState().currentTime;
-    const ts = resolveTweenStart(anim);
-    const td = resolveEditableTweenDuration(anim, selection);
-    const hasSelectedKeyframe = usePlayerStore.getState().activeKeyframePct != null;
-    const outsideRange =
-      !hasSelectedKeyframe && ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
-    const dragProps: Record<string, number> = { x: newX, y: newY };
-
-    if (outsideRange && ts !== null) {
-      await callbacks.commitMutation(
-        selection,
-        { type: "split-into-property-groups", animationId: anim.id },
-        { label: "Split from() for drag", skipReload: true },
-      );
-
-      const allAnims = callbacks.fetchAnimations ? await callbacks.fetchAnimations() : [];
-      const existingPosAnim = allAnims.find(
-        (a) => a.propertyGroup === "position" && a.targetSelector === anim.targetSelector,
-      );
-
-      if (existingPosAnim?.keyframes) {
-        const posTs = resolveTweenStart(existingPosAnim);
-        const posTd = resolveEditableTweenDuration(existingPosAnim, selection);
-        if (posTs !== null) {
-          await extendTweenAndAddKeyframe(
-            selection,
-            existingPosAnim,
-            { x: newX, y: newY },
-            ct,
-            posTs,
-            posTd,
-            callbacks,
-            restoreOffset,
-            backfillDefaults,
-          );
-          return;
-        }
-      }
-
-      const newStart = Math.min(ct, ts);
-      const newEnd = Math.max(ct, ts + td);
-      const newDuration = Math.max(0.01, newEnd - newStart);
-      const dragBefore = ct < ts;
-      const origStartPct = Math.round(((ts - newStart) / newDuration) * 1000) / 10;
-      const origEndPct = Math.round(((ts + td - newStart) / newDuration) * 1000) / 10;
-
-      const keyframes: Array<{ percentage: number; properties: Record<string, number | string> }> =
-        [];
-      if (dragBefore) {
-        keyframes.push({ percentage: 0, properties: { x: newX, y: newY } });
-        if (origStartPct > 0.5 && origStartPct < 99.5) {
-          keyframes.push({ percentage: origStartPct, properties: { x: 0, y: 0 } });
-        }
-        keyframes.push({ percentage: 100, properties: { x: 0, y: 0 } });
-      } else {
-        keyframes.push({ percentage: 0, properties: { x: 0, y: 0 } });
-        if (origEndPct > 0.5 && origEndPct < 99.5) {
-          keyframes.push({ percentage: origEndPct, properties: { x: 0, y: 0 } });
-        }
-        keyframes.push({ percentage: 100, properties: { x: newX, y: newY } });
-      }
-      keyframes.sort((a, b) => a.percentage - b.percentage);
-
-      const baseKf = {
-        targetSelector: anim.targetSelector,
-        position: roundTo3(newStart),
-        duration: roundTo3(newDuration),
-        keyframes,
-      };
-      await callbacks.commitMutation(
-        selection,
-        existingPosAnim
-          ? { type: "replace-with-keyframes", animationId: existingPosAnim.id, ...baseKf }
-          : { type: "add-with-keyframes", ...baseKf },
-        { label: "Move layer (from extended)", softReload: true, beforeReload: restoreOffset },
-      );
-    } else {
-      const coalesceKey = `gsap:convert-drag:${anim.id}`;
-      await callbacks.commitMutation(
-        selection,
-        {
-          type: "convert-to-keyframes",
-          animationId: anim.id,
-        },
-        { label: "Convert from() for drag", skipReload: true, coalesceKey },
-      );
-      const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
-      const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
-      if (activeKeyframePct != null) setActiveKeyframePct(null);
-      await callbacks.commitMutation(
-        selection,
-        {
-          type: "add-keyframe",
-          animationId: anim.id,
-          percentage: pct,
-          properties: dragProps,
-          ...(backfillDefaults ? { backfillDefaults } : {}),
-        },
-        {
-          label: `Move layer (keyframe ${pct}%)`,
-          softReload: true,
-          beforeReload: restoreOffset,
-          coalesceKey,
-        },
-      );
-    }
-  } else {
-    await commitFlatViaKeyframes(
-      selection,
-      anim,
-      { x: newX, y: newY },
-      callbacks,
-      restoreOffset,
-      iframe,
-      selector,
-      backfillDefaults,
+      {
+        label: "Move layer (new keyframe)",
+        keyframeAction: "add",
+        softReload: true,
+        beforeReload: restoreOffset,
+      },
     );
+    return { status: "persisted" };
   }
+  return commitValueAtPlayhead(selection, anim, { x: newX, y: newY }, iframe, callbacks, {
+    label: "Move layer",
+    backfill: { x: baseGsapX, y: baseGsapY },
+    beforeReload: restoreOffset,
+  });
 }

package/src/hooks/gsapEditOutcome.ts

@@ -1,6 +1,11 @@
 import { editabilityForProvenance, type GsapAnimation } from "@hyperframes/core/gsap-parser";
 
-export type GsapEditBlockReason = "no-selector" | "unroll-required" | "source-uneditable";
+export type GsapEditBlockReason =
+  | "no-selector"
+  | "unroll-required"
+  | "source-uneditable"
+  | "keyframes-uneditable"
+  | "mixed-files";
 
 /**
  * Which of the nine situations produced a block. The user-facing `reason` stays
@@ -21,7 +26,18 @@ export type GsapEditBlockDetail =
   | "no-position-tween"
   | "live-rotation-no-source-tween"
   | "live-resize-no-source-tween"
-  | "zero-duration-tween";
+  | "zero-duration-tween"
+  | PlayheadEditRefusal;
+
+/** Why an edit at the playhead could not be written as keyframes of the file's tween. */
+export type PlayheadEditRefusal =
+  | "eased-keyframes"
+  | "simple-array-keyframes"
+  | "unknown-ease"
+  | "implicit-end-unknown"
+  | "not-a-tween"
+  | "no-timing"
+  | "shared-tween";
 
 export type GsapEditOutcome =
   | {
@@ -52,6 +68,10 @@ export const GSAP_EDIT_BLOCK_COPY: Record<GsapEditBlockReason, string> = {
   "unroll-required":
     "This motion comes from a helper or loop. Choose Unroll to edit it explicitly.",
   "source-uneditable": "This animation is computed at runtime. Edit the animation in the Code tab.",
+  "keyframes-uneditable":
+    "Studio can't add this edit to the animation's keyframes. Edit this animation in the Code tab.",
+  "mixed-files":
+    "These layers are animated in different files. Move each file's layers separately.",
 };
 
 export class GsapEditBlockedError extends Error {

package/src/hooks/gsapGestureOutcome.test.ts

@@ -0,0 +1,161 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
+import { observeGsapGesture } from "./gsapGestureOutcome";
+import type { CommitMutation, MutationResult } from "./gsapScriptCommitTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+beforeEach(() => vi.clearAllMocks());
+const selection = {} as Parameters<CommitMutation>[0];
+const mutation = {
+  type: "add-keyframe",
+  animationId: "private-target",
+  properties: { text: "private-content" },
+};
+function writer(result?: MutationResult): CommitMutation {
+  const commit: CommitMutation = async (_selection, _mutation, options) => {
+    if (result) options.onResult?.(result);
+  };
+  commit.batch = async (_calls, options) => {
+    if (result) options.onResult?.(result);
+  };
+  return commit;
+}
+
+describe("GSAP gesture usage", () => {
+  it("counts a multi-write add gesture once from successful writer results", async () => {
+    const observed = observeGsapGesture(
+      writer({ ok: true, changed: true, mutationChanges: [true] }),
+    );
+    const onResult = vi.fn();
+    await observed.commit!(
+      selection,
+      { type: "convert-to-keyframes" },
+      { label: "Convert", onResult },
+    );
+    await observed.commit!(selection, mutation, { label: "Add" });
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+    expect(observed.finish()).toEqual({ ok: true, changed: true });
+    expect(onResult).toHaveBeenCalledWith({ ok: true, changed: true, mutationChanges: [true] });
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+  });
+
+  it("counts a batched insertion once", async () => {
+    const observed = observeGsapGesture(
+      writer({ ok: true, changed: true, mutationChanges: [true, true] }),
+    );
+    await observed.commit!.batch!(
+      [
+        { selection, mutation, options: { label: "Add" } },
+        { selection, mutation, options: { label: "Add" } },
+      ],
+      { label: "Add together" },
+    );
+    expect(observed.finish().changed).toBe(true);
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+  });
+
+  it("retains insertion metadata from an earlier member of a mixed batch", async () => {
+    const observed = observeGsapGesture(
+      writer({ ok: true, changed: true, mutationChanges: [true, true] }),
+    );
+    await observed.commit!.batch!(
+      [
+        {
+          selection,
+          mutation: { type: "replace-with-keyframes" },
+          options: { label: "Extend", keyframeAction: "add" },
+        },
+        { selection, mutation: { type: "update-keyframe" }, options: { label: "Update" } },
+      ],
+      { label: "Update" },
+    );
+    observed.finish();
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+  });
+
+  it("uses semantic insertion metadata for a replacement", async () => {
+    const observed = observeGsapGesture(
+      writer({ ok: true, changed: true, mutationChanges: [true] }),
+    );
+    await observed.commit!(
+      selection,
+      { type: "replace-with-keyframes" },
+      { label: "Replace", keyframeAction: "add" },
+    );
+    observed.finish();
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action: "add" });
+  });
+
+  it.each([undefined, { ok: true }, { ok: true, changed: false }, { ok: false, changed: true }])(
+    "does not count resolution without a changed successful write (%j)",
+    async (result) => {
+      const observed = observeGsapGesture(writer(result));
+      await observed.commit!(selection, mutation, { label: "Add" });
+      expect(observed.finish()).toEqual({ ok: true, changed: false });
+      expect(trackStudioEvent).not.toHaveBeenCalled();
+    },
+  );
+
+  it("does not count missing writers or an unfinished group", async () => {
+    expect(observeGsapGesture(null).finish()).toEqual({ ok: true, changed: false });
+    const observed = observeGsapGesture(writer());
+    await observed.commit!(selection, mutation, { label: "Add" });
+    expect(observed.finish(true).changed).toBe(false);
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+
+  it("reports a successful plain DOM gesture without inventing keyframes", () => {
+    expect(observeGsapGesture(null).finish(true).changed).toBe(true);
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+});
+
+it.each([
+  [[false, true], 0],
+  [[true, false], 1],
+  [undefined, 0],
+] as const)(
+  "attributes mixed batches only to changed members (%j)",
+  async (mutationChanges, count) => {
+    const result = {
+      ok: true,
+      changed: true,
+      mutationChanges: mutationChanges && [...mutationChanges],
+    };
+    const observed = observeGsapGesture(writer(result));
+    const mutations = [mutation, { type: "update-property" }];
+    await observed.commit!.batch!(
+      mutations.map((mutation) => ({ selection, mutation, options: { label: "Edit" } })),
+      { label: "Edit" },
+    );
+    expect(observed.finish()).toEqual({ ok: true, changed: true });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(count);
+    if (count) expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+    vi.mocked(trackStudioEvent).mockClear();
+    trackKeyframeCommit(mutations, result, { label: "Edit" });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(count);
+  },
+);
+
+it("excludes a suppressed preparation from mixed-batch attribution", async () => {
+  const result = { ok: true, changed: true, mutationChanges: [true, false] };
+  const calls = [
+    {
+      selection,
+      mutation: { type: "convert-to-keyframes" },
+      options: { label: "Prepare", keyframeTelemetry: false },
+    },
+    { selection, mutation, options: { label: "Add" } },
+  ];
+  const observed = observeGsapGesture(writer(result));
+  await observed.commit!.batch!(calls, { label: "Add" });
+  expect(observed.finish()).toEqual({ ok: true, changed: true });
+  trackKeyframeCommit(
+    calls.map((call) => call.mutation),
+    result,
+    { label: "Add" },
+    calls.map((call) => call.options),
+  );
+  expect(trackStudioEvent).not.toHaveBeenCalled();
+});