Skip to content

Commit 684ec4e

Browse files
vanceingallsclaude
andcommitted
fix(studio): reconcile keyframe-seek timing basis between flat Layout and Motion groups
Whole-plan coherence review (Plan 3a Layout + Plan 3b Motion) found that Layout's keyframe gutter and Motion's Timing row independently derived an element's start/duration and disagreed whenever an element had animations but no explicit data-duration: Motion correctly inferred the range from the element's GSAP tweens, while Layout's keyframe gutter fell back to a naive `duration ?? 1`, so clicking a keyframe percentage in Layout could seek to a different absolute time than what Motion's Timing row displayed. Extract deriveElementTiming (propertyPanelFlatTimingDerivation.ts) as the single shared basis both paths now consume: FlatTimingRow (Motion) and PropertyPanelFlat's own elStart/elDuration (Layout's keyframe gutter and 3D Transform block). PropertyPanelFlat now recomputes this basis itself from its own element/gsapAnimations props instead of trusting the parent's naive value, so PropertyPanel.tsx (and its legacy non-flat panel) is untouched. Co-Authored-By: Claude Sonnet 5 <[email protected]>
1 parent 710a248 commit 684ec4e

5 files changed

Lines changed: 241 additions & 26 deletions

File tree

‎packages/studio/src/components/editor/PropertyPanel.test.tsx‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,40 @@ function animatedElement() {
143143
};
144144
}
145145

146+
// Inferred-timing fixture (whole-plan coherence fix): NO explicit data-start
147+
// or data-duration — sections.timing must turn on via animationCount (fed
148+
// from gsapAnimations.length), not an authored attribute, so both the Motion
149+
// Timing row and the Layout keyframe gutter are forced to infer the range
150+
// from the element's own GSAP tween instead of reading it off an attribute.
151+
function inferredMotionElement() {
152+
return {
153+
...baseElement(),
154+
id: "inferred-anim",
155+
selector: "#inferred-anim",
156+
label: "Inferred Anim",
157+
};
158+
}
159+
160+
// A single "to" tween running from t=2 to t=5 (position 2, duration 3), with
161+
// keyframes on "x" at 0/50/100% — enough to drive both FlatTimingRow's
162+
// inference and the Layout "x" row's keyframe-seek gutter.
163+
const INFERRED_TIMING_ANIMATION = {
164+
id: "a1",
165+
targetSelector: "#inferred-anim",
166+
method: "to",
167+
position: 2,
168+
duration: 3,
169+
properties: { x: 100 },
170+
keyframes: {
171+
format: "percentage",
172+
keyframes: [
173+
{ percentage: 0, properties: { x: 0 } },
174+
{ percentage: 50, properties: { x: 50 } },
175+
{ percentage: 100, properties: { x: 100 } },
176+
],
177+
},
178+
} as never;
179+
146180
async function renderPanel(
147181
flatEnabled: boolean,
148182
elementOverride: ReturnType<typeof baseElement> = baseElement(),
@@ -418,3 +452,65 @@ describe("PropertyPanel — Motion group (Plan 3b)", () => {
418452
RENDER_TIMEOUT_MS,
419453
);
420454
});
455+
456+
// Whole-plan coherence fix: Layout's keyframe-seek basis and Motion's Timing
457+
// row basis must agree on the same start/duration for an element that has
458+
// animations but no explicit data-duration — before the fix, Layout fell back
459+
// to a naive `duration ?? 1` while Motion correctly inferred the range from
460+
// the tween (position 2, duration 3 -> start 2 / duration 3 / end 5).
461+
describe("PropertyPanel — flat Layout/Motion timing agreement (whole-plan coherence fix)", () => {
462+
it(
463+
"Motion's Timing row shows the inferred start/end/duration for an element with animations but no explicit duration",
464+
async () => {
465+
const { host, root } = await renderPanel(true, inferredMotionElement(), {
466+
gsapAnimations: [INFERRED_TIMING_ANIMATION],
467+
});
468+
openFlatGroup(host, "Motion");
469+
const motionGroup = host.querySelector('[data-flat-group-open="true"]');
470+
if (!motionGroup) throw new Error("expected the Motion group to be open");
471+
expect(motionGroup.textContent).toContain("Inferred");
472+
const inputs = motionGroup.querySelectorAll<HTMLInputElement>("input");
473+
// FlatTimingRow renders Start, End, Duration in that order.
474+
expect(inputs[0]?.value).toBe("2.00s");
475+
expect(inputs[1]?.value).toBe("5.00s");
476+
expect(inputs[2]?.value).toBe("3.00s");
477+
act(() => root.unmount());
478+
},
479+
RENDER_TIMEOUT_MS,
480+
);
481+
482+
it(
483+
"Layout's X-row keyframe gutter seeks to the SAME absolute time Motion's Timing row shows as the midpoint (50% of an inferred 2s-5s range = 3.5s)",
484+
async () => {
485+
const onSeekToTime = vi.fn();
486+
const { host, root } = await renderPanel(true, inferredMotionElement(), {
487+
gsapAnimations: [INFERRED_TIMING_ANIMATION],
488+
onSeekToTime,
489+
});
490+
openFlatGroup(host, "Layout");
491+
const layoutGroup = host.querySelector('[data-flat-group-open="true"]');
492+
if (!layoutGroup) throw new Error("expected the Layout group to be open");
493+
494+
const xRow = Array.from(layoutGroup.querySelectorAll<HTMLElement>(".group")).find(
495+
(el) => el.querySelector("span")?.textContent === "X",
496+
);
497+
if (!xRow) throw new Error("expected an X row");
498+
const gutter = xRow.querySelector('[data-flat-kf-gutter="true"]');
499+
if (!gutter) throw new Error("expected a keyframe gutter on the X row");
500+
// The diamond button always carries a `title`; the two plain arrow
501+
// buttons don't. At currentPct=0 with keyframes at 0/50/100%, the prev
502+
// arrow is disabled (no earlier keyframe) and the next arrow seeks to
503+
// the 50% keyframe — exactly the case the coherence bug affected.
504+
const nextArrow = Array.from(gutter.querySelectorAll<HTMLButtonElement>("button")).find(
505+
(b) => !b.title && !b.disabled,
506+
);
507+
if (!nextArrow) throw new Error("expected an enabled next-keyframe arrow button");
508+
act(() => nextArrow.dispatchEvent(new MouseEvent("click", { bubbles: true })));
509+
510+
// Same basis as the Timing row: start 2 + 50% * duration 3 = 3.5.
511+
expect(onSeekToTime).toHaveBeenCalledWith(3.5);
512+
act(() => root.unmount());
513+
},
514+
RENDER_TIMEOUT_MS,
515+
);
516+
});

‎packages/studio/src/components/editor/PropertyPanelFlat.tsx‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import { FlatTextSection } from "./propertyPanelFlatTextSection";
1111
import { FlatStyleSection } from "./propertyPanelFlatStyleSections";
1212
import { FlatLayoutSection } from "./propertyPanelFlatLayoutSection";
1313
import { FlatMotionSection } from "./propertyPanelFlatMotionSection";
14+
import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
1415
import { createGsapLivePreview } from "./gsapLivePreview";
1516
import { formatTextFieldPreview, StyleSections } from "./propertyPanelSections";
1617
import { STUDIO_GSAP_PANEL_ENABLED } from "./manualEditingAvailability";
@@ -96,8 +97,12 @@ export function PropertyPanelFlat({
9697
currentPct,
9798
animIdForProp,
9899
gsapRuntimeValues,
99-
elStart,
100-
elDuration,
100+
// Renamed: PropertyPanel.tsx still computes/passes these for its own legacy
101+
// (non-flat) panel, but the flat path recomputes its own basis below via
102+
// deriveElementTiming so it agrees with Motion's Timing row — ignore the
103+
// parent's naive `elDuration ?? 1` fallback.
104+
elStart: _elStart,
105+
elDuration: _elDuration,
101106
onCommitAnimatedProperty,
102107
onCommitAnimatedProperties,
103108
onSeekToTime,
@@ -222,6 +227,12 @@ export function PropertyPanelFlat({
222227
setPinnedGroupIds((current) =>
223228
current.includes(groupId) ? current.filter((id) => id !== groupId) : [...current, groupId],
224229
);
230+
// Basis for the Layout keyframe gutter (X/Y/W/H/Angle + 3D Transform) —
231+
// must agree with Motion's Timing row (FlatTimingRow), which infers the
232+
// range from animations when there's no explicit data-duration. Computed
233+
// here (not threaded from PropertyPanel) both to keep that file under its
234+
// 600-LOC gate and because element/gsapAnimations are already in scope.
235+
const { start: elStart, duration: elDuration } = deriveElementTiming(element, gsapAnimations);
225236
// Trivial percentage→time seek, derived here rather than threaded from
226237
// PropertyPanel (keeps that file under its 600-LOC gate).
227238
const seekFromKfPct = (pct: number) => onSeekToTime?.(elStart + (pct / 100) * elDuration);

‎packages/studio/src/components/editor/propertyPanelFlatMotionSection.tsx‎

Lines changed: 2 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,7 @@ import { CommitField } from "./propertyPanelPrimitives";
77
import { AnimationCard } from "./AnimationCard";
88
import { ADD_METHODS, ADD_METHOD_LABELS, METHOD_TOOLTIPS } from "./gsapAnimationConstants";
99
import type { GsapAnimationEditCallbacks } from "./gsapAnimationCallbacks";
10-
11-
function deriveTimingFromAnimations(
12-
animations: GsapAnimation[],
13-
): { start: number; duration: number } | null {
14-
let lo = Infinity;
15-
let hi = -Infinity;
16-
for (const a of animations) {
17-
const s = a.resolvedStart ?? (typeof a.position === "number" ? a.position : 0);
18-
const d = a.duration ?? 0;
19-
lo = Math.min(lo, s);
20-
hi = Math.max(hi, s + d);
21-
}
22-
if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi <= lo) return null;
23-
return { start: lo, duration: hi - lo };
24-
}
10+
import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
2511

2612
export function FlatTimingRow({
2713
element,
@@ -32,15 +18,7 @@ export function FlatTimingRow({
3218
animations?: GsapAnimation[];
3319
onSetAttribute: (attr: string, value: string) => void | Promise<void>;
3420
}) {
35-
const explicitStart = Number.parseFloat(element.dataAttributes.start ?? "0") || 0;
36-
const explicitDuration =
37-
Number.parseFloat(
38-
element.dataAttributes.duration ?? element.dataAttributes["hf-authored-duration"] ?? "0",
39-
) || 0;
40-
41-
const derived = explicitDuration > 0 ? null : deriveTimingFromAnimations(animations);
42-
const start = derived ? derived.start : explicitStart;
43-
const duration = derived ? derived.duration : explicitDuration;
21+
const { start, duration, inferred: derived } = deriveElementTiming(element, animations);
4422
const end = start + duration;
4523

4624
const commitStart = (nextValue: string) => {
Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
import { describe, expect, it } from "vitest";
2+
import { deriveElementTiming } from "./propertyPanelFlatTimingDerivation";
3+
import type { DomEditSelection } from "./domEditingTypes";
4+
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
5+
6+
function withDataAttributes(
7+
dataAttributes: Record<string, string>,
8+
): Pick<DomEditSelection, "dataAttributes"> {
9+
return { dataAttributes };
10+
}
11+
12+
describe("deriveElementTiming", () => {
13+
it("uses the explicit data-start/data-duration attributes when duration is authored", () => {
14+
const result = deriveElementTiming(withDataAttributes({ start: "8", duration: "4" }));
15+
expect(result).toEqual({ start: 8, duration: 4, inferred: false });
16+
});
17+
18+
it("infers start/duration from animations when there is no explicit data-duration", () => {
19+
const animations = [{ position: 2, duration: 3 } as unknown as GsapAnimation];
20+
const result = deriveElementTiming(
21+
withDataAttributes({ start: "0", duration: "0" }),
22+
animations,
23+
);
24+
expect(result).toEqual({ start: 2, duration: 3, inferred: true });
25+
});
26+
27+
it("spans the earliest tween start to the latest tween end across multiple animations", () => {
28+
const animations = [
29+
{ position: 1, duration: 2 } as unknown as GsapAnimation, // 1 -> 3
30+
{ position: 2, duration: 4 } as unknown as GsapAnimation, // 2 -> 6
31+
];
32+
const result = deriveElementTiming(withDataAttributes({}), animations);
33+
expect(result).toEqual({ start: 1, duration: 5, inferred: true });
34+
});
35+
36+
it("prefers an explicit data-duration over inference even when animations exist", () => {
37+
const animations = [{ position: 2, duration: 3 } as unknown as GsapAnimation];
38+
const result = deriveElementTiming(
39+
withDataAttributes({ start: "0", duration: "10" }),
40+
animations,
41+
);
42+
expect(result).toEqual({ start: 0, duration: 10, inferred: false });
43+
});
44+
45+
it("falls back to hf-authored-duration when data-duration is absent", () => {
46+
const result = deriveElementTiming(
47+
withDataAttributes({ start: "1", "hf-authored-duration": "6" }),
48+
);
49+
expect(result).toEqual({ start: 1, duration: 6, inferred: false });
50+
});
51+
52+
it("returns a zero-duration, non-inferred result with no attributes and no animations", () => {
53+
const result = deriveElementTiming(withDataAttributes({}));
54+
expect(result).toEqual({ start: 0, duration: 0, inferred: false });
55+
});
56+
57+
// This is the exact bug from the whole-plan coherence review: Layout's
58+
// keyframe-seek basis must land on the same absolute time that Motion's
59+
// Timing row displays as the element's midpoint.
60+
it("agrees with a keyframe-percentage seek: 50% lands on the same midpoint the Timing row would show", () => {
61+
const animations = [{ position: 2, duration: 3 } as unknown as GsapAnimation];
62+
const timing = deriveElementTiming(
63+
withDataAttributes({ start: "0", duration: "0" }),
64+
animations,
65+
);
66+
const seekTimeAt50Pct = timing.start + (50 / 100) * timing.duration;
67+
const timingRowMidpoint = timing.start + timing.duration / 2;
68+
expect(seekTimeAt50Pct).toBe(timingRowMidpoint);
69+
expect(seekTimeAt50Pct).toBe(3.5);
70+
});
71+
});
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
2+
import type { DomEditSelection } from "./domEditingTypes";
3+
4+
/**
5+
* The single source of truth for an element's clip start/duration in the flat
6+
* inspector. Both the Motion group's Timing row (`FlatTimingRow`) and the
7+
* Layout group's keyframe gutter (fed via `elStart`/`elDuration` from
8+
* `PropertyPanel.tsx` through `PropertyPanelFlat.tsx`) must derive this the
9+
* same way — otherwise a keyframe-percentage seek in Layout lands on a
10+
* different absolute time than the range Motion displays for the same
11+
* element (found by the Plan 3a+3b whole-plan coherence review).
12+
*
13+
* Precedence: an explicit `data-duration` (or `data-hf-authored-duration`)
14+
* wins outright. Only when neither is present do we infer the range from the
15+
* element's own GSAP tweens (earliest tween start → latest tween end).
16+
*
17+
* Scoped to the FLAT inspector only — the legacy (non-flat) panel keeps its
18+
* own, unrelated `elStart`/`elDuration ?? 1` computation in `PropertyPanel.tsx`
19+
* untouched.
20+
*/
21+
export interface ElementTiming {
22+
start: number;
23+
duration: number;
24+
/** True when duration/start came from `deriveTimingFromAnimations`, not an authored attribute. */
25+
inferred: boolean;
26+
}
27+
28+
function deriveTimingFromAnimations(
29+
animations: GsapAnimation[],
30+
): { start: number; duration: number } | null {
31+
let lo = Infinity;
32+
let hi = -Infinity;
33+
for (const a of animations) {
34+
const s = a.resolvedStart ?? (typeof a.position === "number" ? a.position : 0);
35+
const d = a.duration ?? 0;
36+
lo = Math.min(lo, s);
37+
hi = Math.max(hi, s + d);
38+
}
39+
if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi <= lo) return null;
40+
return { start: lo, duration: hi - lo };
41+
}
42+
43+
export function deriveElementTiming(
44+
element: Pick<DomEditSelection, "dataAttributes">,
45+
animations: GsapAnimation[] = [],
46+
): ElementTiming {
47+
const explicitStart = Number.parseFloat(element.dataAttributes.start ?? "0") || 0;
48+
const explicitDuration =
49+
Number.parseFloat(
50+
element.dataAttributes.duration ?? element.dataAttributes["hf-authored-duration"] ?? "0",
51+
) || 0;
52+
53+
const derived = explicitDuration > 0 ? null : deriveTimingFromAnimations(animations);
54+
return {
55+
start: derived ? derived.start : explicitStart,
56+
duration: derived ? derived.duration : explicitDuration,
57+
inferred: derived !== null,
58+
};
59+
}

0 commit comments

Comments
 (0)