Merge pull request #2847 from heygen-com/fix/studio-playhead-keyframe-target

fix(studio): target one element when adding a keyframe at the playhead
This commit is contained in:
Miguel Ángel
2026-07-28 21:57:24 +02:00
committed by GitHub
5 changed files with 422 additions and 7 deletions
@@ -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;
@@ -65,7 +68,11 @@ export async function commitKeyframeAtTimeImpl(
selection,
{
type: "add-with-keyframes" as const,
targetSelector: selector,
// Null here means the live DOM could not prove any one-element form.
// This branch has no graceful no-op to fall to, so it takes the
// author's own selector, group collapse and all, over dropping the
// keyframe the user just asked for.
targetSelector: writeTargetSelector(selection) ?? selector,
position: absoluteTime,
duration: defaultDuration,
keyframes: [
+105
View File
@@ -181,6 +181,111 @@ export function selectorFromSelection(selection: DomEditSelection): string | nul
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")}"]`;
}
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. Callers decide what to do with the null: the
* add-keyframe path has a graceful no-animation fallback, and the paths that
* cannot afford to drop a user edit opt back in with `?? selectorFromSelection`
* where the trade is visible. 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);
}
// ── Percentage computation ────────────────────────────────────────────────────
/**
@@ -0,0 +1,246 @@
// @vitest-environment jsdom
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 { resolveSelectorElementIds, writeTargetSelector } from "./gsapShared";
import { commitKeyframeAtTimeImpl } from "./gsapKeyframeCommit";
import { promoteSetToKeyframes } from "./useEnableKeyframes";
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);
`.trim();
const KEYFRAMES = [
{ percentage: 0, properties: { x: 0 } },
{ percentage: 100, properties: { x: 40 } },
];
/** Author the selector into a real script and read the tween's targets back. */
function roundTripTargets(selector: string): { script: string; targets: string[] } {
const { script } = addAnimationWithKeyframesToScript(BASE_SCRIPT, selector, 0, 1, KEYFRAMES);
const added = parseGsapScript(script).animations.find((a) => a.targetSelector === selector);
if (!added) throw new Error(`written selector did not re-parse: ${selector}`);
return { script, targets: resolveSelectorElementIds(added.targetSelector, document) };
}
describe("writeTargetSelector", () => {
it("addresses exactly one element when the only identity is a shared class", () => {
const groups = mountGroupSiblings();
const selection = selectionFor(groups[2]);
// Precondition: this is the defect's input — a bare class hitting all five.
expect(selection.selector).toBe(".group");
expect(document.querySelectorAll(".group")).toHaveLength(5);
const written = writeTargetSelector(selection);
expect(written).toBeTruthy();
expect(document.querySelectorAll(written!)).toHaveLength(1);
expect(document.querySelector(written!)).toBe(groups[2]);
});
it("keeps a unique #id target", () => {
document.body.innerHTML = `<div id="box" class="card"></div>`;
const el = document.querySelector<HTMLElement>("#box")!;
expect(writeTargetSelector(selectionFor(el))).toBe("#box");
});
it("prefers data-hf-id over a generated structural selector", () => {
document.body.innerHTML = `
<div id="scene"><div class="group"></div><div class="group" data-hf-id="hf-42"></div></div>
`;
const el = document.querySelectorAll<HTMLElement>(".group")[1]!;
const written = writeTargetSelector(selectionFor(el));
expect(written).toBe('[data-hf-id="hf-42"]');
expect(document.querySelector(written!)).toBe(el);
});
it("keeps an already-unique class selector as authored", () => {
document.body.innerHTML = `<div id="scene"><div class="header"></div></div>`;
const el = document.querySelector<HTMLElement>(".header")!;
expect(writeTargetSelector(selectionFor(el))).toBe(".header");
});
it("hands identity back to a data-hf-id ancestor part way up a deep chain", () => {
// Mixed identity: the walk must step past the id-less <section>, stop at the
// data-hf-id row, and NOT keep climbing to #outer.
document.body.innerHTML = `
<div id="outer">
<header></header>
<section>
<div data-hf-id="mid">
<div class="cell"></div>
<div class="cell"></div>
<div class="cell"></div>
</div>
</section>
</div>
`;
const el = document.querySelectorAll<HTMLElement>(".cell")[2]!;
const written = writeTargetSelector(selectionFor(el));
expect(written).toBe('[data-hf-id="mid"] > div:nth-child(3)');
expect(document.querySelectorAll(written!)).toHaveLength(1);
expect(document.querySelector(written!)).toBe(el);
});
it("falls through to the structural walk when the selection's selector is not valid CSS", () => {
document.body.innerHTML = `<div id="scene"><div></div><div></div></div>`;
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;
expect(writeTargetSelector(selection)).toBe("#scene > div:nth-child(2)");
});
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);
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
// ".group" here would re-author the very selector this function replaces.
el.remove();
expect(writeTargetSelector(selection)).toBeNull();
});
it("still returns the selection's own selector when there is no DOM to check against", () => {
const selection = {
selector: ".group",
sourceFile: "index.html",
} as unknown as DomEditSelection;
expect(writeTargetSelector(selection)).toBe(".group");
});
});
describe("writeTargetSelector — write/read round trip", () => {
it("re-parses and attributes the new tween to the one element it targeted", () => {
const groups = mountGroupSiblings();
// 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 written = writeTargetSelector(selection);
const { targets } = roundTripTargets(written!);
expect(targets).toEqual(["group-2"]);
});
it("does not widen the add to the element's four class siblings", () => {
const groups = mountGroupSiblings();
groups.forEach((el, i) => el.setAttribute("id", `group-${i}`));
const selection = { ...selectionFor(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".
expect(roundTripTargets(".group").targets).toHaveLength(5);
expect(roundTripTargets(writeTargetSelector(selection)!).targets).toHaveLength(1);
});
});
describe("existingTweenTargetSelector", () => {
it("keeps the narrowed target when a replace re-authors the tween", async () => {
const groups = mountGroupSiblings();
const selection = selectionFor(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.
const setAnim = {
id: "a1",
targetSelector: "#scene > div:nth-child(3)",
method: "set",
position: 0,
properties: { x: 10 },
};
await promoteSetToKeyframes({ commitMutation } as never, selection, setAnim as never, 0, null);
const mutation = commitMutation.mock.calls[0]?.[0] as { targetSelector: string };
expect(mutation.targetSelector).toBe("#scene > div:nth-child(3)");
expect(document.querySelectorAll(mutation.targetSelector)).toHaveLength(1);
});
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 commitMutation = vi.fn(async () => undefined);
const setAnim = {
id: "a1",
targetSelector: "targets[i]",
hasUnresolvedSelector: true,
method: "set",
position: 0,
properties: { x: 10 },
};
await promoteSetToKeyframes({ commitMutation } as never, selection, setAnim as never, 0, null);
const mutation = commitMutation.mock.calls[0]?.[0] as { targetSelector: string };
expect(mutation.targetSelector).toBe(".group");
});
});
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 commitMutation = vi.fn(async () => undefined);
await commitKeyframeAtTimeImpl(selection, 1, [], { x: 12 }, commitMutation);
const mutation = commitMutation.mock.calls[0]?.[1] as { targetSelector: string };
expect(mutation.targetSelector).not.toBe(".group");
expect(document.querySelectorAll(mutation.targetSelector)).toHaveLength(1);
expect(document.querySelector(mutation.targetSelector)).toBe(groups[3]);
});
});
@@ -466,3 +466,47 @@ describe("useEnableKeyframes — flat tween transaction", () => {
});
});
});
describe("useEnableKeyframes — new tween on a class-only element", () => {
it("targets the selected sibling alone, not every element sharing its class", async () => {
window.location.hash = "#/project/test-project";
usePlayerStore.setState({ currentTime: 1 });
vi.stubGlobal(
"fetch",
vi.fn(async () => ({ ok: true, json: async () => ({ animations: [] }) })),
);
const scene = document.body.appendChild(document.createElement("div"));
scene.id = "scene";
scene.innerHTML = '<i class="group"></i>'.repeat(5);
const groups = Array.from(scene.querySelectorAll<HTMLElement>(".group"));
const commitMutation = vi.fn(async () => undefined);
const enable = renderEnableKeyframes({
// A bare `.group` here writes `tl.to(".group", …)`, which animates all five
// siblings and reads back as all five — one add wiped the timeline.
domEditSelection: {
selector: ".group",
selectorIndex: 3,
sourceFile: "index.html",
element: groups[3],
dataAttributes: { start: "0", duration: "2" },
} as unknown as DomEditSelection,
selectedGsapAnimations: [],
previewIframeRef: {
current: {
contentWindow: { gsap: { getProperty: () => 7 } },
} as unknown as HTMLIFrameElement,
},
handleGsapAddAnimation: vi.fn(),
handleGsapConvertToKeyframes: vi.fn(),
handleGsapRemoveKeyframe: vi.fn(),
commitMutation,
});
await act(async () => enable());
const mutation = commitMutation.mock.calls[0]?.[0] as { targetSelector: string };
expect(mutation?.targetSelector).toBeTruthy();
expect(document.querySelectorAll(mutation.targetSelector)).toHaveLength(1);
expect(document.querySelector(mutation.targetSelector)).toBe(groups[3]);
});
});
@@ -13,11 +13,12 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { usePlayerStore } from "../player/store/playerStore";
import { fetchParsedAnimations, getAnimationsForElement } from "./useGsapTweenCache";
import {
selectorFromSelection,
existingTweenTargetSelector,
computeElementPercentage,
KEYFRAME_PCT_MATCH,
isInstantHold,
resolveEditableTweenDuration,
writeTargetSelector,
} from "./gsapShared";
import {
absoluteToPercentage,
@@ -250,7 +251,10 @@ async function extendKeyframedTweenToPlayhead(
iframe: HTMLIFrameElement | null,
commitOverrides?: Partial<CommitMutationOptions>,
): Promise<void> {
const selector = selectorFromSelection(sel);
// Re-authoring an EXISTING tween: keep the target it already writes rather
// than re-deriving one from the selection, which would widen a tween already
// narrowed to one element back onto its class siblings (existingTweenTargetSelector).
const selector = existingTweenTargetSelector(anim, sel);
const position = readElementPosition(iframe, sel, anim);
if (!selector || Object.keys(position).length === 0 || !session.commitMutation) return;
const extended = buildExtendedKeyframes(anim, currentTime, position, duration);
@@ -335,7 +339,10 @@ export async function promoteSetToKeyframes(
t: number,
iframe: HTMLIFrameElement | null,
): Promise<void> {
const selector = selectorFromSelection(sel);
// Re-authoring an EXISTING tween: keep the target it already writes rather
// than re-deriving one from the selection, which would widen a tween already
// narrowed to one element back onto its class siblings (existingTweenTargetSelector).
const selector = existingTweenTargetSelector(setAnim, sel);
const setStart = resolveTweenStart(setAnim) ?? 0;
if (!selector || !session.commitMutation) return;
// Playhead at or before the set → there's no forward range to promote into.
@@ -389,7 +396,10 @@ export async function applyArcKeyframeAtPlayhead(
iframe: HTMLIFrameElement | null,
): Promise<void> {
if (!session.commitMutation) return;
const targetSelector = selectorFromSelection(sel);
// Re-authoring an EXISTING tween: keep the target it already writes rather
// than re-deriving one from the selection, which would widen a tween already
// narrowed to one element back onto its class siblings (existingTweenTargetSelector).
const targetSelector = existingTweenTargetSelector(arcAnim, sel);
if (!targetSelector) return;
const start = resolveTweenStart(arcAnim) ?? 0;
const duration = resolveEditableTweenDuration(arcAnim, sel);
@@ -523,7 +533,10 @@ export function useEnableKeyframes(
sel.dataAttributes?.duration,
t,
);
const selector = selectorFromSelection(sel);
// A brand-new tween: author it against the one element the user selected.
// The bare class selectorFromSelection hands back for an id-less element
// animates every sibling sharing the class (see writeTargetSelector).
const selector = writeTargetSelector(sel);
if (!selector) {
session.handleGsapAddAnimation("to");