@hyperframes/studio 0.8.115 → 0.8.117

package/src/hooks/gsapValueAtPlayhead.ts

@@ -0,0 +1,292 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { usePlayerStore } from "../player/store/playerStore";
+import { resolveTweenDuration, resolveTweenStart } from "../utils/globalTimeCompiler";
+import { roundTo3 } from "../utils/rounding";
+import {
+  materializeIfDynamic,
+  parkPlayheadOnKeyframe,
+  type GsapDragCommitCallbacks,
+} from "./gsapDragCommit";
+import type { GsapEditOutcome, PlayheadEditRefusal } from "./gsapEditOutcome";
+import {
+  findParsedTween,
+  parsedImplicitEndValue,
+  parsedTweenEase,
+  withExactStepTimes,
+  withLiveTiming,
+} from "./gsapParsedTween";
+import { KEYFRAME_PCT_MATCH } from "./gsapShared";
+import { tweenReach } from "./gsapTweenReach";
+
+type Props = Record<string, number | string>;
+interface Keyframe {
+  percentage: number;
+  properties: Props;
+  ease?: string;
+  auto?: boolean;
+}
+
+/** A tween's un-animated value of `prop` at its start or end, from GSAP's own parse; null when unknown. */
+export type ImplicitEndValue = (prop: string, end: "start" | "end") => number | null;
+
+export interface PlayheadEdit {
+  anim: GsapAnimation;
+  /** The playhead's composition time, or a keyframe the user selected in the lane. */
+  at: { time: number } | { percentage: number };
+  /** Every channel here must already be animated by `anim`. */
+  values: Record<string, number>;
+  implicitEndValue: ImplicitEndValue;
+  /** The flat tween's ease as GSAP resolved it, for a tween that authors none. */
+  parsedEase?: string | null;
+  /** A channel of the edit the tween does not animate yet, held at this value on its keyframes. */
+  backfill?: Record<string, number>;
+  /** Hold the backfill from the tween's start too, where GSAP would otherwise begin at the old value. */
+  holdFromStart?: boolean;
+}
+
+export type PlayheadEditPlan =
+  | {
+      ok: true;
+      mutation: {
+        type: "replace-with-keyframes";
+        animationId: string;
+        targetSelector: string;
+        position: number;
+        duration: number;
+        keyframes: Keyframe[];
+        easeEach?: string;
+      };
+      /** A keyframe was added, not only changed: keyframe usage counts it as an add. */
+      added: boolean;
+    }
+  | { ok: false; reason: PlayheadEditRefusal };
+
+// GSAP 3.14 defaults: a percentage keyframe eases its segment power1.inOut; an array step is linear.
+const PERCENTAGE_SEGMENT_EASE = "power1.inOut";
+const ARRAY_STEP_EASE = "none";
+const roundPct = (pct: number) => Math.round(pct * 1000) / 1000;
+const isLinear = (ease: string | undefined) => !ease || ease === "none" || ease === "linear";
+
+interface Normalized {
+  keyframes: Keyframe[];
+  easeEach?: string;
+}
+
+function refuse(reason: PlayheadEditRefusal): { ok: false; reason: PlayheadEditRefusal } {
+  return { ok: false, reason };
+}
+
+// fallow-ignore-next-line complexity
+function normalize(edit: PlayheadEdit): Normalized | { reason: PlayheadEditRefusal } {
+  const { anim } = edit;
+  const data = anim.keyframes;
+  if (data) {
+    if (!isLinear(anim.ease) || !isLinear(data.ease)) return { reason: "eased-keyframes" };
+    if (data.format === "simple-array") return { reason: "simple-array-keyframes" };
+    const arrayStep = data.format === "object-array";
+    return {
+      keyframes: data.keyframes.map((kf) => ({
+        ...kf,
+        properties: { ...kf.properties },
+        ...(arrayStep ? { ease: kf.ease ?? ARRAY_STEP_EASE } : {}),
+      })),
+      ...(data.easeEach && !arrayStep ? { easeEach: data.easeEach } : {}),
+    };
+  }
+  // The flat tween's ease becomes easeEach: a top-level ease would leave each segment power1.inOut.
+  const easeEach = anim.ease ?? edit.parsedEase;
+  if (!easeEach) return { reason: "unknown-ease" };
+  const to = { percentage: 100, properties: { ...anim.properties } };
+  if (anim.method === "to") return { keyframes: [to], easeEach };
+  if (anim.method === "fromTo") {
+    return { keyframes: [{ percentage: 0, properties: { ...anim.fromProperties } }, to], easeEach };
+  }
+  if (anim.method === "from") {
+    const end: Props = {};
+    for (const prop of Object.keys(anim.properties)) {
+      const value = edit.implicitEndValue(prop, "end");
+      if (value == null) return { reason: "implicit-end-unknown" };
+      end[prop] = value;
+    }
+    return {
+      keyframes: [
+        { percentage: 0, properties: { ...anim.properties } },
+        { percentage: 100, properties: end },
+      ],
+      easeEach,
+    };
+  }
+  return { reason: "not-a-tween" };
+}
+
+function valueAt(keyframes: Keyframe[], prop: string, side: "first" | "last") {
+  const carrying = keyframes.filter((kf) => kf.properties[prop] != null);
+  const kf = side === "first" ? carrying[0] : carrying.at(-1);
+  return kf ? { percentage: kf.percentage, value: kf.properties[prop]! } : null;
+}
+
+function upsert(keyframes: Keyframe[], percentage: number, properties: Props, ease?: string) {
+  const hit = keyframes.find((kf) => Math.abs(kf.percentage - percentage) <= KEYFRAME_PCT_MATCH);
+  if (hit) {
+    Object.assign(hit.properties, properties);
+    return hit;
+  }
+  const added = { percentage, properties, ...(ease ? { ease } : {}) };
+  keyframes.push(added);
+  return added;
+}
+
+/** Every channel the tween animates, held at its value at the tween's authored start or end. */
+function heldEnds(
+  norm: Normalized,
+  end: "start" | "end",
+  implicit: ImplicitEndValue,
+  backfilled: Record<string, number>,
+) {
+  const props = new Set(norm.keyframes.flatMap((kf) => Object.keys(kf.properties)));
+  const held: Props = {};
+  for (const prop of props) {
+    const known = valueAt(norm.keyframes, prop, end === "start" ? "first" : "last");
+    // A channel holds its last keyframe after it; only a start can be implicit.
+    const value =
+      known && (end === "end" || known.percentage <= 0)
+        ? known.value
+        : (backfilled[prop] ?? implicit(prop, "start"));
+    if (value == null) return null;
+    held[prop] = value;
+  }
+  return held;
+}
+
+/** On a keyframe, change it; between two, add one at the playhead; outside the tween, add one there
+ *  and keep the authored ends. Values come from the file's tween or GSAP's parse, never the DOM. */
+// fallow-ignore-next-line complexity
+export function planValueAtPlayhead(edit: PlayheadEdit): PlayheadEditPlan {
+  const { anim, values } = edit;
+  const start = resolveTweenStart(anim);
+  const duration = resolveTweenDuration(anim);
+  if (start == null || !(duration > 0)) return refuse("no-timing");
+  const norm = normalize(edit);
+  if ("reason" in norm) return refuse(norm.reason);
+  const keyframes = norm.keyframes;
+  const authored = keyframes.length;
+  // GSAP runs `scale` beside scaleX/scaleY and the longhands win, so a per-axis edit splits it.
+  if ("scaleX" in values || "scaleY" in values) {
+    for (const kf of keyframes) {
+      const { scale, ...rest } = kf.properties;
+      if (scale != null) kf.properties = { scaleX: scale, scaleY: scale, ...rest };
+    }
+  }
+  const backfilled: Record<string, number> = {};
+  for (const [prop, value] of Object.entries(edit.backfill ?? {})) {
+    if (!(prop in values) || keyframes.some((kf) => kf.properties[prop] != null)) continue;
+    if (edit.holdFromStart && !keyframes.some((kf) => kf.percentage <= 0))
+      keyframes.unshift({ percentage: 0, properties: {} });
+    for (const kf of keyframes) kf.properties[prop] = value;
+    backfilled[prop] = value;
+  }
+  if (Object.keys(values).some((prop) => !keyframes.some((kf) => kf.properties[prop] != null)))
+    return refuse("implicit-end-unknown");
+  let position = start;
+  let span = duration;
+
+  const pct =
+    "percentage" in edit.at
+      ? edit.at.percentage
+      : roundPct(((edit.at.time - start) / duration) * 100);
+  if (pct >= -KEYFRAME_PCT_MATCH && pct <= 100 + KEYFRAME_PCT_MATCH) {
+    const at = Math.min(100, Math.max(0, pct));
+    const next = [...keyframes]
+      .sort((a, b) => a.percentage - b.percentage)
+      .find((kf) => kf.percentage > at + KEYFRAME_PCT_MATCH);
+    // The new keyframe splits next's segment, so it takes next's ease.
+    upsert(keyframes, at, { ...values }, next?.ease);
+  } else {
+    const time = (edit.at as { time: number }).time;
+    const before = time < start;
+    const held = heldEnds(norm, before ? "start" : "end", edit.implicitEndValue, backfilled);
+    if (!held) return refuse("implicit-end-unknown");
+    position = before ? time : start;
+    span = before ? start + duration - time : time - start;
+    for (const kf of keyframes) {
+      kf.percentage = roundPct(
+        ((start + (kf.percentage / 100) * duration - position) / span) * 100,
+      );
+    }
+    const oldEdge = roundPct((((before ? start : start + duration) - position) / span) * 100);
+    // The span the tween gains is new and linear; the authored segments keep their eases.
+    const linear = isLinear(norm.easeEach ?? PERCENTAGE_SEGMENT_EASE) ? undefined : "none";
+    const edge = upsert(keyframes, oldEdge, held, linear);
+    if (before && linear) edge.ease ??= linear;
+    upsert(keyframes, before ? 0 : 100, { ...held, ...values }, before ? undefined : linear);
+  }
+
+  keyframes.sort((a, b) => a.percentage - b.percentage);
+  return {
+    ok: true,
+    mutation: {
+      type: "replace-with-keyframes",
+      animationId: anim.id,
+      targetSelector: anim.targetSelector,
+      position: roundTo3(position),
+      duration: roundTo3(span),
+      keyframes,
+      ...(norm.easeEach ? { easeEach: norm.easeEach } : {}),
+    },
+    added: keyframes.length > authored,
+  };
+}
+
+/** commitValueAtPlayhead's plan, writing nothing, so a group can plan every member first. */
+export function planValueEdit(
+  selection: DomEditSelection,
+  anim: GsapAnimation,
+  values: Record<string, number>,
+  iframe: HTMLIFrameElement | null,
+  { backfill, holdFromStart }: Pick<PlayheadEdit, "backfill" | "holdFromStart"> = {},
+): PlayheadEditPlan {
+  // One keyframe of a tween its siblings share would move them all.
+  if (tweenReach(anim, selection.element) === "shared") return refuse("shared-tween");
+  const { activeKeyframePct, currentTime } = usePlayerStore.getState();
+  const tween = findParsedTween(iframe, selection.element, anim);
+  const timed = withExactStepTimes(anim, tween);
+  return planValueAtPlayhead({
+    anim: withLiveTiming(timed, tween),
+    at: activeKeyframePct != null ? { percentage: activeKeyframePct } : { time: currentTime },
+    values,
+    backfill,
+    holdFromStart,
+    implicitEndValue: parsedImplicitEndValue(tween),
+    parsedEase: parsedTweenEase(iframe, tween),
+  });
+}
+
+/** Writes `values` into `anim` at the playhead (or the keyframe selected in the lane). */
+export async function commitValueAtPlayhead(
+  selection: DomEditSelection,
+  anim: GsapAnimation,
+  values: Record<string, number>,
+  iframe: HTMLIFrameElement | null,
+  callbacks: GsapDragCommitCallbacks,
+  options: Pick<PlayheadEdit, "backfill" | "holdFromStart"> & {
+    label: string;
+    beforeReload?: () => void;
+  },
+): Promise<GsapEditOutcome> {
+  await materializeIfDynamic(anim, iframe, callbacks.commitMutation, selection);
+  const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
+  const plan = planValueEdit(selection, anim, values, iframe, options);
+  if (!plan.ok) return { status: "blocked", reason: "keyframes-uneditable", detail: plan.reason };
+  await callbacks.commitMutation(selection, plan.mutation, {
+    label: options.label,
+    softReload: true,
+    beforeReload: options.beforeReload,
+    ...(plan.added && { keyframeAction: "add" as const }),
+  });
+  if (activeKeyframePct != null) {
+    setActiveKeyframePct(null);
+    parkPlayheadOnKeyframe(anim, activeKeyframePct);
+  }
+  return { status: "persisted" };
+}

package/src/hooks/gsapWholePropertyOffsetCommit.test.ts

@@ -26,6 +26,29 @@ function recordingCallbacks(): {
   };
 }
 
+/** Rotates a 2s `#box` tween made of `fields` to 50deg at its end; returns what was committed. */
+async function rotateTo50AtEnd(fields: Record<string, unknown>) {
+  const anim = {
+    id: "#box-rotate",
+    targetSelector: "#box",
+    method: "to",
+    resolvedStart: 0,
+    duration: 2,
+    ...fields,
+  } as unknown as GsapAnimation;
+  const { mutations, callbacks } = recordingCallbacks();
+  await commitWholePropertyOffset(
+    selection(),
+    anim,
+    { rotation: 50 },
+    100,
+    null,
+    callbacks,
+    "Rotate",
+  );
+  return mutations;
+}
+
 describe("commitWholePropertyOffset", () => {
   it("shifts every keyframe of a keyframed tween by the delta at the nearest keyframe", async () => {
     const anim = {
@@ -159,4 +182,24 @@ describe("commitWholePropertyOffset", () => {
       { type: "update-properties", animationId: "#box-hold", properties: { width: 300 } },
     ]);
   });
+
+  it("keeps a linear flat tween linear: its ease becomes the keyframes' easeEach", async () => {
+    // A tween-level ease leaves each percentage segment power1.inOut, so the box drifts mid-segment.
+    const mutations = await rotateTo50AtEnd({ ease: "none", properties: { rotation: 40 } });
+    expect(mutations[0]).toMatchObject({ type: "replace-with-keyframes", easeEach: "none" });
+    expect(mutations[0]).not.toHaveProperty("ease", "none");
+  });
+
+  it("keeps a keyframed tween's easeEach", async () => {
+    const mutations = await rotateTo50AtEnd({
+      keyframes: {
+        easeEach: "none",
+        keyframes: [
+          { percentage: 0, properties: { rotation: 10 } },
+          { percentage: 100, properties: { rotation: 40 } },
+        ],
+      },
+    });
+    expect(mutations[0]).toMatchObject({ easeEach: "none" });
+  });
 });

package/src/hooks/gsapWholePropertyOffsetCommit.ts

@@ -6,7 +6,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 import { roundTo3 } from "../utils/rounding";
-import { PROPERTY_DEFAULTS } from "./gsapShared";
+import { keyframeEases, PROPERTY_DEFAULTS } from "./gsapShared";
 import { synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
 import { materializeIfDynamic, type GsapDragCommitCallbacks } from "./gsapDragCommit";
 
@@ -38,7 +38,6 @@ export async function commitWholePropertyOffset(
 
   const ts = resolveTweenStart(effectiveAnim);
   const td = resolveTweenDuration(effectiveAnim);
-  const ease = effectiveAnim.keyframes?.easeEach ?? effectiveAnim.ease;
   const keys = Object.keys(newValues);
   const at = (props: Record<string, number | string>, key: string) =>
     typeof props[key] === "number" ? (props[key] as number) : (PROPERTY_DEFAULTS[key] ?? 0);
@@ -79,7 +78,7 @@ export async function commitWholePropertyOffset(
       position: roundTo3(ts ?? 0),
       duration: roundTo3(td || 1),
       keyframes: shifted,
-      ease,
+      ...keyframeEases(effectiveAnim),
     },
     { label, softReload: true },
   );

package/src/hooks/keyframeCacheAstLoad.ts

@@ -14,6 +14,7 @@ import {
   synthesizeFlatTweenKeyframes,
   type MergeableKeyframe,
 } from "./gsapTweenSynth";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 export { resolveSelectorElementIds };
 
@@ -79,7 +80,7 @@ async function requestParsedAnimations(
 ): Promise<ParsedGsapAnimations | null> {
   if (!isPreviewBooted(projectId) && !(await whenPreviewBooted(projectId))) return null;
   try {
-    const res = await fetch(
+    const res = await studioApiFetch(
       `/api/projects/${encodeURIComponent(projectId)}/gsap-animations/${encodeURIComponent(sourceFile)}`,
       // Always revalidate; an unchanged file answers 304. No per-call timestamp
       // (a deterministic-render no-no).

package/src/hooks/newTweenTarget.test.ts

@@ -13,57 +13,30 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { parseGsapScript } from "@hyperframes/core/gsap-parser";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
-import { buildStableSelector, getSelectorIndex } from "../components/editor/domEditingDom";
+import { mountGroupSiblings, stableSelectionFor } from "./domSelectionTestHarness";
 import { resolveSelectorElementIds } from "./gsapShared";
 import { ensureElementAddressable } from "./gsapScriptCommitHelpers";
 import {
   commitStaticGsapPosition,
   commitStaticGsapRotation,
   commitStaticGsapSize,
-  commitKeyframedSizeFromResize,
   commitWholePathOffset,
   findExistingPositionWrite,
 } from "./gsapDragCommit";
 import { promoteSetToKeyframes } from "./useEnableKeyframes";
+import { commitValueAtPlayhead } from "./gsapValueAtPlayhead";
 
 afterEach(() => {
   document.body.innerHTML = "";
 });
 
-function selectionFor(el: HTMLElement): DomEditSelection {
-  const selector = buildStableSelector(el);
-  return {
-    element: el,
-    id: el.id || undefined,
-    hfId: el.getAttribute("data-hf-id") || undefined,
-    selector,
-    selectorIndex: getSelectorIndex(document, el, selector, "index.html", null),
-    sourceFile: "index.html",
-    dataAttributes: { start: "0", duration: "2" },
-  } as unknown as DomEditSelection;
-}
-
-/** Five class-only siblings, each with an id so attribution is nameable. */
-function mountGroupSiblings(): HTMLElement[] {
-  document.body.innerHTML = `
-    <div id="scene" class="clip" data-start="0" data-duration="2">
-      <div class="group" id="group-0"></div>
-      <div class="group" id="group-1"></div>
-      <div class="group" id="group-2"></div>
-      <div class="group" id="group-3"></div>
-      <div class="group" id="group-4"></div>
-    </div>
-  `;
-  return Array.from(document.querySelectorAll<HTMLElement>(".group"));
-}
-
 /**
  * The selection production hands these writers: the element HAS an id in the
  * DOM (so resolveSelectorElementIds can name it) but the SELECTION carries none,
  * which is the id-less shape buildStableSelector answers with a bare class.
  */
 function classOnlySelection(el: HTMLElement): DomEditSelection {
-  return { ...selectionFor(el), id: undefined, selector: ".group" } as DomEditSelection;
+  return { ...stableSelectionFor(el), id: undefined, selector: ".group" } as DomEditSelection;
 }
 
 /** The elements a written targetSelector actually attributes the tween to. */
@@ -94,7 +67,7 @@ describe("ensureElementAddressable — add-animation button", () => {
       </div>
     `;
     const el = document.querySelectorAll<HTMLElement>(".group")[1]!;
-    const selection = selectionFor(el);
+    const selection = stableSelectionFor(el);
     expect(selection.selector).toBe(".group");
 
     const { selector, autoId } = ensureElementAddressable(selection);
@@ -109,20 +82,20 @@ describe("ensureElementAddressable — add-animation button", () => {
     document.body.innerHTML = `<div id="box" class="card"></div>`;
     const el = document.querySelector<HTMLElement>("#box")!;
 
-    expect(ensureElementAddressable(selectionFor(el)).selector).toBe("#box");
+    expect(ensureElementAddressable(stableSelectionFor(el)).selector).toBe("#box");
   });
 
   it("keeps an already-unique class selector as authored", () => {
     document.body.innerHTML = `<div id="scene"><div class="header"></div></div>`;
     const el = document.querySelector<HTMLElement>(".header")!;
 
-    expect(ensureElementAddressable(selectionFor(el)).selector).toBe(".header");
+    expect(ensureElementAddressable(stableSelectionFor(el)).selector).toBe(".header");
   });
 
   it("still mints an id when there is no live element to disambiguate against", () => {
     document.body.innerHTML = `<div id="scene"><div></div></div>`;
     const el = document.querySelector<HTMLElement>("#scene > div")!;
-    const selection = { ...selectionFor(el), selector: undefined } as DomEditSelection;
+    const selection = { ...stableSelectionFor(el), selector: undefined } as DomEditSelection;
 
     const { selector, autoId } = ensureElementAddressable(selection);
 
@@ -131,25 +104,28 @@ describe("ensureElementAddressable — add-animation button", () => {
   });
 });
 
+/** Moves the middle of five class-only siblings with no position yet; returns the selector written. */
+async function positionMiddleSibling(): Promise<string> {
+  const groups = mountGroupSiblings(5, true);
+  const { mutations, callbacks } = recorder();
+  await commitStaticGsapPosition(
+    classOnlySelection(groups[2]!),
+    { x: 10, y: 10 },
+    { x: 0, y: 0 },
+    ".group",
+    null,
+    callbacks,
+  );
+  return writtenTargets(mutations)[0]!;
+}
+
 describe("gsapDragCommit — new-tween targets", () => {
   it("commitStaticGsapPosition authors the new set against one element", async () => {
-    const groups = mountGroupSiblings();
-    const { mutations, callbacks } = recorder();
-
-    await commitStaticGsapPosition(
-      classOnlySelection(groups[2]!),
-      { x: 10, y: 10 },
-      { x: 0, y: 0 },
-      ".group",
-      null,
-      callbacks,
-    );
-
-    expect(attributedTo(writtenTargets(mutations)[0]!)).toEqual(["group-2"]);
+    expect(attributedTo(await positionMiddleSibling())).toEqual(["group-2"]);
   });
 
   it("commitStaticGsapRotation authors the new set against one element", async () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5, true);
     const { mutations, callbacks } = recorder();
 
     await commitStaticGsapRotation(classOnlySelection(groups[1]!), 42, ".group", null, callbacks);
@@ -158,7 +134,7 @@ describe("gsapDragCommit — new-tween targets", () => {
   });
 
   it("commitStaticGsapSize authors the new set against one element", async () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5, true);
     const { mutations, callbacks } = recorder();
 
     await commitStaticGsapSize(
@@ -172,34 +148,34 @@ describe("gsapDragCommit — new-tween targets", () => {
     expect(attributedTo(writtenTargets(mutations)[0]!)).toEqual(["group-4"]);
   });
 
-  it("commitKeyframedSizeFromResize authors the new keyframe tween against one element", async () => {
-    const groups = mountGroupSiblings();
+  it("a keyframe edit refuses a tween its siblings share instead of moving them all", async () => {
+    const groups = mountGroupSiblings(5, true);
     const { mutations, callbacks } = recorder();
-    const animatedTween = {
+    const sharedTween = {
       id: "t1",
       targetSelector: ".group",
       method: "to",
-      properties: {},
+      properties: { width: 120 },
       resolvedStart: 0,
       duration: 2,
-      keyframes: { keyframes: [{ percentage: 0, properties: { x: 0 } }] },
+      ease: "none",
     } as unknown as GsapAnimation;
 
-    const handled = await commitKeyframedSizeFromResize(
+    const outcome = await commitValueAtPlayhead(
       classOnlySelection(groups[3]!),
-      { width: 80, height: 40 },
-      ".group",
+      sharedTween,
+      { width: 80 },
       null,
-      animatedTween,
       callbacks,
+      { label: "Resize" },
     );
 
-    expect(handled).toBe(true);
-    expect(attributedTo(writtenTargets(mutations)[0]!)).toEqual(["group-3"]);
+    expect(outcome).toMatchObject({ status: "blocked", detail: "shared-tween" });
+    expect(mutations).toEqual([]);
   });
 
   it("commitStaticGsapPosition replaces a corrupt keyframed hold against one element", async () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5, true);
     const { mutations, callbacks } = recorder();
     const corruptHold = {
       id: "hold-1",
@@ -225,7 +201,7 @@ describe("gsapDragCommit — new-tween targets", () => {
 
 describe("gsapDragCommit — retargeting an existing tween is left alone", () => {
   it("commitWholePathOffset keeps the tween's own group target", async () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5, true);
     const { mutations, callbacks } = recorder();
     const groupTween = {
       id: "t-group",
@@ -261,7 +237,7 @@ describe("gsapDragCommit — retargeting an existing tween is left alone", () =>
  */
 describe("a re-nudge updates its own previous write instead of stacking a second one", () => {
   it("finds the write the first nudge authored", async () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5, true);
     const selection = classOnlySelection(groups[2]!);
     const first = recorder();
 
@@ -309,7 +285,7 @@ gsap.set(${JSON.stringify(written)}, { x: 10, y: 10 });
  */
 describe("useEnableKeyframes — rewriting an existing tween keeps its group target", () => {
   it("promoteSetToKeyframes leaves a group-authored set aimed at the group", async () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5, true);
     const mutations: Array<Record<string, unknown>> = [];
     const setAnim = {
       id: "set-group",
@@ -339,18 +315,7 @@ describe("useEnableKeyframes — rewriting an existing tween keeps its group tar
 
 describe("the written selector survives the real writer and parser", () => {
   it("re-parses to a tween attributed to the one element it targeted", async () => {
-    const groups = mountGroupSiblings();
-    const { mutations, callbacks } = recorder();
-
-    await commitStaticGsapPosition(
-      classOnlySelection(groups[2]!),
-      { x: 10, y: 10 },
-      { x: 0, y: 0 },
-      ".group",
-      null,
-      callbacks,
-    );
-    const written = writtenTargets(mutations)[0]!;
+    const written = await positionMiddleSibling();
 
     const script = `
 const tl = gsap.timeline({ paused: true });

package/src/hooks/plainRotation.ts

@@ -27,7 +27,11 @@ export function savePlainRotation(
     ? buildClearRotationPatches(element)
     : [];
   if (patches.length) clearStudioRotation(element);
-  const drawn = applyCssRotation(element, next.angle, patches.length ? undefined : next.plain);
+  const drawn = applyCssRotation(
+    element,
+    next.angle,
+    patches.length ? undefined : (next.plain ?? undefined),
+  );
   patches.push(...drawn);
   const turn = drawn.at(-1)!;
   return commitPositionPatchToHtml(selection, patches, {

package/src/hooks/timelineTimingSync.test.ts

@@ -593,6 +593,7 @@ describe("a timing edit's soft reload restores what GSAP wrote from the files",
 
     expect(fetchMock).toHaveBeenCalledWith(
       expect.stringContaining("/files/compositions%2Fsub.html"),
+      { credentials: "omit" },
     );
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(wt.getAttribute("style")).toBe("left: 700px;");

package/src/hooks/timelineTimingSync.ts

@@ -28,12 +28,13 @@ import {
   serializeStudioFileMutations,
   type StudioProjectFileWriter,
 } from "../utils/studioFileMutationCoordinator";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 export async function readFileContent(projectId: string, targetPath: string): Promise<string> {
   if (targetPath.includes("\0") || targetPath.includes("..")) {
     throw new Error(`Unsafe path: ${targetPath}`);
   }
-  const response = await fetch(
+  const response = await studioApiFetch(
     `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(targetPath)}`,
   );
   if (!response.ok) {