@hyperframes/studio 0.7.75 → 0.7.77

package/src/hooks/gsapKeyframeCacheHelpers.test.ts

@@ -4,6 +4,7 @@ import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerS
 import {
   clearKeyframeCacheForElement,
   clearKeyframeCacheForFile,
+  pruneKeyframeCacheToFiles,
   updateKeyframeCacheFromParsed,
 } from "./gsapKeyframeCacheHelpers";
 
@@ -28,7 +29,7 @@ const animWithKeyframes = (id: string): GsapAnimation => ({
 });
 
 beforeEach(() => {
-  usePlayerStore.setState({ keyframeCache: new Map(), elements: [] });
+  usePlayerStore.setState({ keyframeCache: new Map(), gsapAnimations: new Map(), elements: [] });
 });
 
 describe("clearKeyframeCacheForElement", () => {
@@ -84,6 +85,20 @@ describe("clearKeyframeCacheForFile", () => {
     }
   });
 
+  // Several composition files re-scan concurrently, so a clear that walked the
+  // index.html alias would delete rows a sibling file had just written.
+  it("leaves an index.html-owned element alone when another file re-scans", () => {
+    seed("index.html#title");
+    seed("title");
+    seed("comp.html#a");
+
+    clearKeyframeCacheForFile("comp.html");
+
+    expect(cache().has("index.html#title")).toBe(true);
+    expect(cache().has("title")).toBe(true);
+    expect(cache().has("comp.html#a")).toBe(false);
+  });
+
   it("leaves entries that belong to a different source file", () => {
     seed("comp.html#a");
     seed("a");
@@ -97,7 +112,84 @@ describe("clearKeyframeCacheForFile", () => {
   });
 });
 
+describe("pruneKeyframeCacheToFiles", () => {
+  // Switching composition leaves the previous comp's elements cached with no
+  // owner left to clear them: each file only ever clears its own entries.
+  it("drops every element of a file the next scan no longer covers", () => {
+    seed("index.html#stress-1");
+    seed("stress-1");
+    seed("index.html#stress-2");
+    seed("stress-2");
+    seed("kf200.html#kf200");
+    seed("index.html#kf200");
+    seed("kf200");
+
+    pruneKeyframeCacheToFiles(["kf200.html"]);
+
+    for (const key of ["index.html#stress-1", "stress-1", "index.html#stress-2", "stress-2"]) {
+      expect(cache().has(key)).toBe(false);
+    }
+    expect(cache().has("kf200.html#kf200")).toBe(true);
+  });
+
+  it("prunes gsapAnimations alongside keyframeCache", () => {
+    usePlayerStore.getState().setGsapAnimations("index.html#stress-1", [animWithKeyframes("t")]);
+    usePlayerStore.getState().setGsapAnimations("kf200.html#kf200", [animWithKeyframes("u")]);
+
+    pruneKeyframeCacheToFiles(["kf200.html"]);
+
+    const animations = usePlayerStore.getState().gsapAnimations;
+    expect(animations.has("index.html#stress-1")).toBe(false);
+    expect(animations.has("kf200.html#kf200")).toBe(true);
+  });
+
+  it("keeps everything when every cached file is still covered", () => {
+    seed("index.html#hero");
+    seed("comp.html#a");
+
+    pruneKeyframeCacheToFiles(["index.html", "comp.html"]);
+
+    expect(cache().has("index.html#hero")).toBe(true);
+    expect(cache().has("comp.html#a")).toBe(true);
+  });
+});
+
 describe("updateKeyframeCacheFromParsed", () => {
+  it("serializes a multi-keyframe tween with a stable shape and animation identity", () => {
+    const animation: GsapAnimation = {
+      ...animWithKeyframes("hero"),
+      duration: 2,
+      resolvedStart: 3,
+      keyframes: {
+        format: "percentage",
+        keyframes: [
+          { percentage: 0, properties: { x: 0 } },
+          { percentage: 50, properties: { x: 100 }, ease: "power1.inOut" },
+          { percentage: 100, properties: { x: 200 } },
+        ],
+        easeEach: "power1.inOut",
+      },
+    };
+    usePlayerStore.setState({
+      elements: [
+        {
+          id: "hero-clip",
+          domId: "hero",
+          tag: "div",
+          start: 2,
+          duration: 4,
+          track: 0,
+        },
+      ],
+    });
+
+    updateKeyframeCacheFromParsed([animation], "scene.html", "hero", {});
+
+    expect(JSON.stringify(cache().get("scene.html#hero"))).toBe(
+      '{"format":"percentage","keyframes":[{"percentage":25,"properties":{"x":0},"tweenPercentage":0,"propertyGroup":"position","animationId":"hero"},{"percentage":50,"properties":{"x":100},"ease":"power1.inOut","tweenPercentage":50,"propertyGroup":"position","animationId":"hero"},{"percentage":75,"properties":{"x":200},"tweenPercentage":100,"propertyGroup":"position","animationId":"hero"}],"easeEach":"power1.inOut"}',
+    );
+  });
+
   it("clears the bare key when the selected element no longer has keyframes", () => {
     // Element previously had keyframes, so a bare entry exists (writes set both).
     seed("index.html#box");
@@ -118,4 +210,87 @@ describe("updateKeyframeCacheFromParsed", () => {
     expect(cache().has("index.html#hero")).toBe(true);
     expect(cache().has("hero")).toBe(true);
   });
+
+  it("caches flat tweens as clip-relative start and end keyframes", () => {
+    const animation: GsapAnimation = {
+      id: "flat-box",
+      targetSelector: "#box",
+      method: "to",
+      position: 1,
+      properties: { x: 420 },
+      duration: 2,
+      resolvedStart: 1,
+      ease: "power2.out",
+      propertyGroup: "position",
+    };
+    usePlayerStore.setState({
+      elements: [{ id: "box-clip", domId: "box", tag: "div", start: 1, duration: 2, track: 0 }],
+    });
+
+    updateKeyframeCacheFromParsed([animation], "scene.html", "box", {});
+
+    expect(cache().get("scene.html#box")).toEqual({
+      format: "percentage",
+      keyframes: [
+        {
+          percentage: 0,
+          properties: { x: 0 },
+          tweenPercentage: 0,
+          propertyGroup: "position",
+          animationId: "flat-box",
+        },
+        {
+          percentage: 100,
+          properties: { x: 420 },
+          ease: "power2.out",
+          tweenPercentage: 100,
+          propertyGroup: "position",
+          animationId: "flat-box",
+        },
+      ],
+    });
+    expect(usePlayerStore.getState().gsapAnimations.get("scene.html#box")).toEqual([animation]);
+  });
+
+  it("records an ungrouped tween in gsapAnimations too, so the two stores agree", () => {
+    // `{ x, opacity }` spans two property groups, so the parser leaves
+    // propertyGroup undefined. Skipping it here used to cache diamonds with no
+    // source animation behind them: the collapsed row drew keyframes the
+    // expanded lanes could not render.
+    const animation: GsapAnimation = {
+      id: "mixed-box",
+      targetSelector: "#box",
+      method: "to",
+      position: 0,
+      properties: { x: 100, opacity: 0 },
+      duration: 1,
+      resolvedStart: 0,
+    };
+    usePlayerStore.setState({
+      elements: [{ id: "box-clip", domId: "box", tag: "div", start: 0, duration: 1, track: 0 }],
+    });
+
+    updateKeyframeCacheFromParsed([animation], "scene.html", "box", {});
+
+    expect(cache().has("scene.html#box")).toBe(true);
+    expect(usePlayerStore.getState().gsapAnimations.get("scene.html#box")).toEqual([animation]);
+  });
+
+  it("does not cache a flat tween without animatable numeric properties", () => {
+    const animation: GsapAnimation = {
+      id: "flat-box",
+      targetSelector: "#box",
+      method: "to",
+      position: 0,
+      properties: { backgroundColor: "#fff" },
+      duration: 1,
+      propertyGroup: "visual",
+    };
+
+    updateKeyframeCacheFromParsed([animation], "scene.html", "box", {});
+
+    expect(cache().has("scene.html#box")).toBe(false);
+    expect(cache().has("box")).toBe(false);
+    expect(usePlayerStore.getState().gsapAnimations.has("scene.html#box")).toBe(false);
+  });
 });

package/src/hooks/gsapKeyframeCacheHelpers.ts

@@ -4,7 +4,8 @@
  */
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerStore";
-import { toAbsoluteTime } from "./gsapShared";
+import { idFromSelector, toClipKeyframes } from "./gsapShared";
+import { deduplicateKeyframes, synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
 
 export function updateKeyframeCacheFromParsed(
   animations: GsapAnimation[],
@@ -15,57 +16,52 @@ export function updateKeyframeCacheFromParsed(
   const { setKeyframeCache, elements } = 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 = anim.targetSelector.match(/^#([\w-]+)/)?.[1];
-    if (!id || !anim.keyframes) continue;
+    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]);
 
     // Convert tween-relative percentages to clip-relative so diamonds
     // render at the correct position within the timeline clip.
-    const tweenPos = anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
-    const tweenDur = anim.duration ?? 1;
     const timelineEl = elements.find(
       (el) => el.domId === id || (el.key ?? el.id) === `${targetPath}#${id}`,
     );
-    const elStart = timelineEl?.start ?? 0;
-    const elDuration = timelineEl?.duration ?? 1;
-    const clipKeyframes = anim.keyframes.keyframes.map((kf) => {
-      const absTime = toAbsoluteTime(tweenPos, tweenDur, kf.percentage);
-      const clipPct =
-        elDuration > 0 ? Math.round(((absTime - elStart) / elDuration) * 1000) / 10 : kf.percentage;
-      return {
-        ...kf,
-        percentage: clipPct,
-        tweenPercentage: kf.percentage,
-        propertyGroup: anim.propertyGroup,
-      };
-    });
+    const clipKeyframes = toClipKeyframes(
+      kfSource,
+      anim,
+      timelineEl?.start ?? 0,
+      timelineEl?.duration ?? 1,
+    );
 
     const existing = merged.get(id);
     if (existing) {
-      const byPct = new Map<number, (typeof existing.keyframes)[0]>();
-      for (const kf of [...existing.keyframes, ...clipKeyframes]) {
-        const prev = byPct.get(kf.percentage);
-        if (prev) {
-          prev.properties = { ...prev.properties, ...kf.properties };
-          if (kf.ease) prev.ease = kf.ease;
-        } else {
-          byPct.set(kf.percentage, { ...kf, properties: { ...kf.properties } });
-        }
-      }
-      existing.keyframes = Array.from(byPct.values()).sort((a, b) => a.percentage - b.percentage);
+      // 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, keyframes: clipKeyframes });
+      merged.set(id, {
+        ...anim.keyframes,
+        format: anim.keyframes?.format ?? "percentage",
+        keyframes: clipKeyframes,
+      });
     }
   }
   for (const [id, entry] of merged) {
-    setKeyframeCache(`${targetPath}#${id}`, entry);
-    setKeyframeCache(id, entry);
-    if (targetPath !== "index.html") setKeyframeCache(`index.html#${id}`, entry);
+    for (const key of elementCacheKeys(targetPath, id)) setKeyframeCache(key, entry);
+    writeGsapAnimationsForElement(targetPath, id, sourceAnimations.get(id));
   }
   const targetId =
-    (mutation as { targetSelector?: string }).targetSelector?.match(/^#([\w-]+)/)?.[1] ??
-    selectionId;
+    idFromSelector((mutation as { targetSelector?: string }).targetSelector) ?? selectionId;
   if (targetId && !idsWithKeyframes.has(targetId)) {
     clearKeyframeCacheForElement(targetPath, targetId);
   }
@@ -84,40 +80,85 @@ export function updateKeyframeCacheFromParsed(
  * a new cache map and re-render every subscriber.
  */
 export function clearKeyframeCacheForElement(sourceFile: string, elementId: string): void {
-  const { keyframeCache, setKeyframeCache } = usePlayerStore.getState();
-  const keys =
-    sourceFile === "index.html"
-      ? [`index.html#${elementId}`, elementId]
-      : [`${sourceFile}#${elementId}`, `index.html#${elementId}`, elementId];
+  const { keyframeCache, setKeyframeCache, gsapAnimations, setGsapAnimations } =
+    usePlayerStore.getState();
+  const keys = elementCacheKeys(sourceFile, elementId);
   for (const key of keys) {
     if (keyframeCache.has(key)) setKeyframeCache(key, undefined);
+    if (gsapAnimations.has(key)) setGsapAnimations(key, undefined);
   }
 }
 
 /**
  * Clear every cached element of `sourceFile` before a full re-scan repopulates
- * it. Collects the element ids that currently have a prefixed or index.html
- * fallback key for the file and drops each through clearKeyframeCacheForElement
- * so the bare key goes too — an element whose keyframes were removed (and so is
- * absent from the re-scan) leaves no stale bare entry behind.
+ * it. Only the file's OWN prefixed keys name the ids to clear: every write sets
+ * the prefixed key (see elementCacheKeys), so the file's elements are all
+ * reachable that way, and clearKeyframeCacheForElement then takes the
+ * index.html alias and the bare key with them — an element whose keyframes were
+ * removed (and so is absent from the re-scan) leaves no stale bare entry
+ * behind. Reading the alias prefix here instead would collect ids owned by
+ * OTHER files, and several files re-scan concurrently, so this file's clear
+ * would wipe the entries a sibling file had just written.
  */
 export function clearKeyframeCacheForFile(sourceFile: string): void {
-  const { keyframeCache } = usePlayerStore.getState();
+  const { keyframeCache, gsapAnimations } = usePlayerStore.getState();
   const sfPrefix = `${sourceFile}#`;
-  const fallbackPrefix = "index.html#";
   const ids = new Set<string>();
-  for (const key of keyframeCache.keys()) {
-    const matchesFile =
-      key.startsWith(sfPrefix) || (sourceFile !== "index.html" && key.startsWith(fallbackPrefix));
-    if (!matchesFile) continue;
-    const hashIdx = key.indexOf("#");
-    if (hashIdx !== -1) ids.add(key.slice(hashIdx + 1));
+  for (const key of [...keyframeCache.keys(), ...gsapAnimations.keys()]) {
+    if (!key.startsWith(sfPrefix)) continue;
+    ids.add(key.slice(sfPrefix.length));
   }
   for (const id of ids) {
     clearKeyframeCacheForElement(sourceFile, id);
   }
 }
 
+/**
+ * Drop every cached element owned by a file that is no longer on screen. Each
+ * file only ever clears its OWN entries (see clearKeyframeCacheForFile), so
+ * switching composition left the previous composition's elements cached forever
+ * — 240 entries per switch on a 120-clip comp, in both keyframeCache and
+ * gsapAnimations, with nothing to evict them. Called once before a re-scan, with
+ * the full set of files that scan covers.
+ */
+export function pruneKeyframeCacheToFiles(files: readonly string[]): void {
+  const keep = new Set(files);
+  const { keyframeCache, gsapAnimations } = usePlayerStore.getState();
+  const stale = new Map<string, Set<string>>();
+  for (const key of [...keyframeCache.keys(), ...gsapAnimations.keys()]) {
+    const hash = key.indexOf("#");
+    // Bare-id aliases carry no owner; clearKeyframeCacheForElement takes them
+    // with their prefixed key, so skipping them here loses nothing.
+    if (hash < 0) continue;
+    const sourceFile = key.slice(0, hash);
+    if (keep.has(sourceFile)) continue;
+    const ids = stale.get(sourceFile) ?? new Set<string>();
+    ids.add(key.slice(hash + 1));
+    stale.set(sourceFile, ids);
+  }
+  for (const [sourceFile, ids] of stale) {
+    for (const id of ids) clearKeyframeCacheForElement(sourceFile, id);
+  }
+}
+
+/** Every cache key a write for this element sets, in read-preference order. */
+export function elementCacheKeys(sourceFile: string, elementId: string): string[] {
+  return sourceFile === "index.html"
+    ? [`index.html#${elementId}`, elementId]
+    : [`${sourceFile}#${elementId}`, `index.html#${elementId}`, elementId];
+}
+
+export function writeGsapAnimationsForElement(
+  sourceFile: string,
+  elementId: string,
+  animations: GsapAnimation[] | undefined,
+): void {
+  const { setGsapAnimations } = usePlayerStore.getState();
+  for (const key of elementCacheKeys(sourceFile, elementId)) {
+    setGsapAnimations(key, animations);
+  }
+}
+
 function buildCacheKey(sourceFile: string, elementId: string): string {
   return `${sourceFile}#${elementId}`;
 }

package/src/hooks/gsapRuntimeBridge.test.ts

@@ -280,3 +280,103 @@ describe("tryGsapDragIntercept — autoKeyframeEnabled toggle (#1808)", () => {
     expect(types).not.toContain("replace-with-keyframes");
   });
 });
+
+describe("tryGsapDragIntercept — motion paths", () => {
+  const motionPathAnim = {
+    id: "#puck-b-to-12170-position",
+    targetSelector: "#puck-b",
+    propertyGroup: "position",
+    method: "to",
+    position: 12.17,
+    resolvedStart: 12.17,
+    duration: 16.055,
+    ease: "power1.inOut",
+    properties: {},
+    keyframes: {
+      keyframes: [
+        { percentage: 0, properties: { x: -184, y: 326 } },
+        { percentage: 50, properties: { x: 416, y: 804 } },
+        { percentage: 100, properties: { x: 796, y: 237 } },
+      ],
+    },
+    arcPath: {
+      enabled: true,
+      autoRotate: false,
+      segments: [{ curviness: 1 }, { curviness: 1 }],
+    },
+  } as unknown as GsapAnimation;
+  const liveTween = {
+    targets: () => [{ id: "puck-b" }],
+    vars: { motionPath: { path: [] }, duration: 16.055 },
+    duration: () => 16.055,
+    startTime: () => 12.17,
+  };
+
+  async function dragMotionPath(activeKeyframePct: number | null) {
+    usePlayerStore.setState({
+      autoKeyframeEnabled: true,
+      activeKeyframePct,
+      currentTime: 15.9,
+    });
+    const commitMutation = vi.fn();
+    const handled = await tryGsapDragIntercept(
+      selection,
+      { x: -50, y: 30 },
+      [motionPathAnim],
+      fakeIframe("puck-b", [liveTween]),
+      commitMutation,
+    );
+    return { commitMutation, handled };
+  }
+
+  afterEach(() => {
+    usePlayerStore.setState({ activeKeyframePct: null });
+  });
+
+  it("creates a temporal keyframe at the exact playhead instead of redistributing path waypoints", async () => {
+    const { commitMutation, handled } = await dragMotionPath(null);
+
+    expect(handled).toBe(true);
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      {
+        type: "replace-with-keyframes",
+        animationId: motionPathAnim.id,
+        targetSelector: "#puck-b",
+        position: 12.17,
+        duration: 16.055,
+        keyframes: [
+          { percentage: 0, properties: { x: -184, y: 326 } },
+          { percentage: 23.233, properties: { x: -50, y: 30 } },
+          { percentage: 50, properties: { x: 416, y: 804 } },
+          { percentage: 100, properties: { x: 796, y: 237 } },
+        ],
+        ease: "none",
+      },
+      expect.objectContaining({ label: "Move layer (new keyframe)", softReload: true }),
+    );
+    expect(commitMutation.mock.calls.map(([, mutation]) => mutation.type)).not.toContain(
+      "add-motion-path-point",
+    );
+  });
+
+  it("keeps an explicitly selected path waypoint as a spatial edit", async () => {
+    const { commitMutation, handled } = await dragMotionPath(50);
+
+    expect(handled).toBe(true);
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      {
+        type: "update-motion-path-point",
+        animationId: motionPathAnim.id,
+        pointIndex: 1,
+        x: -50,
+        y: 30,
+      },
+      expect.objectContaining({ label: "Move layer (waypoint)", softReload: true }),
+    );
+    expect(commitMutation.mock.calls.map(([, mutation]) => mutation.type)).not.toContain(
+      "replace-with-keyframes",
+    );
+  });
+});

package/src/hooks/gsapScriptCommitHelpers.ts

@@ -2,12 +2,13 @@ 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";
 
 export function ensureElementAddressable(selection: DomEditSelection): {
   selector: string;
   autoId?: string;
 } {
-  if (selection.id) return { selector: `#${selection.id}` };
+  if (selection.id) return { selector: idSelector(selection.id) };
   if (selection.selector) return { selector: selection.selector };
 
   const el = selection.element;
@@ -20,7 +21,7 @@ export function ensureElementAddressable(selection: DomEditSelection): {
     id = `${tag}-${n}`;
   }
   el.setAttribute("id", id);
-  return { selector: `#${id}`, autoId: id };
+  return { selector: idSelector(id), autoId: id };
 }
 
 export class GsapMutationHttpError extends Error {

package/src/hooks/gsapScriptCommitTypes.ts

@@ -16,6 +16,8 @@ export interface MutationResult {
 
 export interface CommitMutationOptions {
   label: string;
+  /** Observe the durable writer result without duplicating the request path. */
+  onResult?: (result: MutationResult) => void;
   coalesceKey?: string;
   coalesceMs?: number;
   softReload?: boolean;

package/src/hooks/gsapShared.test.ts

@@ -1,6 +1,31 @@
 import { describe, it, expect } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { isInstantHold, parsePercentageKeyframes } from "./gsapShared";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import {
+  idFromSelector,
+  idSelector,
+  isInstantHold,
+  parsePercentageKeyframes,
+  resolveEditableTweenDuration,
+  toClipKeyframes,
+  toClipPercentage,
+} from "./gsapShared";
+
+// Fixtures carry only the fields the function under test reads; the double-cast
+// is the documented way to stand in for the full runtime shape (CONTRIBUTING.md).
+const tween = (duration: number | undefined) => ({ duration }) as unknown as GsapAnimation;
+
+describe("resolveEditableTweenDuration", () => {
+  const selection = { dataAttributes: { duration: "16.26" } } as unknown as DomEditSelection;
+
+  it("uses the owning clip duration when the tween omits an outer duration", () => {
+    expect(resolveEditableTweenDuration(tween(undefined), selection)).toBe(16.26);
+  });
+
+  it("keeps an explicitly-authored tween duration", () => {
+    expect(resolveEditableTweenDuration(tween(4), selection)).toBe(4);
+  });
+});
 
 describe("isInstantHold", () => {
   const animation = (method: GsapAnimation["method"], duration?: number) =>
@@ -74,3 +99,86 @@ describe("parsePercentageKeyframes", () => {
     expect(parsePercentageKeyframes({})).toBeNull();
   });
 });
+
+describe("idSelector", () => {
+  it("uses #id for valid CSS identifiers", () => {
+    expect(idSelector("hero-word")).toBe("#hero-word");
+    expect(idSelector("el_1")).toBe("#el_1");
+  });
+
+  it("uses an attribute selector for ids that #id can't address (digit-leading, dots, spaces)", () => {
+    // #01-... / #a.b / #a b throw a SyntaxError in querySelector / GSAP, crashing
+    // the preview when such a target is committed (e.g. dragging the element).
+    expect(idSelector("01-hook-hero-word")).toBe('[id="01-hook-hero-word"]');
+    expect(idSelector("my.class")).toBe('[id="my.class"]');
+    expect(idSelector("1box")).toBe('[id="1box"]');
+  });
+
+  it("escapes quotes and backslashes in the attribute selector value", () => {
+    expect(idSelector('1"x')).toBe('[id="1\\"x"]');
+  });
+
+  it("only ever emits #id for ids that can't break querySelector", () => {
+    // Every id resolves to either a plain #id (only when safe) or an attribute
+    // selector — never a #id that would throw a SyntaxError.
+    for (const id of ["hero-word", "01-hook", "a.b", "a b", "1", "--x", '1"q']) {
+      const sel = idSelector(id);
+      if (sel.startsWith("#")) expect(sel).toBe(`#${id}`);
+      else expect(sel.startsWith('[id="')).toBe(true);
+    }
+  });
+});
+
+describe("toClipPercentage", () => {
+  // Selection keys embed this number, so every keyframe-cache writer has to round
+  // it identically: a coarser writer rewrites the cache with a different value and
+  // orphans the live selection key built from the finer one.
+  it("keeps three decimals so a beat-snapped keyframe lands on its beat", () => {
+    expect(toClipPercentage(1 / 3, 0, 1, 0)).toBe(33.333);
+    expect(toClipPercentage(2.5, 2, 4, 0)).toBe(12.5);
+  });
+
+  it("passes the tween percentage through for a zero-length clip", () => {
+    expect(toClipPercentage(5, 0, 0, 42)).toBe(42);
+  });
+});
+
+describe("toClipKeyframes", () => {
+  // Fixture carries only the fields the function under test reads; the
+  // double-cast is the documented way to stand in for the full runtime shape
+  // (CONTRIBUTING.md).
+  const durationless = {
+    id: "a1",
+    method: "to",
+    targetSelector: "#box",
+    vars: {},
+    resolvedStart: 0,
+  } as unknown as GsapAnimation;
+
+  // A tween with no duration spans its clip everywhere else in Studio
+  // (resolveEditableTweenDuration), so the cache rows have to agree: a fixed 1s
+  // basis put the end keyframe at 25% of a 4s clip instead of 100%.
+  it("spans the clip when the tween has no duration", () => {
+    const rows = toClipKeyframes([{ percentage: 0 }, { percentage: 100 }], durationless, 0, 4);
+    expect(rows.map((row) => row.percentage)).toEqual([0, 100]);
+  });
+
+  it("keeps the tween percentage and the animation identity on every row", () => {
+    const rows = toClipKeyframes([{ percentage: 50 }], durationless, 0, 4);
+    expect(rows[0]).toMatchObject({ tweenPercentage: 50, animationId: "a1" });
+  });
+});
+
+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']) {
+      expect(idFromSelector(idSelector(id))).toBe(id);
+    }
+  });
+
+  it("returns null for a selector that does not address an id", () => {
+    expect(idFromSelector(".dot")).toBeNull();
+    expect(idFromSelector("[data-hf-id='x']")).toBeNull();
+    expect(idFromSelector(undefined)).toBeNull();
+  });
+});