@hyperframes/studio 0.7.77 → 0.7.79

package/src/hooks/gsapKeyframeCacheHelpers.ts

@@ -4,7 +4,7 @@
  */
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerStore";
-import { idFromSelector, toClipKeyframes } from "./gsapShared";
+import { resolveClipTimingBasis, resolveSelectorElementIds, toClipKeyframes } from "./gsapShared";
 import { deduplicateKeyframes, synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
 
 export function updateKeyframeCacheFromParsed(
@@ -12,58 +12,65 @@ export function updateKeyframeCacheFromParsed(
   targetPath: string,
   selectionId: string | undefined,
   mutation: Record<string, unknown>,
+  doc?: Document | null,
 ): void {
-  const { setKeyframeCache, elements } = usePlayerStore.getState();
+  const { setKeyframeCache, elements, domClipChildren } = usePlayerStore.getState();
   const idsWithKeyframes = new Set<string>();
   const merged = new Map<string, KeyframeCacheEntry>();
   const sourceAnimations = new Map<string, GsapAnimation[]>();
   for (const anim of animations) {
-    const id = idFromSelector(anim.targetSelector);
     const kfSource =
       anim.keyframes?.keyframes ?? synthesizeFlatTweenKeyframes(anim)?.keyframes ?? [];
-    if (!id || kfSource.length === 0) continue;
-    idsWithKeyframes.add(id);
-    // Every tween that fed keyframeCache also lands in gsapAnimations, group or
-    // not: a mixed-group tween (`{ x, opacity }` classifies to undefined) used to
-    // cache diamonds with no source animation behind them, so the collapsed row
-    // drew keyframes the expanded lanes couldn't render. Lane consumers do the
-    // group filtering themselves (animationContributesLane).
-    sourceAnimations.set(id, [...(sourceAnimations.get(id) ?? []), anim]);
+    if (kfSource.length === 0) continue;
+    // Attribute the tween to every element it actually animates. A leading-id
+    // match filed `#stat3 .block` under `#stat3`: the child's diamonds landed on
+    // its ancestor AND collided with the ancestor's own tween at the shared
+    // percentage, which the same-% merge then resolved by dropping the ease.
+    for (const id of resolveSelectorElementIds(anim.targetSelector, doc)) {
+      idsWithKeyframes.add(id);
+      // Every tween that fed keyframeCache also lands in gsapAnimations, group or
+      // not: a mixed-group tween (`{ x, opacity }` classifies to undefined) used to
+      // cache diamonds with no source animation behind them, so the collapsed row
+      // drew keyframes the expanded lanes couldn't render. Lane consumers do the
+      // group filtering themselves (animationContributesLane).
+      sourceAnimations.set(id, [...(sourceAnimations.get(id) ?? []), anim]);
 
-    // Convert tween-relative percentages to clip-relative so diamonds
-    // render at the correct position within the timeline clip.
-    const timelineEl = elements.find(
-      (el) => el.domId === id || (el.key ?? el.id) === `${targetPath}#${id}`,
-    );
-    const clipKeyframes = toClipKeyframes(
-      kfSource,
-      anim,
-      timelineEl?.start ?? 0,
-      timelineEl?.duration ?? 1,
-    );
+      // Convert tween-relative percentages to clip-relative so diamonds
+      // render at the correct position within the timeline clip. The basis comes
+      // from the shared resolver, so this writer agrees with the AST load on both
+      // the sub-comp host fallback and the tween's own time frame.
+      const { elStart, elDuration } = resolveClipTimingBasis(
+        id,
+        targetPath,
+        elements,
+        domClipChildren,
+      );
+      const clipKeyframes = toClipKeyframes(kfSource, anim, elStart, elDuration);
 
-    const existing = merged.get(id);
-    if (existing) {
-      // deduplicateKeyframes owns the same-% merge (including the easeAmbiguous
-      // flag downstream lanes read); a second copy of that rule here is how the
-      // two writers drift.
-      existing.keyframes = deduplicateKeyframes([...existing.keyframes, ...clipKeyframes]);
-    } else {
-      merged.set(id, {
-        ...anim.keyframes,
-        format: anim.keyframes?.format ?? "percentage",
-        keyframes: clipKeyframes,
-      });
+      const existing = merged.get(id);
+      if (existing) {
+        // deduplicateKeyframes owns the same-% merge (including the easeAmbiguous
+        // flag downstream lanes read); a second copy of that rule here is how the
+        // two writers drift.
+        existing.keyframes = deduplicateKeyframes([...existing.keyframes, ...clipKeyframes]);
+      } else {
+        merged.set(id, {
+          ...anim.keyframes,
+          format: anim.keyframes?.format ?? "percentage",
+          keyframes: clipKeyframes,
+        });
+      }
     }
   }
   for (const [id, entry] of merged) {
     for (const key of elementCacheKeys(targetPath, id)) setKeyframeCache(key, entry);
     writeGsapAnimationsForElement(targetPath, id, sourceAnimations.get(id));
   }
-  const targetId =
-    idFromSelector((mutation as { targetSelector?: string }).targetSelector) ?? selectionId;
-  if (targetId && !idsWithKeyframes.has(targetId)) {
-    clearKeyframeCacheForElement(targetPath, targetId);
+  const mutationSelector = (mutation as { targetSelector?: string }).targetSelector;
+  const mutated = mutationSelector ? resolveSelectorElementIds(mutationSelector, doc) : [];
+  const targetIds = mutated.length > 0 ? mutated : selectionId ? [selectionId] : [];
+  for (const targetId of targetIds) {
+    if (!idsWithKeyframes.has(targetId)) clearKeyframeCacheForElement(targetPath, targetId);
   }
 }
 

package/src/hooks/gsapKeyframeCommit.ts

@@ -1,7 +1,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { absoluteToPercentageForAnimation, findTweenAtTime } from "../utils/globalTimeCompiler";
-import { PROPERTY_DEFAULTS, selectorFromSelection } from "./gsapShared";
+import { PROPERTY_DEFAULTS, selectorFromSelection, writeTargetSelector } from "./gsapShared";
 import { roundToCenti } from "../utils/rounding";
 
 type CommitFn = (
@@ -22,6 +22,9 @@ export async function commitKeyframeAtTimeImpl(
   properties: Record<string, number | string>,
   commitMutation: CommitFn,
 ): Promise<void> {
+  // Matching an authored tween is a string compare against what the author
+  // wrote, so it keeps using the selection's own selector; the NEW tween below
+  // is authored with the one-element form instead.
   const selector = selectorFromSelection(selection);
   if (!selector) return;
 
@@ -60,12 +63,18 @@ export async function commitKeyframeAtTimeImpl(
       },
     );
   } else {
+    // Null means the live DOM could not prove any one-element form. Falling
+    // back to the author's own selector would write the group-collapsing
+    // target this narrowing exists to prevent, so the keyframe is dropped
+    // instead (see writeTargetSelector).
+    const target = writeTargetSelector(selection);
+    if (!target) return;
     const defaultDuration = 0.5;
     await commitMutation(
       selection,
       {
         type: "add-with-keyframes" as const,
-        targetSelector: selector,
+        targetSelector: target,
         position: absoluteTime,
         duration: defaultDuration,
         keyframes: [

package/src/hooks/gsapResizeIntercept.ts

@@ -79,7 +79,7 @@ export async function tryGsapResizeIntercept(
   if (!anim || isInstantHold(anim)) {
     const sel = selectorFromSelection(selection);
     if (!sel) return false;
-    const sizeSet = anim ?? findSizeSetAnimation(animations, sel);
+    const sizeSet = anim ?? findSizeSetAnimation(animations, sel, selection.element);
 
     // If the element is animated (has a real tween, not just a static size
     // hold), keyframe the size at the playhead so other keyframes keep theirs —
@@ -242,7 +242,7 @@ export async function tryGsapResizeIntercept(
     const currentAnimations = fetchFallbackAnimations
       ? await fetchFallbackAnimations()
       : (resolved?.animations ?? animations);
-    const existingSet = findExistingPositionWrite(currentAnimations, selector);
+    const existingSet = findExistingPositionWrite(currentAnimations, selector, selection.element);
     // Delta chosen so the drag-path math composes back to exactly `corrected`
     // (no drag scratch attrs exist during a resize, so base = gsapPos).
     await commitStaticGsapPosition(

package/src/hooks/gsapRuntimeBridge.ts

@@ -213,7 +213,7 @@ export async function tryGsapDragIntercept(
     const existingSet =
       posAnim && isInstantHold(posAnim) && posAnim.targetSelector === selector
         ? posAnim
-        : findExistingPositionWrite(resolvedAnimations, selector);
+        : findExistingPositionWrite(resolvedAnimations, selector, selection.element);
     await commitStaticGsapPosition(selection, offset, gsapPos, selector, existingSet, {
       commitMutation,
       fetchAnimations: fetchFallbackAnimations,
@@ -301,7 +301,8 @@ export async function tryGsapRotationIntercept(
   // rotation set in place, else add a new one. This replaces the old
   // `--hf-studio-rotation` CSS-var fallback (the same dual-channel bug class).
   if (!anim || isInstantHold(anim)) {
-    const existingSet = anim ?? findRotationSetAnimation(resolvedAnimations, selector);
+    const existingSet =
+      anim ?? findRotationSetAnimation(resolvedAnimations, selector, selection.element);
     await commitStaticGsapRotation(selection, newRotation, selector, existingSet, {
       commitMutation,
       fetchAnimations: fetchFallbackAnimations,

package/src/hooks/gsapScriptCommitHelpers.ts

@@ -2,17 +2,32 @@ import { findUnsafeDomPatchValues } from "@hyperframes/core/studio-api/finite-mu
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 
 export { PROPERTY_DEFAULTS } from "./gsapShared";
-import { idSelector } from "./gsapShared";
+import { idSelector, matchesExactlyOne } from "./gsapShared";
 
+/**
+ * The selector to author a NEW tween against, minting an id on the element when
+ * it has no address of its own.
+ *
+ * `selection.selector` is only usable when it addresses ONE element:
+ * `buildStableSelector` hands back a bare class for an id-less element, so
+ * returning it unconditionally aimed "add animation" at every sibling sharing
+ * the class (the attribution blow-up that collapsed the timeline to one row,
+ * see writeTargetSelector). A non-unique selector falls through to the id mint
+ * below, which is the stronger fix here than a structural path: the id it writes
+ * back to the source also makes every later lookup for this element exact.
+ */
 export function ensureElementAddressable(selection: DomEditSelection): {
   selector: string;
   autoId?: string;
 } {
   if (selection.id) return { selector: idSelector(selection.id) };
-  if (selection.selector) return { selector: selection.selector };
 
   const el = selection.element;
   const doc = el.ownerDocument;
+  if (selection.selector && matchesExactlyOne(doc, selection.selector, el)) {
+    return { selector: selection.selector };
+  }
+
   const tag = el.tagName.toLowerCase();
   let id = tag;
   let n = 1;

package/src/hooks/gsapShared.test.ts

@@ -6,6 +6,7 @@ import {
   idSelector,
   isInstantHold,
   parsePercentageKeyframes,
+  resolveClipTimingBasis,
   resolveEditableTweenDuration,
   toClipKeyframes,
   toClipPercentage,
@@ -169,6 +170,149 @@ describe("toClipKeyframes", () => {
   });
 });
 
+describe("resolveClipTimingBasis", () => {
+  // Measured on v-product-promo: `captions-comp` mounts at 1.5s for 12.5s, and the
+  // six tweens inside it resolve to 0..12.5 — composition-local, not main-timeline
+  // absolute. Subtracting the host's 1.5 mount from a 0s tween cached pct -12.
+  const host = { id: "captions-comp", domId: "captions-comp", start: 1.5, duration: 12.5 };
+  const children = [{ id: "line", hostId: "captions-comp" }];
+
+  it("gives a sub-composition inner element the host window in the tween's own frame", () => {
+    expect(resolveClipTimingBasis("line", "captions.html", [host], children)).toEqual({
+      elStart: 0,
+      elDuration: 12.5,
+    });
+  });
+
+  it("leaves a root-composition element on the main timeline", () => {
+    const box = { id: "box", domId: "box", start: 3, duration: 2 };
+    expect(resolveClipTimingBasis("box", "index.html", [box], [])).toEqual({
+      elStart: 3,
+      elDuration: 2,
+    });
+  });
+
+  it("rebases an expanded sub-comp child by its host mount", () => {
+    // Expanded children carry host-ABSOLUTE display starts; the tweens they own are
+    // still composition-local, so the basis is the child's local start.
+    const pill = { id: "pill", domId: "pill", start: 8, duration: 4, expandedParentStart: 6 };
+    expect(resolveClipTimingBasis("pill", "scene.html", [pill], [])).toEqual({
+      elStart: 2,
+      elDuration: 4,
+    });
+  });
+
+  it("rebases by the parent composition clip when the child is not expanded", () => {
+    const parent = { id: "scene-comp", domId: "scene-comp", start: 5, duration: 10 };
+    const pill = {
+      id: "pill",
+      domId: "pill",
+      start: 7,
+      duration: 3,
+      parentCompositionId: "scene-comp",
+    };
+    expect(resolveClipTimingBasis("pill", "scene.html", [parent, pill], [])).toEqual({
+      elStart: 2,
+      elDuration: 3,
+    });
+  });
+
+  it("treats a child whose parent composition is missing as starting at 0", () => {
+    // The mount is unknowable, so the only safe frame is the child's own. The
+    // old `?? 0` handed back `start` unchanged, which is a main-timeline value
+    // masquerading as a composition-local one and caches negative percentages.
+    const pill = {
+      id: "pill",
+      domId: "pill",
+      start: 7,
+      duration: 3,
+      parentCompositionId: "not-in-elements",
+    };
+    expect(resolveClipTimingBasis("pill", "scene.html", [pill], [])).toEqual({
+      elStart: 0,
+      elDuration: 3,
+    });
+  });
+
+  it("keeps a main-timeline clip's own start when it names no parent", () => {
+    const box = { id: "box", domId: "box", start: 4, duration: 2 };
+    expect(resolveClipTimingBasis("box", "index.html", [box], [])).toEqual({
+      elStart: 4,
+      elDuration: 2,
+    });
+  });
+
+  it("falls back to a unit window when neither the element nor a host resolves", () => {
+    expect(resolveClipTimingBasis("ghost", "index.html", [], [])).toEqual({
+      elStart: 0,
+      elDuration: 1,
+    });
+  });
+});
+
+describe("sub-composition keyframe percentages", () => {
+  const host = { id: "captions-comp", domId: "captions-comp", start: 1.5, duration: 12.5 };
+  const children = [{ id: "line", hostId: "captions-comp" }];
+  const basis = () => resolveClipTimingBasis("line", "captions.html", [host], children);
+  const inner = (resolvedStart: number, duration?: number) =>
+    ({
+      id: `t-${resolvedStart}`,
+      method: "to",
+      targetSelector: "#line",
+      vars: {},
+      resolvedStart,
+      duration,
+    }) as unknown as GsapAnimation;
+  const percentages = (animation: GsapAnimation) => {
+    const { elStart, elDuration } = basis();
+    return toClipKeyframes(
+      [{ percentage: 0 }, { percentage: 100 }],
+      animation,
+      elStart,
+      elDuration,
+    ).map((row) => row.percentage);
+  };
+
+  it("puts a tween on the host's first frame at 0%, never below zero", () => {
+    // A clip-relative percentage can never be negative; this one cached -12.
+    expect(percentages(inner(0))).toEqual([0, 100]);
+  });
+
+  it("puts the last tween's end keyframe at 100%", () => {
+    expect(percentages(inner(12.1, 0.4))).toEqual([96.8, 100]);
+  });
+
+  it("keeps every measured tween of the fixture inside 0..100", () => {
+    for (const start of [0, 3.2, 3.5, 7.7, 8, 12.1]) {
+      for (const percentage of percentages(inner(start, 0.4))) {
+        expect(percentage).toBeGreaterThanOrEqual(0);
+        expect(percentage).toBeLessThanOrEqual(100);
+      }
+    }
+  });
+
+  it("keeps a root-composition tween at the head of its own clip", () => {
+    const box = { id: "box", domId: "box", start: 3, duration: 2 };
+    const { elStart, elDuration } = resolveClipTimingBasis("box", "index.html", [box], []);
+    const rows = toClipKeyframes([{ percentage: 0 }], inner(3, 2), elStart, elDuration);
+    expect(rows[0]!.percentage).toBe(0);
+  });
+
+  it("passes tween percentages through for a zero-length clip", () => {
+    expect(toClipKeyframes([{ percentage: 40 }], inner(0, 0.4), 0, 0)[0]!.percentage).toBe(40);
+  });
+
+  it("round-trips a clip percentage through the basis it was written with", () => {
+    // The drag commit converts a dropped clip-% back to a time with this basis
+    // (useTimelineEditCallbacks) and compares it against the tween's own
+    // resolvedStart, so the basis has to be in the tween's frame on both sides.
+    const { elStart, elDuration } = basis();
+    const absTime = elStart + (40 / 100) * elDuration;
+    expect(absTime).toBe(5);
+    expect(toClipPercentage(absTime, elStart, elDuration, 0)).toBe(40);
+  });
+});
+
 describe("idFromSelector", () => {
   it("round-trips every shape idSelector emits", () => {
     for (const id of ["hero-word", "el_1", "01-hook-hero-word", "my.class", "1box", '1"x']) {

package/src/hooks/gsapShared.ts

@@ -110,12 +110,215 @@ export function idFromSelector(selector: string | undefined | null): string | nu
   return (attribute[1] ?? "").replace(/\\(["\\])/g, "$1");
 }
 
+/** Either shape {@link idSelector} emits, anchored to the WHOLE selector. */
+const WHOLE_SELECTOR_ID = /^(#[\w-]+|\[id="(?:\\.|[^"\\])*"\])$/;
+
+/**
+ * The id a selector addresses **as a whole**, or null. `"#stat3 .block"` animates
+ * the `.block` INSIDE `#stat3`, not `#stat3`, so the unanchored leading-id match
+ * of {@link idFromSelector} is wrong for attribution: it files the child's
+ * keyframes under its ancestor. `idFromSelector` stays unanchored on purpose
+ * (two non-attribution callers want the leading id); attribution goes through
+ * here, or through the DOM (see resolveSelectorElementIds).
+ */
+function wholeSelectorElementId(selector: string): string | null {
+  const trimmed = selector.trim();
+  return WHOLE_SELECTOR_ID.test(trimmed) ? idFromSelector(trimmed) : null;
+}
+
+/**
+ * Resolve a tween's target selector to the ids of the element(s) it animates.
+ * A whole-selector `#id` resolves directly; anything else (a class like `.dot`,
+ * a group `.a, .b`, or a descendant selector) is matched against the live
+ * preview DOM so class/selector tweens (e.g. `gsap.from(".dot", {stagger})`)
+ * attribute to every element they animate — not just one parsed from the string.
+ * With no DOM, only whole-selector ids resolve: a descendant selector has no
+ * answer that isn't a guess at its ancestor.
+ */
+export function resolveSelectorElementIds(
+  selector: string,
+  doc: Document | null | undefined,
+): string[] {
+  const bareId = wholeSelectorElementId(selector);
+  if (bareId) return [bareId];
+  const ids = new Set<string>();
+  for (const part of selector.split(",")) {
+    const sel = part.trim();
+    if (!sel) continue;
+    if (!doc) {
+      const whole = wholeSelectorElementId(sel);
+      if (whole) ids.add(whole);
+      continue;
+    }
+    try {
+      for (const el of Array.from(doc.querySelectorAll(sel))) {
+        if (el.id) ids.add(el.id);
+      }
+    } catch {
+      // An unsupported/invalid selector never reached the DOM, so the leading id
+      // is the best available answer (`[id="01-hook"]:has(>*)` still names it).
+      const lead = idFromSelector(sel);
+      if (lead) ids.add(lead);
+    }
+  }
+  return Array.from(ids);
+}
+
+/**
+ * The clip start in the frame the element's OWN tweens are measured in. An
+ * expanded sub-composition child sits on the master timeline at a host-absolute
+ * `start`, but its tweens are parsed from its own source file and are local to
+ * it, so the two must be brought into one frame before any clip-% math — or
+ * every keyframe rebases to a percentage far outside the clip.
+ */
+export function clipTimingStart(element: { start: number; expandedParentStart?: number }): number {
+  return element.start - (element.expandedParentStart ?? 0);
+}
+
 export function selectorFromSelection(selection: DomEditSelection): string | null {
   if (selection.id) return idSelector(selection.id);
   if (selection.selector) return selection.selector;
   return null;
 }
 
+/** `[name="value"]`, with the quote/backslash escaping a CSS string needs. */
+function attributeSelector(name: string, value: string): string {
+  return `[${name}="${value.replace(/(["\\])/g, "\\$1")}"]`;
+}
+
+/**
+ * Whether `selector` addresses `element` AND NOTHING ELSE. The single test for
+ * "this string is safe to author a new tween against": a selector that also
+ * hits siblings writes a tween that animates all of them.
+ */
+export function matchesExactlyOne(doc: Document, selector: string, element: Element): boolean {
+  try {
+    const matches = doc.querySelectorAll(selector);
+    return matches.length === 1 && matches[0] === element;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A structural address for an element that carries no identity of its own:
+ * `:nth-child` steps up to the nearest ancestor that IS uniquely addressable
+ * (an id or a data-hf-id). This is the `selector` + `selectorIndex` pair the
+ * selection already carries, resolved through the live DOM the index was
+ * counted in — an index can't be spelled in CSS, but the element's position can.
+ */
+function structuralSelector(element: Element): string | null {
+  const doc = element.ownerDocument;
+  if (!doc) return null;
+  const parts: string[] = [];
+  for (let node: Element | null = element; node; node = node.parentElement) {
+    if (node !== element) {
+      const id = node instanceof HTMLElement ? node.id : "";
+      const hfId = node.getAttribute("data-hf-id");
+      if (id) {
+        parts.unshift(idSelector(id));
+        break;
+      }
+      if (hfId) {
+        parts.unshift(attributeSelector("data-hf-id", hfId));
+        break;
+      }
+    }
+    const parent = node.parentElement;
+    if (!parent) break;
+    const index = [...parent.children].indexOf(node) + 1;
+    if (index < 1) return null;
+    parts.unshift(`${node.tagName.toLowerCase()}:nth-child(${index})`);
+  }
+  if (parts.length === 0) return null;
+  const selector = parts.join(" > ");
+  return matchesExactlyOne(doc, selector, element) ? selector : null;
+}
+
+/**
+ * The selector to author a NEW tween with. Distinct from
+ * {@link selectorFromSelection}, which must keep returning the exact string an
+ * already-authored tween is string-matched against (findTweenAtTime): this one
+ * has to ADDRESS ONE ELEMENT.
+ *
+ * `buildStableSelector` hands back a bare class for any element without an id,
+ * so "add keyframe at playhead" on one of five `.group` siblings wrote
+ * `tl.set(".group", …)` — a tween that animates all five and that
+ * {@link resolveSelectorElementIds} reads back as all five, collapsing their
+ * timeline rows into one. Every rung below resolves to exactly one element.
+ *
+ * Null means "no string here addresses one element". With a live DOM to check
+ * against, a failed structural walk (detached between select and commit, a
+ * shadow-root boundary, a chain that no longer re-resolves) IS that evidence,
+ * so returning the bare selector anyway would hand back the exact input this
+ * function exists to replace. Every caller treats the null as "do not author
+ * this tween": falling back to the selection's own selector would write the
+ * group-collapsing target this function exists to prevent, and a gesture that
+ * does not persist reverts visibly on the next reload, where a tween silently
+ * aimed at five elements does not. The bare selector comes back only with no DOM
+ * to disambiguate against, where refusing would be guessing rather than knowing.
+ */
+export function writeTargetSelector(selection: DomEditSelection): string | null {
+  if (selection.id) return idSelector(selection.id);
+  if (selection.hfId) return attributeSelector("data-hf-id", selection.hfId);
+  const element = selection.element;
+  const doc = element?.ownerDocument;
+  if (element && doc) {
+    if (selection.selector && matchesExactlyOne(doc, selection.selector, element)) {
+      return selection.selector;
+    }
+    return structuralSelector(element);
+  }
+  return selection.selector ?? null;
+}
+
+/**
+ * The selector a `replace-with-keyframes` mutation must re-author an EXISTING
+ * tween against. The server deletes the tween and adds it back, so this string
+ * REWRITES its target: deriving it from the selection instead discards whatever
+ * the author aimed at, and silently widens a tween {@link writeTargetSelector}
+ * had already narrowed to one element back onto every class sibling.
+ *
+ * The selection is the fallback only for a target the parser could not resolve
+ * statically, where there is no authored string to preserve.
+ */
+export function existingTweenTargetSelector(
+  animation: Pick<GsapAnimation, "targetSelector" | "hasUnresolvedSelector">,
+  selection: DomEditSelection,
+): string | null {
+  if (animation.targetSelector && !animation.hasUnresolvedSelector) {
+    return animation.targetSelector;
+  }
+  return selectorFromSelection(selection);
+}
+
+/**
+ * The read half of {@link writeTargetSelector}: does an already-authored tween
+ * write THIS element?
+ *
+ * String equality against `selectorFromSelection` alone is not enough once new
+ * tweens are authored with a narrowed one-element selector: the next edit would
+ * miss the write it just made and append a second, conflicting one. Falling back
+ * to the live DOM keeps the pair consistent.
+ *
+ * That fallback is `matchesExactlyOne`, not a bare `element.matches`. A target
+ * the element merely shares with its siblings is a GROUP tween, and the callers
+ * here MUTATE what they find: an individual nudge on one of five `.group`
+ * siblings would rewrite the group's own tween and move all five. Only the
+ * selection that IS the group (string equality above, where the author selected
+ * `.group` itself) may edit it; every other element authors its own write.
+ */
+export function tweenTargetsElement(
+  targetSelector: string,
+  selector: string,
+  element: Element | null | undefined,
+): boolean {
+  if (targetSelector === selector) return true;
+  const doc = element?.ownerDocument;
+  if (!element || !doc) return false;
+  return matchesExactlyOne(doc, targetSelector, element);
+}
+
 // ── Percentage computation ────────────────────────────────────────────────────
 
 /**
@@ -259,6 +462,67 @@ export function toAbsoluteTime(tweenPos: number, tweenDur: number, percentage: n
   return tweenPos + (percentage / 100) * tweenDur;
 }
 
+/**
+ * Timing basis for an element's keyframes, expressed in the TWEEN's own time
+ * frame. Sub-composition internals (e.g. pills inside a scene) aren't timeline
+ * clips themselves — they're derived at expand time — so they're absent from
+ * `elements`. Without a basis, elDuration defaulted to 1 and clip-relative
+ * keyframe percentages blew past 100% (rendering off the clip). Fall back to the
+ * sub-comp HOST's bounds, resolved via domClipChildren (the host's
+ * data-composition-src is stripped in the rendered DOM, so we can't query it).
+ *
+ * `elStart` is the clip's start in the frame the tween's own times are measured
+ * in. A sub-composition tween's resolvedStart is composition-local while a
+ * timeline element's start is main-timeline absolute, so passing the raw element
+ * start subtracted two different frames from each other: a host mounted at 1.5s
+ * cached its 0s tween at -12%, and a clip-relative percentage can never be
+ * negative. The composition's mount is `expandedParentStart` for an expanded
+ * child, the parent composition clip's start otherwise, and 0 for a
+ * root-composition element, whose start already IS the tween frame.
+ */
+export function resolveClipTimingBasis(
+  elementId: string,
+  sourceFile: string,
+  elements: ReadonlyArray<{
+    domId?: string;
+    key?: string;
+    id: string;
+    start: number;
+    duration: number;
+    expandedParentStart?: number;
+    parentCompositionId?: string | null;
+  }>,
+  domClipChildren: ReadonlyArray<{ id: string; hostId: string }>,
+): { elStart: number; elDuration: number } {
+  const direct = elements.find(
+    (el) => el.domId === elementId || (el.key ?? el.id) === `${sourceFile}#${elementId}`,
+  );
+  if (direct) {
+    const parentId = direct.parentCompositionId;
+    const parent = parentId
+      ? elements.find((el) => el.domId === parentId || el.id === parentId)
+      : undefined;
+    const mount = direct.expandedParentStart ?? parent?.start;
+    if (mount !== undefined) return { elStart: direct.start - mount, elDuration: direct.duration };
+    // No parent composition named, so this IS a main-timeline clip and its own
+    // start is already the basis.
+    if (!parentId) return { elStart: direct.start, elDuration: direct.duration };
+    // It named a parent we cannot find, so the mount is unknowable. Its tweens
+    // are still composition-local, so treat its own window as the frame rather
+    // than subtracting nothing and handing back a main-timeline start, which is
+    // exactly the mixed-frame subtraction this function exists to prevent.
+    return { elStart: 0, elDuration: direct.duration };
+  }
+  const hostId = domClipChildren.find((c) => c.id === elementId)?.hostId;
+  const host = hostId
+    ? elements.find((el) => el.domId === hostId || (el.key ?? el.id) === `index.html#${hostId}`)
+    : undefined;
+  // The inner element is not a clip of its own: the host's window IS the frame
+  // its tweens are timed in, so the start in that frame is 0, not the host's
+  // main-timeline mount.
+  return { elStart: 0, elDuration: host?.duration ?? 1 };
+}
+
 /**
  * An absolute time as a percentage of a timeline clip, at the one precision every
  * keyframe-cache writer must share. 0.001% keeps a beat-snapped keyframe centered