{formatDisplayValue?.(draft) ?? displayValue}
diff --git a/packages/studio/src/components/nle/TimelineResizeDivider.tsx b/packages/studio/src/components/nle/TimelineResizeDivider.tsx
index fc27d769695..30a462c71f1 100644
--- a/packages/studio/src/components/nle/TimelineResizeDivider.tsx
+++ b/packages/studio/src/components/nle/TimelineResizeDivider.tsx
@@ -73,9 +73,9 @@ export function TimelineResizeDivider({
);
return (
- // Horizontal resize divider: 3px visible seam (h-[3px]), 8px pointer-capture
+ // Horizontal resize divider: 3px visible seam (h-[3px]), 10px pointer-capture
// zone via the absolutely-positioned inner hit area so the layout gap stays
- // at 3px while draggability is preserved over the full 8px band.
+ // at 3px while draggability is preserved over the full band.
- {/* Expanded hit zone: 8px tall, centered on the 3px seam */}
-
+ {/* Expanded hit zone, deliberately asymmetric: 4px up into the transport
+ row's vertical centring slack, the 3px seam, then 3px down into the
+ timeline card's border + toolbar padding. It stops at 10px rather than
+ the 24px WCAG 2.2 (2.5.8) target because that is all the dead space
+ there is: 28px transport buttons sit above and 28px toolbar buttons
+ below, and silently stealing their clicks is the worse bug. */}
+
{/* Visible hairline — invisible at rest, subtle wash on hover/drag/focus */}
diff --git a/packages/studio/src/components/pointerTargetSize.test.tsx b/packages/studio/src/components/pointerTargetSize.test.tsx
new file mode 100644
index 00000000000..fd1923533a3
--- /dev/null
+++ b/packages/studio/src/components/pointerTargetSize.test.tsx
@@ -0,0 +1,65 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { CompositionsTab } from "./sidebar/CompositionsTab";
+import { TimelineToolbar } from "./TimelineToolbar";
+
+// WCAG 2.2 (2.5.8) requires a 24x24 CSS pixel pointer target. happy-dom has no
+// CSS engine, so getBoundingClientRect() is 0x0 for everything here and the size
+// itself cannot be measured — these assert the utility classes that PRODUCE the
+// size instead, which is enough to fail if someone drops them. Real geometry
+// still needs a browser check.
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+(
+ window as unknown as { happyDOM: { settings: { disableIframePageLoading: boolean } } }
+).happyDOM.settings.disableIframePageLoading = true;
+
+let root: Root | null = null;
+
+afterEach(() => {
+ if (root) act(() => root?.unmount());
+ root = null;
+ document.body.innerHTML = "";
+});
+
+function mount(element: React.ReactNode) {
+ const host = document.createElement("div");
+ document.body.append(host);
+ root = createRoot(host);
+ act(() => root?.render(element));
+ return host;
+}
+
+describe("pointer target sizing classes (proxy for WCAG 2.5.8, not a geometry check)", () => {
+ it("gives the timeline zoom slider a 24px box without changing its 2px track or 10px thumb", () => {
+ const host = mount(
);
+ const slider = host.querySelector
('input[aria-label="Timeline zoom"]');
+ if (!slider) throw new Error("zoom slider did not render");
+
+ expect(slider.className).toContain("h-6");
+ expect(slider.className).toContain("[&::-webkit-slider-runnable-track]:h-[2px]");
+ expect(slider.className).toContain("[&::-webkit-slider-thumb]:h-[10px]");
+ expect(slider.className).toContain("[&::-webkit-slider-thumb]:w-[10px]");
+ });
+
+ it("gives the composition card's render button a 24x24 box around its 14px glyph", () => {
+ const host = mount(
+ ('button[aria-label="Render headline"]');
+ if (!button) throw new Error("render button did not render");
+
+ expect(button.className).toContain("h-6");
+ expect(button.className).toContain("w-6");
+ expect(button.querySelector("svg")?.getAttribute("width")).toBe("14");
+ });
+});
diff --git a/packages/studio/src/components/sidebar/CompositionsTab.tsx b/packages/studio/src/components/sidebar/CompositionsTab.tsx
index 5de9703dbed..96607f33816 100644
--- a/packages/studio/src/components/sidebar/CompositionsTab.tsx
+++ b/packages/studio/src/components/sidebar/CompositionsTab.tsx
@@ -317,7 +317,10 @@ function CompCard({
e.stopPropagation();
onRender();
}}
- className={`flex-shrink-0 p-1 rounded transition-colors ${
+ // h-6 w-6 = the 24x24 WCAG 2.2 (2.5.8) minimum target; the 14px glyph
+ // is unchanged, only the box grows. The sibling "+" button is h-8 w-8,
+ // so the card row already has the room.
+ className={`flex h-6 w-6 flex-shrink-0 items-center justify-center rounded transition-colors ${
isRendering
? "text-neutral-600 cursor-not-allowed"
: "text-neutral-600 hover:text-studio-accent hover:bg-neutral-800"
diff --git a/packages/studio/src/hooks/gsapDragCommit.ts b/packages/studio/src/hooks/gsapDragCommit.ts
index 4774c17e1b5..62fd190e75d 100644
--- a/packages/studio/src/hooks/gsapDragCommit.ts
+++ b/packages/studio/src/hooks/gsapDragCommit.ts
@@ -12,7 +12,7 @@ import { usePlayerStore } from "../player/store/playerStore";
import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeKeyframes";
import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
import { roundTo3 } from "../utils/rounding";
-import { computeElementPercentage, idSelector } from "./gsapShared";
+import { computeElementPercentage, idSelector, writeTargetSelector } from "./gsapShared";
import { computeDraggedGsapPosition } from "./draggedGsapPosition";
import type { RuntimeTweenChange } from "./gsapRuntimePatch";
import { isGestureTransactionCommit, runGestureTransaction } from "./gestureTransaction";
@@ -44,6 +44,23 @@ export interface GsapDragCommitCallbacks {
fetchAnimations?: () => Promise;
}
+/**
+ * The target for a tween these helpers are about to CREATE. Callers derive
+ * `selector` with `selectorFromSelection`, which hands back a bare class for an
+ * id-less element: authoring that widens a one-element drag/resize/rotate into a
+ * write over every sibling sharing the class. Retargets of an EXISTING tween
+ * must NOT come through here (they keep `anim.targetSelector`, so a tween the
+ * author aimed at a group stays aimed at it).
+ *
+ * Null means no one-element form exists, and every caller drops the commit
+ * rather than falling back to `selector` (see writeTargetSelector): the drag
+ * reverts on the next reload, which is recoverable, where a `.group` write is
+ * not.
+ */
+function newTweenTarget(selection: DomEditSelection): string | null {
+ return writeTargetSelector(selection);
+}
+
// Re-export for backward compatibility with existing imports.
export function computeCurrentPercentage(
selection: DomEditSelection,
@@ -65,17 +82,18 @@ export function parkPlayheadOnKeyframe(anim: GsapAnimation, pct: number): void {
async function replaceKeyframedPositionHold(
selection: DomEditSelection,
- selector: string,
existingSet: GsapAnimation,
properties: { x: number; y: number },
commitMutation: GsapDragCommitCallbacks["commitMutation"],
): Promise {
+ const target = newTweenTarget(selection);
+ if (!target) return;
const persist = async (commit: GsapDragCommitCallbacks["commitMutation"]) => {
await commit(
selection,
{
type: "add",
- targetSelector: selector,
+ targetSelector: target,
method: "set",
position: 0,
properties,
@@ -174,7 +192,6 @@ export async function commitStaticGsapPosition(
// least one hold on disk, then delete the corrupt tween in one transaction.
await replaceKeyframedPositionHold(
selection,
- selector,
existingSet,
{ x: newX, y: newY },
callbacks.commitMutation,
@@ -199,11 +216,15 @@ export async function commitStaticGsapPosition(
}
// New static hold → a base `gsap.set` (off-timeline, no 0% keyframe marker), with
// an instant patch so the first nudge shows immediately (no soft-reload flash).
+ // The patch reuses the WRITTEN target so the runtime moves exactly the element
+ // the source write names.
+ const target = newTweenTarget(selection);
+ if (!target) return;
await callbacks.commitMutation(
selection,
{
type: "add",
- targetSelector: selector,
+ targetSelector: target,
method: "set",
position: 0,
properties: { x: newX, y: newY },
@@ -212,7 +233,10 @@ export async function commitStaticGsapPosition(
{
label: "Move layer",
softReload: true,
- instantPatch: { selector, change: { kind: "global-set", props: { x: newX, y: newY } } },
+ instantPatch: {
+ selector: target,
+ change: { kind: "global-set", props: { x: newX, y: newY } },
+ },
},
);
}
@@ -252,11 +276,13 @@ export async function commitStaticGsapRotation(
return;
}
// New static hold → off-timeline `gsap.set` (no 0% keyframe marker) + instant patch.
+ const target = newTweenTarget(selection);
+ if (!target) return;
await callbacks.commitMutation(
selection,
{
type: "add",
- targetSelector: selector,
+ targetSelector: target,
method: "set",
position: 0,
properties: { rotation: newRotation },
@@ -265,7 +291,10 @@ export async function commitStaticGsapRotation(
{
label: "Rotate layer",
softReload: true,
- instantPatch: { selector, change: { kind: "global-set", props: { rotation: newRotation } } },
+ instantPatch: {
+ selector: target,
+ change: { kind: "global-set", props: { rotation: newRotation } },
+ },
},
);
}
@@ -301,11 +330,13 @@ export async function commitStaticGsapSize(
);
return;
}
+ const target = newTweenTarget(selection);
+ if (!target) return;
await callbacks.commitMutation(
selection,
{
type: "add",
- targetSelector: selector,
+ targetSelector: target,
method: "set",
position: 0,
properties: { width, height },
@@ -389,11 +420,13 @@ export async function commitKeyframedSizeFromResize(
// transport applies both in one ordered batch; a plain commit fallback keeps the
// same recoverable ordering. Only the transaction's result triggers the reload.
const addLabel = `Resize (size keyframe ${pct.toFixed(0)}%)`;
+ const target = newTweenTarget(selection);
+ if (!target) return false;
await callbacks.commitMutation(
selection,
{
type: "add-with-keyframes",
- targetSelector: selector,
+ targetSelector: target,
position: roundTo3(ts),
duration: roundTo3(td),
keyframes,
diff --git a/packages/studio/src/hooks/gsapDragStaticSetHelpers.ts b/packages/studio/src/hooks/gsapDragStaticSetHelpers.ts
index 243ddbd818d..ecba30bd41e 100644
--- a/packages/studio/src/hooks/gsapDragStaticSetHelpers.ts
+++ b/packages/studio/src/hooks/gsapDragStaticSetHelpers.ts
@@ -1,6 +1,6 @@
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
import type { RuntimeTweenChange, SetPatchProps } from "./gsapRuntimePatch";
-import { isInstantHold } from "./gsapShared";
+import { isInstantHold, tweenTargetsElement } from "./gsapShared";
/** The shape of an `update-property` mutation a static-set nudge POSTs. */
interface UpdatePropertyMutation {
@@ -34,12 +34,13 @@ export function setPatchFromUpdateProperty(
function findPositionSetAnimation(
animations: GsapAnimation[],
selector: string,
+ element?: Element | null,
): GsapAnimation | null {
return (
animations.find(
(a) =>
a.method === "set" &&
- a.targetSelector === selector &&
+ tweenTargetsElement(a.targetSelector, selector, element) &&
("x" in a.properties || "y" in a.properties),
) ?? null
);
@@ -61,12 +62,16 @@ function findPositionSetAnimation(
export function findExistingPositionWrite(
animations: GsapAnimation[],
selector: string,
+ element?: Element | null,
): GsapAnimation | null {
- const set = findPositionSetAnimation(animations, selector);
+ const set = findPositionSetAnimation(animations, selector, element);
if (set) return set;
return (
animations.find(
- (a) => a.targetSelector === selector && a.propertyGroup === "position" && isInstantHold(a),
+ (a) =>
+ tweenTargetsElement(a.targetSelector, selector, element) &&
+ a.propertyGroup === "position" &&
+ isInstantHold(a),
) ?? null
);
}
@@ -74,10 +79,14 @@ export function findExistingPositionWrite(
export function findRotationSetAnimation(
animations: GsapAnimation[],
selector: string,
+ element?: Element | null,
): GsapAnimation | null {
return (
animations.find(
- (a) => isInstantHold(a) && a.targetSelector === selector && "rotation" in a.properties,
+ (a) =>
+ isInstantHold(a) &&
+ tweenTargetsElement(a.targetSelector, selector, element) &&
+ "rotation" in a.properties,
) ?? null
);
}
@@ -85,12 +94,13 @@ export function findRotationSetAnimation(
export function findSizeSetAnimation(
animations: GsapAnimation[],
selector: string,
+ element?: Element | null,
): GsapAnimation | null {
return (
animations.find(
(a) =>
isInstantHold(a) &&
- a.targetSelector === selector &&
+ tweenTargetsElement(a.targetSelector, selector, element) &&
("width" in a.properties || "height" in a.properties),
) ?? null
);
diff --git a/packages/studio/src/hooks/gsapKeyframeCacheHelpers.test.ts b/packages/studio/src/hooks/gsapKeyframeCacheHelpers.test.ts
index 05e5c93da87..2434f6c87c1 100644
--- a/packages/studio/src/hooks/gsapKeyframeCacheHelpers.test.ts
+++ b/packages/studio/src/hooks/gsapKeyframeCacheHelpers.test.ts
@@ -276,6 +276,69 @@ describe("updateKeyframeCacheFromParsed", () => {
expect(usePlayerStore.getState().gsapAnimations.get("scene.html#box")).toEqual([animation]);
});
+ // `#stat3 .block` animates the BLOCK inside #stat3, not #stat3. An unanchored
+ // `^#([\w-]+)/` prefix match filed it under "stat3", which both stole the
+ // child's diamonds and collided with #stat3's own tween at the shared
+ // percentage (dropping #stat3's ease as ambiguous).
+ it("attributes a descendant selector to the child, not to its ancestor", () => {
+ const parent: GsapAnimation = {
+ id: "stat3-fromTo",
+ targetSelector: "#stat3",
+ method: "fromTo",
+ position: 8.88,
+ resolvedStart: 8.88,
+ duration: 0.25,
+ fromProperties: { y: 20 },
+ properties: { y: 0 },
+ ease: "power2.out",
+ propertyGroup: "position",
+ };
+ const child: GsapAnimation = {
+ id: "block-from",
+ targetSelector: "#stat3 .block",
+ method: "from",
+ position: 9.13,
+ resolvedStart: 9.13,
+ duration: 0.3,
+ properties: { opacity: 0 },
+ ease: "power2.in",
+ propertyGroup: "visual",
+ };
+ usePlayerStore.setState({
+ elements: [
+ { id: "stat3-clip", domId: "stat3", tag: "div", start: 8.88, duration: 1, track: 0 },
+ ],
+ });
+ const doc = {
+ querySelectorAll: (selector: string) =>
+ (selector === "#stat3 .block"
+ ? [{ id: "stat3-block" }]
+ : []) as unknown as NodeListOf,
+ } as unknown as Document;
+
+ updateKeyframeCacheFromParsed([parent, child], "scene.html", "stat3", {}, doc);
+
+ expect(usePlayerStore.getState().gsapAnimations.get("scene.html#stat3")).toEqual([parent]);
+ expect(usePlayerStore.getState().gsapAnimations.get("scene.html#stat3-block")).toEqual([child]);
+ // With the collision gone, #stat3's own curve survives instead of being
+ // deleted as an ambiguous same-percentage merge.
+ const parentKeyframes = cache().get("scene.html#stat3")?.keyframes ?? [];
+ expect(parentKeyframes.at(-1)?.ease).toBe("power2.out");
+ expect(parentKeyframes.some((keyframe) => "easeAmbiguous" in keyframe)).toBe(false);
+ });
+
+ it("attributes a descendant selector to nothing when there is no document", () => {
+ const child: GsapAnimation = {
+ ...animWithKeyframes("block-from"),
+ targetSelector: "#stat3 .block",
+ };
+
+ updateKeyframeCacheFromParsed([child], "scene.html", "stat3", {});
+
+ expect(cache().has("scene.html#stat3")).toBe(false);
+ expect(usePlayerStore.getState().gsapAnimations.has("scene.html#stat3")).toBe(false);
+ });
+
it("does not cache a flat tween without animatable numeric properties", () => {
const animation: GsapAnimation = {
id: "flat-box",
diff --git a/packages/studio/src/hooks/gsapKeyframeCacheHelpers.ts b/packages/studio/src/hooks/gsapKeyframeCacheHelpers.ts
index 929960a16dc..a2ed338cb83 100644
--- a/packages/studio/src/hooks/gsapKeyframeCacheHelpers.ts
+++ b/packages/studio/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,
+ doc?: Document | null,
): void {
- const { setKeyframeCache, elements } = usePlayerStore.getState();
+ const { setKeyframeCache, elements, domClipChildren } = usePlayerStore.getState();
const idsWithKeyframes = new Set();
const merged = new Map();
const sourceAnimations = new Map();
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);
}
}
diff --git a/packages/studio/src/hooks/gsapKeyframeCommit.ts b/packages/studio/src/hooks/gsapKeyframeCommit.ts
index c2715984eb2..ed3ecc498ea 100644
--- a/packages/studio/src/hooks/gsapKeyframeCommit.ts
+++ b/packages/studio/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,
commitMutation: CommitFn,
): Promise {
+ // 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: [
diff --git a/packages/studio/src/hooks/gsapResizeIntercept.ts b/packages/studio/src/hooks/gsapResizeIntercept.ts
index a0042b6020d..e9eecef829e 100644
--- a/packages/studio/src/hooks/gsapResizeIntercept.ts
+++ b/packages/studio/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(
diff --git a/packages/studio/src/hooks/gsapRuntimeBridge.ts b/packages/studio/src/hooks/gsapRuntimeBridge.ts
index d102e7a81ba..5f8514630a9 100644
--- a/packages/studio/src/hooks/gsapRuntimeBridge.ts
+++ b/packages/studio/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,
diff --git a/packages/studio/src/hooks/gsapScriptCommitHelpers.ts b/packages/studio/src/hooks/gsapScriptCommitHelpers.ts
index e6d17338f3d..8c6e45a0203 100644
--- a/packages/studio/src/hooks/gsapScriptCommitHelpers.ts
+++ b/packages/studio/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;
diff --git a/packages/studio/src/hooks/gsapShared.test.ts b/packages/studio/src/hooks/gsapShared.test.ts
index 604b93b6945..9df0b2f65cf 100644
--- a/packages/studio/src/hooks/gsapShared.test.ts
+++ b/packages/studio/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']) {
diff --git a/packages/studio/src/hooks/gsapShared.ts b/packages/studio/src/hooks/gsapShared.ts
index 00c79ceda6e..a0ce6317c68 100644
--- a/packages/studio/src/hooks/gsapShared.ts
+++ b/packages/studio/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();
+ 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,
+ 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
diff --git a/packages/studio/src/hooks/gsapShared.writeTarget.test.ts b/packages/studio/src/hooks/gsapShared.writeTarget.test.ts
new file mode 100644
index 00000000000..1be27acf50e
--- /dev/null
+++ b/packages/studio/src/hooks/gsapShared.writeTarget.test.ts
@@ -0,0 +1,289 @@
+// @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, tweenTargetsElement, 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 = `
+
+ `;
+ return Array.from(document.querySelectorAll(".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 = `
`;
+ const el = document.querySelector("#box")!;
+
+ expect(writeTargetSelector(selectionFor(el))).toBe("#box");
+ });
+
+ it("prefers data-hf-id over a generated structural selector", () => {
+ document.body.innerHTML = `
+
+ `;
+ const el = document.querySelectorAll(".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 = `
`;
+ const el = document.querySelector(".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 , stop at the
+ // data-hf-id row, and NOT keep climbing to #outer.
+ document.body.innerHTML = `
+
+ `;
+ const el = document.querySelectorAll(".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 = ``;
+ const el = document.querySelectorAll("#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 = ``;
+ const el = document.querySelectorAll(".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]);
+ });
+});
+
+describe("tweenTargetsElement", () => {
+ it("matches a tween narrowed to this element by a selector the selection does not use", () => {
+ const groups = mountGroupSiblings();
+ groups[2]!.id = "narrowed";
+
+ // The write half authored "#narrowed"; the read half still has ".group".
+ expect(tweenTargetsElement("#narrowed", ".group", groups[2])).toBe(true);
+ });
+
+ it("does not hand an individual element the group tween it merely inherits", () => {
+ const groups = mountGroupSiblings();
+
+ // Selecting one sibling by its own address must not let an edit mutate the
+ // ".group" tween: that write moves all five, not the one being nudged.
+ expect(tweenTargetsElement(".group", "#scene > div:nth-child(3)", groups[2])).toBe(false);
+ });
+
+ it("still edits a group tween when the group itself is the selection", () => {
+ const groups = mountGroupSiblings();
+
+ expect(tweenTargetsElement(".group", ".group", groups[0])).toBe(true);
+ });
+
+ it("does not match a target that is not a selector matches() understands", () => {
+ const groups = mountGroupSiblings();
+
+ expect(tweenTargetsElement("div[unclosed", ".group", groups[0])).toBe(false);
+ });
+});
+
+describe("commitKeyframeAtTimeImpl — no one-element target", () => {
+ it("drops the keyframe rather than authoring the bare class", async () => {
+ const groups = mountGroupSiblings();
+ const selection = selectionFor(groups[3]!);
+ groups[3]!.remove();
+ const commitMutation = vi.fn(async () => undefined);
+
+ await commitKeyframeAtTimeImpl(selection, 1, [], { x: 12 }, commitMutation);
+
+ expect(commitMutation).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/studio/src/hooks/keyframeCacheAstLoad.ts b/packages/studio/src/hooks/keyframeCacheAstLoad.ts
index bca5f4b233d..9ae59b3d557 100644
--- a/packages/studio/src/hooks/keyframeCacheAstLoad.ts
+++ b/packages/studio/src/hooks/keyframeCacheAstLoad.ts
@@ -1,6 +1,6 @@
/**
- * Reading a composition file's GSAP tweens into the keyframe cache: fetch,
- * selector -> element id resolution, and the clip-relative timing basis.
+ * Reading a composition file's GSAP tweens into the keyframe cache: fetch and
+ * selector -> element id resolution.
* Split from useGsapTweenCache to keep that file under the 600-line limit.
*/
import type { GsapAnimation, GsapKeyframesData, ParsedGsap } from "@hyperframes/core/gsap-parser";
@@ -11,50 +11,15 @@ import {
elementCacheKeys,
writeGsapAnimationsForElement,
} from "./gsapKeyframeCacheHelpers";
-import { idFromSelector, toClipKeyframes } from "./gsapShared";
+import { resolveClipTimingBasis, resolveSelectorElementIds, toClipKeyframes } from "./gsapShared";
import {
deduplicateKeyframes,
isStaticPositionHold,
synthesizeFlatTweenKeyframes,
} from "./gsapTweenSynth";
-/**
- * Resolve a tween's target selector to the ids of the element(s) it animates.
- * A bare `#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. Falls back to a
- * leading `#id` when there's no DOM (so the cache still populates pre-iframe).
- */
-// fallow-ignore-next-line complexity
-export function resolveSelectorElementIds(
- selector: string,
- doc: Document | null | undefined,
-): string[] {
- // A whole-selector id match (either shape) addresses exactly one element.
- const bareId = /^(#[\w-]+|\[id="(?:\\.|[^"\\])*"\])$/.test(selector)
- ? idFromSelector(selector)
- : null;
- if (bareId) return [bareId];
- if (!doc) {
- const lead = idFromSelector(selector);
- return lead ? [lead] : [];
- }
- const ids = new Set();
- for (const part of selector.split(",")) {
- const sel = part.trim();
- if (!sel) continue;
- try {
- for (const el of Array.from(doc.querySelectorAll(sel))) {
- if (el.id) ids.add(el.id);
- }
- } catch {
- const lead = idFromSelector(sel);
- if (lead) ids.add(lead);
- }
- }
- return Array.from(ids);
-}
+export { resolveSelectorElementIds };
+
/**
* The slice of the parse response callers actually read. The endpoint returns
* the full `ParsedGsap` (preamble/postamble and all), but nothing downstream of
@@ -103,37 +68,6 @@ export async function fetchParsedAnimations(
}
}
-/**
- * Clip-relative timing basis for an element. 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).
- */
-export function resolveClipTimingBasis(
- elementId: string,
- sourceFile: string,
- elements: ReadonlyArray<{
- domId?: string;
- key?: string;
- id: string;
- start: number;
- duration: number;
- }>,
- 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) return { elStart: direct.start, 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;
- return { elStart: host?.start ?? 0, elDuration: host?.duration ?? 1 };
-}
-
/**
* Read one composition file's tweens into the keyframe cache. Split out of the
* hook so the effect can run it per file without re-nesting the whole body.
diff --git a/packages/studio/src/hooks/newTweenTarget.test.ts b/packages/studio/src/hooks/newTweenTarget.test.ts
new file mode 100644
index 00000000000..33ef3e7dd78
--- /dev/null
+++ b/packages/studio/src/hooks/newTweenTarget.test.ts
@@ -0,0 +1,364 @@
+// @vitest-environment jsdom
+/**
+ * Sibling writers of the "add keyframe at playhead" path fixed in
+ * gsapShared.writeTarget.test.ts. Every mutation that authors a NEW tween must
+ * address ONE element; a bare class attributes the write to every sibling that
+ * shares it, which is what collapsed the timeline to a single row.
+ *
+ * Same round trip as the U3 test: author through the real writer, re-parse with
+ * the real parser, resolve through the very function that feeds the keyframe
+ * cache and the lanes.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { parseGsapScript } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { buildStableSelector, getSelectorIndex } from "../components/editor/domEditingDom";
+import { resolveSelectorElementIds } from "./gsapShared";
+import { ensureElementAddressable } from "./gsapScriptCommitHelpers";
+import {
+ commitStaticGsapPosition,
+ commitStaticGsapRotation,
+ commitStaticGsapSize,
+ commitKeyframedSizeFromResize,
+ commitWholePathOffset,
+ findExistingPositionWrite,
+} from "./gsapDragCommit";
+import { promoteSetToKeyframes } from "./useEnableKeyframes";
+
+afterEach(() => {
+ document.body.innerHTML = "";
+});
+
+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, each with an id so attribution is nameable. */
+function mountGroupSiblings(): HTMLElement[] {
+ document.body.innerHTML = `
+
+ `;
+ return Array.from(document.querySelectorAll(".group"));
+}
+
+/**
+ * The selection production hands these writers: the element HAS an id in the
+ * DOM (so resolveSelectorElementIds can name it) but the SELECTION carries none,
+ * which is the id-less shape buildStableSelector answers with a bare class.
+ */
+function classOnlySelection(el: HTMLElement): DomEditSelection {
+ return { ...selectionFor(el), id: undefined, selector: ".group" } as DomEditSelection;
+}
+
+/** The elements a written targetSelector actually attributes the tween to. */
+function attributedTo(targetSelector: string): string[] {
+ return resolveSelectorElementIds(targetSelector, document);
+}
+
+function recorder() {
+ const mutations: Array> = [];
+ const commitMutation = vi.fn(async (_sel, mutation, _opts) => {
+ mutations.push(mutation as Record);
+ });
+ return { mutations, callbacks: { commitMutation } as never };
+}
+
+/** Every `targetSelector` a run of mutations wrote. */
+function writtenTargets(mutations: Array>): string[] {
+ return mutations.map((m) => m.targetSelector).filter((s): s is string => typeof s === "string");
+}
+
+describe("ensureElementAddressable — add-animation button", () => {
+ it("addresses one element when the selection's only identity is a shared class", () => {
+ // Truly id-less siblings: the shape production reaches this path with (an
+ // element WITH an id never gets here, selection.id short-circuits above).
+ document.body.innerHTML = `
+
+ `;
+ const el = document.querySelectorAll(".group")[1]!;
+ const selection = selectionFor(el);
+ expect(selection.selector).toBe(".group");
+
+ const { selector, autoId } = ensureElementAddressable(selection);
+
+ expect(autoId).toBeTruthy();
+ expect(document.querySelectorAll(selector)).toHaveLength(1);
+ expect(document.querySelector(selector)).toBe(el);
+ expect(attributedTo(selector)).toEqual([autoId]);
+ });
+
+ it("keeps a unique #id target", () => {
+ document.body.innerHTML = `
`;
+ const el = document.querySelector("#box")!;
+
+ expect(ensureElementAddressable(selectionFor(el)).selector).toBe("#box");
+ });
+
+ it("keeps an already-unique class selector as authored", () => {
+ document.body.innerHTML = `
`;
+ const el = document.querySelector(".header")!;
+
+ expect(ensureElementAddressable(selectionFor(el)).selector).toBe(".header");
+ });
+
+ it("still mints an id when there is no live element to disambiguate against", () => {
+ document.body.innerHTML = ``;
+ const el = document.querySelector("#scene > div")!;
+ const selection = { ...selectionFor(el), selector: undefined } as DomEditSelection;
+
+ const { selector, autoId } = ensureElementAddressable(selection);
+
+ expect(autoId).toBe("div");
+ expect(selector).toBe("#div");
+ });
+});
+
+describe("gsapDragCommit — new-tween targets", () => {
+ it("commitStaticGsapPosition authors the new set against one element", async () => {
+ const groups = mountGroupSiblings();
+ const { mutations, callbacks } = recorder();
+
+ await commitStaticGsapPosition(
+ classOnlySelection(groups[2]!),
+ { x: 10, y: 10 },
+ { x: 0, y: 0 },
+ ".group",
+ null,
+ callbacks,
+ );
+
+ expect(attributedTo(writtenTargets(mutations)[0]!)).toEqual(["group-2"]);
+ });
+
+ it("commitStaticGsapRotation authors the new set against one element", async () => {
+ const groups = mountGroupSiblings();
+ const { mutations, callbacks } = recorder();
+
+ await commitStaticGsapRotation(classOnlySelection(groups[1]!), 42, ".group", null, callbacks);
+
+ expect(attributedTo(writtenTargets(mutations)[0]!)).toEqual(["group-1"]);
+ });
+
+ it("commitStaticGsapSize authors the new set against one element", async () => {
+ const groups = mountGroupSiblings();
+ const { mutations, callbacks } = recorder();
+
+ await commitStaticGsapSize(
+ classOnlySelection(groups[4]!),
+ { width: 100, height: 50 },
+ ".group",
+ null,
+ callbacks,
+ );
+
+ expect(attributedTo(writtenTargets(mutations)[0]!)).toEqual(["group-4"]);
+ });
+
+ it("commitKeyframedSizeFromResize authors the new keyframe tween against one element", async () => {
+ const groups = mountGroupSiblings();
+ const { mutations, callbacks } = recorder();
+ const animatedTween = {
+ id: "t1",
+ targetSelector: ".group",
+ method: "to",
+ properties: {},
+ resolvedStart: 0,
+ duration: 2,
+ keyframes: { keyframes: [{ percentage: 0, properties: { x: 0 } }] },
+ } as unknown as GsapAnimation;
+
+ const handled = await commitKeyframedSizeFromResize(
+ classOnlySelection(groups[3]!),
+ { width: 80, height: 40 },
+ ".group",
+ null,
+ animatedTween,
+ callbacks,
+ );
+
+ expect(handled).toBe(true);
+ expect(attributedTo(writtenTargets(mutations)[0]!)).toEqual(["group-3"]);
+ });
+
+ it("commitStaticGsapPosition replaces a corrupt keyframed hold against one element", async () => {
+ const groups = mountGroupSiblings();
+ const { mutations, callbacks } = recorder();
+ const corruptHold = {
+ id: "hold-1",
+ targetSelector: ".group",
+ method: "to",
+ properties: {},
+ duration: 0,
+ keyframes: { keyframes: [{ percentage: 0, properties: { x: 0, y: 0 } }] },
+ } as unknown as GsapAnimation;
+
+ await commitStaticGsapPosition(
+ classOnlySelection(groups[0]!),
+ { x: 5, y: 5 },
+ { x: 0, y: 0 },
+ ".group",
+ corruptHold,
+ callbacks,
+ );
+
+ expect(attributedTo(writtenTargets(mutations)[0]!)).toEqual(["group-0"]);
+ });
+});
+
+describe("gsapDragCommit — retargeting an existing tween is left alone", () => {
+ it("commitWholePathOffset keeps the tween's own group target", async () => {
+ const groups = mountGroupSiblings();
+ const { mutations, callbacks } = recorder();
+ const groupTween = {
+ id: "t-group",
+ targetSelector: ".group",
+ method: "to",
+ properties: { x: 100 },
+ resolvedStart: 0,
+ duration: 2,
+ } as unknown as GsapAnimation;
+
+ await commitWholePathOffset(
+ classOnlySelection(groups[2]!),
+ groupTween,
+ { x: 10, y: 0 },
+ { x: 0, y: 0 },
+ null,
+ ".group",
+ callbacks,
+ );
+
+ // A tween the author aimed at all five siblings must STAY aimed at all five:
+ // narrowing it here would silently drop four elements out of the animation.
+ expect(writtenTargets(mutations)[0]).toBe(".group");
+ expect(attributedTo(writtenTargets(mutations)[0]!)).toHaveLength(5);
+ });
+});
+
+/**
+ * The write selector and the "is there already a write for this element?"
+ * lookup are two halves of one contract. Narrowing only the write half would
+ * make the next nudge miss its own previous write and append a second one — the
+ * duplicate-position-write bug findExistingPositionWrite exists to prevent.
+ */
+describe("a re-nudge updates its own previous write instead of stacking a second one", () => {
+ it("finds the write the first nudge authored", async () => {
+ const groups = mountGroupSiblings();
+ const selection = classOnlySelection(groups[2]!);
+ const first = recorder();
+
+ await commitStaticGsapPosition(
+ selection,
+ { x: 10, y: 10 },
+ { x: 0, y: 0 },
+ ".group",
+ null,
+ first.callbacks,
+ );
+ const written = writtenTargets(first.mutations)[0]!;
+
+ // Read the first write back the way the next drag does: parse the source,
+ // then run the production lookup for this element's position write.
+ const script = `
+const tl = gsap.timeline({ paused: true });
+gsap.set(${JSON.stringify(written)}, { x: 10, y: 10 });
+`.trim();
+ const animations = parseGsapScript(script).animations;
+ const existing = findExistingPositionWrite(animations, ".group", selection.element);
+ expect(existing).toBeTruthy();
+
+ const second = recorder();
+ await commitStaticGsapPosition(
+ selection,
+ { x: 5, y: 0 },
+ { x: 10, y: 10 },
+ ".group",
+ existing,
+ second.callbacks,
+ );
+
+ expect(second.mutations[0]!.type).toBe("update-properties");
+ expect(second.mutations[0]!.animationId).toBe(existing!.id);
+ });
+});
+
+/**
+ * Candidate C. Every `replace-with-keyframes` in useEnableKeyframes names an
+ * `animationId` parsed out of the CURRENT SOURCE (the anims list comes from
+ * tryFetchAnimationsForElement), so each one rewrites a tween the author already
+ * has. Narrowing those to one element would silently drop the other four
+ * siblings out of an animation that was aimed at the group on purpose.
+ */
+describe("useEnableKeyframes — rewriting an existing tween keeps its group target", () => {
+ it("promoteSetToKeyframes leaves a group-authored set aimed at the group", async () => {
+ const groups = mountGroupSiblings();
+ const mutations: Array> = [];
+ const setAnim = {
+ id: "set-group",
+ targetSelector: ".group",
+ method: "set",
+ properties: { x: 0, y: 0 },
+ resolvedStart: 0,
+ duration: 0,
+ } as unknown as GsapAnimation;
+ const session = {
+ commitMutation: async (mutation: Record) => {
+ mutations.push(mutation);
+ },
+ handleGsapRemoveKeyframe: vi.fn(),
+ };
+
+ // Playhead at the set: the branch that replaces it with a single keyframe,
+ // which can source its value from the set itself (no live iframe needed).
+ await promoteSetToKeyframes(session as never, classOnlySelection(groups[2]!), setAnim, 0, null);
+
+ expect(mutations[0]!.type).toBe("replace-with-keyframes");
+ expect(mutations[0]!.animationId).toBe("set-group");
+ expect(mutations[0]!.targetSelector).toBe(".group");
+ expect(attributedTo(mutations[0]!.targetSelector as string)).toHaveLength(5);
+ });
+});
+
+describe("the written selector survives the real writer and parser", () => {
+ it("re-parses to a tween attributed to the one element it targeted", async () => {
+ const groups = mountGroupSiblings();
+ const { mutations, callbacks } = recorder();
+
+ await commitStaticGsapPosition(
+ classOnlySelection(groups[2]!),
+ { x: 10, y: 10 },
+ { x: 0, y: 0 },
+ ".group",
+ null,
+ callbacks,
+ );
+ const written = writtenTargets(mutations)[0]!;
+
+ const script = `
+const tl = gsap.timeline({ paused: true });
+gsap.set(${JSON.stringify(written)}, { x: 10, y: 10 });
+`.trim();
+ const parsed = parseGsapScript(script).animations.find((a) => a.targetSelector === written);
+
+ expect(parsed).toBeTruthy();
+ expect(resolveSelectorElementIds(parsed!.targetSelector, document)).toEqual(["group-2"]);
+ });
+});
diff --git a/packages/studio/src/hooks/newTweenTargetHooks.test.tsx b/packages/studio/src/hooks/newTweenTargetHooks.test.tsx
new file mode 100644
index 00000000000..8ed60bd7919
--- /dev/null
+++ b/packages/studio/src/hooks/newTweenTargetHooks.test.tsx
@@ -0,0 +1,255 @@
+// @vitest-environment jsdom
+/**
+ * Hook-level siblings of newTweenTarget.test.ts: the property panel and the
+ * gesture recorder also author NEW tweens, so they face the same bare-class
+ * blow-up. Driven through the real hooks so the classification under test
+ * (new tween vs retarget of an existing one) is the production one.
+ */
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { usePlayerStore } from "../player/store/playerStore";
+import { resolveSelectorElementIds } from "./gsapShared";
+import { useAnimatedPropertyCommit } from "./useAnimatedPropertyCommit";
+import { useGestureCommit } from "./useGestureCommit";
+import { mountReactHarness, installReactActEnvironment } from "./domSelectionTestHarness";
+
+installReactActEnvironment();
+
+const frozenSamples = [
+ { time: 0, properties: { x: 0, y: 0 } },
+ { time: 0.5, properties: { x: 60, y: 10 } },
+ { time: 1, properties: { x: 120, y: 40 } },
+];
+
+vi.mock("./useGestureRecording", () => ({
+ useGestureRecording: () => ({
+ startRecording: vi.fn(),
+ stopRecording: () => frozenSamples,
+ clearSamples: vi.fn(),
+ samples: frozenSamples,
+ }),
+}));
+
+afterEach(() => {
+ document.body.innerHTML = "";
+ usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 0 });
+});
+
+function mountGroupSiblings(): HTMLElement[] {
+ document.body.innerHTML = `
+
+ `;
+ return Array.from(document.querySelectorAll(".group"));
+}
+
+/** The id-less shape buildStableSelector answers with a bare class. */
+function classOnlySelection(el: HTMLElement): DomEditSelection {
+ return {
+ element: el,
+ id: undefined,
+ selector: ".group",
+ selectorIndex: Array.prototype.indexOf.call(el.parentElement!.children, el),
+ sourceFile: "index.html",
+ dataAttributes: { start: "0", duration: "2" },
+ } as unknown as DomEditSelection;
+}
+
+function attributedTo(targetSelector: unknown): string[] {
+ return resolveSelectorElementIds(String(targetSelector), document);
+}
+
+type Commit = (
+ selection: DomEditSelection,
+ props: Record,
+) => Promise;
+
+function renderPropertyCommit(
+ animations: GsapAnimation[],
+ mutations: Array>,
+ onReady: (commit: Commit) => void,
+) {
+ function Harness() {
+ const { commitAnimatedProperties } = useAnimatedPropertyCommit({
+ selectedGsapAnimations: animations,
+ gsapCommitMutation: async (_sel: DomEditSelection, mutation: Record) => {
+ mutations.push(mutation);
+ },
+ addGsapAnimation: vi.fn(),
+ convertToKeyframes: vi.fn(),
+ previewIframeRef: { current: null },
+ bumpGsapCache: vi.fn(),
+ } as never);
+ onReady(commitAnimatedProperties);
+ return null;
+ }
+ return mountReactHarness(> = [];
+ let commit: Commit | undefined;
+ const root = renderPropertyCommit([], mutations, (fn) => (commit = fn));
+
+ await act(async () => {
+ await commit!(classOnlySelection(groups[2]!), { rotationX: 30 });
+ });
+
+ const added = mutations.find((m) => m.type === "add");
+ expect(added).toBeTruthy();
+ expect(attributedTo(added!.targetSelector)).toEqual(["group-2"]);
+ act(() => root.unmount());
+ });
+
+ it("authors the first same-group keyframe tween against one element", async () => {
+ const groups = mountGroupSiblings();
+ // A position tween exists, so the element IS animated; a rotation edit has
+ // no same-group tween to join and must author a fresh one.
+ const positionTween = {
+ id: "t-pos",
+ targetSelector: ".group",
+ propertyGroup: "position",
+ method: "to",
+ properties: { x: 0 },
+ resolvedStart: 0,
+ duration: 2,
+ keyframes: {
+ keyframes: [
+ { percentage: 0, properties: { x: 0 } },
+ { percentage: 100, properties: { x: 50 } },
+ ],
+ },
+ } as unknown as GsapAnimation;
+ const mutations: Array> = [];
+ let commit: Commit | undefined;
+ const root = renderPropertyCommit([positionTween], mutations, (fn) => (commit = fn));
+
+ await act(async () => {
+ await commit!(classOnlySelection(groups[1]!), { rotationY: 15 });
+ });
+
+ const added = mutations.find((m) => m.type === "add-with-keyframes");
+ expect(added).toBeTruthy();
+ expect(attributedTo(added!.targetSelector)).toEqual(["group-1"]);
+ act(() => root.unmount());
+ });
+
+ it("leaves an existing group tween aimed at its whole group", async () => {
+ const groups = mountGroupSiblings();
+ usePlayerStore.setState({ autoKeyframeEnabled: false, currentTime: 0 });
+ const groupTween = {
+ id: "t-pos",
+ targetSelector: ".group",
+ propertyGroup: "position",
+ method: "to",
+ properties: { x: 0 },
+ resolvedStart: 0,
+ duration: 2,
+ keyframes: {
+ keyframes: [
+ { percentage: 0, properties: { x: 0, y: 0 } },
+ { percentage: 100, properties: { x: 50, y: 0 } },
+ ],
+ },
+ } as unknown as GsapAnimation;
+ const mutations: Array> = [];
+ let commit: Commit | undefined;
+ const root = renderPropertyCommit([groupTween], mutations, (fn) => (commit = fn));
+
+ await act(async () => {
+ await commit!(classOnlySelection(groups[2]!), { x: 90 });
+ });
+
+ const replaced = mutations.find((m) => m.type === "replace-with-keyframes");
+ expect(replaced).toBeTruthy();
+ expect(replaced!.targetSelector).toBe(".group");
+ act(() => root.unmount());
+ });
+});
+
+function renderGestureCommit(
+ animations: GsapAnimation[],
+ mutations: Array>,
+ selection: DomEditSelection,
+) {
+ let toggle: (() => void) | undefined;
+ function Harness() {
+ const { handleToggleRecording } = useGestureCommit({
+ domEditSessionRef: {
+ current: {
+ domEditSelection: selection,
+ selectedGsapAnimations: animations,
+ commitMutation: async (mutation: Record) => {
+ mutations.push(mutation);
+ },
+ },
+ } as never,
+ previewIframeRef: { current: document.createElement("iframe") },
+ showToast: vi.fn(),
+ isGestureRecordingRef: { current: false },
+ });
+ toggle = handleToggleRecording;
+ return null;
+ }
+ const root = mountReactHarness(> = [];
+ const { root, toggle } = renderGestureCommit([], mutations, classOnlySelection(groups[3]!));
+
+ act(() => toggle()); // start
+ await act(async () => {
+ toggle(); // stop + commit
+ await Promise.resolve();
+ });
+
+ const added = mutations.find((m) => m.type === "add-with-keyframes");
+ expect(added).toBeTruthy();
+ expect(attributedTo(added!.targetSelector)).toEqual(["group-3"]);
+ act(() => root.unmount());
+ });
+
+ it("leaves a merged existing group tween aimed at its whole group", async () => {
+ const groups = mountGroupSiblings();
+ const existing = {
+ id: "t-pos",
+ targetSelector: ".group",
+ propertyGroup: "position",
+ method: "to",
+ properties: { x: 0 },
+ resolvedStart: 0,
+ duration: 2,
+ keyframes: { keyframes: [{ percentage: 0, properties: { x: 0, y: 0 } }] },
+ } as unknown as GsapAnimation;
+ const mutations: Array> = [];
+ const { root, toggle } = renderGestureCommit(
+ [existing],
+ mutations,
+ classOnlySelection(groups[3]!),
+ );
+
+ act(() => toggle());
+ await act(async () => {
+ toggle();
+ await Promise.resolve();
+ });
+
+ const replaced = mutations.find((m) => m.type === "replace-with-keyframes");
+ expect(replaced).toBeTruthy();
+ expect(replaced!.targetSelector).toBe(".group");
+ act(() => root.unmount());
+ });
+});
diff --git a/packages/studio/src/hooks/timelineTrackVisibility.test.ts b/packages/studio/src/hooks/timelineTrackVisibility.test.ts
index 8ccb088fe0c..24d114b98ee 100644
--- a/packages/studio/src/hooks/timelineTrackVisibility.test.ts
+++ b/packages/studio/src/hooks/timelineTrackVisibility.test.ts
@@ -95,7 +95,9 @@ describe("toggleTimelineTrackHidden", () => {
expect(pendingRef.current).toEqual(new Set(["index.html", "scene.html"]));
expect(timestampRef.current).toBeGreaterThan(0);
expect(recordEdit).toHaveBeenCalledTimes(1);
- expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Hide track 0");
+ // Display row, not the raw key: track 0 is the first row, so it reads "1",
+ // the same number the track header announces for that row.
+ expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Hide track 1");
expect(Object.keys(recordEdit.mock.calls[0]?.[0]?.files ?? {}).sort()).toEqual([
"index.html",
"scene.html",
@@ -134,6 +136,64 @@ describe("toggleTimelineTrackHidden", () => {
expect(writes.get("index.html")).not.toContain("data-hidden");
});
+
+ // An expanded sub-comp child gets a synthesized FRACTIONAL track key
+ // (`display.track + n / (siblings + 2)`), so a label built from the raw key
+ // reads "Hide track 0.16666666666666666" in the undo history. Track 0 would
+ // format cleanly and prove nothing, hence 1 / 6.
+ it("labels the undo entry with the display row, not the fractional track key", async () => {
+ const files = new Map([
+ ["index.html", `
`],
+ ]);
+ stubProjectFiles(files);
+
+ const recordEdit = vi.fn();
+
+ await toggleTimelineTrackHidden({
+ projectId: "project-1",
+ activeCompPath: "index.html",
+ timelineElements: [
+ element({ id: "host", domId: "host", track: 0 }),
+ element({ id: "child", domId: "child", track: 1 / 6 }),
+ ],
+ track: 1 / 6,
+ hidden: true,
+ previewIframe: null,
+ writeProjectFile: async () => {},
+ recordEdit,
+ domEditSaveTimestampRef: { current: 0 },
+ pendingTimelineEditPathRef: { current: new Set() },
+ });
+
+ expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Hide track 2");
+ });
+
+ it("labels a show back with the display row too", async () => {
+ const files = new Map([
+ ["index.html", `
`],
+ ]);
+ stubProjectFiles(files);
+
+ const recordEdit = vi.fn();
+
+ await toggleTimelineTrackHidden({
+ projectId: "project-1",
+ activeCompPath: "index.html",
+ timelineElements: [
+ element({ id: "host", domId: "host", track: 0 }),
+ element({ id: "child", domId: "child", track: 1 / 6, hidden: true }),
+ ],
+ track: 1 / 6,
+ hidden: false,
+ previewIframe: null,
+ writeProjectFile: async () => {},
+ recordEdit,
+ domEditSaveTimestampRef: { current: 0 },
+ pendingTimelineEditPathRef: { current: new Set() },
+ });
+
+ expect(recordEdit.mock.calls[0]?.[0]?.label).toBe("Show track 2");
+ });
});
describe("toggleTimelineElementHidden", () => {
diff --git a/packages/studio/src/hooks/timelineTrackVisibility.ts b/packages/studio/src/hooks/timelineTrackVisibility.ts
index f305226c92d..7860ad38b35 100644
--- a/packages/studio/src/hooks/timelineTrackVisibility.ts
+++ b/packages/studio/src/hooks/timelineTrackVisibility.ts
@@ -1,6 +1,11 @@
import { useCallback } from "react";
import { usePlayerStore, type TimelineElement } from "../player";
import { useExpandedTimelineElements } from "../player/hooks/useExpandedTimelineElements";
+import {
+ timelineTrackOrder,
+ trackDisplayNumber,
+ trackDisplaySuffix,
+} from "../player/components/timelineTrackDisplay";
import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
import {
@@ -208,12 +213,17 @@ export async function toggleTimelineTrackHidden({
domEditSaveTimestampRef,
pendingTimelineEditPathRef,
}: ToggleTimelineTrackHiddenInput): Promise {
+ // `track` is the fractional sort key the callback needs; the history entry is
+ // read by a human, so it gets the display row instead.
+ const suffix = trackDisplaySuffix(
+ trackDisplayNumber(timelineTrackOrder(timelineElements), track),
+ );
return setElementsHidden({
projectId,
activeCompPath,
elements: timelineElements.filter((element) => element.track === track),
hidden,
- label: hidden ? `Hide track ${track}` : `Show track ${track}`,
+ label: hidden ? `Hide track${suffix}` : `Show track${suffix}`,
previewIframe,
writeProjectFile,
recordEdit,
diff --git a/packages/studio/src/hooks/useAnimatedPropertyCommit.ts b/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
index a454a4bf668..640f593281d 100644
--- a/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
+++ b/packages/studio/src/hooks/useAnimatedPropertyCommit.ts
@@ -14,7 +14,13 @@ import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { usePlayerStore } from "../player/store/playerStore";
import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeBridge";
import type { SetPatchProps } from "./gsapRuntimePatch";
-import { selectorFromSelection, computeElementPercentage, isInstantHold } from "./gsapShared";
+import {
+ selectorFromSelection,
+ computeElementPercentage,
+ isInstantHold,
+ writeTargetSelector,
+ tweenTargetsElement,
+} from "./gsapShared";
import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
import { roundTo3 } from "../utils/rounding";
import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
@@ -185,7 +191,9 @@ async function commitStaticSet(
batch.push(entry);
byGroup.set(group, batch);
}
- const staticWrites = animations.filter((a) => isInstantHold(a) && a.targetSelector === selector);
+ const staticWrites = animations.filter(
+ (a) => isInstantHold(a) && tweenTargetsElement(a.targetSelector, selector, selection.element),
+ );
// Resolve every group's target BEFORE committing anything, and coalesce
// groups that land on the SAME write into one commit: the snapshot is captured
// once, so if two groups resolved to one legacy mixed write, a first
@@ -206,7 +214,7 @@ async function commitStaticSet(
}
// Fresh adds don't reshape existing sets, so their ids can't go stale.
for (const batch of newSetBatches) {
- await addGlobalStaticSet(selection, batch, selector, commit);
+ await addGlobalStaticSet(selection, batch, commit);
}
}
@@ -236,18 +244,22 @@ function findGroupOwningStaticWrite(
async function addGlobalStaticSet(
selection: DomEditSelection,
batch: [string, number | string][],
- selector: string,
commit: Commit,
): Promise {
const numericProps: SetPatchProps = {};
for (const [k, v] of batch) {
if (typeof v === "number") numericProps[k as keyof SetPatchProps] = v;
}
+ // A brand-new write, so it must address ONE element: the selection's own
+ // selector is the bare class an id-less element yields, which would hold every
+ // sibling. No one-element form means no write at all (see writeTargetSelector).
+ const target = writeTargetSelector(selection);
+ if (!target) return;
await commit(
selection,
{
type: "add",
- targetSelector: selector,
+ targetSelector: target,
method: "set",
position: 0,
properties: Object.fromEntries(batch),
@@ -259,7 +271,7 @@ async function addGlobalStaticSet(
...(Object.keys(numericProps).length > 0
? {
instantPatch: {
- selector,
+ selector: target,
change: { kind: "global-set" as const, props: numericProps },
},
}
@@ -482,7 +494,11 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
// contaminating a foreign-group tween. Mirror an existing keyframed tween's
// time range so the new group animates over the same span. The 0% baseline is
// an `_auto` endpoint so it tracks the nearest keyframe as you add more.
- if (selector) {
+ // A fresh tween, so its target must address ONE element; with no
+ // one-element form the edit is dropped rather than written onto every
+ // class sibling (see writeTargetSelector).
+ const newTweenTarget = writeTargetSelector(selection);
+ if (selector && newTweenTarget) {
const template = selectedGsapAnimations.find((a) => !!a.keyframes);
const tStart = template ? (resolveTweenStart(template) ?? 0) : 0;
const tDur = template ? resolveTweenDuration(template) || 1 : 1;
@@ -503,7 +519,7 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
selection,
{
type: "add-with-keyframes",
- targetSelector: selector,
+ targetSelector: newTweenTarget,
position: roundTo3(tStart),
duration: roundTo3(tDur),
keyframes,
diff --git a/packages/studio/src/hooks/useEnableKeyframes.test.ts b/packages/studio/src/hooks/useEnableKeyframes.test.ts
index f9cac5e9ec5..19cb618616f 100644
--- a/packages/studio/src/hooks/useEnableKeyframes.test.ts
+++ b/packages/studio/src/hooks/useEnableKeyframes.test.ts
@@ -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 = '(".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]);
+ });
+});
diff --git a/packages/studio/src/hooks/useEnableKeyframes.ts b/packages/studio/src/hooks/useEnableKeyframes.ts
index 38c8f500860..c886ca58b8d 100644
--- a/packages/studio/src/hooks/useEnableKeyframes.ts
+++ b/packages/studio/src/hooks/useEnableKeyframes.ts
@@ -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,
): Promise {
- 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 {
- 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 {
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");
diff --git a/packages/studio/src/hooks/useGestureCommit.ts b/packages/studio/src/hooks/useGestureCommit.ts
index cdc51dcf97d..bc87caac394 100644
--- a/packages/studio/src/hooks/useGestureCommit.ts
+++ b/packages/studio/src/hooks/useGestureCommit.ts
@@ -13,7 +13,7 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
import { roundTo3 } from "../utils/rounding";
import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
-import { isInstantHold, idSelector } from "./gsapShared";
+import { isInstantHold, idSelector, writeTargetSelector, tweenTargetsElement } from "./gsapShared";
type RecordedKeyframe = {
percentage: number;
@@ -168,11 +168,24 @@ export function useGestureCommit({
if (!sortedPcts.includes(0)) sortedPcts.unshift(0);
}
+ // Two different jobs, two different selectors. `selector` is the string an
+ // ALREADY-AUTHORED tween is matched against (and retargeted with, so a
+ // tween aimed at a whole group stays aimed at it). `writeSelector` is what
+ // a NEW tween is authored with: the bare class the id-less case yields here
+ // would record the gesture onto every sibling sharing it.
const selector = sel.id ? idSelector(sel.id) : sel.selector;
if (!selector) {
showToast("Cannot save — element has no selector", "error");
return;
}
+ // A recorded gesture becomes a NEW tween, so its target must address one
+ // element; the selection's own selector would record the motion onto
+ // every sibling sharing its class (see writeTargetSelector).
+ const writeSelector = writeTargetSelector(sel);
+ if (!writeSelector) {
+ showToast("Cannot save: element has no unique selector", "error");
+ return;
+ }
if (liveSession.commitMutation) {
const recStart = recordingStartTimeRef.current;
const rawKeyframes = sortedPcts.map((pct) => ({
@@ -186,7 +199,11 @@ export function useGestureCommit({
);
const allAnims = liveSession.selectedGsapAnimations ?? [];
const existingPositionTween = hasPositionProps
- ? allAnims.find((a) => a.propertyGroup === "position" && a.targetSelector === selector)
+ ? allAnims.find(
+ (a) =>
+ a.propertyGroup === "position" &&
+ tweenTargetsElement(a.targetSelector, selector, sel.element),
+ )
: undefined;
if (existingPositionTween) {
if (isInstantHold(existingPositionTween)) {
@@ -261,7 +278,7 @@ export function useGestureCommit({
await liveSession.commitMutation(
{
type: "add-with-keyframes",
- targetSelector: selector,
+ targetSelector: writeSelector,
position: roundTo3(recStart),
duration: roundTo3(duration),
keyframes: groupKfs,
@@ -287,7 +304,7 @@ export function useGestureCommit({
await liveSession.commitMutation(
{
type: "add-with-keyframes",
- targetSelector: selector,
+ targetSelector: writeSelector,
position: roundTo3(recStart),
duration: roundTo3(duration),
keyframes: groupKfs,
diff --git a/packages/studio/src/hooks/useGsapScriptCommits.ts b/packages/studio/src/hooks/useGsapScriptCommits.ts
index 566d2bc538e..b4b7d6f6365 100644
--- a/packages/studio/src/hooks/useGsapScriptCommits.ts
+++ b/packages/studio/src/hooks/useGsapScriptCommits.ts
@@ -186,6 +186,9 @@ function syncCommittedGsapMutation({
targetPath,
selection.id ?? undefined,
mutation,
+ // The live preview document is what resolves a class / descendant tween to
+ // the elements it really animates; without it only whole-id selectors do.
+ iframe?.contentDocument,
);
}
refreshMutationPreview(iframe, result, options, reloadPreview, onCacheInvalidate);
diff --git a/packages/studio/src/hooks/useGsapTweenCache.test.ts b/packages/studio/src/hooks/useGsapTweenCache.test.ts
index 0492a1f501a..43cb03a41b6 100644
--- a/packages/studio/src/hooks/useGsapTweenCache.test.ts
+++ b/packages/studio/src/hooks/useGsapTweenCache.test.ts
@@ -86,16 +86,24 @@ describe("resolveSelectorElementIds", () => {
expect(resolveSelectorElementIds(".a, .b", doc).sort()).toEqual(["x", "y"]);
});
- it("falls back to a leading #id when there is no DOM", () => {
- expect(resolveSelectorElementIds("#card .label", null)).toEqual(["card"]);
+ // A DOM-less LEADING-id fallback attributed `#card .label` to `#card`, the
+ // ancestor it merely scopes to. Without a DOM there is nothing to resolve the
+ // descendant against, so the honest answer is no element at all.
+ it("resolves nothing for a compound selector when there is no DOM", () => {
+ expect(resolveSelectorElementIds("#card .label", null)).toEqual([]);
expect(resolveSelectorElementIds(".dot", null)).toEqual([]);
});
+ it("still resolves every whole-id part of a group selector without a DOM", () => {
+ expect(resolveSelectorElementIds("#a, #b", null)).toEqual(["a", "b"]);
+ });
+
// The `[id="…"]` form is what writers emit for a CSS-unsafe id (digit-leading,
// dotted). The old local `#id`-only regex read no id at all for those, so they
// silently dropped out of both DOM-less paths.
it("falls back to a bracketed id when there is no DOM", () => {
- expect(resolveSelectorElementIds('[id="01-hook"] .label', null)).toEqual(["01-hook"]);
+ expect(resolveSelectorElementIds('[id="01-hook"]', null)).toEqual(["01-hook"]);
+ expect(resolveSelectorElementIds('[id="01-hook"] .label', null)).toEqual([]);
});
it("falls back to a bracketed id when querySelectorAll rejects the selector", () => {
diff --git a/packages/studio/src/hooks/useGsapTweenCache.ts b/packages/studio/src/hooks/useGsapTweenCache.ts
index 0f89be655c4..23a8ea72822 100644
--- a/packages/studio/src/hooks/useGsapTweenCache.ts
+++ b/packages/studio/src/hooks/useGsapTweenCache.ts
@@ -7,24 +7,17 @@ import {
pruneKeyframeCacheToFiles,
writeGsapAnimationsForElement,
} from "./gsapKeyframeCacheHelpers";
-import { toAbsoluteTime, toClipPercentage } from "./gsapShared";
+import { resolveClipTimingBasis, toAbsoluteTime, toClipPercentage } from "./gsapShared";
import {
deduplicateKeyframes,
isStaticPositionHold,
synthesizeFlatTweenKeyframes,
} from "./gsapTweenSynth";
-import {
- fetchParsedAnimations,
- populateKeyframeCacheFromAst,
- resolveClipTimingBasis,
-} from "./keyframeCacheAstLoad";
+import { fetchParsedAnimations, populateKeyframeCacheFromAst } from "./keyframeCacheAstLoad";
// Re-exported so callers keep importing the GSAP cache surface from one module.
-export {
- fetchParsedAnimations,
- resolveClipTimingBasis,
- resolveSelectorElementIds,
-} from "./keyframeCacheAstLoad";
+export { resolveClipTimingBasis } from "./gsapShared";
+export { fetchParsedAnimations, resolveSelectorElementIds } from "./keyframeCacheAstLoad";
/** The selected element's identity for matching tweens to it. */
export interface GsapElementTarget {
diff --git a/packages/studio/src/player/components/LayerDisclosureRow.tsx b/packages/studio/src/player/components/LayerDisclosureRow.tsx
index 2f56f0aa822..415b72c0991 100644
--- a/packages/studio/src/player/components/LayerDisclosureRow.tsx
+++ b/packages/studio/src/player/components/LayerDisclosureRow.tsx
@@ -22,7 +22,10 @@ export function LayerDisclosureRow({
/** Same adaptive width the lane rows use: a narrowed header column must not
* leave this row hanging over the clips it labels. */
columnWidth: number;
- /** Id of the element holding the lanes this row's caret expands. */
+ /** Id of the CANVAS-side element holding the diamond lanes this row's caret
+ * expands (see TimelinePropertyLanes). The caret also reveals the per-lane
+ * control rows in this column, but the diamonds are what following the
+ * reference should land on. */
lanesId: string;
onToggleClipExpanded: () => void;
/** Trailing controls that act on the LAYER (the visibility eye), not on a lane. */
diff --git a/packages/studio/src/player/components/ShortcutsPanel.test.tsx b/packages/studio/src/player/components/ShortcutsPanel.test.tsx
new file mode 100644
index 00000000000..31d5b0f9f7a
--- /dev/null
+++ b/packages/studio/src/player/components/ShortcutsPanel.test.tsx
@@ -0,0 +1,158 @@
+// @vitest-environment happy-dom
+
+import React, { act, Profiler } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ShortcutsPanel } from "./ShortcutsPanel";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const roots: Root[] = [];
+
+afterEach(() => {
+ for (const root of roots.splice(0)) act(() => root.unmount());
+ document.body.innerHTML = "";
+});
+
+function renderPanel(onRender = vi.fn()) {
+ const host = document.createElement("div");
+ document.body.append(host);
+ const root = createRoot(host);
+ roots.push(root);
+ act(() => {
+ root.render(
+
+ ,
+ );
+ });
+
+ const trigger = host.querySelector(
+ 'button[aria-label="Shortcuts and tools"]',
+ )!;
+ return { host, trigger, onRender };
+}
+
+function pressAndClick(target: HTMLElement): void {
+ target.dispatchEvent(
+ new PointerEvent("pointerdown", { bubbles: true, cancelable: true, button: 0 }),
+ );
+ target.dispatchEvent(new MouseEvent("mousedown", { bubbles: true, cancelable: true, button: 0 }));
+ target.dispatchEvent(new MouseEvent("mouseup", { bubbles: true, cancelable: true, button: 0 }));
+ target.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true, button: 0 }));
+}
+
+function openPanel(trigger: HTMLButtonElement): void {
+ act(() => pressAndClick(trigger));
+ expect(trigger.getAttribute("aria-expanded")).toBe("true");
+}
+
+describe("ShortcutsPanel", () => {
+ it.each(["page", "button", "panel"] as const)(
+ "closes with Escape from the %s-focused position",
+ (focusPosition) => {
+ const { host, trigger } = renderPanel();
+ openPanel(trigger);
+
+ let eventTarget: Document | HTMLElement;
+ if (focusPosition === "page") {
+ document.body.tabIndex = -1;
+ document.body.focus();
+ eventTarget = document;
+ expect(document.activeElement).toBe(document.body);
+ } else if (focusPosition === "button") {
+ trigger.focus();
+ eventTarget = trigger;
+ expect(document.activeElement).toBe(trigger);
+ } else {
+ const panelInput = host.querySelector('[aria-label="Jump to frame"]')!;
+ panelInput.focus();
+ eventTarget = panelInput;
+ expect(document.activeElement).toBe(panelInput);
+ }
+
+ act(() => {
+ eventTarget.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+ });
+
+ expect(trigger.getAttribute("aria-expanded")).toBe("false");
+ expect(host.querySelector('[aria-label="Jump to frame"]')).toBeNull();
+ },
+ );
+
+ it("closes on capture-phase pointerdown even when its default is prevented", () => {
+ const preventDefault = (event: Event) => event.preventDefault();
+ document.addEventListener("pointerdown", preventDefault, true);
+ const { host, trigger } = renderPanel();
+ openPanel(trigger);
+ const outside = document.createElement("div");
+ document.body.append(outside);
+ const pointerDown = new PointerEvent("pointerdown", {
+ bubbles: true,
+ cancelable: true,
+ button: 0,
+ });
+
+ act(() => outside.dispatchEvent(pointerDown));
+
+ document.removeEventListener("pointerdown", preventDefault, true);
+ expect(pointerDown.defaultPrevented).toBe(true);
+ expect(trigger.getAttribute("aria-expanded")).toBe("false");
+ expect(host.querySelector('[aria-label="Jump to frame"]')).toBeNull();
+ });
+
+ it("does not close on a click inside the panel", () => {
+ const { host, trigger } = renderPanel();
+ openPanel(trigger);
+ const panelInput = host.querySelector('[aria-label="Jump to frame"]')!;
+
+ act(() => pressAndClick(panelInput));
+
+ expect(trigger.getAttribute("aria-expanded")).toBe("true");
+ expect(host.querySelector('[aria-label="Jump to frame"]')).not.toBeNull();
+ });
+
+ it("toggles once per trigger click", () => {
+ const { trigger } = renderPanel();
+
+ act(() => pressAndClick(trigger));
+ expect(trigger.getAttribute("aria-expanded")).toBe("true");
+
+ act(() => pressAndClick(trigger));
+ expect(trigger.getAttribute("aria-expanded")).toBe("false");
+ });
+
+ it("does not re-render when Escape is pressed while closed", () => {
+ const { trigger, onRender } = renderPanel();
+ expect(onRender).toHaveBeenCalledTimes(1);
+
+ act(() => {
+ document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+ });
+
+ expect(trigger.getAttribute("aria-expanded")).toBe("false");
+ expect(onRender).toHaveBeenCalledTimes(1);
+ });
+
+ it("connects the trigger to the dialog with aria-controls", () => {
+ const { host, trigger } = renderPanel();
+ openPanel(trigger);
+ const panelId = trigger.getAttribute("aria-controls");
+ const panel = panelId ? host.querySelector(`#${CSS.escape(panelId)}`) : null;
+
+ expect(panelId).not.toBeNull();
+ expect(panel?.getAttribute("role")).toBe("dialog");
+ // Non-modal on purpose: focus is not trapped and the editor behind stays
+ // operable, so aria-modal would lie to assistive tech about inertness.
+ expect(panel?.getAttribute("aria-modal")).toBeNull();
+ expect(panel?.id).toBe(panelId);
+ });
+});
diff --git a/packages/studio/src/player/components/ShortcutsPanel.tsx b/packages/studio/src/player/components/ShortcutsPanel.tsx
index 50506ad46aa..d36336e41ef 100644
--- a/packages/studio/src/player/components/ShortcutsPanel.tsx
+++ b/packages/studio/src/player/components/ShortcutsPanel.tsx
@@ -1,6 +1,7 @@
-import { useState, useCallback, useRef, useEffect, memo } from "react";
+import { useState, useCallback, useId, memo } from "react";
import { formatTime, frameToSeconds } from "../lib/time";
import { Tooltip } from "../../components/ui";
+import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
const SHORTCUT_SECTIONS = [
{
@@ -108,20 +109,9 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
}: ShortcutsPanelProps) {
const [showShortcuts, setShowShortcuts] = useState(false);
const [jumpFrame, setJumpFrame] = useState("");
- const shortcutsPanelRef = useRef(null);
-
- useEffect(() => {
- if (!showShortcuts) return;
- const handleMouseDown = (e: MouseEvent) => {
- if (shortcutsPanelRef.current && !shortcutsPanelRef.current.contains(e.target as Node)) {
- setShowShortcuts(false);
- }
- };
- document.addEventListener("mousedown", handleMouseDown);
- return () => {
- document.removeEventListener("mousedown", handleMouseDown);
- };
- }, [showShortcuts]);
+ const shortcutsPanelId = useId();
+ const closeShortcuts = useCallback(() => setShowShortcuts(false), []);
+ const shortcutsPanelRef = useContextMenuDismiss(closeShortcuts);
const commitJumpFrame = useCallback(() => {
if (disabled) return;
@@ -158,6 +148,7 @@ export const ShortcutsPanel = memo(function ShortcutsPanel({
}`}
aria-label="Shortcuts and tools"
aria-expanded={showShortcuts}
+ aria-controls={shortcutsPanelId}
>
{showShortcuts && (
{
// mounted before we query it.
act(() => {});
- const button = host.querySelector
('button[aria-label="Show track 0"]');
+ // "1", not "0": the label carries the 1-based display row, while the
+ // callback below still routes by the track's own key.
+ const button = host.querySelector('button[aria-label="Show track 1"]');
expect(button).not.toBeNull();
if (!button) throw new Error("Expected a track visibility toggle");
diff --git a/packages/studio/src/player/components/TimelineCanvas.tsx b/packages/studio/src/player/components/TimelineCanvas.tsx
index bdf63bbc5c9..3cb0d52e645 100644
--- a/packages/studio/src/player/components/TimelineCanvas.tsx
+++ b/packages/studio/src/player/components/TimelineCanvas.tsx
@@ -20,7 +20,8 @@ import { type MultiDragPreviewInput } from "./timelineMultiDragPreview";
import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
import type { Rect } from "../../utils/marqueeGeometry";
import { TimelineClip } from "./TimelineClip";
-import { TimelineLanes, type TimelineLaneBaseProps } from "./TimelineLanes";
+import { TimelineLanes } from "./TimelineLanes";
+import type { TimelineLaneBaseProps } from "./timelineLaneProps";
import { renderClipChildren } from "./timelineClipChildren";
import { useTimelineRevealClip } from "./useTimelineRevealClip";
import type { TimelineLaneGapStrips } from "./useTimelineGapHighlights";
diff --git a/packages/studio/src/player/components/TimelineClipDiamonds.test.tsx b/packages/studio/src/player/components/TimelineClipDiamonds.test.tsx
index aff08c08221..fc00b55c03d 100644
--- a/packages/studio/src/player/components/TimelineClipDiamonds.test.tsx
+++ b/packages/studio/src/player/components/TimelineClipDiamonds.test.tsx
@@ -641,7 +641,7 @@ describe("TimelineClipDiamonds", () => {
act(() => root.unmount());
});
- const renderSegmentLane = (lastAmbiguous: boolean) => {
+ const renderSegmentLane = (lastAmbiguous: boolean, clipWidthPx = 200) => {
const host = document.createElement("div");
document.body.append(host);
const root = createRoot(host);
@@ -660,7 +660,7 @@ describe("TimelineClipDiamonds", () => {
format: "percentage",
keyframes: [kf(0), kf(50), kf(100, { easeAmbiguous: lastAmbiguous })],
}}
- clipWidthPx={200}
+ clipWidthPx={clipWidthPx}
clipHeightPx={48}
accentColor="#4ba3d2"
isSelected
@@ -698,6 +698,21 @@ describe("TimelineClipDiamonds", () => {
expect(segment?.style.pointerEvents).toBe("none");
expect(ease?.style.pointerEvents).toBe("auto");
expect(Number(segment?.style.zIndex)).toBeGreaterThan(Number(diamond?.style.zIndex));
+ // Room to spare here, so the button carries the 24x24 WCAG 2.5.8 overlay.
+ expect(ease?.className).toContain("before:h-6");
+ act(() => root.unmount());
+ });
+
+ it("drops the 24x24 ease overlay when the segment is too narrow to hold it", () => {
+ // The segment wrapper outranks the diamonds, so an overlay wider than the
+ // clear span between them would steal their clicks at fit zoom. 40px of clip
+ // across three keyframes leaves well under 24px of clear span per segment.
+ const { host, root } = renderSegmentLane(false, 40);
+ const ease = host.querySelector("[data-keyframe-ease-button]");
+
+ expect(ease).not.toBeNull();
+ expect(ease?.className).not.toContain("before:h-6");
+ expect(ease?.style.width).toBe("16px");
act(() => root.unmount());
});
diff --git a/packages/studio/src/player/components/TimelineClipDiamonds.tsx b/packages/studio/src/player/components/TimelineClipDiamonds.tsx
index 2f6ec31b8df..a56cd789bd6 100644
--- a/packages/studio/src/player/components/TimelineClipDiamonds.tsx
+++ b/packages/studio/src/player/components/TimelineClipDiamonds.tsx
@@ -27,6 +27,12 @@ export type { TimelineDiamondKeyframe } from "./timelineDiamondTypes";
// stops there: at the zoom floor the gap alone left a ~7px target, which is
// neither hittable nor selectable with any accuracy. Boxes may overlap slightly
// below this width; each diamond still owns the half-gap around its own centre.
+//
+// Deliberately below the 24px WCAG 2.2 (2.5.8) minimum, under that criterion's
+// own spacing exception: at normal keyframe density the neighbour gap is under
+// 24px, so a 24px floor would make adjacent diamonds' hit boxes OVERLAP — one
+// diamond swallowing its neighbour's clicks is a worse 2.5.8 failure than a
+// small target. Do not "fix" this to 24.
const KF_MIN_HIT_W = 12;
/** A clip-% is a float division, so a raw tooltip reads `25.032499999999995%`. */
@@ -141,6 +147,10 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
? Math.round(clipHeightPx * 0.45)
: Math.round(LANE_H * DIAMOND_RATIO);
const centerY = beatsActive ? BEAT_BAND_H + (clipHeightPx - BEAT_BAND_H) / 2 : clipHeightPx / 2;
+ // Hit-box height only — the glyph keeps `marker.visualSize`. 24 is the WCAG 2.2
+ // (2.5.8) minimum and still fits the 28px lane. Beat-strip lanes keep the
+ // shrunken box: 24px there would reach up into the beat strip.
+ const hitHeight = beatsActive ? diamondSize : 24;
const sorted = keyframesData.keyframes
.filter((kf) => kf.percentage >= KF_MIN_PCT && kf.percentage <= KF_MAX_PCT)
.sort((a, b) => a.percentage - b.percentage);
@@ -412,7 +422,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
top: centerY,
transform: "translateY(-50%)",
width: marker.hitWidth,
- height: diamondSize,
+ height: hitHeight,
zIndex: isHighlighted ? 2 : 1,
pointerEvents: "auto",
background: "none",
diff --git a/packages/studio/src/player/components/TimelineDiamondConnectors.tsx b/packages/studio/src/player/components/TimelineDiamondConnectors.tsx
index a0689213dda..4b155ef7100 100644
--- a/packages/studio/src/player/components/TimelineDiamondConnectors.tsx
+++ b/packages/studio/src/player/components/TimelineDiamondConnectors.tsx
@@ -62,6 +62,12 @@ export function TimelineDiamondConnectors({
// no source animation id (runtime-scanned) so there is no tween to target.
const target = keyframeTarget(kf);
const ease = kf.ease ?? globalEase;
+ // connectorWidth is the clear span between the two diamonds' edges, so a
+ // 24x24 target centred in it overhangs a diamond as soon as the span is
+ // narrower than 24. The segment wrapper sits at z-index 3, above the
+ // diamonds, so that overhang would win the hit test and steal their
+ // clicks at fit zoom. Grow the target only where the room exists.
+ const roomForFullTarget = connectorWidth >= 24;
return (
{
+ document.body.innerHTML = "";
+ usePlayerStore.getState().reset();
+});
+
+/** The z-order sort keys really are fractional: a clip nudged between two lanes
+ * lands on the midpoint. These are the values that used to reach aria-label. */
+const TRACK_A = 1 / 6;
+const TRACK_B = 0.5;
+
+function element(id: string, track: number): TimelineElement {
+ return { id, label: id, tag: "div", start: 0, duration: 2, track };
+}
+
+function positionTween(id: string): GsapAnimation {
+ return {
+ id: `${id}-tween`,
+ targetSelector: `#${id}`,
+ method: "to",
+ position: 0,
+ duration: 2,
+ properties: {},
+ propertyGroup: "position",
+ keyframes: {
+ format: "percentage",
+ keyframes: [
+ { percentage: 0, properties: { x: 0 } },
+ { percentage: 100, properties: { x: 100 } },
+ ],
+ },
+ };
+}
+
+interface RenderLanesOptions {
+ elements?: TimelineElement[];
+ animations?: Map
;
+ expandedClipIds?: string[];
+ selectedElementIds?: Set;
+ multiDragPreview?: MultiDragPreviewInput | null;
+ draggedClip?: DraggedClipState | null;
+ onToggleTrackHidden?: TimelineEditCallbacks["onToggleTrackHidden"];
+ onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
+}
+
+function renderLanes(options: RenderLanesOptions = {}): {
+ host: HTMLDivElement;
+ root: Root;
+ rerender: (next: RenderLanesOptions) => void;
+} {
+ const host = document.createElement("div");
+ document.body.append(host);
+ const root = createRoot(host);
+ const render = (next: RenderLanesOptions) => {
+ const elements = next.elements ?? [element("clip-a", TRACK_A)];
+ const gsapAnimations = next.animations ?? new Map();
+ const displayTrackOrder = [...new Set(elements.map((el) => el.track))].sort((a, b) => a - b);
+ const tracks: [number, TimelineElement[]][] = displayTrackOrder.map((track) => [
+ track,
+ elements.filter((el) => el.track === track),
+ ]);
+ const laneCounts = new Map(
+ elements.map((el) => [el.id, (gsapAnimations.get(el.id) ?? []).length]),
+ );
+ act(() => {
+ usePlayerStore.setState({ expandedClipIds: new Set(next.expandedClipIds ?? []) });
+ root.render(
+ TRACK_H)}
+ trackOrder={displayTrackOrder}
+ tracks={tracks}
+ trackStyles={new Map()}
+ laneCounts={laneCounts}
+ selectedElementId={null}
+ selectedElementIds={next.selectedElementIds ?? new Set()}
+ hoveredClip={null}
+ draggedClip={next.draggedClip ?? null}
+ draggedElement={null}
+ multiDragPreview={next.multiDragPreview ?? null}
+ blockedClipRef={createRef()}
+ suppressClickRef={{ current: false }}
+ scrollRef={createRef()}
+ setHoveredClip={vi.fn()}
+ setShowPopover={vi.fn()}
+ setRangeSelection={vi.fn()}
+ setResizingClip={vi.fn()}
+ setDraggedClip={vi.fn()}
+ setSelectedElementId={vi.fn()}
+ syncClipDragAutoScroll={vi.fn()}
+ shiftClickClipRef={createRef()}
+ getPreviewElement={(el) => el}
+ getTrackStyle={getTrackStyle}
+ gsapAnimations={gsapAnimations}
+ selectedKeyframes={new Set()}
+ currentTime={0}
+ onContextMenuLane={next.onContextMenuLane}
+ onToggleTrackHidden={next.onToggleTrackHidden}
+ onTogglePropertyGroupKeyframe={vi.fn()}
+ onResizeElement={vi.fn()}
+ onMoveElement={vi.fn()}
+ onRazorSplit={vi.fn()}
+ onRazorSplitAll={vi.fn()}
+ />,
+ );
+ });
+ };
+ render(options);
+ return { host, root, rerender: render };
+}
+
+function visibilityLabels(host: HTMLElement): (string | null)[] {
+ return Array.from(host.querySelectorAll("button[aria-label^='Hide track ']")).map((button) =>
+ button.getAttribute("aria-label"),
+ );
+}
+
+describe("TimelineLanes track numbering", () => {
+ // Screen readers literally announced "Hide track 0.16666666666666666".
+ it("numbers tracks contiguously from 1 regardless of the fractional sort keys", () => {
+ const view = renderLanes({
+ elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
+ });
+
+ expect(visibilityLabels(view.host)).toEqual(["Hide track 1", "Hide track 2"]);
+ expect(view.host.innerHTML).not.toContain("0.16666666666666666");
+ act(() => view.root.unmount());
+ });
+
+ it("hands the visibility toggle the real track key, not the display index", () => {
+ const onToggleTrackHidden = vi.fn();
+ const view = renderLanes({
+ elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
+ onToggleTrackHidden,
+ });
+
+ const second = view.host.querySelector('button[aria-label="Hide track 2"]');
+ act(() => second?.click());
+
+ expect(onToggleTrackHidden).toHaveBeenCalledWith(TRACK_B, true);
+ act(() => view.root.unmount());
+ });
+
+ // The gap menu inserts at the track it is given, so a display index here would
+ // drop the new clip on the wrong lane.
+ it("hands the lane context menu the real track key, not the display index", () => {
+ const onContextMenuLane = vi.fn();
+ const view = renderLanes({
+ elements: [element("clip-a", TRACK_A), element("clip-b", TRACK_B)],
+ onContextMenuLane,
+ });
+
+ // Row children: [sticky header column, time-mapped track content].
+ const rows = Array.from(view.host.children);
+ const secondTrackContent = rows[1]?.children.item(1);
+ act(() => {
+ secondTrackContent?.dispatchEvent(
+ new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 100 }),
+ );
+ });
+
+ expect(onContextMenuLane).toHaveBeenCalledOnce();
+ expect(onContextMenuLane.mock.calls[0]?.[1]).toBe(TRACK_B);
+ act(() => view.root.unmount());
+ });
+});
+
+describe("TimelineLanes disclosure target", () => {
+ const ANIMATIONS = new Map([["clip-a", [positionTween("clip-a")]]]);
+
+ function ariaControlsTarget(host: HTMLElement): HTMLElement | null {
+ const caret = host.querySelector("button[aria-controls]");
+ const id = caret?.getAttribute("aria-controls");
+ return id ? host.querySelector(`#${id}`) : null;
+ }
+
+ // aria-controls used to name a div in the sticky label column: it computed to
+ // 0x0 and held no diamonds at all.
+ it("resolves the caret's aria-controls to an element holding the property lanes", () => {
+ const view = renderLanes({ animations: ANIMATIONS, expandedClipIds: ["clip-a"] });
+ const target = ariaControlsTarget(view.host);
+
+ expect(target).not.toBeNull();
+ expect(target?.querySelectorAll("[data-timeline-property-lane]").length).toBeGreaterThan(0);
+ act(() => view.root.unmount());
+ });
+
+ it("still resolves the caret's aria-controls while the layer is collapsed", () => {
+ const view = renderLanes({ animations: ANIMATIONS, expandedClipIds: [] });
+ const target = ariaControlsTarget(view.host);
+
+ expect(target).not.toBeNull();
+ expect(target?.querySelectorAll("[data-timeline-property-lane]")).toHaveLength(0);
+ act(() => view.root.unmount());
+ });
+
+ // Two timelines on one page (a mini-timeline in a modal beside the main one)
+ // both minted `timeline-lanes-track-0`, so every caret's aria-controls
+ // resolved to whichever instance mounted first.
+ it("mints lane ids that do not collide with a second TimelineLanes on the page", () => {
+ const first = renderLanes({ animations: ANIMATIONS, expandedClipIds: ["clip-a"] });
+ const second = renderLanes({ animations: ANIMATIONS, expandedClipIds: ["clip-a"] });
+
+ const idsFor = (host: HTMLElement) =>
+ Array.from(host.querySelectorAll("button[aria-controls]")).map((caret) =>
+ caret.getAttribute("aria-controls"),
+ );
+ const firstIds = idsFor(first.host);
+ const secondIds = idsFor(second.host);
+
+ expect(firstIds.length).toBeGreaterThan(0);
+ expect(firstIds.some((id) => secondIds.includes(id))).toBe(false);
+ // Still a legal CSS id selector: the aria-controls lookups above use `#id`.
+ for (const id of [...firstIds, ...secondIds]) {
+ expect(id).toMatch(/^[A-Za-z][\w-]*$/);
+ }
+ act(() => first.root.unmount());
+ act(() => second.root.unmount());
+ });
+
+ // The passenger branch wraps [clip, lanes] in a transformed div that re-renders
+ // on every pointer move. An unstable key there remounts the lanes and drops the
+ // in-flight drag.
+ it("does not remount the lanes while a multi-clip drag slides the formation", () => {
+ const elements = [element("clip-a", TRACK_A), element("clip-b", TRACK_A)];
+ const selectedElementIds = new Set(["clip-a", "clip-b"]);
+ const preview = (draggedPreviewStart: number): MultiDragPreviewInput => ({
+ dragStarted: true,
+ draggedKey: "clip-b",
+ draggedOriginStart: 0,
+ draggedPreviewStart,
+ selectedKeys: selectedElementIds,
+ });
+ const view = renderLanes({
+ elements,
+ animations: ANIMATIONS,
+ expandedClipIds: ["clip-a"],
+ selectedElementIds,
+ multiDragPreview: preview(0.25),
+ });
+
+ const before = ariaControlsTarget(view.host);
+ const beforeLane = before?.querySelector("[data-timeline-property-lane]");
+ expect(before).not.toBeNull();
+ expect(beforeLane).not.toBeNull();
+
+ view.rerender({
+ elements,
+ animations: ANIMATIONS,
+ expandedClipIds: ["clip-a"],
+ selectedElementIds,
+ multiDragPreview: preview(0.75),
+ });
+
+ // Node identity, not just presence: a remount replaces these nodes.
+ expect(ariaControlsTarget(view.host)).toBe(before);
+ expect(before?.querySelector("[data-timeline-property-lane]")).toBe(beforeLane);
+ act(() => view.root.unmount());
+ });
+});
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index d8b622f2cab..58d857762f6 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -1,28 +1,21 @@
-import { type ReactNode } from "react";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { useId } from "react";
import { BeatStrip, BeatBackgroundLines } from "./BeatStrip";
import { TimelineClip } from "./TimelineClip";
import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
import { TimelinePropertyLanes } from "./TimelinePropertyLanes";
import { TimelineTrackHeader } from "./TimelineTrackHeader";
import { resolveTrackKeyframeClip } from "./useTimelineTrackLayout";
-import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
-import type { MusicBeatAnalysis } from "@hyperframes/core/beats";
+import { trackDisplayNumber, trackDisplaySuffix } from "./timelineTrackDisplay";
+import { clipTimingStart } from "../../hooks/gsapShared";
import { getTimelineEditCapabilities, resolveBlockedTimelineEditIntent } from "./timelineEditing";
-import type { TimelineTheme } from "./timelineTheme";
import { CLIP_Y, CLIP_HANDLE_W, TRACK_H, getTimelineRowHeight } from "./timelineLayout";
-import {
- usePlayerStore,
- type TimelineElement,
- type KeyframeCacheEntry,
-} from "../store/playerStore";
-import type { DraggedClipState, ResizingClipState, BlockedClipState } from "./useTimelineClipDrag";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
import {
isMultiDragPassenger,
multiDragPassengerOffsetPx,
type MultiDragPreviewInput,
} from "./timelineMultiDragPreview";
-import type { TrackVisualStyle } from "./timelineIcons";
+import type { TimelineLaneBaseProps } from "./timelineLaneProps";
import type { TimelineEditCallbacks } from "./timelineCallbacks";
import { STUDIO_KEYFRAMES_ENABLED } from "../../components/editor/manualEditingAvailability";
import { trackStudioKeyframeLaneExpand } from "../../telemetry/events";
@@ -30,83 +23,6 @@ import { SPLIT_BOUNDARY_EPSILON_S } from "../../utils/timelineElementSplit";
import { isAudioTimelineElement, isMusicTrack } from "../../utils/timelineInspector";
import { renderClipChildren } from "./timelineClipChildren";
-/**
- * Props shared by the scroll container ({@link TimelineCanvas}) and the lane
- * renderer below. TimelineCanvas passes these straight through via spread, so
- * they are declared once here and both prop types compose from this base — no
- * duplicated prop list.
- */
-export interface TimelineLaneBaseProps {
- pps: number;
- contentOrigin: number;
- contentGutter: number;
- trackContentWidth: number;
- theme: TimelineTheme;
- displayTrackOrder: number[];
- rowHeights: readonly number[];
- trackOrder: number[];
- tracks: [number, TimelineElement[]][];
- trackStyles: Map;
- laneCounts: ReadonlyMap;
- selectedElementId: string | null;
- selectedElementIds: Set;
- hoveredClip: string | null;
- draggedClip: DraggedClipState | null;
- blockedClipRef: React.RefObject;
- suppressClickRef: React.RefObject;
- scrollRef: React.RefObject;
- renderClipContent?: (
- element: TimelineElement,
- style: { clip: string; label: string },
- ) => ReactNode;
- renderClipOverlay?: (element: TimelineElement) => ReactNode;
- onDrillDown?: (element: TimelineElement) => void;
- onSelectElement?: (element: TimelineElement | null) => void;
- setHoveredClip: (key: string | null) => void;
- setShowPopover: (v: boolean) => void;
- setRangeSelection: (v: null) => void;
- setResizingClip: (v: ResizingClipState | null) => void;
- setDraggedClip: (v: DraggedClipState | null) => void;
- setSelectedElementId: (id: string | null) => void;
- syncClipDragAutoScroll: (x: number, y: number) => void;
- shiftClickClipRef: React.RefObject<{
- element: TimelineElement;
- anchorX: number;
- anchorY: number;
- } | null>;
- getPreviewElement: (element: TimelineElement) => TimelineElement;
- getTrackStyle: (tag: string) => TrackVisualStyle;
- keyframeCache?: Map;
- gsapAnimations: Map;
- selectedKeyframes: Set;
- currentTime: number;
- onSeek?: (time: number) => void;
- onSelectSegment?: (elementId: string, target: TimelineKeyframeTarget) => void;
- onClickKeyframe?: (element: TimelineElement, target: TimelineKeyframeTarget) => void;
- onShiftClickKeyframe?: (elementId: string, target: TimelineKeyframeTarget) => void;
- onContextMenuKeyframe?: (
- e: React.MouseEvent,
- elementId: string,
- target: TimelineKeyframeTarget,
- ) => void;
- onMoveKeyframe?: (
- elementId: string,
- keyframe: TimelineKeyframeTarget,
- toClipPercentage: number,
- propertyGroup?: string,
- tweenPercentage?: number,
- animationId?: string,
- ) => Promise;
- onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
- /**
- * Right-click on EMPTY lane space (not on a clip — those preventDefault
- * before this fires — not the gutter/ruler, not below the lanes). `time` is
- * the timeline time (seconds) under the pointer on that lane.
- */
- onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
- beatAnalysis?: MusicBeatAnalysis | null;
-}
-
interface TimelineLanesProps extends TimelineLaneBaseProps {
/** Live-derived by TimelineCanvas from {@link TimelineLaneBaseProps.draggedClip}. */
draggedElement: TimelineElement | null;
@@ -174,6 +90,12 @@ export function TimelineLanes({
onRazorSplit,
onRazorSplitAll,
}: TimelineLanesProps) {
+ // Per-INSTANCE, so two timelines on one page (a mini-timeline in a modal
+ // beside the main one) cannot both mint `...-track-0` and have every caret's
+ // aria-controls resolve to whichever mounted first. React's useId embeds
+ // colons, which are legal in an id and in aria-controls but need escaping in
+ // a CSS `#id` selector, so they come out here and the prefix stays plain.
+ const lanesIdPrefix = `timeline-lanes${useId().replaceAll(":", "")}`;
const expandedClipIds = usePlayerStore((s) => s.expandedClipIds);
const toggleClipExpanded = usePlayerStore((s) => s.toggleClipExpanded);
const toggleClipExpandedTracked = (key: string) => {
@@ -191,6 +113,7 @@ export function TimelineLanes({
// in a virtualizer if editorial workflows ever push very high clip counts.
// fallow-ignore-next-line complexity
displayTrackOrder.map((trackNum, row) => {
+ const displayNumber = trackDisplayNumber(displayTrackOrder, trackNum);
const rowHeight = getTimelineRowHeight(row, rowHeights);
const els = tracks.find(([t]) => t === trackNum)?.[1] ?? [];
const ts = trackStyles.get(trackNum) ?? getTrackStyle("");
@@ -217,6 +140,11 @@ export function TimelineLanes({
const keyframeClipKey = keyframeClip?.key ?? keyframeClip?.id;
const keyframeClipExpanded =
keyframeClipKey != null && expandedClipIds.has(keyframeClipKey);
+ // Minted here because this is the only place that sees BOTH ends of
+ // the disclosure: the caret in the sticky header and the diamond lanes
+ // on the canvas. Keyed by display row, not by `trackNum`, which is a
+ // fractional sort key and would mint ids like `...-0.16666666666666666`.
+ const lanesId = `${lanesIdPrefix}-track-${row}`;
return (
);
- const propertyLanes = showsLanes && (
+ // Mounted for the track's keyframe clip in BOTH disclosure
+ // states, so the header caret's aria-controls resolves while
+ // collapsed too; collapsed just feeds it no animations, so
+ // the wrapper renders empty. The key is stable across a
+ // multi-drag: without it the passenger branch below remounts
+ // this subtree and interrupts the gesture.
+ const propertyLanes = isTrackKeyframeClip && (
,
+): GsapAnimation {
+ return {
+ id,
+ targetSelector: "#clip-1",
+ method: "to",
+ position: 0,
+ duration: 1,
+ properties,
+ };
+}
+
describe("TimelinePropertyLanes", () => {
+ // `{ x, opacity }` is the canonical HyperFrames entrance tween. The parser
+ // classifies it to `undefined` (two groups), which used to erase it from the
+ // lanes entirely — no caret, no reserved row, nothing to edit.
+ it("lanes a mixed-group tween once per group it animates", () => {
+ const lanes = getTimelinePropertyLanes(
+ [ungroupedAnimation("entrance", { x: 0, opacity: 1 })],
+ 0,
+ 1,
+ );
+
+ expect(lanes.map((lane) => lane.group).sort()).toEqual(["position", "visual"]);
+ for (const lane of lanes) {
+ expect(lane.keyframes.map((keyframe) => keyframe.percentage)).toEqual([0, 100]);
+ expect(lane.keyframes.every((keyframe) => keyframe.animationId === "entrance")).toBe(true);
+ }
+ });
+
+ it("lanes a tween whose properties are all unknown as one 'other' lane", () => {
+ const lanes = getTimelinePropertyLanes(
+ [ungroupedAnimation("rounded", { borderRadius: 12, fontSize: 24 })],
+ 0,
+ 1,
+ );
+
+ expect(lanes).toHaveLength(1);
+ expect(lanes[0]?.group).toBe("other");
+ expect(groupLabel("other", lanes[0]!.keyframes[0]!.properties)).toBe("BorderRadius");
+ });
+
+ // An expanded sub-composition child sits on the MASTER timeline at a
+ // host-absolute start while its tweens are parsed from its own file and are
+ // local to it. clipTimingStart is what brings the two into one frame.
+ it("keeps an expanded sub-comp child's lane percentages inside the clip", () => {
+ const child = { start: 16.5, duration: 2, expandedParentStart: 16 };
+ const local = animation("pill-tween", "position", [
+ { percentage: 0, properties: { x: 0 } },
+ { percentage: 100, properties: { x: 100 } },
+ ]);
+ local.position = 0.5;
+ local.resolvedStart = 0.5;
+ local.duration = 2;
+
+ const percentages = getTimelinePropertyLanes(
+ [local],
+ clipTimingStart(child),
+ child.duration,
+ ).flatMap((lane) => lane.keyframes.map((keyframe) => keyframe.percentage));
+
+ expect(percentages).toHaveLength(2);
+ for (const percentage of percentages) {
+ expect(percentage).toBeGreaterThanOrEqual(0);
+ expect(percentage).toBeLessThanOrEqual(100);
+ }
+ // Falsifier: the raw host-absolute start is what used to be passed.
+ expect(
+ getTimelinePropertyLanes([local], child.start, child.duration)[0]?.keyframes[0]?.percentage,
+ ).toBeLessThan(0);
+ });
+
+ it("still lanes a single-group tween exactly once", () => {
+ const lanes = getTimelinePropertyLanes(
+ [animation("position-tween", "position", [{ percentage: 0, properties: { x: 0, y: 0 } }])],
+ 0,
+ 1,
+ );
+
+ expect(lanes.map((lane) => lane.group)).toEqual(["position"]);
+ });
+
+ // A lane can merge several tweens, so an edit routed from it must carry the
+ // clicked keyframe's own animation identity — group matching alone is
+ // ambiguous once two tweens feed the same lane.
+ it("routes a mixed-tween lane edit to the tween that owns the keyframe", () => {
+ const mixed = ungroupedAnimation("entrance", { x: 40, opacity: 1 });
+ const sibling = animation("drift", "position", [
+ { percentage: 0, properties: { x: 0 } },
+ { percentage: 100, properties: { x: 9 } },
+ ]);
+ const lanes = getTimelinePropertyLanes([mixed, sibling], 0, 1);
+ const position = lanes.find((lane) => lane.group === "position");
+
+ expect(
+ resolveTimelineKeyframeTarget(100, position?.keyframes ?? [], [
+ { id: "entrance" },
+ { id: "drift", propertyGroup: "position" },
+ ]),
+ ).toEqual({ animId: "entrance", tweenPct: 100 });
+ });
+
it("returns a position lane with synthesized endpoints for a flat tween", () => {
const lanes = getTimelinePropertyLanes(
[flatAnimation("position-tween", "position", { x: 420 })],
@@ -399,6 +508,68 @@ describe("TimelinePropertyLanes", () => {
act(() => root.unmount());
});
+ // The disclosure caret's aria-controls used to name a div in the STICKY LABEL
+ // COLUMN whose children are all absolutely positioned: it computed to 0x0 and
+ // held no diamonds. The real lanes had no wrapper at all to point at.
+ it("wraps the lanes in the identified element so aria-controls resolves to the diamonds", () => {
+ const animations = [
+ animation("position-tween", "position", [
+ { percentage: 0, properties: { x: 0 } },
+ { percentage: 100, properties: { x: 100 } },
+ ]),
+ animation("visual-tween", "visual", [
+ { percentage: 0, properties: { opacity: 0 } },
+ { percentage: 100, properties: { opacity: 1 } },
+ ]),
+ ];
+ const { host, root } = renderPropertyLanes({ id: "timeline-lanes-track-0", animations });
+ const wrapper = host.querySelector("#timeline-lanes-track-0");
+
+ expect(wrapper).not.toBeNull();
+ expect(wrapper?.querySelectorAll("[data-timeline-property-lane]")).toHaveLength(2);
+ expect(wrapper?.querySelectorAll("button[data-keyframe-percentage]").length).toBeGreaterThan(0);
+ // Load-bearing: a `position: relative` wrapper would become the containing
+ // block for the absolute lanes below and shift every one of them.
+ expect((wrapper as HTMLElement).style.position).toBe("");
+ act(() => root.unmount());
+ });
+
+ // happy-dom has no CSS engine, so measured geometry is always 0x0. The lanes'
+ // own inline offsets are what the component actually computes, so pin those.
+ it("leaves every lane's inline offsets untouched by the wrapper", () => {
+ const animations = [
+ animation("position-tween", "position", [{ percentage: 0, properties: { x: 0 } }]),
+ animation("visual-tween", "visual", [{ percentage: 0, properties: { opacity: 0 } }]),
+ ];
+ const { host, root } = renderPropertyLanes({
+ id: "timeline-lanes-track-0",
+ animations,
+ clipLeftPx: 120,
+ clipWidthPx: 200,
+ });
+
+ const lanes = Array.from(host.querySelectorAll("[data-timeline-property-lane]"));
+ expect(lanes.map((lane) => lane.style.top)).toEqual([
+ `${getTimelineLaneTop(0)}px`,
+ `${getTimelineLaneTop(1)}px`,
+ ]);
+ expect(lanes.map((lane) => lane.style.left)).toEqual(["120px", "120px"]);
+ expect(lanes.map((lane) => lane.style.width)).toEqual(["200px", "200px"]);
+ expect(lanes.map((lane) => lane.style.height)).toEqual([`${LANE_H}px`, `${LANE_H}px`]);
+ act(() => root.unmount());
+ });
+
+ // The wrapper is the aria-controls target in BOTH disclosure states, so a
+ // collapsed layer (no animations reach it) must still resolve the id.
+ it("still renders the identified wrapper when there are no lanes to show", () => {
+ const { host, root } = renderPropertyLanes({ id: "timeline-lanes-track-0", animations: [] });
+
+ const wrapper = host.querySelector("#timeline-lanes-track-0");
+ expect(wrapper).not.toBeNull();
+ expect(wrapper?.querySelectorAll("[data-timeline-property-lane]")).toHaveLength(0);
+ act(() => root.unmount());
+ });
+
it("keeps the collapsed TimelineClipDiamonds positions and callback contract unchanged", () => {
const onClickKeyframe = vi.fn();
const COLLAPSED_IDENTITY = { animationId: "position-tween", propertyGroup: "position" };
@@ -448,3 +619,49 @@ describe("TimelinePropertyLanes", () => {
act(() => root.unmount());
});
});
+
+describe("resolveAnimIdForProperty", () => {
+ /** A legacy mixed tween: the parser leaves propertyGroup undefined for it. */
+ const mixed = {
+ id: "mixed-1",
+ targetSelector: "#box",
+ method: "to",
+ position: 0,
+ properties: {},
+ keyframes: {
+ keyframes: [
+ { percentage: 0, properties: { x: 0, opacity: 0 } },
+ { percentage: 100, properties: { x: 40, opacity: 1 } },
+ ],
+ },
+ } as unknown as GsapAnimation;
+
+ it("routes both groups of a mixed tween to that tween, not the fallback", () => {
+ expect(mixed.propertyGroup).toBeUndefined();
+
+ expect(resolveAnimIdForProperty("x", [mixed], "fallback")).toBe("mixed-1");
+ expect(resolveAnimIdForProperty("opacity", [mixed], "fallback")).toBe("mixed-1");
+ });
+
+ it("falls back only when no tween animates the property's group", () => {
+ expect(resolveAnimIdForProperty("rotation", [mixed], "fallback")).toBe("fallback");
+ expect(resolveAnimIdForProperty("rotation", [mixed], undefined)).toBe("");
+ });
+
+ it("prefers a single-group tween that owns the lane", () => {
+ const opacityOnly = {
+ ...mixed,
+ id: "opacity-1",
+ propertyGroup: "visual",
+ keyframes: {
+ keyframes: [
+ { percentage: 0, properties: { opacity: 0 } },
+ { percentage: 100, properties: { opacity: 1 } },
+ ],
+ },
+ } as unknown as GsapAnimation;
+
+ expect(resolveAnimIdForProperty("opacity", [opacityOnly, mixed], "fallback")).toBe("opacity-1");
+ expect(resolveAnimIdForProperty("x", [opacityOnly, mixed], "fallback")).toBe("mixed-1");
+ });
+});
diff --git a/packages/studio/src/player/components/TimelinePropertyLanes.tsx b/packages/studio/src/player/components/TimelinePropertyLanes.tsx
index 018aa4f8a06..641d5eba502 100644
--- a/packages/studio/src/player/components/TimelinePropertyLanes.tsx
+++ b/packages/studio/src/player/components/TimelinePropertyLanes.tsx
@@ -11,6 +11,12 @@ import { LANE_H, getTimelineLaneTop } from "./timelineLayout";
import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
export interface TimelinePropertyLanesProps {
+ /**
+ * Id of the wrapper below, so the layer's disclosure caret can point
+ * `aria-controls` at the lanes a sighted user sees it reveal. Minted by
+ * TimelineLanes, which owns both this subtree and the caret's.
+ */
+ id?: string;
animations: readonly GsapAnimation[];
clipStart: number;
clipDuration: number;
@@ -29,11 +35,25 @@ export interface TimelinePropertyLanesProps {
suppressClickRef?: RefObject;
}
+/**
+ * Keys that ride along in a tween's property bag without being animated: a
+ * transform modifier, Studio's internal endpoint marker, and GSAP's reserved
+ * `data`. Same exclusion list the parser's classifyTweenPropertyGroup applies —
+ * without it `{ x, transformOrigin }` would draw a spurious "Other" lane.
+ */
+const NON_ANIMATED_PROPERTIES = new Set(["transformOrigin", "_auto", "data"]);
+
+function isAnimatedProperty(property: string): boolean {
+ return !NON_ANIMATED_PROPERTIES.has(property);
+}
+
function hasGroupProperty(
properties: Record,
group: PropertyGroupName,
): boolean {
- return Object.keys(properties).some((property) => classifyPropertyGroup(property) === group);
+ return Object.keys(properties).some(
+ (property) => isAnimatedProperty(property) && classifyPropertyGroup(property) === group,
+ );
}
/** The tween's editable keyframes: its real keyframes, or the start→end pair
@@ -42,19 +62,63 @@ function animationKeyframes(animation: GsapAnimation) {
return animation.keyframes?.keyframes ?? synthesizeFlatTweenKeyframes(animation)?.keyframes ?? [];
}
-/** A tween contributes a property lane when it has a group and at least one
- * editable keyframe (real or synthesized). */
+/**
+ * Every property group a tween draws a lane for, classified PER PROPERTY.
+ * `animation.propertyGroup` is the parser's whole-tween verdict and is
+ * `undefined` for anything spanning more than one group — but `{ x, opacity }`
+ * is the canonical HyperFrames entrance tween, and reading that verdict gave it
+ * no caret, no reserved row and no diamonds. classifyPropertyGroup is total, so
+ * an unrecognised property still lands in "other" rather than vanishing.
+ *
+ * Single owner: the rendered lanes (sourceGroups) and the reserved row heights
+ * (computeLaneCounts) both count groups through here, or they drift.
+ */
+export function animationLaneGroups(animation: GsapAnimation): PropertyGroupName[] {
+ const groups = new Set();
+ for (const keyframe of animationKeyframes(animation)) {
+ for (const property of Object.keys(keyframe.properties)) {
+ if (isAnimatedProperty(property)) groups.add(classifyPropertyGroup(property));
+ }
+ }
+ return Array.from(groups);
+}
+
+/**
+ * Which tween a panel edit to `prop` belongs to.
+ *
+ * Matches on the groups the tween's KEYFRAMES animate, not on the parser's
+ * whole-tween `propertyGroup` verdict: that field is undefined for a legacy
+ * mixed tween such as `{ x, opacity }`, so matching it dropped every such
+ * tween and sent the edit to the selection's default animation instead, which
+ * is a different tween than the lane the user is looking at.
+ * {@link animationLaneGroups} is the single owner the rendered lanes count
+ * groups through, so resolving here through the same helper keeps the panel
+ * and the lanes on one answer.
+ */
+export function resolveAnimIdForProperty(
+ prop: string,
+ animations: readonly GsapAnimation[] | undefined,
+ fallbackAnimId: string | undefined,
+): string {
+ const group = classifyPropertyGroup(prop);
+ const groupAnim = animations?.find((a) => animationLaneGroups(a).includes(group));
+ return groupAnim?.id ?? fallbackAnimId ?? "";
+}
+
+/** A tween contributes a property lane when it animates at least one property
+ * on at least one editable keyframe (real or synthesized). */
export function animationContributesLane(animation: GsapAnimation): boolean {
- return !!animation.propertyGroup && animationKeyframes(animation).length > 0;
+ return animationLaneGroups(animation).length > 0;
}
function sourceGroups(animations: readonly GsapAnimation[]) {
const groups = new Map();
for (const animation of animations) {
- if (!animation.propertyGroup || !animationContributesLane(animation)) continue;
- const groupAnimations = groups.get(animation.propertyGroup) ?? [];
- groupAnimations.push(animation);
- groups.set(animation.propertyGroup, groupAnimations);
+ for (const group of animationLaneGroups(animation)) {
+ const groupAnimations = groups.get(group) ?? [];
+ groupAnimations.push(animation);
+ groups.set(group, groupAnimations);
+ }
}
return groups;
}
@@ -112,6 +176,7 @@ export function getTimelinePropertyLanes(
}
export function TimelinePropertyLanes({
+ id,
animations,
clipStart,
clipDuration,
@@ -148,9 +213,13 @@ export function TimelinePropertyLanes({
[lanes],
);
- if (laneData.length === 0) return null;
+ // One STATIC wrapper, never `relative`: a static box establishes no containing
+ // block, so every absolutely-positioned lane below still resolves against the
+ // track-content div and the rendered geometry is byte-identical to the bare
+ // fragment this replaced. It is also rendered when there are no lanes at all
+ // (collapsed layer), so `id` stays resolvable in both disclosure states.
return (
- <>
+
{laneData.map(({ group, keyframesData }, laneIndex) => (
);
}
diff --git a/packages/studio/src/player/components/TimelineTrackHeader.test.tsx b/packages/studio/src/player/components/TimelineTrackHeader.test.tsx
index 46d4372b534..4a0b11cd0c3 100644
--- a/packages/studio/src/player/components/TimelineTrackHeader.test.tsx
+++ b/packages/studio/src/player/components/TimelineTrackHeader.test.tsx
@@ -60,12 +60,14 @@ const OPACITY = animation("opacity-tween", "visual", [
]);
interface RenderHeaderOptions {
+ keyframeClip?: TimelineElement;
animations?: GsapAnimation[];
clipCount?: number;
currentTime?: number;
expanded?: boolean;
onSeek?: (time: number) => void;
onTogglePropertyGroupKeyframe?: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+ onToggleTrackHidden?: TimelineEditCallbacks["onToggleTrackHidden"];
}
function renderHeader(options: RenderHeaderOptions = {}): {
@@ -80,10 +82,14 @@ function renderHeader(options: RenderHeaderOptions = {}): {
act(() => {
root.render(
('button[aria-label="Next Position keyframe"]')
+ ?.disabled,
+ ).toBe(false);
+ act(() => view.root.unmount());
+ });
+
// The header shows one clip's lanes, so how many clips the track holds is
// otherwise invisible from the label column. A single-clip track stays silent.
it("shows the track's clip count only once the track holds more than one clip", () => {
@@ -125,10 +178,27 @@ describe("TimelineTrackHeader", () => {
// in every disclosure state — a hover-gated eye is unusable by keyboard.
it("keeps the visibility eye mounted whether the layer is expanded or collapsed", () => {
const view = renderHeader({ expanded: true });
- expect(view.host.querySelector('button[aria-label="Hide track 0"]')).not.toBeNull();
+ expect(view.host.querySelector('button[aria-label="Hide track 1"]')).not.toBeNull();
view.rerender({ expanded: false });
- expect(view.host.querySelector('button[aria-label="Hide track 0"]')).not.toBeNull();
+ expect(view.host.querySelector('button[aria-label="Hide track 1"]')).not.toBeNull();
+ act(() => view.root.unmount());
+ });
+
+ // trackNumber is a fractional z-order sort key, so building the label from it
+ // made screen readers announce "Hide track 0.16666666666666666". The display
+ // number is label-only; the toggle still routes by the real key.
+ it("announces the display track number but toggles with the real fractional key", () => {
+ const onToggleTrackHidden = vi.fn();
+ const view = renderHeader({ onToggleTrackHidden });
+ const eye = view.host.querySelector('button[aria-label="Hide track 1"]');
+
+ expect(eye).not.toBeNull();
+ expect(eye?.title).toBe("Hide track 1");
+ expect(view.host.innerHTML).not.toContain("0.16666666666666666");
+
+ act(() => eye?.click());
+ expect(onToggleTrackHidden).toHaveBeenCalledWith(1 / 6, true);
act(() => view.root.unmount());
});
diff --git a/packages/studio/src/player/components/TimelineTrackHeader.tsx b/packages/studio/src/player/components/TimelineTrackHeader.tsx
index 09062978999..f3cc603ffb4 100644
--- a/packages/studio/src/player/components/TimelineTrackHeader.tsx
+++ b/packages/studio/src/player/components/TimelineTrackHeader.tsx
@@ -4,6 +4,7 @@ import { Music } from "../../icons/SystemIcons";
import type { TimelineElement } from "../store/playerStore";
import type { TimelineEditCallbacks } from "./timelineCallbacks";
import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
+import { clipTimingStart } from "../../hooks/gsapShared";
import { LayerDisclosureRow } from "./LayerDisclosureRow";
import { TrackClipCount } from "./TrackClipCount";
import { LABEL_COL_W, LANE_H, getTimelineLaneTop } from "./timelineLayout";
@@ -14,10 +15,21 @@ import {
type TimelinePropertyLane,
} from "./trackHeaderLaneState";
import { valueReadout } from "./trackHeaderLaneValues";
+import { trackDisplaySuffix } from "./timelineTrackDisplay";
interface TimelineTrackHeaderProps {
+ /** The track's real key: a FRACTIONAL z-order sort value. Routes callbacks;
+ * never shown or announced. */
trackNumber: number;
+ /** The track's 1-based position in the rendered order: the only number safe
+ * to put in a label. Announcing `trackNumber` read out "track
+ * 0.16666666666666666". Null when the key has no row, which drops the number
+ * from the label rather than inventing one (see trackDisplayNumber). */
+ trackDisplayNumber: number | null;
trackLabel: string;
+ /** Id of the canvas-side lanes element the disclosure caret expands. Minted by
+ * TimelineLanes, which is the one place that sees both subtrees. */
+ lanesId: string;
contentOrigin: number;
/** The track's active keyframe clip (selected, else primary) — the one whose
* disclosure + property rows this header shows, whether expanded or not. */
@@ -39,16 +51,21 @@ interface TimelineTrackHeaderProps {
function VisibilityButton({
hidden,
trackNumber,
+ trackDisplayNumber,
visible,
onToggle,
}: {
hidden: boolean;
trackNumber: number;
+ trackDisplayNumber: number | null;
visible: boolean;
onToggle: TimelineEditCallbacks["onToggleTrackHidden"];
}) {
if (!visible) return
- {/* Always mounted so the caret's aria-controls resolves in both states. */}
-
- {isExpanded &&
- lanes.map((lane, laneIndex) => (
-
- ))}
-
;
+ laneCounts: ReadonlyMap;
+ selectedElementId: string | null;
+ selectedElementIds: Set;
+ hoveredClip: string | null;
+ draggedClip: DraggedClipState | null;
+ blockedClipRef: React.RefObject;
+ suppressClickRef: React.RefObject;
+ scrollRef: React.RefObject;
+ renderClipContent?: (
+ element: TimelineElement,
+ style: { clip: string; label: string },
+ ) => ReactNode;
+ renderClipOverlay?: (element: TimelineElement) => ReactNode;
+ onDrillDown?: (element: TimelineElement) => void;
+ onSelectElement?: (element: TimelineElement | null) => void;
+ setHoveredClip: (key: string | null) => void;
+ setShowPopover: (v: boolean) => void;
+ setRangeSelection: (v: null) => void;
+ setResizingClip: (v: ResizingClipState | null) => void;
+ setDraggedClip: (v: DraggedClipState | null) => void;
+ setSelectedElementId: (id: string | null) => void;
+ syncClipDragAutoScroll: (x: number, y: number) => void;
+ shiftClickClipRef: React.RefObject<{
+ element: TimelineElement;
+ anchorX: number;
+ anchorY: number;
+ } | null>;
+ getPreviewElement: (element: TimelineElement) => TimelineElement;
+ getTrackStyle: (tag: string) => TrackVisualStyle;
+ keyframeCache?: Map;
+ gsapAnimations: Map;
+ selectedKeyframes: Set;
+ currentTime: number;
+ onSeek?: (time: number) => void;
+ onSelectSegment?: (elementId: string, target: TimelineKeyframeTarget) => void;
+ onClickKeyframe?: (element: TimelineElement, target: TimelineKeyframeTarget) => void;
+ onShiftClickKeyframe?: (elementId: string, target: TimelineKeyframeTarget) => void;
+ onContextMenuKeyframe?: (
+ e: React.MouseEvent,
+ elementId: string,
+ target: TimelineKeyframeTarget,
+ ) => void;
+ onMoveKeyframe?: (
+ elementId: string,
+ keyframe: TimelineKeyframeTarget,
+ toClipPercentage: number,
+ propertyGroup?: string,
+ tweenPercentage?: number,
+ animationId?: string,
+ ) => Promise;
+ onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
+ /**
+ * Right-click on EMPTY lane space (not on a clip — those preventDefault
+ * before this fires — not the gutter/ruler, not below the lanes). `time` is
+ * the timeline time (seconds) under the pointer on that lane.
+ */
+ onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
+ beatAnalysis?: MusicBeatAnalysis | null;
+}
diff --git a/packages/studio/src/player/components/timelineTrackDisplay.test.ts b/packages/studio/src/player/components/timelineTrackDisplay.test.ts
new file mode 100644
index 00000000000..7c7fe3c3756
--- /dev/null
+++ b/packages/studio/src/player/components/timelineTrackDisplay.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { timelineTrackOrder, trackDisplayNumber, trackDisplaySuffix } from "./timelineTrackDisplay";
+
+describe("timelineTrackOrder", () => {
+ it("is the ascending distinct key order, fractional sub-comp keys included", () => {
+ const elements = [{ track: 1 }, { track: 0 }, { track: 1 / 6 }, { track: 1 }];
+
+ expect(timelineTrackOrder(elements)).toEqual([0, 1 / 6, 1]);
+ });
+});
+
+describe("trackDisplayNumber", () => {
+ it("is the key's 1-based row, not the fractional key itself", () => {
+ const order = timelineTrackOrder([{ track: 0 }, { track: 1 / 6 }, { track: 1 }]);
+
+ expect(trackDisplayNumber(order, 1 / 6)).toBe(2);
+ expect(trackDisplayNumber(order, 1)).toBe(3);
+ });
+
+ it("is null for a key with no row rather than a plausible-looking one", () => {
+ // The old end-row fallback announced "track 4" for a track the user cannot
+ // see at row 4, and nothing upstream could tell that apart from a real row.
+ expect(trackDisplayNumber([0, 1, 2], 7)).toBeNull();
+ });
+});
+
+describe("trackDisplaySuffix", () => {
+ it("names the row when there is one", () => {
+ expect(`Hide track${trackDisplaySuffix(3)}`).toBe("Hide track 3");
+ });
+
+ it("drops the number entirely when there is no row", () => {
+ expect(`Hide track${trackDisplaySuffix(null)}`).toBe("Hide track");
+ });
+});
diff --git a/packages/studio/src/player/components/timelineTrackDisplay.ts b/packages/studio/src/player/components/timelineTrackDisplay.ts
new file mode 100644
index 00000000000..5e1af3f6c1d
--- /dev/null
+++ b/packages/studio/src/player/components/timelineTrackDisplay.ts
@@ -0,0 +1,38 @@
+/**
+ * The one owner of "what track number does the user see".
+ *
+ * `TimelineElement.track` is a z-order SORT key, not a row number: an expanded
+ * sub-composition child gets a synthesized fractional key (`host.track + n /
+ * (siblings + 2)`, see `useExpandedTimelineElements`), so putting it in a string
+ * announces "Hide track 0.16666666666666666". Every user-visible track number,
+ * whether it is rendered by a component or baked into an undo-history label,
+ * routes through here; the raw key stays in callbacks and lookups only.
+ */
+
+/** Ascending distinct track keys, the row order the timeline renders in. */
+export function timelineTrackOrder(elements: readonly { track: number }[]): number[] {
+ return [...new Set(elements.map((element) => element.track))].sort((a, b) => a - b);
+}
+
+/**
+ * A track key's 1-based display row, or null when the key is not in
+ * `trackOrder` at all.
+ *
+ * Both callers build `trackOrder` from the same elements the key came from, so
+ * null is unreachable by construction today. It is null rather than a number
+ * because the only numbers available to return (the end row, the last row) are
+ * indistinguishable from a real answer: a label would announce a row the user
+ * can see is wrong, and nothing upstream would ever learn it had guessed.
+ */
+export function trackDisplayNumber(trackOrder: readonly number[], track: number): number | null {
+ const row = trackOrder.indexOf(track);
+ return row < 0 ? null : row + 1;
+}
+
+/**
+ * The `" 3"` in `Hide track 3`, empty when there is no display row to name.
+ * Announcing "Hide track" is thin; announcing an invented row is wrong.
+ */
+export function trackDisplaySuffix(displayNumber: number | null): string {
+ return displayNumber === null ? "" : ` ${displayNumber}`;
+}
diff --git a/packages/studio/src/player/components/useTimelineRangeSelection.ts b/packages/studio/src/player/components/useTimelineRangeSelection.ts
index 1a98e251c67..c4cd930460b 100644
--- a/packages/studio/src/player/components/useTimelineRangeSelection.ts
+++ b/packages/studio/src/player/components/useTimelineRangeSelection.ts
@@ -268,6 +268,11 @@ export function useTimelineRangeSelection({
if (!point || !scrollRect || isTimelineRulerPress(e.clientY, scrollRect.top)) {
isDragging.current = true;
setIsScrubbing(true);
+ // Seed the pending coordinate so a press with no pointermove still
+ // replays THIS x on pointerup. `updateScrubDrag` is the only other
+ // writer, so without this a plain click settles on the ref's initial
+ // 0 and clamps the playhead back to t=0.
+ pendingClientXRef.current = e.clientX;
seekFromX(e.clientX);
return;
}
diff --git a/packages/studio/src/player/components/useTimelineRangeSelectionScrub.test.tsx b/packages/studio/src/player/components/useTimelineRangeSelectionScrub.test.tsx
new file mode 100644
index 00000000000..61c93c6a404
--- /dev/null
+++ b/packages/studio/src/player/components/useTimelineRangeSelectionScrub.test.tsx
@@ -0,0 +1,127 @@
+// @vitest-environment happy-dom
+
+// Regression guard for the ruler-click seek. `handlePointerUp` replays
+// `pendingClientXRef`, which only `updateScrubDrag` (pointermove) used to write,
+// so a press with no move settled on the ref's initial 0 and clamped the
+// playhead to t=0 — silently discarding the correct pointerdown seek.
+import React, { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mountReactHarness } from "../../hooks/domSelectionTestHarness";
+import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+/** Scroll container top; a press within RULER_H of this counts as a ruler press. */
+const SCROLL_TOP = 100;
+/** Comfortably inside the ruler band (RULER_H is 28 at time of writing). */
+const RULER_Y = SCROLL_TOP + 4;
+
+type Handlers = ReturnType;
+
+function makeScrollEl(): HTMLDivElement {
+ const el = document.createElement("div");
+ el.getBoundingClientRect = () =>
+ ({ top: SCROLL_TOP, left: 0, width: 1000, height: 400 }) as DOMRect;
+ return el;
+}
+
+function makePointerEvent(clientX: number, clientY: number): React.PointerEvent {
+ const currentTarget = document.createElement("div");
+ currentTarget.setPointerCapture = vi.fn();
+ return {
+ button: 0,
+ shiftKey: false,
+ metaKey: false,
+ ctrlKey: false,
+ pointerId: 1,
+ clientX,
+ clientY,
+ target: document.createElement("div"),
+ currentTarget,
+ } as unknown as React.PointerEvent;
+}
+
+const roots: Array<{ unmount: () => void }> = [];
+
+afterEach(() => {
+ for (const root of roots.splice(0)) act(() => root.unmount());
+});
+
+function setup(): { handlers: () => Handlers; seekFromX: ReturnType } {
+ const seekFromX = vi.fn();
+ const scrollEl = makeScrollEl();
+ let latest: Handlers | null = null;
+
+ // Hoisted so they survive re-renders. The hook mutates `isDragging.current`
+ // across the press, and a fresh object per render would reset it to false.
+ const scrollRef = { current: scrollEl };
+ const ppsRef = { current: 25 };
+ const dragScrollRaf = { current: 0 };
+ const isDragging = { current: false };
+ const elementsRef = { current: [] };
+ const trackOrderRef = { current: [] };
+ const rowHeightsRef = { current: [] };
+
+ function Probe(): null {
+ latest = useTimelineRangeSelection({
+ scrollRef,
+ ppsRef,
+ effectiveDuration: 30,
+ pps: 25,
+ seekFromX,
+ autoScrollDuringDrag: vi.fn(),
+ dragScrollRaf,
+ isDragging,
+ setShowPopover: vi.fn(),
+ elementsRef,
+ trackOrderRef,
+ rowHeightsRef,
+ contentOrigin: 0,
+ });
+ return null;
+ }
+
+ roots.push(mountReactHarness(([["clip-1", [mixed]]]);
+ usePlayerStore.setState({ expandedClipIds: new Set(["clip-1"]) });
+
+ let layout: ReturnType | undefined;
+ function Probe() {
+ layout = useTimelineTrackLayout(elements, animations, null, new Set());
+ return null;
+ }
+
+ const root = createRoot(document.createElement("div"));
+ act(() => root.render(React.createElement(Probe)));
+
+ expect(getTimelinePropertyLanes([mixed], 0, 1)).toHaveLength(2);
+ expect(layout?.laneCounts.get("clip-1")).toBe(2);
+ expect(layout?.rowHeights).toEqual([TRACK_H + 2 * LANE_H]);
+ act(() => root.unmount());
+ });
});
diff --git a/packages/studio/src/player/components/useTimelineTrackLayout.ts b/packages/studio/src/player/components/useTimelineTrackLayout.ts
index 4aad5a87611..677831fb5be 100644
--- a/packages/studio/src/player/components/useTimelineTrackLayout.ts
+++ b/packages/studio/src/player/components/useTimelineTrackLayout.ts
@@ -1,6 +1,6 @@
import { useMemo, useRef } from "react";
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { animationContributesLane } from "./TimelinePropertyLanes";
+import { animationLaneGroups } from "./TimelinePropertyLanes";
import { usePlayerStore, type TimelineElement } from "../store/playerStore";
import { STUDIO_KEYFRAMES_ENABLED } from "../../components/editor/manualEditingAvailability";
import type { DraggedClipState } from "./timelineClipDragTypes";
@@ -56,9 +56,9 @@ function computeLaneCounts(
const clipId = element.key ?? element.id;
const propertyGroups = new Set();
for (const animation of gsapAnimations.get(clipId) ?? []) {
- if (animation.propertyGroup && animationContributesLane(animation)) {
- propertyGroups.add(animation.propertyGroup);
- }
+ // Same helper the rendered lanes count through, so a reserved row and a
+ // drawn lane can never disagree.
+ for (const group of animationLaneGroups(animation)) propertyGroups.add(group);
}
laneCounts.set(clipId, propertyGroups.size);
}
diff --git a/packages/studio/src/player/hooks/useExpandedTimelineElements.test.ts b/packages/studio/src/player/hooks/useExpandedTimelineElements.test.ts
index 12adcd2cd35..f7100997b87 100644
--- a/packages/studio/src/player/hooks/useExpandedTimelineElements.test.ts
+++ b/packages/studio/src/player/hooks/useExpandedTimelineElements.test.ts
@@ -143,6 +143,51 @@ describe("buildExpandedElements", () => {
expect(child.sourceFile).toBe("c.html"); // C's file, not b.html or a.html
});
+ it("keeps the middle host's row when drilling two levels deep", () => {
+ // A embeds B; C lives in B. Drilling into B must leave BOTH host rows
+ // standing: sparing only the top-level one drops B's row, and its keyframe
+ // lane goes with it because diamonds render per row.
+ const elements = [
+ el({ id: "A", domId: "A", start: 10, duration: 8, compositionSrc: "a.html" }),
+ el({ id: "B", domId: "B", start: 12, duration: 4, track: 1, compositionSrc: "b.html" }),
+ ];
+ const manifest = [
+ clip({ id: "A", start: 10, duration: 8, compositionSrc: "a.html" }),
+ clip({ id: "B", start: 12, duration: 4, compositionSrc: "b.html" }),
+ clip({ id: "C", start: 13, duration: 2 }),
+ ];
+ const parentMap = new Map([
+ ["B", "A"],
+ ["C", "B"],
+ ]);
+
+ const out = buildExpandedElements(elements, manifest, parentMap, "A", "B");
+ const rows = out.map((e) => e.domId ?? e.id);
+ expect(rows).toContain("B");
+ // The child sits under its own host, not under the top-level row.
+ expect(rows.indexOf("C")).toBeGreaterThan(rows.indexOf("B"));
+ });
+
+ it("still drills a host that exists only in the manifest, without a row for it", () => {
+ // Same shape, but B has no store element, so there is no row to spare. The
+ // children stay anchored to the top-level row rather than vanishing.
+ const elements = [
+ el({ id: "A", domId: "A", start: 10, duration: 8, compositionSrc: "a.html" }),
+ ];
+ const manifest = [
+ clip({ id: "A", start: 10, duration: 8, compositionSrc: "a.html" }),
+ clip({ id: "B", start: 12, duration: 4, compositionSrc: "b.html" }),
+ clip({ id: "C", start: 13, duration: 2 }),
+ ];
+ const parentMap = new Map([
+ ["B", "A"],
+ ["C", "B"],
+ ]);
+
+ const out = buildExpandedElements(elements, manifest, parentMap, "A", "B");
+ expect(out.map((e) => e.domId ?? e.id)).toEqual(["A", "C"]);
+ });
+
// Regression: an expanded child must share one identity (`key`) with the flat
// store element for the same DOM id. Before the fix the child key fell back to
// the colon form (`index.html:eyebrow:N`) while the store/selection used the
@@ -240,8 +285,112 @@ describe("buildExpandedElements", () => {
expect(pills[0]!.duration).toBe(6);
expect(pills[0]!.sourceFile).toBe("scene.html");
expect(pills.map((pill) => pill.stackingContextId)).toEqual(["css:0.0", "css:0.1", "css:0.1"]);
- // The host row is replaced by its children.
- expect(out.some((e) => e.domId === "scene-host")).toBe(false);
+ // The host row survives the expansion; its children are added under it.
+ expect(out.some((e) => e.id === "scene-host")).toBe(true);
+ });
+
+ // fallow-ignore-next-line code-duplication
+ it("keeps the host row and appends its children directly below it", () => {
+ const elements = [
+ el({
+ id: "s3",
+ domId: "s3",
+ key: "index.html#s3",
+ start: 16,
+ duration: 7,
+ compositionSrc: "stats.html",
+ }),
+ el({ id: "outro", start: 23, duration: 3, track: 1 }),
+ ];
+ const manifest = [
+ clip({ id: "s3", start: 16, duration: 7, compositionSrc: "stats.html" }),
+ clip({ id: "stat-1", start: 16.5, duration: 5 }),
+ clip({ id: "stat-2", start: 16.9, duration: 5 }),
+ ];
+ const parentMap = new Map([
+ ["stat-1", "s3"],
+ ["stat-2", "s3"],
+ ]);
+
+ const out = buildExpandedElements(elements, manifest, parentMap, "s3", "s3");
+
+ const hostIndex = out.findIndex((e) => e.id === "s3");
+ expect(hostIndex).toBeGreaterThanOrEqual(0);
+ // Host row untouched (same key → same keyframe lane), children nested under it.
+ expect(out[hostIndex]!.key).toBe("index.html#s3");
+ expect(out[hostIndex]!.track).toBe(0);
+ expect(out[hostIndex + 1]!.domId).toBe("stat-1");
+ expect(out[hostIndex + 2]!.domId).toBe("stat-2");
+ // Exactly one more row than the old substitution behaviour (host + 2 children + outro).
+ expect(out).toHaveLength(4);
+ });
+
+ it("keeps the host row present at every playhead position (keyframe lane repro)", () => {
+ // Live repro with no drag at all: seek 0 gave 3 diamonds, seek 7.68 gave 0,
+ // seek 0.2 gave 3. Diamonds render per row from keyframeCache.get(elementKey),
+ // so the whole lane went with the host row whenever the paused drill-in
+ // substituted it for its children.
+ const elements = [
+ el({ id: "scene", domId: "scene", key: "index.html#scene", start: 0, duration: 12 }),
+ ];
+ const manifest = [
+ clip({ id: "scene", start: 0, duration: 12, compositionSrc: "scene.html" }),
+ clip({ id: "headline", start: 0, duration: 12 }),
+ ];
+ const parentMap = new Map([["headline", "scene"]]);
+
+ for (const currentTime of [0, 7.68, 0.2]) {
+ const rawId = resolveTimelineExpansionRawId({
+ selectedElementId: null,
+ isPlaying: false,
+ currentTime,
+ manifest,
+ parentMap,
+ });
+ const rows = rawId
+ ? buildExpandedElements(elements, manifest, parentMap, rawId, rawId)
+ : elements;
+ expect(rows.map((row) => row.key)).toContain("index.html#scene");
+ }
+ });
+
+ // Regression: DOM-only children were synthesized against the TOP-LEVEL element
+ // instead of the sub-comp host they actually live in, so every child row read
+ // the whole top-level window rather than its host's.
+ it("spans DOM-only children over their nested host's window, not the top-level one", () => {
+ const elements = [
+ el({ id: "scene-host", start: 0, duration: 20, compositionSrc: "scene.html" }),
+ ];
+ const manifest = [
+ clip({ id: "scene-host", start: 0, duration: 20, compositionSrc: "scene.html" }),
+ clip({ id: "sub-host", start: 5, duration: 6, compositionSrc: "sub.html" }),
+ ];
+ const parentMap = new Map([
+ ["sub-host", "scene-host"],
+ ["pill-1", "sub-host"],
+ ]);
+ const domClipChildren = [
+ {
+ id: "pill-1",
+ parentId: "sub-host",
+ hostId: "sub-host",
+ label: "pill-1",
+ stackingContextId: "css:0.0",
+ },
+ ];
+
+ const out = buildExpandedElements(
+ elements,
+ manifest,
+ parentMap,
+ "scene-host",
+ "sub-host",
+ domClipChildren,
+ );
+ const pill = out.find((e) => e.domId === "pill-1")!;
+ expect(pill.start).toBe(5);
+ expect(pill.duration).toBe(6);
+ expect(pill.sourceFile).toBe("sub.html");
});
});
diff --git a/packages/studio/src/player/hooks/useExpandedTimelineElements.ts b/packages/studio/src/player/hooks/useExpandedTimelineElements.ts
index 7ce6c5d6617..8a1c95e5856 100644
--- a/packages/studio/src/player/hooks/useExpandedTimelineElements.ts
+++ b/packages/studio/src/player/hooks/useExpandedTimelineElements.ts
@@ -209,7 +209,13 @@ function buildChildElements(
function domSiblingClips(
domClipChildren: DomClipChild[],
siblingParentId: string,
- host: TimelineElement,
+ host: {
+ id: string | null;
+ start: number;
+ duration: number;
+ track: number;
+ compositionSrc?: string | null;
+ },
): ClipManifestClip[] {
return domClipChildren
.filter((c) => c.parentId === siblingParentId)
@@ -243,20 +249,23 @@ export function buildExpandedElements(
const topLevelElement = elements.find((el) => el.id === topLevelId || el.domId === topLevelId);
if (!topLevelElement) return filterToTopLevel(elements, parentMap);
+ // The sub-comp host the children actually live in: top-level host for 1-level
+ // nesting, a nested host for deeper nesting. Its start/file anchor edits.
+ const parentHost = manifest.find((c) => c.id === siblingParentId);
+
// Prefer real manifest children; fall back to DOM-only sub-comp children
// (groups/pills) that have no data-start and thus never enter the manifest.
+ // Those are synthesized against the host they actually live in, not the
+ // top-level element, or every child row reads the whole top-level window.
const siblings = (() => {
const fromManifest = manifest.filter(
(c) => c.id != null && parentMap.get(c.id) === siblingParentId,
);
if (fromManifest.length > 0) return fromManifest;
- return domSiblingClips(domClipChildren, siblingParentId, topLevelElement);
+ return domSiblingClips(domClipChildren, siblingParentId, parentHost ?? topLevelElement);
})();
if (siblings.length === 0) return filterToTopLevel(elements, parentMap);
- // The sub-comp host the children actually live in: top-level host for 1-level
- // nesting, a nested host for deeper nesting. Its start/file anchor edits.
- const parentHost = manifest.find((c) => c.id === siblingParentId);
const editBasis = {
start: parentHost?.start ?? topLevelElement.start,
sourceFile: parentHost?.compositionSrc ?? topLevelElement.compositionSrc ?? undefined,
@@ -275,9 +284,39 @@ export function buildExpandedElements(
);
if (expanded.length === 0) return filterToTopLevel(elements, parentMap);
+ // Every host between the drilled one and the top level owns a row, so the
+ // drill has to spare all of them, not just the top. A middle host is still a
+ // host: dropping its row drops its keyframe lane with it.
+ const drillPath = new Set();
+ for (let cursor: string | undefined = siblingParentId; cursor; ) {
+ if (drillPath.has(cursor)) break;
+ drillPath.add(cursor);
+ if (cursor === topLevelId) break;
+ cursor = parentMap.get(cursor);
+ }
+ // Children hang under the DEEPEST host on that path, so anchor them there
+ // when it has a row of its own and fall back to the top-level row when it
+ // does not (a host that lives only in the manifest never had one).
+ const anchorsChildren = (el: TimelineElement): boolean =>
+ drillPath.has(siblingParentId) && elements.some((e) => (e.domId ?? e.id) === siblingParentId)
+ ? (el.domId ?? el.id) === siblingParentId
+ : (el.key ?? el.id) === parentKey;
+
+ // ADDITIVE drill-in: the host row stays and its children are appended under
+ // it. Expansion is also triggered by the playhead alone (paused auto-expand),
+ // so substituting the host row made it vanish on an ordinary seek, and with
+ // it the host's keyframe lane, since diamonds render per row from
+ // `keyframeCache.get(elementKey)`. The synthetic fractional lanes above sit
+ // strictly between the host's lane and the next integer, so the children have
+ // their own rows without the host having to give up its own.
return elements
- .filter((el) => (el.key ?? el.id) === parentKey || !parentMap.has(el.domId ?? el.id))
- .flatMap((el) => ((el.key ?? el.id) === parentKey ? expanded : [el]));
+ .filter(
+ (el) =>
+ (el.key ?? el.id) === parentKey ||
+ drillPath.has(el.domId ?? el.id) ||
+ !parentMap.has(el.domId ?? el.id),
+ )
+ .flatMap((el) => (anchorsChildren(el) ? [el, ...expanded] : [el]));
}
export function useExpandedTimelineElements(): TimelineElement[] {