@hyperframes/studio 0.8.115 → 0.8.117

package/src/hooks/gsapRuntimeBridge.ts

@@ -9,12 +9,13 @@
  * easing, or seek position.
  */
 import type { GsapAnimation, PropertyGroupName } from "@hyperframes/core/gsap-parser";
-import { isXYPositionWrite } from "@hyperframes/parsers/gsap-constants";
+import { isXYPositionWrite, PROPERTY_GROUPS } from "@hyperframes/parsers/gsap-constants";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 
 import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeReaders";
-import { commitGsapPositionFromDrag } from "./gsapDragPositionCommit";
+import { commitGsapPositionFromDrag, gsapPositionFromDragOutcome } from "./gsapDragPositionCommit";
+import { commitValueAtPlayhead } from "./gsapValueAtPlayhead";
 import {
   commitStaticGsapPosition,
   commitStaticGsapRotation,
@@ -22,7 +23,6 @@ import {
   computeCurrentPercentage,
   findExistingPositionWrite,
   findRotationSetAnimation,
-  materializeIfDynamic,
 } from "./gsapDragCommit";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 import { isGestureTransactionCommit } from "./gestureTransaction";
@@ -54,64 +54,29 @@ const ROTATION_CHANNEL_SET = new Set<string>(ROTATION_CHANNELS);
 // ── Property-group tween resolution ───────────────────────────────────────
 
 /**
- * Find the tween for a given property group, splitting a legacy mixed tween
- * if necessary. Returns the resolved animation or null if none exists.
- *
- * Resolution order:
- * 1. Tween already tagged with `propertyGroup === group`
- * 2. Legacy mixed tween (`!propertyGroup`) → split via server mutation,
- *    re-fetch, then return the group tween
- * 3. null — caller must handle the missing-tween case
+ * The tween to edit for a property group: a tween tagged with it, else a legacy tween that mixes
+ * it with other groups. A mixed tween is edited in place, never split first: inside a gesture the
+ * split is only buffered, so ids read after it are stale and the edit lands beside the old tween.
  */
 export async function resolveGroupTween(
   group: PropertyGroupName,
   animations: GsapAnimation[],
-  selection: DomEditSelection,
-  commitMutation: GsapDragCommitCallbacks["commitMutation"],
+  _selection: DomEditSelection,
+  _commitMutation: GsapDragCommitCallbacks["commitMutation"],
   fetchFallbackAnimations?: () => Promise<GsapAnimation[]>,
 ): Promise<{ anim: GsapAnimation; animations: GsapAnimation[] } | null> {
-  // 1. Already-split group tween — pick the one closest to the current
-  // playhead so a drag at t=6s edits the tween at 4s, not the one at 1.5s.
-  const groupAnims = animations.filter((a) => a.propertyGroup === group);
-  const groupAnim = pickClosestToPlayhead(groupAnims);
-  if (groupAnim) return { anim: groupAnim, animations };
-
-  // 2. Legacy mixed tween — split it, then re-fetch
-  const legacyMixed = animations.find((a) => !a.propertyGroup);
-  if (legacyMixed) {
-    await commitMutation(
-      selection,
-      { type: "split-into-property-groups", animationId: legacyMixed.id },
-      { label: "Split mixed tween into property groups", skipReload: true },
-    );
-    if (fetchFallbackAnimations) {
-      const fresh = await fetchFallbackAnimations();
-      const freshGroupAnim = fresh.find((a) => a.propertyGroup === group);
-      if (freshGroupAnim) return { anim: freshGroupAnim, animations: fresh };
-    }
-  }
-
-  // 3. Try fallback fetch (no split needed, just wasn't in the initial list)
-  if (!legacyMixed && fetchFallbackAnimations) {
-    const fresh = await fetchFallbackAnimations();
-    const freshGroupAnim = fresh.find((a) => a.propertyGroup === group);
-    if (freshGroupAnim) return { anim: freshGroupAnim, animations: fresh };
-
-    // Fallback: legacy mixed in the fresh list
-    const freshLegacy = fresh.find((a) => !a.propertyGroup);
-    if (freshLegacy) {
-      await commitMutation(
-        selection,
-        { type: "split-into-property-groups", animationId: freshLegacy.id },
-        { label: "Split mixed tween into property groups", skipReload: true },
-      );
-      const reFetched = await fetchFallbackAnimations();
-      const reFetchedGroup = reFetched.find((a) => a.propertyGroup === group);
-      if (reFetchedGroup) return { anim: reFetchedGroup, animations: reFetched };
-    }
-  }
-
-  return null;
+  const inGroup = (list: GsapAnimation[]) => {
+    const tagged = list.filter((a) => a.propertyGroup === group);
+    const props = new Set(PROPERTY_GROUPS[group]);
+    const mixed = list.filter((a) => !a.propertyGroup && animationWritesAnyProperty(a, props));
+    return pickClosestToPlayhead(tagged.length > 0 ? tagged : mixed);
+  };
+  const anim = inGroup(animations);
+  if (anim) return { anim, animations };
+  if (!fetchFallbackAnimations) return null;
+  const fresh = await fetchFallbackAnimations();
+  const freshAnim = inGroup(fresh);
+  return freshAnim ? { anim: freshAnim, animations: fresh } : null;
 }
 
 // ── High-level intercept ───────────────────────────────────────────────────
@@ -205,6 +170,59 @@ function oneUndoStep(
     commit(selection, mutation, { ...options, coalesceKey, coalesceMs: Number.POSITIVE_INFINITY });
 }
 
+const isPositionWriteOf = (selector: string) => (a: GsapAnimation) =>
+  a.targetSelector === selector && isXYPositionWrite(a);
+
+/** The one position write a self-heal keeps when holds fight over `selector`, else null. */
+function positionWriteKeeper(animations: GsapAnimation[], selector: string): GsapAnimation | null {
+  const dupes = animations.filter(isPositionWriteOf(selector));
+  // Real tweens one after another are a motion, not a conflict: only holds can fight.
+  if (dupes.length < 2 || dupes.filter((a) => !isInstantHold(a)).length > 1) return null;
+  return dupes.find((a) => a.keyframes) ?? dupes.find((a) => (a.duration ?? 0) > 0) ?? dupes[0]!;
+}
+
+/** Where a drag writes. With no live motion and no keyframed tween (a hold, or a
+ *  zero-length keyframed tween) the position belongs in a `tl.set`, never keyframes. */
+function dragRoute(
+  posAnim: GsapAnimation | null,
+  iframe: HTMLIFrameElement | null,
+  selector: string,
+  altKey?: boolean,
+): "static" | "whole-path" | "at-playhead" {
+  const hasNonHold = hasNonHoldTweenForElement(iframe, selector, undefined, POSITION_CHANNELS);
+  const hasKeyframedPosTween = !!posAnim?.keyframes && resolveTweenDuration(posAnim) > 0;
+  if (!hasNonHold && !hasKeyframedPosTween) return "static";
+  // Alt-drag shifts the whole path; with auto-keyframe off (#1808) that is the default.
+  return altKey || !usePlayerStore.getState().autoKeyframeEnabled ? "whole-path" : "at-playhead";
+}
+
+/** The commit's route and keyframe plan, writing nothing, so a group refuses whole. */
+async function planDrag(
+  selection: DomEditSelection,
+  offset: { x: number; y: number },
+  allAnimations: GsapAnimation[],
+  iframe: HTMLIFrameElement | null,
+  options: { altKey?: boolean },
+): Promise<GsapEditOutcome> {
+  const selector = selectorFromSelection(selection);
+  if (!selector) return { status: "blocked", reason: "no-selector" };
+  const own = tweensForThisElement(selection, allAnimations);
+  const keeper = positionWriteKeeper(own, selector);
+  const animations = keeper
+    ? own.filter((a) => a === keeper || !isPositionWriteOf(selector)(a))
+    : own;
+  const resolved = await resolveGroupTween("position", animations, selection, async () => {});
+  const posAnim = resolved?.anim ?? findGsapPositionAnimation(animations, selector);
+  const route = dragRoute(posAnim, iframe, selector, options.altKey);
+  if (route === "static") return { status: "persisted" };
+  if (!posAnim) {
+    return { status: "blocked", reason: "source-uneditable", detail: "no-position-tween" };
+  }
+  if (route === "whole-path") return { status: "persisted" };
+  const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
+  return gsapPositionFromDragOutcome(selection, posAnim, offset, gsapPos, iframe);
+}
+
 /** Commits a drag through the GSAP script. Callers reject `blocked` (the gesture layer
  *  restores its drafts) and save `element-offset` on the element itself. */
 export async function tryGsapDragIntercept(
@@ -229,7 +247,12 @@ export async function tryGsapDragIntercept(
       fetchAllAnimations,
       options?.group,
     );
-    if (preflight.status !== "persisted" || options?.preflightOnly) return preflight;
+    if (preflight.status !== "persisted") return preflight;
+    if (options?.preflightOnly) {
+      return options.group
+        ? planDrag(selection, offset, allAnimations, iframe, options)
+        : preflight;
+    }
   }
   const animations = tweensForThisElement(selection, allAnimations);
   const fetchFallbackAnimations =
@@ -246,13 +269,10 @@ export async function tryGsapDragIntercept(
   // the live keyframed/real tween if present (else any), strip the rest, so the
   // commit below updates ONE write instead of fighting duplicates.
   let workingAnimations = animations;
-  const isPosWrite = (a: GsapAnimation) => a.targetSelector === selector && isXYPositionWrite(a);
-  if (animations.filter(isPosWrite).length > 1 && fetchFallbackAnimations) {
+  if (animations.filter(isPositionWriteOf(selector)).length > 1 && fetchFallbackAnimations) {
     const fresh = await fetchFallbackAnimations();
-    const dupes = fresh.filter(isPosWrite);
-    if (dupes.length > 1) {
-      const keeper =
-        dupes.find((a) => a.keyframes) ?? dupes.find((a) => (a.duration ?? 0) > 0) ?? dupes[0]!;
+    const keeper = positionWriteKeeper(fresh, selector);
+    if (keeper) {
       await commitMutation(
         selection,
         {
@@ -288,26 +308,8 @@ export async function tryGsapDragIntercept(
   }
 
   const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
-
-  // STATIC case (single source of truth = GSAP timeline): the element has no LIVE
-  // keyframed/tweened position motion. Use the strict non-hold check — a leftover
-  // position-hold `set` (after a delete-all, or a stale parse that lags it) must
-  // NOT count as live motion. Either way the position belongs in a
-  // `tl.set("#el",{x,y})`, not a keyframe conversion: re-nudge an existing set in
-  // place (idempotent), else add a new one. This also covers the stale-cache
-  // phantom — committing a set is correct because the element genuinely has no live motion.
-  const hasNonHold = hasNonHoldTweenForElement(iframe, selector, undefined, POSITION_CHANNELS);
-  // A KEYFRAMED position tween — even one that's currently a flat constant ("hold",
-  // e.g. 0% and 100% identical) — is still an animation the user is building, so a
-  // drag must add/update a keyframe, NOT fall back to a static `set`. Without this,
-  // dragging an element whose position tween is constant writes a `gsap.set` that
-  // fights the tween (the "drag didn't create a keyframe / didn't persist" bug). The
-  // static path is only for elements with NO keyframed position tween (truly static,
-  // or just a leftover position-hold `set`).
-  // A zero-duration keyframed tween is a static HOLD, not a live animation —
-  // treat it as static so the drag heals it instead of feeding it more keyframes.
-  const hasKeyframedPosTween = !!posAnim?.keyframes && resolveTweenDuration(posAnim) > 0;
-  if (!hasNonHold && !hasKeyframedPosTween) {
+  const route = dragRoute(posAnim, iframe, selector, options?.altKey);
+  if (route === "static") {
     const existingSet =
       posAnim && isInstantHold(posAnim) && posAnim.targetSelector === selector
         ? posAnim
@@ -329,27 +331,26 @@ export async function tryGsapDragIntercept(
   // current ID and avoid a stale-ID remove that creates duplicate tweens.
   if (fetchFallbackAnimations) {
     const fresh = await fetchFallbackAnimations();
-    const freshMatch = fresh.find(
-      (a) =>
-        a.targetSelector === posAnim!.targetSelector &&
-        a.propertyGroup === posAnim!.propertyGroup &&
-        isXYPositionWrite(a) === isXYPositionWrite(posAnim!),
-    );
+    const freshMatch =
+      fresh.find((a) => a.id === posAnim!.id) ??
+      pickClosestToPlayhead(
+        fresh.filter(
+          (a) =>
+            a.targetSelector === posAnim!.targetSelector &&
+            a.propertyGroup === posAnim!.propertyGroup &&
+            isXYPositionWrite(a) === isXYPositionWrite(posAnim!),
+        ),
+      );
     if (freshMatch && freshMatch.id !== posAnim.id) {
       posAnim = freshMatch;
     }
   }
 
   const cbs = { commitMutation, fetchAnimations: fetchFallbackAnimations };
-  // Alt-drag already means "shift the whole path" — the global auto-keyframe
-  // toggle (#1808) just makes that the default while it's off, so a manual
-  // edit on an already-animated element nudges the animation instead of
-  // inserting/updating a keyframe at the playhead.
-  const autoKeyframeEnabled = usePlayerStore.getState().autoKeyframeEnabled;
-  if (options?.altKey || !autoKeyframeEnabled) {
+  if (route === "whole-path") {
     await commitWholePathOffset(selection, posAnim, offset, gsapPos, iframe, selector, cbs);
   } else {
-    await commitGsapPositionFromDrag(selection, posAnim, offset, gsapPos, iframe, selector, cbs);
+    return commitGsapPositionFromDrag(selection, posAnim, offset, gsapPos, iframe, cbs);
   }
   return { status: "persisted" };
 }
@@ -428,8 +429,9 @@ export async function tryGsapRotationIntercept(
       ? resolved.anim
       : null;
   if (!anim) {
-    anim =
-      workingAnimations.find((a) => animationWritesAnyProperty(a, ROTATION_CHANNEL_SET)) ?? null;
+    anim = pickClosestToPlayhead(
+      workingAnimations.filter((a) => animationWritesAnyProperty(a, ROTATION_CHANNEL_SET)),
+    );
   }
 
   // `angle` is the ABSOLUTE target rotation resolved by the gesture (gsap base +
@@ -469,42 +471,14 @@ export async function tryGsapRotationIntercept(
     return { status: "persisted" };
   }
 
-  // fallow-ignore-next-line code-duplication
-  if (anim.hasUnresolvedKeyframes || anim.hasUnresolvedSelector) {
-    const newId = await materializeIfDynamic(anim, iframe, commitMutation, selection);
-    if (newId) anim = { ...anim, id: newId };
-  } else if (!anim.keyframes) {
-    const resolvedFromValues = selector
-      ? readAllAnimatedProperties(iframe, selector, anim, "rotation")
-      : undefined;
-    await commitMutation(
-      selection,
-      { type: "convert-to-keyframes", animationId: anim.id, resolvedFromValues },
-      { label: "Convert to keyframes for rotation", skipReload: true },
-    );
-  }
-
-  const runtimeProps = readAllAnimatedProperties(iframe, selector, anim, "rotation");
-
-  const backfillDefaults: Record<string, number> = { ...runtimeProps };
-  if (!("rotation" in runtimeProps)) {
-    backfillDefaults.rotation = readGsapProperty(iframe, selector, "rotation") ?? 0;
-  }
-
-  const properties = { ...runtimeProps, rotation: newRotation };
-
-  await commitMutation(
+  return commitValueAtPlayhead(
     selection,
-    {
-      type: "add-keyframe",
-      animationId: anim.id,
-      percentage: pct,
-      properties,
-      backfillDefaults,
-    },
-    { label: `Rotate (keyframe ${pct}%)`, softReload: true },
+    anim,
+    { rotation: newRotation },
+    iframe,
+    { commitMutation, fetchAnimations: fetchFallbackAnimations },
+    { label: "Rotate", backfill: { rotation: newRotation }, holdFromStart: true },
   );
-  return { status: "persisted" };
 }
 
 export { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeKeyframes";

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -449,12 +449,12 @@ export const ROTATION_CHANNELS: string[] = [
 
 /** GSAP owns this element's position: a tween or hold writes it, or GSAP already renders its
  *  transform (a CSS translate would then apply twice). Everything else moves by plain CSS. */
-export function gsapWritesPosition(el: Element): boolean {
+function gsapWritesPosition(el: Element): boolean {
   return gsapRendersTransform(el) || gsapWritesChannels(el, MOVE_CHANNELS);
 }
 
 /** `gsapWritesPosition` for a rotate: everything else turns by its own CSS `rotate`. */
-export function gsapWritesRotation(el: Element): boolean {
+function gsapWritesRotation(el: Element): boolean {
   return gsapRendersTransform(el) || gsapWritesChannels(el, ROTATION_CHANNELS);
 }
 
@@ -474,10 +474,23 @@ const BOX_CHANNELS = [
 ];
 
 /** GSAP owns this element's box: its position, or any property the CSS box writer sets. Else a resize writes CSS. */
-export function gsapWritesBox(el: Element): boolean {
+function gsapWritesBox(el: Element): boolean {
   return gsapWritesPosition(el) || gsapWritesChannels(el, BOX_CHANNELS);
 }
 
+export type EditGesture = "move" | "resize" | "rotate";
+const GSAP_OWNS: Record<EditGesture, (el: Element) => boolean> = {
+  move: gsapWritesPosition,
+  resize: gsapWritesBox,
+  rotate: gsapWritesRotation,
+};
+
+/** The one GSAP-or-CSS route decision. Make it when an edit starts and carry it: mid-gesture
+ *  writes make GSAP render the element, so asking again at commit can flip the route. */
+export function editsPlainCss(el: Element, gesture: EditGesture): boolean {
+  return !GSAP_OWNS[gesture](el);
+}
+
 /** `hasNonHoldTweenForElement` for an element in hand, read from its own window's timelines. */
 export function elementHasNonHoldTween(el: Element, channels?: string[]): boolean {
   const win = el.ownerDocument.defaultView as {

package/src/hooks/gsapScriptCommitHelpers.ts

@@ -4,6 +4,7 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
 export { PROPERTY_DEFAULTS } from "./gsapShared";
 import { idSelector, matchesExactlyOne } from "./gsapShared";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 /**
  * The selector to author a NEW tween against, minting an id on the element when
@@ -116,7 +117,7 @@ export async function assignGsapTargetAutoIdIfNeeded({
     showToast?.("Couldn't assign element id because the patch contains invalid values", "error");
     return false;
   }
-  const res = await fetch(
+  const res = await studioApiFetch(
     `/api/projects/${encodeURIComponent(projectId)}/file-mutations/patch-element/${encodeURIComponent(targetPath)}`,
     {
       method: "POST",

package/src/hooks/gsapScriptCommitTypes.ts

@@ -5,6 +5,14 @@ import type { PublishSdkSession } from "../utils/sdkCutover";
 import type { RuntimeTweenChange } from "./gsapRuntimePatch";
 import type { KeyframeUsageAction } from "../utils/keyframeUsage";
 
+/** The file a selection's GSAP write goes to. */
+export function gsapWriteFile(
+  selection: Pick<DomEditSelection, "sourceFile">,
+  activeCompPath: string | null | undefined,
+): string {
+  return selection.sourceFile || activeCompPath || "index.html";
+}
+
 export interface MutationResult {
   ok: boolean;
   changed?: boolean;
@@ -36,7 +44,7 @@ export interface CommitMutationOptions {
    * error handling — a failed write still throws.
    */
   deferPreviewSync?: boolean;
-  /** Shares an in-place patch miss with the final render of one multi-write action. */
+  /** Carries a deferred write not yet on screen (no patch, or a missed one) to the final render. */
   previewFallbackLatch?: { pending: boolean };
   beforeReload?: () => void;
   /**

package/src/hooks/gsapShared.ts

@@ -34,6 +34,13 @@ export const PROPERTY_DEFAULTS: Record<string, number> = {
   height: 100,
 };
 
+/** A tween's eases for re-writing it as keyframes: a flat tween's ease must become easeEach,
+ *  since GSAP eases each percentage segment power1.inOut whatever the tween-level ease says. */
+export function keyframeEases(anim: GsapAnimation): { ease?: string; easeEach?: string } {
+  if (!anim.keyframes) return { easeEach: anim.ease };
+  return { ease: anim.ease, easeEach: anim.keyframes.easeEach };
+}
+
 /**
  * A timeline write that applies an instantaneous value and then holds it.
  * `set()` is always a hold; authored `to()` / `fromTo()` tweens are holds only

package/src/hooks/gsapShared.writeTarget.test.ts

@@ -3,7 +3,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { parseGsapScript } from "@hyperframes/core/gsap-parser";
 import { addAnimationWithKeyframesToScript } from "@hyperframes/parsers/gsap-writer-acorn";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
-import { buildStableSelector, getSelectorIndex } from "../components/editor/domEditingDom";
+import { mountGroupSiblings, stableSelectionFor } from "./domSelectionTestHarness";
 import { resolveSelectorElementIds, tweenTargetsElement, writeTargetSelector } from "./gsapShared";
 import { commitKeyframeAtTimeImpl } from "./gsapKeyframeCommit";
 import { trackStudioEvent } from "../utils/studioTelemetry";
@@ -16,38 +16,6 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
-/**
- * A selection built the way production builds it (getDomLayerPatchTarget), so
- * the class-only case under test is the real one: buildStableSelector hands back
- * a BARE class for an element with no id / hf-id / composition id.
- */
-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 — the shape that made one add collapse the timeline. */
-function mountGroupSiblings(): HTMLElement[] {
-  document.body.innerHTML = `
-    <div id="scene" class="clip" data-start="0" data-duration="2">
-      <div class="group"></div>
-      <div class="group"></div>
-      <div class="group"></div>
-      <div class="group"></div>
-      <div class="group"></div>
-    </div>
-  `;
-  return Array.from(document.querySelectorAll<HTMLElement>(".group"));
-}
-
 const BASE_SCRIPT = `
 const tl = gsap.timeline({ paused: true });
 tl.to("#scene", { opacity: 1, duration: 0.5 }, 0);
@@ -68,8 +36,8 @@ function roundTripTargets(selector: string): { script: string; targets: string[]
 
 describe("writeTargetSelector", () => {
   it("addresses exactly one element when the only identity is a shared class", () => {
-    const groups = mountGroupSiblings();
-    const selection = selectionFor(groups[2]);
+    const groups = mountGroupSiblings(5);
+    const selection = stableSelectionFor(groups[2]);
 
     // Precondition: this is the defect's input — a bare class hitting all five.
     expect(selection.selector).toBe(".group");
@@ -86,7 +54,7 @@ describe("writeTargetSelector", () => {
     document.body.innerHTML = `<div id="box" class="card"></div>`;
     const el = document.querySelector<HTMLElement>("#box")!;
 
-    expect(writeTargetSelector(selectionFor(el))).toBe("#box");
+    expect(writeTargetSelector(stableSelectionFor(el))).toBe("#box");
   });
 
   it("prefers data-hf-id over a generated structural selector", () => {
@@ -95,7 +63,7 @@ describe("writeTargetSelector", () => {
     `;
     const el = document.querySelectorAll<HTMLElement>(".group")[1]!;
 
-    const written = writeTargetSelector(selectionFor(el));
+    const written = writeTargetSelector(stableSelectionFor(el));
 
     expect(written).toBe('[data-hf-id="hf-42"]');
     expect(document.querySelector(written!)).toBe(el);
@@ -105,7 +73,7 @@ describe("writeTargetSelector", () => {
     document.body.innerHTML = `<div id="scene"><div class="header"></div></div>`;
     const el = document.querySelector<HTMLElement>(".header")!;
 
-    expect(writeTargetSelector(selectionFor(el))).toBe(".header");
+    expect(writeTargetSelector(stableSelectionFor(el))).toBe(".header");
   });
 
   it("hands identity back to a data-hf-id ancestor part way up a deep chain", () => {
@@ -125,7 +93,7 @@ describe("writeTargetSelector", () => {
     `;
     const el = document.querySelectorAll<HTMLElement>(".cell")[2]!;
 
-    const written = writeTargetSelector(selectionFor(el));
+    const written = writeTargetSelector(stableSelectionFor(el));
 
     expect(written).toBe('[data-hf-id="mid"] > div:nth-child(3)');
     expect(document.querySelectorAll(written!)).toHaveLength(1);
@@ -137,7 +105,7 @@ describe("writeTargetSelector", () => {
     const el = document.querySelectorAll<HTMLElement>("#scene > div")[1]!;
     // querySelectorAll throws on this, so the "does it match exactly one?" rung
     // must read as a miss rather than crashing the add.
-    const selection = { ...selectionFor(el), selector: "div[unclosed" } as DomEditSelection;
+    const selection = { ...stableSelectionFor(el), selector: "div[unclosed" } as DomEditSelection;
 
     expect(writeTargetSelector(selection)).toBe("#scene > div:nth-child(2)");
   });
@@ -145,7 +113,7 @@ describe("writeTargetSelector", () => {
   it("returns null when a live DOM is present and no rung addresses one element", () => {
     document.body.innerHTML = `<div id="scene"><div class="group"></div><div class="group"></div></div>`;
     const el = document.querySelectorAll<HTMLElement>(".group")[1]!;
-    const selection = selectionFor(el);
+    const selection = stableSelectionFor(el);
     expect(selection.selector).toBe(".group");
     // Detached between selecting and committing: ownerDocument still resolves,
     // but there is no parent to count a :nth-child position in. Returning
@@ -167,11 +135,11 @@ describe("writeTargetSelector", () => {
 
 describe("writeTargetSelector — write/read round trip", () => {
   it("re-parses and attributes the new tween to the one element it targeted", () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5);
     // Ids let resolveSelectorElementIds name the attributed elements; the
     // SELECTION still has none, so the write path still faces the bare class.
     groups.forEach((el, i) => el.setAttribute("id", `group-${i}`));
-    const selection = { ...selectionFor(groups[2]), id: undefined } as DomEditSelection;
+    const selection = { ...stableSelectionFor(groups[2]), id: undefined } as DomEditSelection;
 
     const written = writeTargetSelector(selection);
     const { targets } = roundTripTargets(written!);
@@ -180,9 +148,9 @@ describe("writeTargetSelector — write/read round trip", () => {
   });
 
   it("does not widen the add to the element's four class siblings", () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5);
     groups.forEach((el, i) => el.setAttribute("id", `group-${i}`));
-    const selection = { ...selectionFor(groups[0]), id: undefined } as DomEditSelection;
+    const selection = { ...stableSelectionFor(groups[0]), id: undefined } as DomEditSelection;
 
     // The old bare-class write attributed the one add to every sibling — the
     // attribution blow-up behind "one add collapsed the timeline to a single row".
@@ -194,8 +162,8 @@ describe("writeTargetSelector — write/read round trip", () => {
 
 describe("existingTweenTargetSelector", () => {
   it("keeps the narrowed target when a replace re-authors the tween", async () => {
-    const groups = mountGroupSiblings();
-    const selection = selectionFor(groups[2]);
+    const groups = mountGroupSiblings(5);
+    const selection = stableSelectionFor(groups[2]);
     const commitMutation = vi.fn(async () => undefined);
     // A tween a previous add already narrowed to one sibling. Re-deriving the
     // target from the selection would widen it back to all five.
@@ -215,8 +183,8 @@ describe("existingTweenTargetSelector", () => {
   });
 
   it("falls back to the selection when the tween's own target did not resolve", async () => {
-    const groups = mountGroupSiblings();
-    const selection = selectionFor(groups[2]);
+    const groups = mountGroupSiblings(5);
+    const selection = stableSelectionFor(groups[2]);
     const commitMutation = vi.fn(async () => undefined);
     const setAnim = {
       id: "a1",
@@ -236,8 +204,8 @@ describe("existingTweenTargetSelector", () => {
 
 describe("commitKeyframeAtTimeImpl — new-tween target", () => {
   it("authors a one-element selector when no tween exists at the playhead", async () => {
-    const groups = mountGroupSiblings();
-    const selection = selectionFor(groups[3]);
+    const groups = mountGroupSiblings(5);
+    const selection = stableSelectionFor(groups[3]);
     const commitMutation = vi.fn(async () => undefined);
 
     await commitKeyframeAtTimeImpl(selection, 1, [], { x: 12 }, commitMutation);
@@ -251,7 +219,7 @@ describe("commitKeyframeAtTimeImpl — new-tween target", () => {
 
 describe("tweenTargetsElement", () => {
   it("matches a tween narrowed to this element by a selector the selection does not use", () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5);
     groups[2]!.id = "narrowed";
 
     // The write half authored "#narrowed"; the read half still has ".group".
@@ -259,7 +227,7 @@ describe("tweenTargetsElement", () => {
   });
 
   it("does not hand an individual element the group tween it merely inherits", () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5);
 
     // Selecting one sibling by its own address must not let an edit mutate the
     // ".group" tween: that write moves all five, not the one being nudged.
@@ -267,13 +235,13 @@ describe("tweenTargetsElement", () => {
   });
 
   it("still edits a group tween when the group itself is the selection", () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5);
 
     expect(tweenTargetsElement(".group", ".group", groups[0])).toBe(true);
   });
 
   it("does not match a target that is not a selector matches() understands", () => {
-    const groups = mountGroupSiblings();
+    const groups = mountGroupSiblings(5);
 
     expect(tweenTargetsElement("div[unclosed", ".group", groups[0])).toBe(false);
   });
@@ -281,8 +249,8 @@ describe("tweenTargetsElement", () => {
 
 describe("commitKeyframeAtTimeImpl — no one-element target", () => {
   it("drops the keyframe rather than authoring the bare class", async () => {
-    const groups = mountGroupSiblings();
-    const selection = selectionFor(groups[3]!);
+    const groups = mountGroupSiblings(5);
+    const selection = stableSelectionFor(groups[3]!);
     groups[3]!.remove();
     const commitMutation = vi.fn(async () => undefined);
 
@@ -297,7 +265,7 @@ it("counts a keyframe-at-time conversion and insertion as one add gesture", asyn
   const el = document.createElement("div");
   el.id = "target";
   document.body.append(el);
-  const selection = selectionFor(el);
+  const selection = stableSelectionFor(el);
   const animations = parseGsapScript(
     'const tl = gsap.timeline(); tl.to("#target", {x:100,duration:4},0);',
   ).animations;