fix(core): sample authored filters during sequential seeks

This commit is contained in:
Miguel Ángel
2026-10-17 02:00:55 -04:00
parent d6db13f8a0
commit c2c8df0b8d
4 changed files with 327 additions and 78 deletions
+71 -63
View File
@@ -11,6 +11,7 @@ import {
revealTimedClipsAfterFirstPass,
SKIPPED_CLIP,
showHiddenClips,
showHiddenClipFilters,
setTimedClipVisibility,
skipsHiddenImages,
} from "./timedClipHide";
@@ -4564,75 +4565,82 @@ export function initSandboxRuntimeModular(): void {
if (revision !== tweensRenderedThrough.revision)
tweensRenderedThrough = { revision, time: Number.NEGATIVE_INFINITY };
const jumped = !(Math.abs(t - lastTransportSeekTime) <= 1.5 / state.canonicalFps);
const firstRenders = jumped && t > tweensRenderedThrough.time;
const hideClipsAgain = firstRenders ? showHiddenClips() : null;
if (tl) {
// #10: when data-duration exceeds the timeline's intrinsic length the
// engine requests frames past the last tween. Seeking a paused GSAP
// timeline past its end can revert from()-tweens to their empty initial
// state, blanking the final poster. Clamp the MASTER seek to the
// timeline's full extent so it holds the final computed frame instead.
// Adapters still receive the raw `t` (their media may run longer).
// totalDuration() includes repeats; Infinity (infinite repeat) → no clamp.
let tlSeekTime = t;
if (typeof tl.totalDuration === "function") {
const firstRenders = t > tweensRenderedThrough.time;
const hideClipsAgain = firstRenders
? jumped
? showHiddenClips()
: showHiddenClipFilters()
: null;
try {
if (tl) {
// #10: when data-duration exceeds the timeline's intrinsic length the
// engine requests frames past the last tween. Seeking a paused GSAP
// timeline past its end can revert from()-tweens to their empty initial
// state, blanking the final poster. Clamp the MASTER seek to the
// timeline's full extent so it holds the final computed frame instead.
// Adapters still receive the raw `t` (their media may run longer).
// totalDuration() includes repeats; Infinity (infinite repeat) → no clamp.
let tlSeekTime = t;
if (typeof tl.totalDuration === "function") {
try {
const total = Number(tl.totalDuration());
if (Number.isFinite(total) && total > 0 && t > total) {
tlSeekTime = total;
}
} catch (err) {
swallow("runtime.init.transport.clampDuration", err);
}
}
try {
const total = Number(tl.totalDuration());
if (Number.isFinite(total) && total > 0 && t > total) {
tlSeekTime = total;
if (typeof tl.totalTime === "function") {
const redrawn = seekGsapTimeline(tl, tlSeekTime, suppressEvents);
const structure = renderCaptureSeekStarted
? undefined
: {
owner: tl,
version: `${compositionTimingRevision}:${tl.getChildren?.(false, true, true).length ?? 0}`,
};
if (!redrawn && !suppressEvents && !hasZeroDurationCallbackTween(tl, structure)) {
// The first seek is the only eventful one; the re-render only refreshes styles.
rerenderGsapTimelineAt(
{
totalTime: tl.totalTime.bind(tl),
totalDuration: tl.totalDuration?.bind(tl),
getChildren: tl.getChildren?.bind(tl),
},
tlSeekTime,
structure,
);
}
} else {
tl.seek(tlSeekTime, suppressEvents);
}
} catch (err) {
swallow("runtime.init.transport.clampDuration", err);
swallow("runtime.init.transport.seek", err);
}
// Root propagation cannot represent an authored child source offset or
// playback rate. Re-seek registered children below with their host's
// explicit source-time contract.
}
// A second `activateSiblingTimelines` used to follow this call. Dropping it is
// safe because nothing between frames READS a sibling's paused() — grepped over
// the deterministic adapters, syncTimedElementVisibility, the hf-timelines-built
// handler and __hfReseekGpu. It only ever moved the state the seek left behind.
seekStandaloneRegisteredTimelines(t, opts);
tweensRenderedThrough.time = Math.max(tweensRenderedThrough.time, t);
const pageAnimations = pageAnimationsForOnePass();
for (const adapter of state.deterministicAdapters) {
if (adapter.name === "gsap" && tl) continue;
try {
adapter.seek({ time: t, suppressEvents, pageAnimations });
} catch (err) {
swallow("runtime.init.transport.adapter", err);
}
}
try {
if (typeof tl.totalTime === "function") {
const redrawn = seekGsapTimeline(tl, tlSeekTime, suppressEvents);
const structure = renderCaptureSeekStarted
? undefined
: {
owner: tl,
version: `${compositionTimingRevision}:${tl.getChildren?.(false, true, true).length ?? 0}`,
};
if (!redrawn && !suppressEvents && !hasZeroDurationCallbackTween(tl, structure)) {
// The first seek is the only eventful one; the re-render only refreshes styles.
rerenderGsapTimelineAt(
{
totalTime: tl.totalTime.bind(tl),
totalDuration: tl.totalDuration?.bind(tl),
getChildren: tl.getChildren?.bind(tl),
},
tlSeekTime,
structure,
);
}
} else {
tl.seek(tlSeekTime, suppressEvents);
}
} catch (err) {
swallow("runtime.init.transport.seek", err);
}
// Root propagation cannot represent an authored child source offset or
// playback rate. Re-seek registered children below with their host's
// explicit source-time contract.
return pageAnimations;
} finally {
hideClipsAgain?.();
}
// A second `activateSiblingTimelines` used to follow this call. Dropping it is
// safe because nothing between frames READS a sibling's paused() — grepped over
// the deterministic adapters, syncTimedElementVisibility, the hf-timelines-built
// handler and __hfReseekGpu. It only ever moved the state the seek left behind.
seekStandaloneRegisteredTimelines(t, opts);
hideClipsAgain?.();
tweensRenderedThrough.time = Math.max(tweensRenderedThrough.time, t);
const pageAnimations = pageAnimationsForOnePass();
for (const adapter of state.deterministicAdapters) {
if (adapter.name === "gsap" && tl) continue;
try {
adapter.seek({ time: t, suppressEvents, pageAnimations });
} catch (err) {
swallow("runtime.init.transport.adapter", err);
}
}
return pageAnimations;
}
// True while the Studio is mid-drag on an element (the gesture marker is
@@ -4,6 +4,7 @@ import {
setTimedClipPaintVisibility,
setTimedClipVisibility,
showHiddenClips,
showHiddenClipFilters,
} from "./timedClipHide";
const mount = () => document.body.appendChild(document.createElement("div"));
@@ -97,4 +98,59 @@ describe("timed clip paint transitions", () => {
expect(clip.hasAttribute(CLIP_HIDDEN_ATTR)).toBe(false);
expect(gate.finish).toHaveBeenCalledOnce();
});
it("borrows only the filter and restores owned flags after nested calls and authored changes", () => {
const clip = mount();
setTimedClipVisibility(clip, "hidden");
const restore = showHiddenClipFilters();
expect(clip.style.visibility).toBe("hidden");
expect(clip.hasAttribute("data-hf-filter-sampling")).toBe(true);
const restoreNested = showHiddenClipFilters();
restoreNested();
expect(clip.hasAttribute("data-hf-filter-sampling")).toBe(true);
const scans = vi.fn().mockReturnValue([]);
Object.defineProperty(clip, "getAnimations", { value: scans });
setTimedClipPaintVisibility(clip, "visible");
expect(scans).not.toHaveBeenCalled();
clip.remove();
restore();
expect(scans).not.toHaveBeenCalled();
expect(clip.hasAttribute("data-hf-filter-sampling")).toBe(false);
expect(clip.style.visibility).toBe("visible");
clip.setAttribute("data-hf-filter-sampling", "");
restore();
expect(clip.hasAttribute("data-hf-filter-sampling")).toBe(true);
});
it("collects the whole batch before finishing any newly created transition", () => {
const clips = [mount(), mount()];
const order: string[] = [];
for (const [i, clip] of clips.entries()) {
setTimedClipVisibility(clip, "hidden");
const transition = {
transitionProperty: "filter",
effect: { target: clip },
finish: () => order.push(`finish${i}`),
};
Object.defineProperty(clip, "getAnimations", {
value: () => {
order.push(`read${i}`);
return clip.hasAttribute("data-hf-filter-sampling") ? [transition] : [];
},
});
}
const restore = showHiddenClipFilters();
expect(order).toEqual(["read0", "read1", "read0", "read1", "finish0", "finish1"]);
restore();
for (const clip of clips) expect(clip.hasAttribute("data-hf-filter-sampling")).toBe(false);
});
it("keeps an outer jump reveal visible when a nested reveal restores", () => {
const clip = mount();
setTimedClipVisibility(clip, "hidden");
const restore = showHiddenClips();
showHiddenClips()();
expect(clip.style.visibility).toBe("visible");
restore();
expect(clip.style.visibility).toBe("hidden");
});
});
+50 -15
View File
@@ -19,10 +19,12 @@ const SKIP_HIDDEN_IMAGES = `${SKIPPED_CLIP} img { display: none !important; }`;
const STUDIO_PREVIEW_MARK = `meta[name="${STUDIO_PREVIEW_MARK_META}"]`;
export const CLIP_HIDDEN_ATTR = "data-hf-clip-hidden";
const CONTENTS_ATTR = "data-hf-hidden-clip-contents";
const FILTER_SAMPLING_ATTR = "data-hf-filter-sampling";
const HIDDEN_CLIP = `[${CLIP_HIDDEN_ATTR}][style*="visibility: hidden"]`;
const FILTERED_CLIP = `${HIDDEN_CLIP}:not([${FILTER_SAMPLING_ATTR}])`;
// feColorMatrix can make hidden input opaque; filter the final group without changing layout.
const HIDE_HIDDEN_CLIP_CONTENTS = `${HIDDEN_CLIP} * { visibility: hidden !important; }
${HIDDEN_CLIP} { filter: opacity(0) !important; }`;
${FILTERED_CLIP} { filter: opacity(0) !important; }`;
function isHostFilterTransition(animation: Animation, el: StylableElement): boolean {
if (!("transitionProperty" in animation)) return false;
@@ -40,23 +42,33 @@ function isHostFilterTransition(animation: Animation, el: StylableElement): bool
);
}
function changeClipPaint(el: StylableElement, hidden: boolean, change: () => void): void {
const edge = el.matches(HIDDEN_CLIP) !== hidden;
const before =
edge && typeof el.getAnimations === "function" ? new Set(el.getAnimations()) : null;
change();
if (!before) return;
// Finish only new gate transitions; authored, descendant, and pseudo effects keep running.
for (const animation of el.getAnimations()) {
if (before.has(animation) || !isHostFilterTransition(animation, el)) continue;
try {
animation.finish();
} catch (err) {
swallow("runtime.timedClipHide.finishGateTransition", err);
type PaintChange = { el: StylableElement; hidden: boolean; change: () => void };
function changeClipPaintBatch(changes: PaintChange[]): void {
const before = changes.map(({ el, hidden }) =>
el.matches(FILTERED_CLIP) !== hidden && typeof el.getAnimations === "function"
? new Set(el.getAnimations())
: null,
);
for (const { change } of changes) change();
const after = changes.map(({ el }, i) => (before[i] ? el.getAnimations() : []));
for (const [i, { el }] of changes.entries()) {
// Finish only new gate transitions; authored, descendant, and pseudo effects keep running.
for (const animation of after[i] ?? []) {
if (before[i]?.has(animation) || !isHostFilterTransition(animation, el)) continue;
try {
animation.finish();
} catch (err) {
swallow("runtime.timedClipHide.finishGateTransition", err);
}
}
}
}
function changeClipPaint(el: StylableElement, hidden: boolean, change: () => void): void {
changeClipPaintBatch([{ el, hidden: hidden && !el.hasAttribute(FILTER_SAMPLING_ATTR), change }]);
}
/** null leaves Studio-stamped visibility authored while removing its runtime hide flag. */
export function setTimedClipVisibility(
el: StylableElement,
@@ -76,13 +88,36 @@ export function setTimedClipPaintVisibility(el: StylableElement, visibility: str
}
export function showHiddenClips(): () => void {
const hidden = Array.from(document.querySelectorAll<StylableElement>(`[${CLIP_HIDDEN_ATTR}]`));
const hidden = Array.from(document.querySelectorAll<StylableElement>(HIDDEN_CLIP));
for (const el of hidden) setTimedClipPaintVisibility(el, "visible");
return () => {
for (const el of hidden) setTimedClipPaintVisibility(el, "hidden");
};
}
export function showHiddenClipFilters(): () => void {
const hidden = Array.from(document.querySelectorAll<StylableElement>(FILTERED_CLIP));
changeClipPaintBatch(
hidden.map((el) => ({
el,
hidden: false,
change: () => el.setAttribute(FILTER_SAMPLING_ATTR, ""),
})),
);
let restored = false;
return () => {
if (restored) return;
restored = true;
changeClipPaintBatch(
hidden.map((el) => ({
el,
hidden: el.matches(HIDDEN_CLIP),
change: () => el.removeAttribute(FILTER_SAMPLING_ATTR),
})),
);
};
}
type FirstPassWindow = Window & {
__hfFirstPassHidden?: boolean;
__hyperframeRuntimeBootstrapped?: boolean;
@@ -240,6 +240,156 @@ describe("core runtime browser contract", () => {
}
});
it.each([1, 2])(
"samples a stylesheet-only filter endpoint when its tween starts at %ss",
async (fromAt) => {
const sequential = await browser.newPage();
const reference = await browser.newPage();
try {
for (const target of [sequential, reference]) {
await target.setViewport({ width: 320, height: 180 });
await target.setContent(
`<style>body{margin:0}#fade{position:absolute;width:100px;height:80px;background:red;filter:opacity(1)}</style><div data-composition-id="root" data-duration="6" data-width="320" data-height="180"><div id="fade" class="clip" data-start="2" data-duration="3"></div></div>`,
);
}
await sequential.addScriptTag({
path: resolve(import.meta.dirname, "../../../core/node_modules/gsap/dist/gsap.min.js"),
});
await sequential.addScriptTag({
content: `window.__timelines={root:gsap.timeline({paused:true}).from("#fade",{filter:"opacity(0)",duration:1,immediateRender:false,lazy:false,ease:"none"},${fromAt})};`,
});
await addRuntime(sequential);
const samples = await sequential.evaluate(() => {
const records = [];
for (let frame = 0; frame <= 90; frame++) {
window.__player!.renderSeek!(frame / 30, { exact: true });
if ([59, 60, 75, 90].includes(frame)) {
const clip = document.getElementById("fade")!;
records.push({
frame,
visibility: clip.style.visibility,
filter: getComputedStyle(clip).filter,
});
}
}
return records;
});
expect(samples).toEqual([
{ frame: 59, visibility: "hidden", filter: "opacity(0)" },
{ frame: 60, visibility: "visible", filter: fromAt === 1 ? "opacity(1)" : "opacity(0)" },
{
frame: 75,
visibility: "visible",
filter: fromAt === 1 ? "opacity(1)" : "opacity(0.5)",
},
{ frame: 90, visibility: "visible", filter: "opacity(1)" },
]);
expect(Buffer.from(await sequential.screenshot())).toEqual(
Buffer.from(await reference.screenshot()),
);
} finally {
await sequential.close();
await reference.close();
}
},
);
it("samples stylesheet filters in source-offset standalone timelines before clip activation", async () => {
const child = await browser.newPage();
try {
await child.setContent(
`<style>#fade{filter:opacity(1)}</style><div data-composition-id="root" data-duration="6" data-width="320" data-height="180"><div data-composition-id="child" data-start="0" data-duration="6" data-playback-start="1"><div id="fade" data-start="2" data-duration="3"></div></div></div>`,
);
await child.addScriptTag({
path: resolve(import.meta.dirname, "../../../core/node_modules/gsap/dist/gsap.min.js"),
});
await child.addScriptTag({
content: `window.__timelines={root:gsap.timeline({paused:true}).to({}, {duration:6}),child:gsap.timeline({paused:true}).from("#fade",{filter:"opacity(0)",duration:1,immediateRender:false,lazy:false,ease:"none"},2)};`,
});
await addRuntime(child);
const result = await child.evaluate(() => {
for (let frame = 0; frame <= 90; frame++)
window.__player!.renderSeek!(frame / 30, { exact: true });
return {
filter: getComputedStyle(document.getElementById("fade")!).filter,
flags: document.querySelectorAll("[data-hf-filter-sampling]").length,
};
});
expect(result).toEqual({ filter: "opacity(1)", flags: 0 });
} finally {
await child.close();
}
});
it("keeps filter sampling available through adapter seeks and restores it after errors", async () => {
const adapted = await browser.newPage();
try {
await adapted.setContent(
`<style>#fade{filter:opacity(1)}</style><div data-composition-id="root" data-duration="6" data-width="320" data-height="180"><div id="fade" data-start="2" data-duration="3"></div></div>`,
);
await adapted.addScriptTag({
content: `window.samples=[];window.__hfAnime=[{pause(){},play(){},seek(ms){if(ms>=1000){const el=document.getElementById("fade");window.samples.push({filter:getComputedStyle(el).filter,visibility:el.style.visibility});throw new Error("authored adapter failure");}}}];`,
});
await addRuntime(adapted);
const result = await adapted.evaluate(() => {
for (let frame = 0; frame <= 45; frame++)
window.__player!.renderSeek!(frame / 30, { exact: true });
return {
samples: (window as unknown as { samples: unknown[] }).samples,
flags: document.querySelectorAll("[data-hf-filter-sampling]").length,
filter: getComputedStyle(document.getElementById("fade")!).filter,
};
});
expect(result.samples.length).toBeGreaterThan(0);
for (const sample of result.samples)
expect(sample).toEqual({ filter: "opacity(1)", visibility: "hidden" });
expect(result.flags).toBe(0);
expect(result.filter).toBe("opacity(0)");
} finally {
await adapted.close();
}
});
it("keeps Studio future images unfetched during sequential filter sampling", async () => {
const preview = await browser.newPage();
const hits: string[] = [];
try {
await preview.setRequestInterception(true);
preview.on("request", (request) => {
if (request.url().startsWith("https://assets.invalid/")) {
hits.push(request.url());
void request.respond({
status: 200,
contentType: "image/png",
body: Buffer.from(PNG_1PX, "base64"),
});
} else void request.continue();
});
await preview.setContent(
`<meta name="hyperframes-studio-preview"><style>.clip{position:absolute;width:100px;height:80px;filter:opacity(1)}</style><div data-composition-id="root" data-duration="30" data-width="320" data-height="180"><div class="clip" data-start="1" data-duration="4"><img id="near" loading="lazy"></div><div class="clip" data-start="20" data-duration="2"><img id="far" loading="lazy"></div></div>`,
);
await addRuntime(preview);
await preview.evaluate(() => {
for (const id of ["near", "far"])
(document.getElementById(id) as HTMLImageElement).src =
`https://assets.invalid/${id}.png`;
for (let frame = 0; frame <= 90; frame++)
window.__player!.renderSeek!(frame / 30, { exact: true });
});
await preview.waitForFunction(
() => (document.getElementById("near") as HTMLImageElement).naturalWidth > 0,
);
const far = await preview.evaluate(() => ({
display: getComputedStyle(document.getElementById("far")!).display,
width: (document.getElementById("far") as HTMLImageElement).naturalWidth,
}));
expect(hits).toEqual(["https://assets.invalid/near.png"]);
expect(far).toEqual({ display: "none", width: 0 });
} finally {
await preview.close();
}
});
it("leaves existing author filter, clip-path and transform transitions running", async () => {
const authorPage = await browser.newPage();
try {