Skip to content

Commit b5ba4dc

Browse files
fix: report HDR auto-promotion
Report HDR auto-promotion consistently from the render media set, including remote media, and make its regression coverage portable across supported paths. Co-authored-by: miguel.sierra <[email protected]>
1 parent edb6e87 commit b5ba4dc

14 files changed

Lines changed: 431 additions & 34 deletions

File tree

‎packages/cli/src/commands/check.test.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,7 @@ function dependencies(
268268
runtime?: CheckFinding[];
269269
writeSnapshot?: CheckDependencies["writeSnapshot"];
270270
captureFindingCrops?: CheckDependencies["captureFindingCrops"];
271+
inspectHdrAutoPromotion?: NonNullable<CheckDependencies["inspectHdrAutoPromotion"]>;
271272
} = {},
272273
): { deps: CheckDependencies; runBrowserCheck: ReturnType<typeof vi.fn> } {
273274
const runBrowserCheck = vi.fn(
@@ -292,6 +293,7 @@ function dependencies(
292293
),
293294
),
294295
captureFindingCrops: options.captureFindingCrops ?? vi.fn(async () => []),
296+
inspectHdrAutoPromotion: options.inspectHdrAutoPromotion ?? vi.fn(async () => null),
295297
};
296298
return { deps, runBrowserCheck };
297299
}
@@ -423,6 +425,45 @@ it("preserves --json after bare --frame-check", async () => {
423425
expect(log).toHaveBeenCalledWith(expect.stringContaining('"ok"'));
424426
});
425427

428+
it("includes local HDR auto-promotion attribution in --json output", async () => {
429+
const { report } = await runScenario(
430+
fakeDriver(),
431+
{},
432+
{
433+
inspectHdrAutoPromotion: vi.fn(async () => ({
434+
triggeringAsset: "assets/source-hdr.mp4",
435+
output: { colorSpace: "BT.2020", codec: "HEVC Main10" } as const,
436+
})),
437+
},
438+
);
439+
const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
440+
const command = createCheckCommand({
441+
resolveProject: () => PROJECT,
442+
runPipeline: vi.fn(async () => report),
443+
withMeta: (value) => value,
444+
});
445+
446+
await runCommand(command, { rawArgs: ["--json"] });
447+
448+
expect(log).toHaveBeenCalledTimes(1);
449+
expect(JSON.parse(String(log.mock.calls[0]?.[0])).hdr.autoPromotion).toEqual({
450+
triggeringAsset: "assets/source-hdr.mp4",
451+
output: { colorSpace: "BT.2020", codec: "HEVC Main10" },
452+
});
453+
});
454+
455+
it("distinguishes unavailable HDR inspection from no promotion", async () => {
456+
const { report } = await runScenario(
457+
fakeDriver(),
458+
{},
459+
{
460+
inspectHdrAutoPromotion: vi.fn(async () => Promise.reject(new Error("ffprobe unavailable"))),
461+
},
462+
);
463+
464+
expect(report.hdr).toEqual({ autoPromotion: null, inspection: "unavailable" });
465+
});
466+
426467
it("threads --no-proxy into the browser check options", async () => {
427468
const { report } = await runScenario(fakeDriver());
428469
const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
@@ -922,6 +963,7 @@ function reportWithFindings(overrides: Partial<CheckReport> = {}): CheckReport {
922963
},
923964
motion: { ...emptySection(), enabled: false, samples: 0 },
924965
contrast: { ...emptySection(), enabled: true, samples: [], checked: 0, passed: 0 },
966+
hdr: { autoPromotion: null, inspection: "available" },
925967
snapshots: { enabled: false, files: [], times: [], findingFiles: [] },
926968
...overrides,
927969
};

‎packages/cli/src/utils/checkPipeline.ts‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ import {
2323
type MotionFrame,
2424
} from "./motionAudit.js";
2525
import { findMotionSpec, readMotionSpec, type MotionAssertion } from "./motionSpec.js";
26+
import { inspectHdrAutoPromotion } from "./hdrPromotion.js";
2627
import { normalizeErrorMessage } from "./errorMessage.js";
2728
import {
2829
parseColorRGBA,
@@ -1145,8 +1146,24 @@ export async function runCheckPipeline(
11451146
});
11461147

11471148
const lint = buildLintSection(lintResult);
1149+
let hdrPromotion: CheckReport["hdr"]["autoPromotion"] = null;
1150+
let hdrInspection: CheckReport["hdr"]["inspection"] = "available";
1151+
try {
1152+
hdrPromotion = await (dependencies.inspectHdrAutoPromotion ?? inspectHdrAutoPromotion)(project);
1153+
} catch {
1154+
hdrInspection = "unavailable";
1155+
}
11481156
if (shouldBlockRender(true, false, lintResult.totalErrors, lintResult.totalWarnings)) {
1149-
return buildReport(options, lint, emptyBrowserResult(), { kind: "none" }, [], []);
1157+
return buildReport(
1158+
options,
1159+
lint,
1160+
emptyBrowserResult(),
1161+
{ kind: "none" },
1162+
[],
1163+
[],
1164+
hdrPromotion,
1165+
hdrInspection,
1166+
);
11501167
}
11511168

11521169
const motion = dependencies.resolveMotionSpec(project.dir);
@@ -1173,7 +1190,16 @@ export async function runCheckPipeline(
11731190
const snapshotFiles = options.snapshots
11741191
? await writeContrastSnapshots(dependencies, project.dir, browser)
11751192
: [];
1176-
const report = buildReport(options, lint, browser, motion, specFindings, snapshotFiles);
1193+
const report = buildReport(
1194+
options,
1195+
lint,
1196+
browser,
1197+
motion,
1198+
specFindings,
1199+
snapshotFiles,
1200+
hdrPromotion,
1201+
hdrInspection,
1202+
);
11771203
return options.snapshots
11781204
? await withFindingCrops(dependencies, project, options, report)
11791205
: report;
@@ -1353,6 +1379,8 @@ function buildReport(
13531379
motion: MotionSpecResolution,
13541380
extraMotionFindings: CheckFinding[],
13551381
snapshotFiles: string[],
1382+
hdrPromotion: CheckReport["hdr"]["autoPromotion"] = null,
1383+
hdrInspection: CheckReport["hdr"]["inspection"] = "available",
13561384
): CheckReport {
13571385
const layout = shapeLayoutSection(browser.layoutIssues, browser, options);
13581386
const shapedMotion = shapeLayoutFindings(browser.motionIssues, options);
@@ -1391,6 +1419,7 @@ function buildReport(
13911419
checked: browser.contrastChecked,
13921420
passed: browser.contrastPassed,
13931421
},
1422+
hdr: { autoPromotion: hdrPromotion, inspection: hdrInspection },
13941423
snapshots: {
13951424
enabled: options.snapshots,
13961425
files: snapshotFiles,
@@ -1595,4 +1624,5 @@ const DEFAULT_DEPENDENCIES: CheckDependencies = {
15951624
runBrowserCheck,
15961625
writeSnapshot,
15971626
captureFindingCrops,
1627+
inspectHdrAutoPromotion,
15981628
};

‎packages/cli/src/utils/checkTypes.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import type { Canvas, MotionFrame } from "./motionAudit.js";
44
import type { MotionSpec } from "./motionSpec.js";
55
import type { ProjectDir } from "./project.js";
66
import type { BrowserGpuMode } from "../browser/gpuPolicy.js";
7+
import type { HdrAutoPromotion } from "@hyperframes/engine";
78

89
export interface CheckOptions {
910
samples: number;
@@ -282,6 +283,7 @@ export interface CheckReport {
282283
checked: number;
283284
passed: number;
284285
};
286+
hdr: { autoPromotion: HdrAutoPromotion | null; inspection: "available" | "unavailable" };
285287
snapshots: { enabled: boolean; files: string[]; times: number[]; findingFiles: string[] };
286288
}
287289

@@ -304,6 +306,7 @@ export interface CheckDependencies {
304306
options: CheckOptions,
305307
requests: CheckFindingCropRequest[],
306308
): Promise<string[]>;
309+
inspectHdrAutoPromotion?(project: ProjectDir): Promise<CheckReport["hdr"]["autoPromotion"]>;
307310
}
308311

309312
export function rectToBbox(rect: {
Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
import { describe, expect, it, vi } from "vitest";
2+
import type { VideoColorSpace } from "@hyperframes/engine";
3+
import { resolveProjectRelativeSrc } from "@hyperframes/engine";
4+
import { inspectHdrAutoPromotion } from "./hdrPromotion.js";
5+
6+
const PROJECT = { dir: "/project", name: "hdr-check", indexPath: "/project/index.html" };
7+
const HDR: VideoColorSpace = {
8+
colorTransfer: "smpte2084",
9+
colorPrimaries: "bt2020",
10+
colorSpace: "bt2020nc",
11+
};
12+
const SDR: VideoColorSpace = {
13+
colorTransfer: "bt709",
14+
colorPrimaries: "bt709",
15+
colorSpace: "bt709",
16+
};
17+
18+
function metadata(colorSpace: VideoColorSpace, videoCodec = "hevc") {
19+
return {
20+
durationSeconds: 1,
21+
videoStreamDurationSeconds: 1,
22+
width: 1920,
23+
height: 1080,
24+
fps: 30,
25+
videoCodec,
26+
hasAudio: false,
27+
isVFR: false,
28+
hasAlpha: false,
29+
colorSpace,
30+
};
31+
}
32+
33+
function bundledMedia(videos: string[], images: string[]) {
34+
return {
35+
bundleHtml: vi.fn(async () => "<html>bundled sub-composition</html>"),
36+
collectMedia: vi.fn(() => ({
37+
videos: videos.map((src) => ({ src })),
38+
images: images.map((src) => ({ src })),
39+
})),
40+
};
41+
}
42+
43+
describe("inspectHdrAutoPromotion", () => {
44+
it("reports the local HDR asset that promotes automatic output", async () => {
45+
const assetPath = resolveProjectRelativeSrc("assets/source-hdr.mp4", PROJECT.dir, PROJECT.dir);
46+
const extractMetadata = vi.fn(async () => metadata(HDR));
47+
48+
await expect(
49+
inspectHdrAutoPromotion(
50+
PROJECT,
51+
extractMetadata,
52+
bundledMedia(["assets/source-hdr.mp4?token=secret#preview"], []),
53+
),
54+
).resolves.toEqual({
55+
triggeringAsset: "assets/source-hdr.mp4",
56+
output: { colorSpace: "BT.2020", codec: "HEVC Main10" },
57+
});
58+
expect(extractMetadata).toHaveBeenCalledOnce();
59+
expect(extractMetadata).toHaveBeenCalledWith(assetPath);
60+
});
61+
62+
it("reports an active remote HDR video from the bundled render media", async () => {
63+
const remote = "https://media.example/remote-hdr.mp4?token=secret";
64+
const extractMetadata = vi.fn(async () => metadata(HDR));
65+
66+
await expect(
67+
inspectHdrAutoPromotion(PROJECT, extractMetadata, bundledMedia([remote], [])),
68+
).resolves.toEqual({
69+
triggeringAsset: "https://media.example/remote-hdr.mp4",
70+
output: { colorSpace: "BT.2020", codec: "HEVC Main10" },
71+
});
72+
expect(extractMetadata).toHaveBeenCalledWith(remote);
73+
});
74+
75+
it("uses the first HDR video before an HDR image and still inspects images", async () => {
76+
const firstVideo = "https://media.example/first-hdr-video.mp4?token=secret";
77+
const image = "assets/fallback-hdr-image.png";
78+
const extractMetadata = vi.fn(async (src: string) =>
79+
metadata(src.replaceAll("\\", "/").endsWith("/assets/sdr.mp4") ? SDR : HDR),
80+
);
81+
82+
await expect(
83+
inspectHdrAutoPromotion(
84+
PROJECT,
85+
extractMetadata,
86+
bundledMedia(["assets/sdr.mp4", firstVideo], [image]),
87+
),
88+
).resolves.toMatchObject({ triggeringAsset: "https://media.example/first-hdr-video.mp4" });
89+
expect(extractMetadata).toHaveBeenCalledWith(
90+
resolveProjectRelativeSrc("assets/sdr.mp4", PROJECT.dir, PROJECT.dir),
91+
);
92+
expect(extractMetadata).toHaveBeenCalledWith(firstVideo);
93+
expect(extractMetadata).toHaveBeenCalledWith(
94+
resolveProjectRelativeSrc("assets/fallback-hdr-image.png", PROJECT.dir, PROJECT.dir),
95+
);
96+
});
97+
98+
it("reports an HDR image when no HDR video is present", async () => {
99+
const extractMetadata = vi.fn(async () =>
100+
metadata(
101+
{ colorTransfer: "arib-std-b67", colorPrimaries: "bt2020", colorSpace: "bt2020nc" },
102+
"png",
103+
),
104+
);
105+
106+
await expect(
107+
inspectHdrAutoPromotion(PROJECT, extractMetadata, bundledMedia([], ["assets/hdr.png"])),
108+
).resolves.toMatchObject({ triggeringAsset: "assets/hdr.png" });
109+
});
110+
});
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import {
2+
extractMediaMetadata,
3+
findHdrAutoPromotion,
4+
resolveProjectRelativeSrc,
5+
type HdrAutoPromotion,
6+
} from "@hyperframes/engine";
7+
import type { ProjectDir } from "./project.js";
8+
import { loadProducer } from "./producer.js";
9+
10+
type ExtractMetadata = typeof extractMediaMetadata;
11+
type MediaSource = { src: string };
12+
type RenderMedia = { videos: readonly MediaSource[]; images: readonly MediaSource[] };
13+
14+
interface InspectHdrAutoPromotionDependencies {
15+
bundleHtml(projectDir: string): Promise<string>;
16+
collectMedia(html: string): RenderMedia | Promise<RenderMedia>;
17+
}
18+
19+
async function bundleProjectHtml(projectDir: string): Promise<string> {
20+
const { bundleToSingleHtml } = await import("@hyperframes/core/compiler");
21+
return bundleToSingleHtml(projectDir);
22+
}
23+
24+
async function collectBundledRenderMedia(html: string): Promise<RenderMedia> {
25+
const producer = (await loadProducer()) as {
26+
collectRenderMedia?: (source: string) => RenderMedia;
27+
};
28+
if (!producer.collectRenderMedia) throw new Error("Render media collector unavailable");
29+
return producer.collectRenderMedia(html);
30+
}
31+
32+
const DEFAULT_DEPENDENCIES: InspectHdrAutoPromotionDependencies = {
33+
bundleHtml: bundleProjectHtml,
34+
collectMedia: collectBundledRenderMedia,
35+
};
36+
37+
export async function inspectHdrAutoPromotion(
38+
project: ProjectDir,
39+
extractMetadata: ExtractMetadata = extractMediaMetadata,
40+
dependencies: InspectHdrAutoPromotionDependencies = DEFAULT_DEPENDENCIES,
41+
): Promise<HdrAutoPromotion | null> {
42+
const assets: Array<{
43+
asset: string;
44+
colorSpace: Awaited<ReturnType<typeof extractMediaMetadata>>["colorSpace"];
45+
}> = [];
46+
const media = await dependencies.collectMedia(await dependencies.bundleHtml(project.dir));
47+
for (const { src } of [...media.videos, ...media.images]) {
48+
const path = /^https?:\/\//i.test(src)
49+
? src
50+
: resolveProjectRelativeSrc(src, project.dir, project.dir);
51+
try {
52+
assets.push({
53+
asset: src,
54+
colorSpace: (await extractMetadata(path)).colorSpace,
55+
});
56+
} catch {
57+
continue;
58+
}
59+
}
60+
return findHdrAutoPromotion(assets);
61+
}

‎packages/engine/src/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -400,9 +400,14 @@ export {
400400
detectTransfer,
401401
getHdrEncoderColorParams,
402402
analyzeCompositionHdr,
403+
findHdrAutoPromotion,
404+
formatHdrAutoPromotionWarning,
405+
sanitizeHdrAutoPromotionAsset,
403406
DEFAULT_HDR10_MASTERING,
407+
HDR_AUTO_PROMOTION_PIPELINE,
404408
type HdrTransfer,
405409
type HdrEncoderColorParams,
410+
type HdrAutoPromotion,
406411
type CompositionHdrInfo,
407412
type HdrMasteringMetadata,
408413
} from "./utils/hdr.js";

0 commit comments

Comments
 (0)