Skip to content

Commit f4e00ce

Browse files
fix(runtime): a finished film rests on its last frame instead of a blank one (#4158)
* fix(runtime): a finished film rests on its last frame instead of a blank one The clip-visibility check was half-open (start <= t < end), so a clip whose authored end reached the composition's total duration hid at exactly that instant. The player parks there when playback ends, so a finished film went blank instead of holding its last frame, in both the published player and Studio's scrub-to-end. Extracts the shared half-open comparison used in seven places into isInClipWindow (packages/core/src/runtime/clipWindow.ts) and adds isClipVisibleAt, which additionally treats a clip reaching the composition's terminal instant as visible. Only the DOM-visibility gate uses the terminal rule; playback and media-activation windows keep the plain half-open check, so two back-to-back clips still never both show at their shared boundary and audio never re-activates past the end. * fix(runtime): hold a terminal video on its last frame at the composition end * refactor(player): route the proxy clip-window checks through the shared predicate Makes the composition duration required on syncRuntimeMedia so a caller cannot drop the terminal rule, exposes the predicate as a core subpath, and adds a nested-timeline float-noise test. * build(core): declare the runtime/clip-window subpath in the package-subpaths descriptor * test(runtime): a speed-ramped video that runs to the composition end holds its last frame Covers the composition of the terminal hold with a rate lane: at a time past the clip end the video sits at the source time of its own end.
1 parent 3f3f3b7 commit f4e00ce

12 files changed

Lines changed: 315 additions & 42 deletions

File tree

‎packages/core/package-subpaths.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,12 @@
248248
"types": "./dist/runtime/protocol.d.ts",
249249
"environments": ["browser", "bun", "node"]
250250
},
251+
"./runtime/clip-window": {
252+
"source": "./src/runtime/clipWindow.ts",
253+
"runtime": "./dist/runtime/clipWindow.js",
254+
"types": "./dist/runtime/clipWindow.d.ts",
255+
"environments": ["browser", "bun", "node"]
256+
},
251257
"./runtime/stacking-context": {
252258
"source": "./src/runtime/stackingContext.ts",
253259
"runtime": "./dist/runtime/stackingContext.js",

‎packages/core/package.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,12 @@
257257
"import": "./src/runtime/protocol.ts",
258258
"types": "./src/runtime/protocol.ts"
259259
},
260+
"./runtime/clip-window": {
261+
"bun": "./src/runtime/clipWindow.ts",
262+
"node": "./dist/runtime/clipWindow.js",
263+
"import": "./src/runtime/clipWindow.ts",
264+
"types": "./src/runtime/clipWindow.ts"
265+
},
260266
"./runtime/stacking-context": {
261267
"bun": "./src/runtime/stackingContext.ts",
262268
"node": "./dist/runtime/stackingContext.js",
@@ -571,6 +577,10 @@
571577
"import": "./dist/runtime/protocol.js",
572578
"types": "./dist/runtime/protocol.d.ts"
573579
},
580+
"./runtime/clip-window": {
581+
"import": "./dist/runtime/clipWindow.js",
582+
"types": "./dist/runtime/clipWindow.d.ts"
583+
},
574584
"./runtime/stacking-context": {
575585
"import": "./dist/runtime/stackingContext.js",
576586
"types": "./dist/runtime/stackingContext.d.ts"

‎packages/core/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,8 @@ export {
319319
// publishConfig entry points at a file the pack doesn't contain
320320
// (verify:packed-manifests catches exactly that).
321321
export { createRuntimeStartTimeResolver } from "./runtime/startResolver.js";
322+
// Also exposed via the ./runtime/clip-window subpath; re-exported here for the same dist-emit reason.
323+
export { isClipVisibleAt, isInClipWindow } from "./runtime/clipWindow.js";
322324
export {
323325
normalizePlaybackRate,
324326
normalizeRateSpec,
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import { describe, expect, it } from "vitest";
2+
import { isClipVisibleAt, isInClipWindow } from "./clipWindow";
3+
4+
describe("isInClipWindow", () => {
5+
it("includes the start and excludes the end", () => {
6+
expect([1, 1.5, 2].map((t) => isInClipWindow(t, 1, 2))).toEqual([true, true, false]);
7+
});
8+
});
9+
10+
describe("isClipVisibleAt", () => {
11+
it("hides a clip that ends before the composition does, from its end on", () => {
12+
expect([1.99, 2, 5].map((t) => isClipVisibleAt(t, 1, 2, 5))).toEqual([true, false, false]);
13+
});
14+
15+
it("keeps a clip that runs to the composition end visible at and past it", () => {
16+
expect([4.99, 5, 6].map((t) => isClipVisibleAt(t, 4, 5, 5))).toEqual([true, true, true]);
17+
});
18+
19+
it("does not show a clip before its start", () => {
20+
expect(isClipVisibleAt(3.99, 4, 5, 5)).toBe(false);
21+
});
22+
23+
it("treats float noise in the summed end as reaching the composition end", () => {
24+
expect(isClipVisibleAt(0.35, 0.1, 0.3, 0.1 + 0.2)).toBe(true);
25+
});
26+
27+
it("gives no terminal grace when the composition duration is unknown", () => {
28+
expect(isClipVisibleAt(5, 4, 5, 0)).toBe(false);
29+
});
30+
});
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
/** Half-open: two back-to-back clips never both hold the shared boundary instant. */
2+
export const isInClipWindow = (time: number, start: number, end: number): boolean =>
3+
time >= start && time < end;
4+
5+
const TERMINAL_EPSILON_SECONDS = 1e-6;
6+
7+
/**
8+
* Visibility window: half-open, except a clip that runs to the composition's end also owns
9+
* the terminal instant, so a finished film rests on its last frame instead of going blank.
10+
*/
11+
export const isClipVisibleAt = (
12+
time: number,
13+
start: number,
14+
end: number,
15+
compositionDuration: number,
16+
): boolean =>
17+
isInClipWindow(time, start, end) ||
18+
(time >= start &&
19+
compositionDuration > 0 &&
20+
end >= compositionDuration - TERMINAL_EPSILON_SECONDS);

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

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -949,6 +949,95 @@ describe("initSandboxRuntimeModular", () => {
949949
expect(clip.style.visibility).toBe("hidden");
950950
});
951951

952+
describe("at the composition's terminal time", () => {
953+
const buildRoot = () => {
954+
const root = document.createElement("div");
955+
root.setAttribute("data-composition-id", "main");
956+
root.setAttribute("data-root", "true");
957+
root.setAttribute("data-start", "0");
958+
root.setAttribute("data-width", "1920");
959+
root.setAttribute("data-height", "1080");
960+
document.body.appendChild(root);
961+
return root;
962+
};
963+
const addClip = (root: HTMLElement, start: number, duration: number) => {
964+
const clip = document.createElement("div");
965+
clip.setAttribute("data-start", String(start));
966+
clip.setAttribute("data-duration", String(duration));
967+
root.appendChild(clip);
968+
return clip;
969+
};
970+
971+
it("keeps a clip that runs to the composition duration visible at and past the duration", () => {
972+
const root = buildRoot();
973+
const lastClip = addClip(root, 2.5, 2.5);
974+
window.__timelines = { main: createMockTimeline(5) };
975+
initSandboxRuntimeModular();
976+
977+
window.__player?.renderSeek(5 - 1e-9);
978+
expect(lastClip.style.visibility).toBe("visible");
979+
window.__player?.renderSeek(5);
980+
expect(lastClip.style.visibility).toBe("visible");
981+
window.__player?.renderSeek(5.5);
982+
expect(lastClip.style.visibility).toBe("visible");
983+
});
984+
985+
it("seeks a terminal video to its last authored frame and keeps it paused on a direct seek", () => {
986+
const root = buildRoot();
987+
const video = document.createElement("video");
988+
video.setAttribute("data-start", "2.5");
989+
video.setAttribute("data-duration", "2.5");
990+
root.appendChild(video);
991+
Object.defineProperty(video, "duration", { value: 10, configurable: true });
992+
Object.defineProperty(video, "currentTime", { value: 0, writable: true, configurable: true });
993+
video.play = vi.fn(() => Promise.resolve());
994+
window.__timelines = { main: createMockTimeline(5) };
995+
initSandboxRuntimeModular();
996+
997+
window.__player?.renderSeek(5);
998+
999+
expect(video.style.visibility).toBe("visible");
1000+
expect(video.currentTime).toBe(2.5);
1001+
expect(video.paused).toBe(true);
1002+
expect(video.play).not.toHaveBeenCalled();
1003+
});
1004+
1005+
it("keeps a nested clip visible when its summed end falls one ulp short of the timeline duration", () => {
1006+
const root = buildRoot();
1007+
// GSAP reports 0.8 for a 0.7s tween followed by a 0.1s tween; the authored end sums to 0.7999999999999999.
1008+
const nested = addClip(root, 0.7, 0.1);
1009+
window.__timelines = { main: createMockTimeline(0.8) };
1010+
initSandboxRuntimeModular();
1011+
1012+
window.__player?.renderSeek(0.8);
1013+
expect(nested.style.visibility).toBe("visible");
1014+
});
1015+
1016+
it("still hides a clip that ended before the composition duration", () => {
1017+
const root = buildRoot();
1018+
const earlyClip = addClip(root, 0, 2.5);
1019+
addClip(root, 2.5, 2.5);
1020+
window.__timelines = { main: createMockTimeline(5) };
1021+
initSandboxRuntimeModular();
1022+
1023+
window.__player?.renderSeek(5);
1024+
expect(earlyClip.style.visibility).toBe("hidden");
1025+
});
1026+
1027+
it("never shows two back-to-back clips at their shared boundary", () => {
1028+
const root = buildRoot();
1029+
const first = addClip(root, 0, 2.5);
1030+
const second = addClip(root, 2.5, 2.5);
1031+
window.__timelines = { main: createMockTimeline(5) };
1032+
initSandboxRuntimeModular();
1033+
1034+
window.__player?.renderSeek(2.5);
1035+
expect([first.style.visibility, second.style.visibility]).toEqual(["hidden", "visible"]);
1036+
window.__player?.renderSeek(5);
1037+
expect([first.style.visibility, second.style.visibility]).toEqual(["hidden", "visible"]);
1038+
});
1039+
});
1040+
9521041
it("keeps external composition hosts visible through their authored duration", async () => {
9531042
const root = document.createElement("div");
9541043
root.setAttribute("data-composition-id", "main");

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

Lines changed: 35 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// fallow-ignore-file code-duplication complexity
22
import { installRuntimeControlBridge, postRuntimeMessage, setRuntimeProtocolFps } from "./bridge";
3+
import { isClipVisibleAt, isInClipWindow } from "./clipWindow";
34
import { initRuntimeAnalytics, emitAnalyticsEvent } from "./analytics";
45
import { injectCompositionCssVariables } from "./getVariables";
56
import { createCssAdapter } from "./adapters/css";
@@ -805,7 +806,11 @@ export function initSandboxRuntimeModular(): void {
805806
}
806807
});
807808

808-
const isTimedElementVisibleAt = (rawNode: HTMLElement, currentTime: number): boolean => {
809+
const isTimedElementVisibleAt = (
810+
rawNode: HTMLElement,
811+
currentTime: number,
812+
compositionDuration: number,
813+
): boolean => {
809814
const tag = rawNode.tagName.toLowerCase();
810815
if (tag === "script" || tag === "style" || tag === "link" || tag === "meta") {
811816
return false;
@@ -846,10 +851,7 @@ export function initSandboxRuntimeModular(): void {
846851
window.__HF_EXPORT_RENDER_SEEK_CONFIG && Number.isFinite(computedEnd)
847852
? snapTimeToFrameBoundary(computedEnd, state.canonicalFps)
848853
: computedEnd;
849-
return (
850-
currentTime >= visibilityStart &&
851-
(Number.isFinite(visibilityEnd) ? currentTime < visibilityEnd : true)
852-
);
854+
return isClipVisibleAt(currentTime, visibilityStart, visibilityEnd, compositionDuration);
853855
};
854856

855857
const hasExternalCompositions = !!document.querySelector("[data-composition-src]");
@@ -2394,8 +2396,17 @@ export function initSandboxRuntimeModular(): void {
23942396
}
23952397
};
23962398

2397-
const applyTimedElementVisibility = (currentTime: number, visibilityNodes: Element[]) => {
2399+
const applyTimedElementVisibility = (
2400+
currentTime: number,
2401+
visibilityNodes: Element[],
2402+
timingRevision?: number,
2403+
) => {
23982404
const rootComp = resolveRootCompositionElement();
2405+
const compositionDuration = getSafeTimelineDurationSeconds(
2406+
state.capturedTimeline,
2407+
0,
2408+
timingRevision,
2409+
);
23992410
for (const rawNode of visibilityNodes) {
24002411
if (!isHtmlElement(rawNode)) continue;
24012412

@@ -2426,7 +2437,7 @@ export function initSandboxRuntimeModular(): void {
24262437
groupMuteDirty = true;
24272438
}
24282439

2429-
let isVisibleNow = isTimedElementVisibleAt(rawNode, currentTime);
2440+
let isVisibleNow = isTimedElementVisibleAt(rawNode, currentTime, compositionDuration);
24302441
// Descendants must not override a hidden ancestor clip. CSS visibility can
24312442
// otherwise leak child pixels through inactive scenes because a descendant
24322443
// with visibility:visible escapes an ancestor's visibility:hidden.
@@ -2435,7 +2446,7 @@ export function initSandboxRuntimeModular(): void {
24352446
while (ancestor) {
24362447
if (ancestor === rootComp) break;
24372448
if (isHtmlElement(ancestor) && ancestor.hasAttribute("data-start")) {
2438-
if (!isTimedElementVisibleAt(ancestor, currentTime)) {
2449+
if (!isTimedElementVisibleAt(ancestor, currentTime, compositionDuration)) {
24392450
isVisibleNow = false;
24402451
break;
24412452
}
@@ -2476,7 +2487,11 @@ export function initSandboxRuntimeModular(): void {
24762487
const syncTimedElementVisibility = (
24772488
currentTime: number,
24782489
visibilityNodes: Element[] = Array.from(document.querySelectorAll("[data-start]")),
2479-
) => withTimingResolver(() => applyTimedElementVisibility(currentTime, visibilityNodes));
2490+
timingRevision?: number,
2491+
) =>
2492+
withTimingResolver(() =>
2493+
applyTimedElementVisibility(currentTime, visibilityNodes, timingRevision),
2494+
);
24802495

24812496
/**
24822497
* Clip windows sorted by each endpoint, so a seek can ask which windows it
@@ -2657,7 +2672,7 @@ export function initSandboxRuntimeModular(): void {
26572672
document.removeEventListener("play", onMediaPlayWakeTransport, true);
26582673
});
26592674

2660-
const syncMediaForCurrentState = () => {
2675+
const syncMediaForCurrentState = (timingRevision?: number) => {
26612676
// Scope 1 of 3 (see `withTimingResolver`). Closes before `syncRuntimeMedia`,
26622677
// which may call `el.load()` and invalidate every cached duration.
26632678
//
@@ -2703,6 +2718,8 @@ export function initSandboxRuntimeModular(): void {
27032718
userMuted: state.bridgeMuted,
27042719
userVolume: state.bridgeVolume,
27052720
forceSync,
2721+
getCompositionDuration: () =>
2722+
getSafeTimelineDurationSeconds(state.capturedTimeline, 0, timingRevision),
27062723
onElementVolume: (el, _effectiveVolume, authorVolume) =>
27072724
webAudio.setElementVolume(el, authorVolume),
27082725
isWebAudioOwned: (el) => webAudio.ownsElement(el),
@@ -2717,15 +2734,15 @@ export function initSandboxRuntimeModular(): void {
27172734
lastSyncedMediaTimeSeconds = state.currentTime;
27182735
// Every clip not visited was out of window at both ends of this seek, so
27192736
// the visited ones are the only possible members.
2720-
mediaClipsInWindow = mediaClips.filter(
2721-
(clip) => state.currentTime >= clip.start && state.currentTime < clip.end,
2737+
mediaClipsInWindow = mediaClips.filter((clip) =>
2738+
isInClipWindow(state.currentTime, clip.start, clip.end),
27222739
);
27232740
} else {
27242741
lastSyncedMediaTimeSeconds = null;
27252742
mediaClipsInWindow = [];
27262743
}
27272744
}
2728-
syncTimedElementVisibility(state.currentTime);
2745+
syncTimedElementVisibility(state.currentTime, undefined, timingRevision);
27292746
};
27302747

27312748
const postState = (force: boolean) => {
@@ -3801,7 +3818,7 @@ export function initSandboxRuntimeModular(): void {
38013818
const durAttr = parseStrictFiniteTimingNumber(rawEl.dataset.duration);
38023819
const end = durAttr != null && durAttr > 0 ? start + durAttr : Infinity;
38033820
const mediaStart = readElementPlaybackStart(rawEl);
3804-
if (Number.isFinite(start) && state.currentTime >= start && state.currentTime < end) {
3821+
if (Number.isFinite(start) && isInClipWindow(state.currentTime, start, end)) {
38053822
if (!rawEl.paused) {
38063823
clock.attachAudioSource({
38073824
el: rawEl,
@@ -3874,20 +3891,20 @@ export function initSandboxRuntimeModular(): void {
38743891
seekTimelineAndAdapters(dur);
38753892
}
38763893
runAdapters("pause");
3877-
syncMediaForCurrentState();
3894+
syncMediaForCurrentState(timingRevision);
38783895
postState(true);
38793896
return;
38803897
}
38813898

38823899
if (clock.isPlaying()) {
3883-
syncMediaForCurrentState();
3900+
syncMediaForCurrentState(timingRevision);
38843901
} else if (hasRunningTimedMedia()) {
38853902
// Nothing may run while the clock is paused, and the paused side used to
38863903
// police nothing. Dropping the cursor forces a full visit: the seek-window
38873904
// index skips an element that started outside the current window, which is
38883905
// exactly the one to stop.
38893906
lastSyncedMediaTimeSeconds = null;
3890-
syncMediaForCurrentState();
3907+
syncMediaForCurrentState(timingRevision);
38913908
}
38923909
postState(false);
38933910
} finally {
@@ -3909,7 +3926,7 @@ export function initSandboxRuntimeModular(): void {
39093926
if (!Number.isFinite(start)) continue;
39103927
const durAttr = parseStrictFiniteTimingNumber(el.dataset.duration);
39113928
const end = durAttr != null && durAttr > 0 ? start + durAttr : Infinity;
3912-
if (timeSeconds < start || timeSeconds >= end) continue;
3929+
if (!isInClipWindow(timeSeconds, start, end)) continue;
39133930
const mediaStart = readElementPlaybackStart(el);
39143931
const relTime = timeSeconds - start + mediaStart;
39153932
if (relTime >= 0) {

0 commit comments

Comments
 (0)