Skip to content

Commit 2b65b4e

Browse files
fix(studio): harden composition timeline reliability (#2615)
* fix(studio): preserve composition playback continuity * feat(studio): drag compositions into the timeline * fix(studio): collapse expanded composition move aliases * fix(studio): make timeline cuts atomic * fix(studio): group inspector gesture history * test(studio): cover masked text selection * fix(studio): harden composition timeline reliability * fix(studio): satisfy CI source gates * fix(studio): harden composition mutation requests
1 parent 2be8a62 commit 2b65b4e

93 files changed

Lines changed: 3925 additions & 758 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/concepts/compositions.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ You can embed one composition inside another in two ways: loading from an extern
4343
data-composition-id="intro-anim"
4444
data-composition-src="compositions/intro-anim.html"
4545
data-start="0"
46+
data-duration="4"
47+
data-playback-start="0"
4648
data-track-index="3"
4749
></div>
4850
```
@@ -68,6 +70,8 @@ You can embed one composition inside another in two ways: loading from an extern
6870
</div>
6971
</template>
7072
```
73+
74+
`data-playback-start` selects the child timeline time shown when the host begins. It defaults to `0`. A left trim or split advances this source-time offset by the elapsed host time multiplied by `data-playback-rate`, so the nested animation remains continuous instead of restarting.
7175
</Tab>
7276
<Tab title="Inline">
7377
Define a nested composition directly inside the parent. This is simpler for one-off compositions that do not need to be reused.

‎docs/concepts/data-attributes.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Hyperframes uses HTML data attributes to control timing, media playback, and [co
1818
| Attribute | Example | Description |
1919
|-----------|---------|-------------|
2020
| `data-media-start` | `"2"` | Media playback offset / trim point in seconds. Default: `0` |
21+
| `data-playback-start` | `"2"` | Source-time offset in seconds for media wrappers and nested composition hosts. Missing values default to `0`; Studio writes this attribute when a composition is trimmed or split. |
22+
| `data-playback-rate` | `"1.5"` | Source playback multiplier, clamped to `0.1`–`5`. Source time advances by timeline elapsed time multiplied by the canonical rate; invalid values default to `1`. |
2123
| `data-volume` | `"0.8"` | Audio/video volume, 0 to 1 |
2224
| `data-has-audio` | `"true"` | Indicates video has an audio track |
2325

‎docs/reference/html-schema.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,9 +52,11 @@ Common sizes:
5252
| `id` | All | Yes | Unique identifier (e.g., `"el-1"`). Used for relative timing references and CSS targeting. |
5353
| `class="clip"` | Visible elements | Yes | Enables runtime visibility management. Omit for audio-only clips. |
5454
| `data-start` | All | Yes | Start time in seconds (e.g., `"0"`, `"5.5"`), or a clip ID reference for [relative timing](#relative-timing) (e.g., `"intro"`). |
55-
| `data-duration` | video, img, audio | See below | Duration in seconds. **Required** for images. Optional for video/audio (defaults to source duration). Not used on compositions. |
55+
| `data-duration` | video, img, audio, nested composition hosts | See below | Timeline slot duration in seconds. **Required** for images and nested composition hosts. Optional for video/audio (defaults to source duration). |
5656
| `data-track-index` | All | Yes | Timeline track number. Controls z-ordering (higher = in front). Clips on the same track cannot overlap. |
5757
| `data-media-start` | video, audio | No | Playback offset / trim point in source file (seconds). Default: `0`. See [Data Attributes](/concepts/data-attributes). |
58+
| `data-playback-start` | video, audio, composition | No | Source-time offset in seconds. On a nested composition, this is the child timeline time shown at the host's `data-start`. Default: `0`. |
59+
| `data-playback-rate` | video, audio, composition | No | Source playback multiplier clamped to `0.1`–`5`. Invalid values default to `1`. |
5860
| `data-volume` | audio, video | No | Volume level from `0` to `1`. Default: `1`. |
5961
| `data-composition-id` | div | On compositions | Unique composition ID. Must match the key used in `window.__timelines`. |
6062
| `data-composition-src` | div | No | Path to external composition HTML file (for [nested compositions](#composition-clips)). |

‎packages/core/src/runtime/init.test.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1102,6 +1102,33 @@ describe("initSandboxRuntimeModular", () => {
11021102
expect(hookHost.style.visibility).toBe("visible");
11031103
});
11041104

1105+
it("seeks child compositions in source time using host offset and playback rate", () => {
1106+
const root = document.createElement("div");
1107+
root.setAttribute("data-composition-id", "main");
1108+
root.setAttribute("data-root", "true");
1109+
root.setAttribute("data-start", "0");
1110+
root.setAttribute("data-duration", "20");
1111+
document.body.appendChild(root);
1112+
1113+
const child = document.createElement("div");
1114+
child.setAttribute("data-composition-id", "child");
1115+
child.setAttribute("data-start", "3");
1116+
child.setAttribute("data-duration", "8");
1117+
child.setAttribute("data-playback-start", "1.5");
1118+
child.setAttribute("data-playback-rate", "2");
1119+
root.appendChild(child);
1120+
1121+
const childTimeline = createMockTimeline(6);
1122+
window.__timelines = { main: createMockTimeline(20), child: childTimeline };
1123+
initSandboxRuntimeModular();
1124+
1125+
window.__player?.renderSeek(5);
1126+
expect(childTimeline.time()).toBeCloseTo(5.5);
1127+
1128+
window.__player?.renderSeek(10);
1129+
expect(childTimeline.time()).toBe(6);
1130+
});
1131+
11051132
it("keeps the root GSAP render nudge for normal frames but not silent probes", () => {
11061133
const root = document.createElement("div");
11071134
root.setAttribute("data-composition-id", "main");

‎packages/core/src/runtime/init.ts‎

Lines changed: 15 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ import {
2020
import { forceDispatchSeekEvent } from "./adapters/seek-dispatch";
2121
import { createWaapiAdapter } from "./adapters/waapi";
2222
import {
23+
readElementPlaybackRate,
24+
readElementPlaybackStart,
2325
refreshRuntimeMediaCache,
2426
resolveRuntimeMediaClipDuration,
2527
syncRuntimeMedia,
@@ -2656,17 +2658,15 @@ export function initSandboxRuntimeModular(): void {
26562658
if (!node) continue;
26572659
const start = resolveStartForElement(node, 0);
26582660
if (!Number.isFinite(start)) continue;
2659-
const authoredDuration = resolveDurationForElement(node, {
2660-
includeAuthoredTimingAttrs: true,
2661-
});
26622661
const timelineDuration = getTimelineDurationSeconds(timeline);
2663-
const duration =
2664-
authoredDuration != null && authoredDuration > 0 ? authoredDuration : timelineDuration;
2662+
const sourceTime =
2663+
readElementPlaybackStart(node) +
2664+
Math.max(0, timeSeconds - start) * readElementPlaybackRate(node);
26652665
const localTime = Math.max(
26662666
0,
2667-
duration != null && duration > 0
2668-
? Math.min(duration, timeSeconds - start)
2669-
: timeSeconds - start,
2667+
timelineDuration != null && timelineDuration > 0
2668+
? Math.min(timelineDuration, sourceTime)
2669+
: sourceTime,
26702670
);
26712671
seekRuntimeTimeline(timeline, localTime, "runtime.init.transport.childTimeline", options);
26722672
}
@@ -2809,15 +2809,13 @@ export function initSandboxRuntimeModular(): void {
28092809
} catch (err) {
28102810
swallow("runtime.init.transport.seek", err);
28112811
}
2812-
// Sibling timelines (registered in __timelines but not nested under
2813-
// the root) are paused alongside the master. We do NOT seek them to
2814-
// absolute position `t` here — child timelines nested under the root
2815-
// are already propagated via tl.totalTime(), and seeking them again
2816-
// at absolute `t` would clobber their offset-relative position.
2817-
// Play/pause propagation for siblings happens in the player.play()
2818-
// and player.pause() overrides via the adapter layer.
2819-
} else {
2820-
seekStandaloneRegisteredTimelines(t, opts);
2812+
// Root propagation cannot represent an authored child source offset or
2813+
// playback rate. Re-seek registered children below with their host's
2814+
// explicit source-time contract.
2815+
}
2816+
seekStandaloneRegisteredTimelines(t, opts);
2817+
if (tl && opts?.activateChildren) {
2818+
activateSiblingTimelines(tl);
28212819
}
28222820
for (const adapter of state.deterministicAdapters) {
28232821
if (adapter.name === "gsap" && tl) continue;

‎packages/core/src/runtime/media.ts‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,23 @@
11
import { swallow } from "./diagnostics";
22
import { interpolateVolumeGain, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
3+
import { normalizePlaybackRate } from "./playbackRate.js";
34

4-
export function readElementPlaybackRate(el: HTMLMediaElement): number {
5-
const raw = el.defaultPlaybackRate;
6-
return Number.isFinite(raw) && raw > 0 ? Math.max(0.1, Math.min(5, raw)) : 1;
5+
export function readElementPlaybackRate(el: Element): number {
6+
const authored = Number.parseFloat(el.getAttribute("data-playback-rate") ?? "");
7+
const raw =
8+
Number.isFinite(authored) && authored > 0
9+
? authored
10+
: el instanceof HTMLMediaElement
11+
? el.defaultPlaybackRate
12+
: 1;
13+
return normalizePlaybackRate(raw);
14+
}
15+
16+
export function readElementPlaybackStart(el: Element): number {
17+
const raw = Number.parseFloat(
18+
el.getAttribute("data-playback-start") ?? el.getAttribute("data-media-start") ?? "",
19+
);
20+
return Number.isFinite(raw) && raw >= 0 ? raw : 0;
721
}
822

923
/**
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
export function normalizePlaybackRate(raw: number): number {
2+
return Number.isFinite(raw) && raw > 0 ? Math.max(0.1, Math.min(5, raw)) : 1;
3+
}

‎packages/core/src/runtime/timeline.test.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -312,10 +312,32 @@ describe("collectRuntimeTimelinePayload", () => {
312312
comp.setAttribute("data-composition-id", "scene-1");
313313
comp.setAttribute("data-start", "0");
314314
comp.setAttribute("data-duration", "10");
315+
comp.setAttribute("data-playback-start", "1.5");
316+
comp.setAttribute("data-playback-rate", "2");
315317
root.appendChild(comp);
316318

317319
const result = collectRuntimeTimelinePayload(defaultParams);
318320
expect(result.clips[0].kind).toBe("composition");
321+
expect(result.clips[0].playbackStart).toBe(1.5);
322+
expect(result.clips[0].playbackRate).toBe(2);
323+
});
324+
325+
it("defaults a legacy composition host playback window to zero at unit rate", () => {
326+
const root = document.createElement("div");
327+
root.setAttribute("data-composition-id", "main");
328+
root.setAttribute("data-duration", "20");
329+
document.body.appendChild(root);
330+
331+
const comp = document.createElement("div");
332+
comp.id = "scene-legacy";
333+
comp.setAttribute("data-composition-id", "scene-legacy");
334+
comp.setAttribute("data-start", "0");
335+
comp.setAttribute("data-duration", "10");
336+
root.appendChild(comp);
337+
338+
const clip = collectRuntimeTimelinePayload(defaultParams).clips[0];
339+
expect(clip.playbackStart).toBe(0);
340+
expect(clip.playbackRate).toBe(1);
319341
});
320342

321343
it("collects scenes from composition nodes", () => {

‎packages/core/src/runtime/timeline.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import type {
66
} from "./types";
77
import { stableClipId } from "./clipTree";
88
import { swallow } from "./diagnostics";
9-
import { readElementPlaybackRate } from "./media";
9+
import { readElementPlaybackRate, readElementPlaybackStart } from "./media";
1010
import { resolveCssStackingContextId } from "./stackingContext";
1111
import { createRuntimeStartTimeResolver } from "./startResolver";
1212
import { isSceneLikeCompositionId } from "../slideshow/index.js";
@@ -412,6 +412,8 @@ export function collectRuntimeTimelinePayload(params: {
412412
parentCompositionId: compositionContext.parentCompositionId,
413413
nodePath: null,
414414
compositionSrc: toAbsoluteAssetUrl(node.getAttribute("data-composition-src")),
415+
playbackStart: readElementPlaybackStart(node),
416+
playbackRate: readElementPlaybackRate(node),
415417
assetUrl: resolveNodeAssetUrl(node),
416418
timelineRole: node.getAttribute("data-timeline-role"),
417419
timelineLabel: node.getAttribute("data-timeline-label"),
@@ -521,6 +523,8 @@ export function collectRuntimeTimelinePayload(params: {
521523
parentCompositionId: rootCompositionIdForGsap,
522524
nodePath: null,
523525
compositionSrc: null,
526+
playbackStart: readElementPlaybackStart(el),
527+
playbackRate: readElementPlaybackRate(el),
524528
assetUrl: null,
525529
timelineRole: el.getAttribute("data-timeline-role"),
526530
timelineLabel: el.getAttribute("data-timeline-label"),
@@ -576,6 +580,8 @@ export function collectRuntimeTimelinePayload(params: {
576580
parentCompositionId: rootCompositionIdForGsap,
577581
nodePath: null,
578582
compositionSrc: null,
583+
playbackStart: readElementPlaybackStart(el),
584+
playbackRate: readElementPlaybackRate(el),
579585
assetUrl: null,
580586
timelineRole,
581587
timelineLabel: el.getAttribute("data-timeline-label"),

‎packages/core/src/runtime/types.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,8 @@ export type RuntimeTimelineClip = {
6464
parentCompositionId: string | null;
6565
nodePath: string | null;
6666
compositionSrc: string | null;
67+
playbackStart: number;
68+
playbackRate: number;
6769
assetUrl: string | null;
6870
timelineRole: string | null;
6971
timelineLabel: string | null;

0 commit comments

Comments
 (0)