@hyperframes/studio 0.8.114 → 0.8.116

package/src/hooks/gsapGestureOutcome.ts

@@ -0,0 +1,64 @@
+import type {
+  CommitMutationCall,
+  CommitMutation,
+  CommitMutationOptions,
+  MutationResult,
+} from "./gsapScriptCommitTypes";
+import {
+  keyframeUsageActions,
+  changedMutationIndices,
+  primaryKeyframeAction,
+  trackKeyframeUsage,
+  type KeyframeUsageAction,
+} from "../utils/keyframeUsage";
+import type { GeometryCommitResult } from "../utils/previewFeatureUsage";
+
+export function observeGsapGesture(writer: CommitMutation | null) {
+  let changed = false;
+  let pendingResults = 0;
+  const actions = new Set<KeyframeUsageAction>();
+  const observe = (calls: CommitMutationCall[], options: CommitMutationOptions) => {
+    pendingResults += 1;
+    return {
+      ...options,
+      keyframeTelemetry: false,
+      onResult: (result: MutationResult) => {
+        pendingResults -= 1;
+        options.onResult?.(result);
+        if (!result.ok || result.changed !== true) return;
+        changed = true;
+        const members = changedMutationIndices(
+          result,
+          calls.length,
+          calls.map((call) => call.options),
+        ).map((index) => calls[index]!);
+        for (const action of keyframeUsageActions(
+          members.map((call) => call.mutation),
+          members.map((call) => call.options.keyframeAction),
+        ))
+          actions.add(action);
+      },
+    };
+  };
+  let commit: CommitMutation | null = null;
+  if (writer) {
+    commit = (selection, mutation, options) =>
+      writer(selection, mutation, observe([{ selection, mutation, options }], options));
+    if (writer.batch) {
+      const batch = writer.batch;
+      commit.batch = (calls, options) => batch(calls, observe(calls, options));
+    }
+  }
+  return {
+    commit,
+    recordDomResult: (result: { changed: boolean } | undefined) => {
+      changed ||= result?.changed === true;
+    },
+    finish: (domChanged = false): GeometryCommitResult => {
+      if (pendingResults !== 0) return { ok: true, changed: false };
+      const action = primaryKeyframeAction(actions);
+      if (action) trackKeyframeUsage(action);
+      return { ok: true, changed: changed || domChanged };
+    },
+  };
+}

package/src/hooks/gsapGroupPreflight.ts

@@ -0,0 +1,34 @@
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { GsapEditBlockedError } from "./gsapEditOutcome";
+import { gsapWriteFile } from "./gsapScriptCommitTypes";
+
+/** The first member a group's preflight refused, else one from a second file. */
+export function firstPreflightFailure(
+  results: PromiseSettledResult<void>[],
+  updates: DomEditGroupPathOffsetCommit[],
+  savedOnElement: Map<DomEditSelection, boolean>,
+  activeCompPath: string | null | undefined,
+): { error: unknown; selection: DomEditSelection } | null {
+  for (const [index, result] of results.entries()) {
+    if (result.status !== "rejected") continue;
+    const selection = updates[index]?.selection;
+    if (selection) return { error: result.reason, selection };
+  }
+  return secondFile(updates, savedOnElement, activeCompPath);
+}
+
+/** The group's script writes go out as one batch to one file, so members from two files refuse. */
+function secondFile(
+  updates: DomEditGroupPathOffsetCommit[],
+  savedOnElement: Map<DomEditSelection, boolean>,
+  activeCompPath: string | null | undefined,
+): { error: unknown; selection: DomEditSelection } | null {
+  const scripted = updates.filter(({ selection }) => !savedOnElement.has(selection));
+  const fileOf = (s: DomEditSelection) => gsapWriteFile(s, activeCompPath);
+  const file = scripted[0] && fileOf(scripted[0].selection);
+  const other = scripted.find(({ selection }) => fileOf(selection) !== file);
+  return other
+    ? { error: new GsapEditBlockedError("mixed-files"), selection: other.selection }
+    : null;
+}

package/src/hooks/gsapKeyframeCommit.ts

@@ -4,23 +4,14 @@ import { absoluteToPercentageForAnimation, findTweenAtTime } from "../utils/glob
 import { PROPERTY_DEFAULTS, selectorFromSelection, writeTargetSelector } from "./gsapShared";
 import { roundToCenti } from "../utils/rounding";
 
-type CommitFn = (
-  selection: DomEditSelection,
-  mutation: Record<string, unknown>,
-  options: {
-    label: string;
-    coalesceKey?: string;
-    softReload?: boolean;
-    skipReload?: boolean;
-  },
-) => Promise<void>;
+import type { CommitMutation } from "./gsapScriptCommitTypes";
 
 export async function commitKeyframeAtTimeImpl(
   selection: DomEditSelection,
   absoluteTime: number,
   animations: GsapAnimation[],
   properties: Record<string, number | string>,
-  commitMutation: CommitFn,
+  commitMutation: CommitMutation,
 ): 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
@@ -38,7 +29,7 @@ export async function commitKeyframeAtTimeImpl(
       await commitMutation(
         selection,
         { type: "convert-to-keyframes", animationId: tween.id },
-        { label: "Convert to keyframes", skipReload: true },
+        { label: "Convert to keyframes", keyframeTelemetry: false, skipReload: true },
       );
     }
 

package/src/hooks/gsapMutationClient.ts

@@ -1,11 +1,12 @@
 import { studioWriteHeaders } from "../utils/studioFileVersion";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 export class GsapPreviewConvergenceError extends Error {}
 export class GsapOwnershipProtocolError extends GsapPreviewConvergenceError {}
 
 /** Verify rollback ownership support before any GSAP mutation can land. */
 export async function requireGsapOwnershipProtocol(projectId: string): Promise<void> {
-  const response = await fetch(
+  const response = await studioApiFetch(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-capabilities`,
   );
   if (!response.ok) {
@@ -29,7 +30,7 @@ export async function rollbackOwnedMutation(
   if (targetPath.includes("\0") || targetPath.includes("..")) {
     throw new Error(`Unsafe path: ${targetPath}`);
   }
-  const response = await fetch(
+  const response = await studioApiFetch(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-rollback/${encodeURIComponent(targetPath)}`,
     {
       method: "POST",
@@ -95,7 +96,7 @@ export async function postGsapMutation(
 ): Promise<GsapMutationStatus> {
   let response: Response;
   try {
-    response = await fetch(
+    response = await studioApiFetch(
       `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(filePath)}`,
       {
         method: "POST",

package/src/hooks/gsapParsedTween.test-helpers.ts

@@ -0,0 +1,75 @@
+import { vi } from "vitest";
+import { classifyTweenPropertyGroup } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { usePlayerStore } from "../player/store/playerStore";
+
+/** A property's `[start, end]` as GSAP parsed it from the file when the tween first rendered. */
+type Ends = Record<string, [number, number]>;
+
+/** A GSAP 3 tween as the preview runtime holds it, with the property tweens the parse readers walk. */
+export function liveTween(
+  target: Element,
+  tween: { start: number; duration: number; vars: Record<string, unknown>; ends?: Ends },
+  { from = false, parts }: { from?: boolean; parts?: unknown[] } = {},
+) {
+  let head: Record<string, unknown> | undefined;
+  for (const [p, [s, e]] of Object.entries(tween.ends ?? {}).reverse())
+    head = from ? { p, s: e, c: s - e, _next: head } : { p, s, c: e - s, _next: head };
+  return {
+    targets: () => [target],
+    startTime: () => tween.start,
+    duration: () => tween.duration,
+    vars: tween.vars,
+    _from: from,
+    ...(head && { _pt: { d: { _pt: head } } }),
+    ...(parts && { timeline: { getChildren: () => parts } }),
+  };
+}
+
+/** A preview iframe whose one timeline holds `tweens`, answering `getProperty` from `live`. */
+export function previewWith(
+  element: Element,
+  tweens: unknown[],
+  live: Record<string, number> = {},
+): HTMLIFrameElement {
+  return {
+    contentWindow: {
+      __timelines: { main: { getChildren: () => tweens, duration: () => 10 } },
+      gsap: {
+        getProperty: (_el: Element, prop: string) => live[prop] ?? 0,
+        defaults: () => ({ ease: "power1.out" }),
+      },
+    },
+    contentDocument: element.ownerDocument,
+  } as unknown as HTMLIFrameElement;
+}
+
+export const tween = (fields: Partial<GsapAnimation>): GsapAnimation =>
+  ({ targetSelector: "#box", propertyGroup: "position", ...fields }) as GsapAnimation;
+
+/** A `to` tween on `#el` from 0, grouped as the parser would; duration 0 is an immediate-render hold. */
+export function elTween(
+  id: string,
+  properties: Record<string, number>,
+  duration: number,
+  ease?: string,
+): GsapAnimation {
+  return {
+    id,
+    targetSelector: "#el",
+    propertyGroup: classifyTweenPropertyGroup(properties),
+    method: "to",
+    properties,
+    position: 0,
+    resolvedStart: 0,
+    duration,
+    ...(duration === 0 ? { extras: { immediateRender: "__raw:true" } } : ease && { ease }),
+  } as unknown as GsapAnimation;
+}
+
+/** Per-test cleanup for the intercept sweeps: mocks, the playhead store and the document. */
+export function resetGsapEditState(): void {
+  vi.restoreAllMocks();
+  usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null });
+  document.body.innerHTML = "";
+}

package/src/hooks/gsapParsedTween.test.ts

@@ -0,0 +1,62 @@
+// @vitest-environment happy-dom
+import { gsap } from "gsap";
+import { afterEach, describe, expect, it } from "vitest";
+import { findParsedTween, parsedImplicitEndValue } from "./gsapParsedTween";
+import { liveTween, previewWith, tween } from "./gsapParsedTween.test-helpers";
+
+type Parsed = Parameters<typeof parsedImplicitEndValue>[0];
+const el = document.createElement("div");
+const part = (start: number, ends?: Record<string, [number, number]>) =>
+  liveTween(el, { start, duration: 1, vars: { x: 0 }, ends });
+const keyframed = (parts: unknown[]) =>
+  liveTween(el, { start: 0, duration: 2, vars: { keyframes: [] } }, { parts }) as Parsed;
+
+describe("parsedImplicitEndValue", () => {
+  it("reads a flat tween's own start and end", () => {
+    const value = parsedImplicitEndValue(part(0, { x: [-60, 0] }) as Parsed);
+    expect([value("x", "start"), value("x", "end")]).toEqual([-60, 0]);
+  });
+
+  it("reads a keyframed tween's start from its first part and its end from its last", () => {
+    const value = parsedImplicitEndValue(
+      keyframed([part(0, { x: [0, 50] }), part(1, { x: [50, 120] })]),
+    );
+    expect([value("x", "start"), value("x", "end")]).toEqual([0, 120]);
+  });
+
+  it("refuses when the part nearest that end is not initialised, rather than read an earlier one", () => {
+    const value = parsedImplicitEndValue(keyframed([part(0, { x: [0, 50] }), part(1)]));
+    expect(value("x", "end")).toBeNull();
+  });
+
+  it("has no value without a parsed tween", () => {
+    expect(parsedImplicitEndValue(null)("x", "start")).toBeNull();
+  });
+});
+
+describe("findParsedTween", () => {
+  afterEach(() => document.body.replaceChildren());
+
+  it("takes the flat tween an edit names, not a keyframed tween at the same start", () => {
+    const fade = liveTween(el, { start: 0, duration: 2, vars: { keyframes: {}, ease: "none" } });
+    const slide = liveTween(el, { start: 0, duration: 2, vars: { x: 300 } });
+    const edit = tween({ method: "to", properties: { x: 300 }, resolvedStart: 0, duration: 2 });
+    expect(findParsedTween(previewWith(el, [fade, slide]), el, edit)).toBe(slide);
+  });
+
+  it("parses a to() tween the playhead has not reached, from its authored start", () => {
+    const box = document.body.appendChild(document.createElement("div"));
+    box.id = "box";
+    const timeline = gsap.timeline({ paused: true }).to(box, { x: 300, duration: 1 }, 2);
+    timeline.seek(0.5);
+    gsap.set(box, { x: 40 });
+    const iframe = { contentWindow: { __timelines: { main: timeline }, gsap } };
+    const edit = tween({ method: "to", properties: { x: 300 }, resolvedStart: 2, duration: 1 });
+
+    const parsed = findParsedTween(iframe as unknown as HTMLIFrameElement, box, edit);
+
+    expect(parsedImplicitEndValue(parsed)("x", "start")).toBe(0);
+    expect([gsap.getProperty(box, "x"), timeline.time()]).toEqual([40, 0.5]);
+    timeline.kill();
+  });
+});

package/src/hooks/gsapParsedTween.ts

@@ -0,0 +1,243 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { elementTargets } from "../utils/elementGsap";
+import { resolveTweenStart } from "../utils/globalTimeCompiler";
+import type { ImplicitEndValue } from "./gsapValueAtPlayhead";
+
+// GSAP 3 internals: a property tween in a tween's `_pt` chain; CSSPlugin keeps its own under `d._pt`.
+interface PropTween {
+  p?: string;
+  s?: number;
+  c?: number;
+  d?: { _pt?: PropTween };
+  _next?: PropTween;
+}
+interface ParsedTween {
+  _pt?: PropTween;
+  _from?: boolean;
+  _initted?: boolean;
+  vars?: Record<string, unknown>;
+  parent?: {
+    vars?: { defaults?: { ease?: unknown } };
+    time?: () => number;
+    seek?: (time: number, suppressEvents?: boolean) => unknown;
+    getChildren?: (nested?: boolean, tweens?: boolean, timelines?: boolean) => ParsedTween[];
+  };
+  timeline?: { getChildren?: () => ParsedTween[] };
+  targets?: () => unknown[];
+  startTime?: () => number;
+  duration?: () => number;
+}
+interface GsapWindow {
+  gsap?: {
+    defaults?: () => { ease?: unknown };
+    getProperty?: (target: Element, prop: string) => unknown;
+    set?: (target: Element, vars: Record<string, unknown>) => void;
+    parseEase?: (name: string) => unknown;
+  };
+  __timelines?: Record<string, { getChildren?: (nested: boolean) => ParsedTween[] }>;
+}
+
+// `scale` parses into the two longhands, which always share a start and end for a `scale` tween.
+const PARSED_NAME: Record<string, string> = { scale: "scaleX", rotate: "rotation" };
+
+function findPropTween(pt: PropTween | undefined, prop: string): PropTween | null {
+  for (let node = pt; node; node = node._next) {
+    if (node.p === prop && typeof node.s === "number" && typeof node.c === "number") return node;
+    const nested = findPropTween(node.d?._pt, prop);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+/** `[start, end]` of `prop` in one initialised tween; a from() tween runs its pair backwards. */
+function endsIn(tween: ParsedTween, prop: string): [number, number] | null {
+  const pt = findPropTween(tween._pt, PARSED_NAME[prop] ?? prop);
+  if (!pt) return null;
+  const pair: [number, number] = [pt.s!, pt.s! + pt.c!];
+  return tween._from ? [pair[1], pair[0]] : pair;
+}
+
+/** The live tween GSAP built from `anim`: same element, start and channels, parsed. */
+// fallow-ignore-next-line complexity
+export function findParsedTween(
+  iframe: HTMLIFrameElement | null,
+  element: Element,
+  anim: GsapAnimation,
+): ParsedTween | null {
+  const win = iframe?.contentWindow as GsapWindow | null;
+  const start = resolveTweenStart(anim);
+  if (!win?.__timelines || start == null) return null;
+  const steps = anim.keyframes?.keyframes.map((kf) => kf.properties) ?? [anim.properties];
+  const props = [...new Set(steps.flatMap((step) => Object.keys(step)))];
+  const keyframed = Boolean(anim.keyframes);
+  for (const timeline of Object.values(win.__timelines)) {
+    for (const tween of timeline?.getChildren?.(true) ?? []) {
+      const targets = (tween.targets?.() ?? []) as Array<{ id?: unknown }>;
+      if (!targets.includes(element) && !targets.some((t) => element.id && t.id === element.id))
+        continue;
+      if (!startsAt(tween, start)) continue;
+      const vars = tween.vars ?? {};
+      const carries = keyframed ? "keyframes" in vars : props.some((p) => p in vars);
+      if (!carries || !((tween.duration?.() ?? 0) > 0)) continue;
+      parseUnplayed(win, element, tween, props);
+      return tween;
+    }
+  }
+  return null;
+}
+
+/** GSAP's startTime() counts the tween's `delay`; the file's parse does not. */
+function startsAt(tween: ParsedTween, start: number): boolean {
+  const delay = Number(tween.vars?.delay) || 0;
+  return Math.abs((tween.startTime?.() ?? Number.NaN) - delay - start) <= 1e-3;
+}
+
+/** `anim` timed as GSAP runs it: its start with any delay, a duration it leaves to GSAP filled in. */
+export function withLiveTiming(anim: GsapAnimation, tween: ParsedTween | null): GsapAnimation {
+  const start = tween?.startTime?.();
+  return {
+    ...anim,
+    ...(Number.isFinite(start) && { resolvedStart: start }),
+    ...(anim.duration == null && tween && { duration: tween.duration?.() }),
+  };
+}
+
+/** GSAP parses a to() tween only when the playhead first passes it, and a soft reload resets that.
+ *  Play its timeline from the tween's start (so earlier tweens set its start value) to its end and
+ *  back, its channels cleared first; then restore every styled element's attributes and GSAP cache. */
+function parseUnplayed(win: GsapWindow, element: Element, tween: ParsedTween, props: string[]) {
+  const seek = !isParsed(tween) && seekable(win, tween);
+  if (!seek) return;
+  const { parent, gsap } = seek;
+  const before = layerStates(tween, element);
+  const now = parent.time();
+  const start = tween.startTime?.() ?? 0;
+  gsap.set(element, { clearProps: props.join(",") });
+  // Re-read now, so GSAP rebuilds its transform cache from the cleared element before the seek.
+  for (const p of props) gsap.getProperty(element, p);
+  try {
+    parent.seek(start, true);
+    parent.seek(start + (tween.duration?.() ?? 0), true);
+  } finally {
+    parent.seek(now, true);
+    restore(before);
+  }
+}
+
+function isParsed(tween: ParsedTween): boolean {
+  const parts = tween.timeline?.getChildren?.() ?? [];
+  return Boolean(tween._initted) && parts.every((part) => part._initted);
+}
+
+type GsapTools = {
+  getProperty: (el: Element, p: string) => unknown;
+  set: (el: Element, v: Record<string, unknown>) => void;
+};
+
+function seekable(win: GsapWindow, tween: ParsedTween) {
+  const { parent } = tween;
+  const gsap = win.gsap;
+  if (!parent?.seek || !parent.time || !gsap?.getProperty || !gsap.set) return null;
+  return {
+    parent: { seek: parent.seek.bind(parent), time: parent.time.bind(parent) },
+    gsap: { getProperty: gsap.getProperty.bind(gsap), set: gsap.set.bind(gsap) } as GsapTools,
+  };
+}
+
+type Layer = Element & { _gsap?: Record<string, unknown> };
+
+function layerStates(tween: ParsedTween, element: Element) {
+  const layers = new Set<Layer>([element]);
+  for (const child of tween.parent?.getChildren?.(true, true, false) ?? [])
+    for (const target of elementTargets(child)) layers.add(target);
+  return [...layers].map((layer) => ({
+    layer,
+    attributes: new Map([...layer.attributes].map((a) => [a.name, a.value])),
+    cache: layer._gsap && { ...layer._gsap },
+  }));
+}
+
+function restore(states: ReturnType<typeof layerStates>) {
+  for (const { layer, attributes, cache } of states) {
+    restoreAttributes(layer, attributes);
+    if (cache && layer._gsap) restoreCache(layer._gsap, cache);
+  }
+}
+
+function restoreAttributes(layer: Element, attributes: Map<string, string>) {
+  for (const { name } of [...layer.attributes])
+    if (!attributes.has(name)) layer.removeAttribute(name);
+  for (const [name, value] of attributes)
+    if (layer.getAttribute(name) !== value) layer.setAttribute(name, value);
+}
+
+function restoreCache(live: Record<string, unknown>, cache: Record<string, unknown>) {
+  for (const key of Object.keys(live)) if (!(key in cache)) delete live[key];
+  Object.assign(live, cache);
+}
+
+/** Start and end values from GSAP's own parse of the tween, as loaded from the file. Null when
+ *  GSAP has not initialised that part of the tween yet: the caller refuses rather than guess. */
+export function parsedImplicitEndValue(tween: ParsedTween | null): ImplicitEndValue {
+  return (prop, end) => {
+    if (!tween) return null;
+    for (const part of partsFrom(tween, end)) {
+      const pair = endsIn(part, prop);
+      if (pair) return end === "start" ? pair[0] : pair[1];
+      // The nearest part animating `prop` is not initialised: an earlier one would be a wrong value.
+      if (prop in (part.vars ?? {})) return null;
+    }
+    return null;
+  };
+}
+
+/** A keyframed tween's parts, nearest `end` first; a flat tween is its own one part. */
+function partsFrom(tween: ParsedTween, end: "start" | "end"): ParsedTween[] {
+  const parts = tween.timeline?.getChildren?.() ?? [];
+  if (parts.length === 0) return [tween];
+  return end === "start" ? parts : [...parts].reverse();
+}
+
+/** The ease GSAP resolved for a flat tween that authors none: its timeline's default, else GSAP's. */
+export function parsedTweenEase(iframe: HTMLIFrameElement | null, tween: ParsedTween | null) {
+  if (!tween) return null;
+  const win = iframe?.contentWindow as GsapWindow | null;
+  const ease =
+    tween.vars?.ease ?? tween.parent?.vars?.defaults?.ease ?? win?.gsap?.defaults?.().ease;
+  if (typeof ease === "string") return ease;
+  const named = (name: string) => win?.gsap?.parseEase?.(name) === ease;
+  return typeof ease === "function" ? (BUILT_IN_EASES.find(named) ?? null) : null;
+}
+
+// GSAP holds a resolved ease, its own default included, as the function parseEase returns.
+const BUILT_IN_EASES = [
+  "none",
+  ...[
+    "power1",
+    "power2",
+    "power3",
+    "power4",
+    "sine",
+    "expo",
+    "circ",
+    "back",
+    "elastic",
+    "bounce",
+  ].flatMap((e) => [`${e}.in`, `${e}.out`, `${e}.inOut`]),
+];
+
+/** An array of keyframe steps at the exact percentages GSAP times them; the parse rounds them. */
+export function withExactStepTimes(anim: GsapAnimation, tween: ParsedTween | null): GsapAnimation {
+  const data = anim.keyframes;
+  const parts = tween?.timeline?.getChildren?.() ?? [];
+  const total = tween?.duration?.() ?? 0;
+  if (data?.format !== "object-array" || parts.length !== data.keyframes.length || !(total > 0))
+    return anim;
+  const ends = parts.map((part) => ((part.startTime?.() ?? 0) + (part.duration?.() ?? 0)) / total);
+  if (ends.some((end) => !Number.isFinite(end))) return anim;
+  const keyframes = data.keyframes.map((kf, i) => ({
+    ...kf,
+    percentage: Math.round(ends[i]! * 100000) / 1000,
+  }));
+  return { ...anim, keyframes: { ...data, keyframes } };
+}

package/src/hooks/gsapPositionDetection.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { usePlayerStore } from "../player/store/playerStore";
+import { tween } from "./gsapParsedTween.test-helpers";
+import { findGsapPositionAnimation, pickClosestToPlayhead } from "./gsapPositionDetection";
+
+afterEach(() => usePlayerStore.setState({ currentTime: 0 }));
+
+const slide = (
+  id: string,
+  resolvedStart: number,
+  duration: number,
+  fields: Partial<GsapAnimation> = {},
+) => tween({ id, method: "to", properties: { x: 10 }, resolvedStart, duration, ...fields });
+const keyed = (...percentages: number[]) => ({
+  keyframes: {
+    format: "object-array" as const,
+    keyframes: percentages.map((percentage) => ({ percentage, properties: { x: percentage } })),
+  },
+});
+
+describe("pickClosestToPlayhead", () => {
+  it.each([
+    ["the one spanning the playhead", 1.5, [slide("a", 0, 1), slide("b", 1, 1)], "b"],
+    ["the nearer end when none spans it", 5, [slide("a", 0, 1), slide("b", 2, 2)], "b"],
+    [
+      "the one whose file states the playhead's value",
+      1,
+      [slide("a", 0, 1), slide("b", 1, 1)],
+      "a",
+    ],
+    [
+      "the later one when both state it",
+      1,
+      [slide("a", 0, 2, keyed(0, 50, 100)), slide("b", 0.5, 1, keyed(0, 50, 100))],
+      "b",
+    ],
+    [
+      "the one with more keyframes on a tie",
+      5,
+      [slide("a", 0, 1, keyed(0, 100)), slide("b", 0, 1, keyed(0, 50, 100))],
+      "b",
+    ],
+  ])("picks %s", (_, time, anims, id) => {
+    usePlayerStore.setState({ currentTime: time });
+    expect(pickClosestToPlayhead(anims)?.id).toBe(id);
+  });
+});
+
+describe("findGsapPositionAnimation", () => {
+  it.each([
+    [
+      "the tween spanning the playhead",
+      1.5,
+      undefined,
+      [slide("a", 0, 1, keyed(0, 100)), slide("b", 1, 1)],
+      "b",
+    ],
+    ["the nearer tween", 9, undefined, [slide("a", 0, 1), slide("b", 6, 1)], "b"],
+    [
+      "the selected target's tween",
+      0.5,
+      "#box",
+      [slide("a", 0, 1, { targetSelector: "#card", ...keyed(0, 100) }), slide("b", 0, 1)],
+      "b",
+    ],
+    [
+      "a tween on one target over a shared one",
+      0.5,
+      undefined,
+      [slide("a", 0, 1, { targetSelector: "#box, #card" }), slide("b", 0, 1)],
+      "b",
+    ],
+  ])("prefers %s", (_, time, selector, anims, id) => {
+    usePlayerStore.setState({ currentTime: time });
+    expect(findGsapPositionAnimation(anims, selector)?.id).toBe(id);
+  });
+});