From 5377b756b5d1fcf06171a133b715003f05ff71c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Thu, 5 Nov 2026 16:21:24 +0000 Subject: [PATCH] fix(core): snapshot and preview show a clip on the frame render shows it (#7238) * fix(core): snapshot and preview show a clip on the frame render shows it * fix(cli): snapshot pulls a video's frame on the same on-screen rule * refactor(cli): drop two doc lines the names already carry --- .../snapshot.heldBoundary.browser.test.ts | 65 +++++++++++++++++++ packages/cli/src/commands/snapshot.test.ts | 15 +++++ packages/cli/src/commands/snapshot.ts | 25 +++++-- .../core/src/compositionReadiness.test.ts | 1 - packages/core/src/compositionReadiness.ts | 1 - packages/core/src/index.ts | 7 +- packages/core/src/runtime/clipWindow.ts | 13 ++++ .../core/src/runtime/frameSources.test.ts | 19 +----- packages/core/src/runtime/frameSources.ts | 17 ++--- packages/core/src/runtime/init.ts | 2 - packages/core/src/runtime/timeline.test.ts | 33 +++++++++- packages/core/src/runtime/timeline.ts | 15 ++--- 12 files changed, 168 insertions(+), 45 deletions(-) create mode 100644 packages/cli/src/commands/snapshot.heldBoundary.browser.test.ts diff --git a/packages/cli/src/commands/snapshot.heldBoundary.browser.test.ts b/packages/cli/src/commands/snapshot.heldBoundary.browser.test.ts new file mode 100644 index 0000000000..91045f4e54 --- /dev/null +++ b/packages/cli/src/commands/snapshot.heldBoundary.browser.test.ts @@ -0,0 +1,65 @@ +import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import sharp from "sharp"; +import { afterAll, expect, it, vi } from "vitest"; +import snapshotCommand from "./snapshot.js"; + +const dir = mkdtempSync(join(tmpdir(), "hf-snapshot-held-boundary-")); + +afterAll(() => rmSync(dir, { recursive: true, force: true })); + +// A title held across two back-to-back clips; the second starts a hair past 100 s, as a start chained after a media +// clip's measured length lands. +writeFileSync( + join(dir, "index.html"), + ` +
+
+
+
+`, +); + +const redAtCentre = async (path: string) => { + const { data, info } = await sharp(path).raw().toBuffer({ resolveWithObject: true }); + const at = + (Math.floor(info.height / 2) * info.width + Math.floor(info.width / 2)) * info.channels; + return data[at]! > 200 && data[at + 1]! < 60; +}; + +// fails without the fix: the still at exactly 100 s came out black, while 98 s, 102 s and the render show the title. +it("keeps a title held across back-to-back clips on screen at the exact second the second clip takes over", async () => { + const log = vi.spyOn(console, "log").mockImplementation(() => undefined); + vi.spyOn(console, "error").mockImplementation(() => undefined); + vi.spyOn(console, "warn").mockImplementation(() => undefined); + try { + await snapshotCommand.run?.({ + args: { + dir, + at: "98,100,102", + end: false, + json: true, + output: join(dir, "out"), + describe: "false", + "browser-gpu": false, + }, + } as never); + const { frames } = JSON.parse(String(log.mock.calls.at(-1)?.[0])) as { + frames: { path: string; time: number }[]; + }; + const shown = await Promise.all( + frames.map(async (frame) => [frame.time, await redAtCentre(frame.path)]), + ); + expect(shown).toEqual([ + [98, true], + [100, true], + [102, true], + ]); + } finally { + vi.restoreAllMocks(); + } +}, 120_000); diff --git a/packages/cli/src/commands/snapshot.test.ts b/packages/cli/src/commands/snapshot.test.ts index 55a8ea54d6..306436bd6d 100644 --- a/packages/cli/src/commands/snapshot.test.ts +++ b/packages/cli/src/commands/snapshot.test.ts @@ -322,6 +322,21 @@ describe("snapshot video overlays and the blurred frame", () => { }); describe("resolveSnapshotVideoFrameTime", () => { + // fails without the fix: the element showed at 100 s on render's window, but no frame was pulled for its video. + it("pulls a frame for a video starting a hair past 100 s at exactly 100 s, as render does", () => { + expect( + resolveSnapshotVideoFrameTime({ + globalTime: 100, + clipStart: 100.00002, + clipDuration: 10, + relativeTime: -0.00002, + sourceDuration: 10, + compositionDuration: 110, + fps: 30, + }), + ).toBe(0); + }); + it("holds a clip ending with the composition on its last decodable frame", () => { expect( resolveSnapshotVideoFrameTime({ diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts index d1195e4a70..548425500a 100644 --- a/packages/cli/src/commands/snapshot.ts +++ b/packages/cli/src/commands/snapshot.ts @@ -70,12 +70,14 @@ import { } from "../capture/captureCompositionFrame.js"; import { firstFrameColourArgs, + exportClipWindow, hdrToSdrToneMapFilter, keyframeTransferArgs, parseKeyframeTransfers, type ToneMapFrameColour, - isClipVisibleAt, + isClipOnScreenAt, isInClipWindow, + parseFpsWithDefault, MEDIA_RENDER_ID_ATTR, parseFirstFrameColour, readsKeyframeTransfers, @@ -84,6 +86,7 @@ import { timeAtSourceTime, type RateSpec, } from "@hyperframes/core"; +import { parseHTML } from "linkedom"; import { resolveProject } from "../utils/project.js"; import { definitiveEntryMismatchComposition, @@ -250,15 +253,18 @@ export function resolveSnapshotVideoFrameTime(input: { relativeTime: number; sourceDuration: number; compositionDuration: number; + fps?: number; }): number | null { const { globalTime, clipStart, clipDuration, sourceDuration, compositionDuration } = input; + const fps = input.fps ?? 30; const clipEnd = clipStart + clipDuration; - if (!isClipVisibleAt(globalTime, clipStart, clipEnd, compositionDuration)) return null; + if (!isClipOnScreenAt(globalTime, clipStart, clipEnd, fps, compositionDuration)) return null; + const onFrames = exportClipWindow(clipStart, clipEnd, fps); const relativeTime = globalTime < clipStart ? Math.max(0, input.relativeTime) : input.relativeTime; if (relativeTime < 0) return null; const pastSource = sourceDuration > 0 && relativeTime >= sourceDuration; - if (isInClipWindow(globalTime, clipStart, clipEnd) && !pastSource) return relativeTime; + if (isInClipWindow(globalTime, onFrames.start, onFrames.end) && !pastSource) return relativeTime; const sourceEnd = sourceDuration > 0 ? sourceDuration : relativeTime; return Math.max(0, Math.min(relativeTime, sourceEnd - 1 / 30)); @@ -312,6 +318,7 @@ export function activeVideoAt( candidate: SnapshotVideoCandidate, time: number, compositionDuration: number, + fps: number, ) { const start = resolveSnapshotVideoClipStart(candidate); const playbackRate = resolveSnapshotVideoRateSpec(candidate); @@ -337,6 +344,7 @@ export function activeVideoAt( relativeTime: relTime, sourceDuration: candidate.srcDuration, compositionDuration, + fps, }); return frameTime === null ? null @@ -901,6 +909,12 @@ export function computeSnapshotTimes( return { times: times.map(round), appendedTail: false }; } +function compositionFps(html: string): number { + const root = parseHTML(html).document.querySelector("[data-composition-id]"); + const declared = parseFpsWithDefault(root?.getAttribute("data-fps") ?? undefined); + return declared.ok ? declared.value.num / declared.value.den : 30; +} + export function serveCapturePage(projectDir: string, html: string, proxy: boolean | undefined) { return serveStaticProjectHtml(projectDir, html, undefined, [], proxy === true); } @@ -971,6 +985,7 @@ export async function captureSnapshots( console.warn(` ${c.warn("⚠")} ${swallowed}`); } const server = await serveCapturePage(projectDir, html, opts.autoProxy); + const fps = compositionFps(html); const heldVideoIds = localVideoRenderIds(html); const heldProbes = new Map>(); const heldHints = await heldVideoHints(projectDir, localVideos(html), heldProbes); @@ -1270,7 +1285,7 @@ export async function captureSnapshots( ); let unreadable = 0; const active = candidates.flatMap((candidate) => { - const video = activeVideoAt(candidate, time, duration); + const video = activeVideoAt(candidate, time, duration, fps); if (!video) return []; if (!candidate.id || !candidate.src) { unreadable += 1; @@ -1314,7 +1329,7 @@ export async function captureSnapshots( (opts.zoom ? (opts.zoomScale ?? DEFAULT_ZOOM_SCALE) : v.devicePixelRatio), ); const wantAt = (t: number): FrameWant | null => { - const shown = activeVideoAt(v, t, duration); + const shown = activeVideoAt(v, t, duration, fps); if (!shown) return null; const holdLastFrame = shown.srcDuration > 0 && shown.relTime >= shown.srcDuration - 1; diff --git a/packages/core/src/compositionReadiness.test.ts b/packages/core/src/compositionReadiness.test.ts index 3dc7c4cb13..6fcae14f08 100644 --- a/packages/core/src/compositionReadiness.test.ts +++ b/packages/core/src/compositionReadiness.test.ts @@ -97,7 +97,6 @@ describe("scanPendingCompositionAssets", () => { currentTime: 0, compositionDuration: Number.POSITIVE_INFINITY, canonicalFps: 30, - exportRenderSeek: false, timelineRegistry: {}, resolver, }); diff --git a/packages/core/src/compositionReadiness.ts b/packages/core/src/compositionReadiness.ts index efa4ebc957..e4f34ebe9a 100644 --- a/packages/core/src/compositionReadiness.ts +++ b/packages/core/src/compositionReadiness.ts @@ -67,7 +67,6 @@ function isActiveAtFirstFrame( currentTime: 0, compositionDuration: Number.POSITIVE_INFINITY, canonicalFps: 30, - exportRenderSeek: false, timelineRegistry, resolver, }) diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index d7a43d2bfb..d14eb1bc2d 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -397,7 +397,12 @@ export { // (verify:packed-manifests catches exactly that). export { createRuntimeStartTimeResolver } from "./runtime/startResolver.js"; // Also exposed via the ./runtime/clip-window subpath; re-exported here for the same dist-emit reason. -export { hasClipStarted, isClipVisibleAt, isInClipWindow } from "./runtime/clipWindow.js"; +export { + hasClipStarted, + isClipOnScreenAt, + isClipVisibleAt, + isInClipWindow, +} from "./runtime/clipWindow.js"; export { MEDIA_ELEMENT_LEAD_SECONDS, mediaElementTime } from "./runtime/mediaClock.js"; export { normalizePlaybackRate, diff --git a/packages/core/src/runtime/clipWindow.ts b/packages/core/src/runtime/clipWindow.ts index 7cf1f9106f..83ac024365 100644 --- a/packages/core/src/runtime/clipWindow.ts +++ b/packages/core/src/runtime/clipWindow.ts @@ -1,4 +1,5 @@ import { sameInstant } from "../clipFacts"; +import { exportClipWindow } from "../inline-scripts/parityContract"; export const hasClipStarted = (time: number, start: number) => time >= start || sameInstant(time, start); @@ -23,3 +24,15 @@ export const isClipVisibleAt = ( (hasClipStarted(time, start) && compositionDuration > 0 && end >= compositionDuration - TERMINAL_EPSILON_SECONDS); + +/** The one on-screen rule render, snapshot and preview share: edges a hair off a frame count as on it. */ +export const isClipOnScreenAt = ( + time: number, + start: number, + end: number, + fps: number, + compositionDuration: number, +): boolean => { + const snapped = exportClipWindow(start, end, fps); + return isClipVisibleAt(time, snapped.start, snapped.end, compositionDuration); +}; diff --git a/packages/core/src/runtime/frameSources.test.ts b/packages/core/src/runtime/frameSources.test.ts index f717fc0c2c..278d3781d8 100644 --- a/packages/core/src/runtime/frameSources.test.ts +++ b/packages/core/src/runtime/frameSources.test.ts @@ -14,13 +14,12 @@ function deferred() { } const adapters: ReturnType[] = []; -const adapter = (compositionDuration = 20, exportRenderSeek = false) => { +const adapter = (compositionDuration = 20) => { const runtime = createFrameSourceAdapter({ start: (element) => createRuntimeStartTimeResolver({}).resolveStartForElement(element, 0), duration: (element) => createRuntimeStartTimeResolver({}).resolveDurationForElement(element), compositionDuration: () => compositionDuration, canonicalFps: () => 30, - exportRenderSeek: () => exportRenderSeek, }); adapters.push(runtime); return runtime; @@ -293,10 +292,10 @@ describe("frame sources", () => { expect(render).toHaveBeenCalledTimes(1); }); - it("matches snapped export visibility at near-frame starts and ends", async () => { + it("shows a source on render's snapped window at near-frame starts and ends, in preview too", async () => { const render = vi.fn(); disposers.push(registerFrameSource({ element: mount("1.00001", "1"), render })); - const runtime = adapter(3, true); + const runtime = adapter(3); runtime.seek({ time: 1 }); await waitForSeekCompletion(); expect(render).toHaveBeenLastCalledWith(0, expect.any(AbortSignal)); @@ -308,18 +307,6 @@ describe("frame sources", () => { expect(render).toHaveBeenCalledTimes(2); }); - it("retains unsnapped authored timing during interactive preview", async () => { - const render = vi.fn(); - disposers.push(registerFrameSource({ element: mount("1.00001", "1"), render })); - const runtime = adapter(3); - runtime.seek({ time: 1 }); - await waitForSeekCompletion(); - expect(render).not.toHaveBeenCalled(); - runtime.seek({ time: 2 }); - await waitForSeekCompletion(); - expect(render).toHaveBeenCalledTimes(1); - }); - it("rejects invalid original ranges before registering a source", () => { const element = mount(); for (const sourceRange of [ diff --git a/packages/core/src/runtime/frameSources.ts b/packages/core/src/runtime/frameSources.ts index e765e2103b..3607b459af 100644 --- a/packages/core/src/runtime/frameSources.ts +++ b/packages/core/src/runtime/frameSources.ts @@ -1,8 +1,7 @@ -import { exportClipWindow } from "../inline-scripts/parityContract"; import { sourceTimeAt } from "../speedRamp"; import { readElementRateSpec, readMediaStart } from "./playbackRate"; import { registerSeekCompletion } from "./adapters/seek-dispatch"; -import { isClipVisibleAt } from "./clipWindow"; +import { isClipOnScreenAt } from "./clipWindow"; import type { RuntimeDeterministicAdapter } from "./types"; export interface FrameSource { @@ -93,7 +92,6 @@ export function createFrameSourceAdapter(timing: { duration: (element: Element) => number | null; compositionDuration: () => number; canonicalFps: () => number; - exportRenderSeek: () => boolean; }): RuntimeDeterministicAdapter { const owned = new Set(); let readySources: RegisteredSource[] = []; @@ -132,11 +130,14 @@ export function createFrameSourceAdapter(timing: { const start = timing.start(element); const duration = timing.duration(element); const end = start + (duration ?? Infinity); - const clipWindow = timing.exportRenderSeek() - ? exportClipWindow(start, end, timing.canonicalFps()) - : { start, end }; - if (!isClipVisibleAt(time, clipWindow.start, clipWindow.end, timing.compositionDuration())) - continue; + const onScreen = isClipOnScreenAt( + time, + start, + end, + timing.canonicalFps(), + timing.compositionDuration(), + ); + if (!onScreen) continue; const localTime = Math.max(0, time - start); const sourceTime = readMediaStart(element) + sourceTimeAt(readElementRateSpec(element), localTime); diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts index c3a0cb1e28..531f36d1e5 100644 --- a/packages/core/src/runtime/init.ts +++ b/packages/core/src/runtime/init.ts @@ -2941,7 +2941,6 @@ export function initSandboxRuntimeModular(): void { currentTime: time, compositionDuration, canonicalFps: state.canonicalFps, - exportRenderSeek: Boolean(window.__HF_EXPORT_RENDER_SEEK_CONFIG), timelineRegistry: window.__timelines ?? {}, resolver: timingResolverFor(true), }); @@ -5091,7 +5090,6 @@ export function initSandboxRuntimeModular(): void { duration: (element) => resolveDurationForElement(element), compositionDuration: () => getSafeTimelineDurationSeconds(state.capturedTimeline, 0), canonicalFps: () => state.canonicalFps, - exportRenderSeek: () => Boolean(window.__HF_EXPORT_RENDER_SEEK_CONFIG), }), createWaapiAdapter(), createCssAdapter({ diff --git a/packages/core/src/runtime/timeline.test.ts b/packages/core/src/runtime/timeline.test.ts index f14d868cb4..13c3251476 100644 --- a/packages/core/src/runtime/timeline.test.ts +++ b/packages/core/src/runtime/timeline.test.ts @@ -1,6 +1,10 @@ import { DEFAULT_IMAGE_TIMELINE_DURATION_SECONDS } from "@hyperframes/parsers/media-duration"; import { describe, it, expect, afterEach } from "vitest"; -import { collectRuntimeTimelinePayload, runtimeElementWindow } from "./timeline"; +import { + collectRuntimeTimelinePayload, + isRuntimeElementVisibleAt, + runtimeElementWindow, +} from "./timeline"; import { createRuntimeStartTimeResolver } from "./startResolver"; type TimelineTestWindow = Window & { @@ -1134,3 +1138,30 @@ describe("runtimeElementWindow", () => { }); }); }); + +describe("isRuntimeElementVisibleAt", () => { + afterEach(() => { + document.body.innerHTML = ""; + }); + + // fails without the fix: snapshot and preview read the authored seconds, so a title held across two clips whose + // second start sits a hair past 100 s went blank at exactly 100 s, the frame render shows it on. + it("puts a clip edge a hair off a frame on that frame for preview and snapshot, as render does", () => { + document.body.innerHTML = `
+
+
`; + const shownAt = (currentTime: number) => + ["held", "rest"].filter((id) => + isRuntimeElementVisibleAt(document.getElementById(id)!, { + currentTime, + compositionDuration: 110, + canonicalFps: 30, + timelineRegistry: {}, + resolver: createRuntimeStartTimeResolver({}), + }), + ); + expect(shownAt(99.875)).toEqual(["held"]); + expect(shownAt(100)).toEqual(["rest"]); + expect(shownAt(100.125)).toEqual(["rest"]); + }); +}); diff --git a/packages/core/src/runtime/timeline.ts b/packages/core/src/runtime/timeline.ts index 80c0cea1c1..aac2d0bd46 100644 --- a/packages/core/src/runtime/timeline.ts +++ b/packages/core/src/runtime/timeline.ts @@ -22,8 +22,7 @@ import { } from "./playbackRate"; import { resolveCssStackingContextId } from "./stackingContext"; import { createRuntimeStartTimeResolver } from "./startResolver"; -import { isClipVisibleAt } from "./clipWindow"; -import { exportClipWindow } from "../inline-scripts/parityContract"; +import { isClipOnScreenAt } from "./clipWindow"; import { isSceneLikeCompositionId } from "../slideshow/index.js"; import { COMPOSITION_CONTRACT_VERSION } from "../compositionContract.js"; import { runtimeProtocolMetadata } from "./protocol.js"; @@ -79,21 +78,17 @@ export function isRuntimeElementVisibleAt( currentTime: number; compositionDuration: number; canonicalFps: number; - exportRenderSeek: boolean; timelineRegistry: Record; resolver: ReturnType; }, ): boolean { const span = runtimeElementWindow(rawNode, options); if (!span) return false; - // Export seeks snap to frame boundaries; interactive visibility uses authored seconds. - const clipWindow = options.exportRenderSeek - ? exportClipWindow(span.start, span.end, options.canonicalFps) - : span; - return isClipVisibleAt( + return isClipOnScreenAt( options.currentTime, - clipWindow.start, - clipWindow.end, + span.start, + span.end, + options.canonicalFps, options.compositionDuration, ); }