Skip to content

Commit 09c04d0

Browse files
fix(cli): report automatic HDR promotion
Expose the existing automatic HDR promotion decision in `check --json` and emit one attributed WARN line during automatic HDR renders. Reuse the current HDR source classification so output selection and HDR flags are unchanged. Add regression coverage for JSON attribution and the single render warning. Co-authored-by: miguel.sierra <[email protected]>
1 parent edb6e87 commit 09c04d0

12 files changed

Lines changed: 354 additions & 32 deletions

File tree

‎.changes.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Changes
2+
3+
## Branch
4+
5+
bugfix/1787766784-prinfra664-hdr-promotion-reporting
6+
7+
## Files modified
8+
9+
- `packages/engine/src/utils/hdr.ts`, `packages/engine/src/index.ts`, and `packages/engine/src/utils/hdr.test.ts` — define, export, and test the canonical HDR auto-promotion report and warning format.
10+
- `packages/cli/src/utils/hdrPromotion.ts`, `packages/cli/src/utils/hdrPromotion.test.ts`, `packages/cli/src/utils/checkPipeline.ts`, `packages/cli/src/utils/checkTypes.ts`, and `packages/cli/src/commands/check.test.ts` — detect local HDR assets and include their triggering path plus BT.2020 / HEVC Main10 output in `check --json`.
11+
- `packages/producer/src/services/render/hdrMode.ts`, `packages/producer/src/services/render/hdrMode.test.ts`, and `packages/producer/src/services/renderOrchestrator.ts` — attribute automatic HDR promotion to the probed composition asset and emit one WARN line for a no-flag render.
12+
13+
## Why this is the right fix
14+
15+
Automatic HDR promotion already selected the correct pipeline, but its diagnostics did not expose which source triggered the decision and render logged the promotion only at INFO. The change reuses the existing HDR classification and native-source ID sets, so rendering behavior and flags are unchanged while CLI JSON and render logs carry the same actionable attribution.
16+
17+
## What I considered and rejected
18+
19+
Deriving the asset name from extracted temporary frame paths was rejected because those paths are implementation details and can no longer identify the authored composition source.
20+
21+
## Tests
22+
23+
- `bunx vitest run packages/engine/src/utils/hdr.test.ts packages/cli/src/utils/hdrPromotion.test.ts packages/cli/src/commands/check.test.ts packages/producer/src/services/render/hdrMode.test.ts` — 88 passed.
24+
- `bun run --cwd packages/engine typecheck` — passed.
25+
- `bun run --cwd packages/cli typecheck` — passed.
26+
- `bun run --cwd packages/producer typecheck` — passed.
27+
- `bunx oxlint <11 touched files>` — 0 warnings, 0 errors.
28+
- `bunx oxfmt --check <11 touched files>` — passed.
29+
- `bun run check:package-subpaths` — passed.

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

Lines changed: 30 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,33 @@ 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+
426455
it("threads --no-proxy into the browser check options", async () => {
427456
const { report } = await runScenario(fakeDriver());
428457
const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
@@ -922,6 +951,7 @@ function reportWithFindings(overrides: Partial<CheckReport> = {}): CheckReport {
922951
},
923952
motion: { ...emptySection(), enabled: false, samples: 0 },
924953
contrast: { ...emptySection(), enabled: true, samples: [], checked: 0, passed: 0 },
954+
hdr: { autoPromotion: null },
925955
snapshots: { enabled: false, files: [], times: [], findingFiles: [] },
926956
...overrides,
927957
};

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

Lines changed: 20 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,14 @@ export async function runCheckPipeline(
11451146
});
11461147

11471148
const lint = buildLintSection(lintResult);
1149+
let hdrPromotion: CheckReport["hdr"]["autoPromotion"] = null;
1150+
try {
1151+
hdrPromotion = await (dependencies.inspectHdrAutoPromotion ?? inspectHdrAutoPromotion)(project);
1152+
} catch {
1153+
hdrPromotion = null;
1154+
}
11481155
if (shouldBlockRender(true, false, lintResult.totalErrors, lintResult.totalWarnings)) {
1149-
return buildReport(options, lint, emptyBrowserResult(), { kind: "none" }, [], []);
1156+
return buildReport(options, lint, emptyBrowserResult(), { kind: "none" }, [], [], hdrPromotion);
11501157
}
11511158

11521159
const motion = dependencies.resolveMotionSpec(project.dir);
@@ -1173,7 +1180,15 @@ export async function runCheckPipeline(
11731180
const snapshotFiles = options.snapshots
11741181
? await writeContrastSnapshots(dependencies, project.dir, browser)
11751182
: [];
1176-
const report = buildReport(options, lint, browser, motion, specFindings, snapshotFiles);
1183+
const report = buildReport(
1184+
options,
1185+
lint,
1186+
browser,
1187+
motion,
1188+
specFindings,
1189+
snapshotFiles,
1190+
hdrPromotion,
1191+
);
11771192
return options.snapshots
11781193
? await withFindingCrops(dependencies, project, options, report)
11791194
: report;
@@ -1353,6 +1368,7 @@ function buildReport(
13531368
motion: MotionSpecResolution,
13541369
extraMotionFindings: CheckFinding[],
13551370
snapshotFiles: string[],
1371+
hdrPromotion: CheckReport["hdr"]["autoPromotion"] = null,
13561372
): CheckReport {
13571373
const layout = shapeLayoutSection(browser.layoutIssues, browser, options);
13581374
const shapedMotion = shapeLayoutFindings(browser.motionIssues, options);
@@ -1391,6 +1407,7 @@ function buildReport(
13911407
checked: browser.contrastChecked,
13921408
passed: browser.contrastPassed,
13931409
},
1410+
hdr: { autoPromotion: hdrPromotion },
13941411
snapshots: {
13951412
enabled: options.snapshots,
13961413
files: snapshotFiles,
@@ -1595,4 +1612,5 @@ const DEFAULT_DEPENDENCIES: CheckDependencies = {
15951612
runBrowserCheck,
15961613
writeSnapshot,
15971614
captureFindingCrops,
1615+
inspectHdrAutoPromotion,
15981616
};

‎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 };
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: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
2+
import { tmpdir } from "node:os";
3+
import { join } from "node:path";
4+
import { describe, expect, it, vi } from "vitest";
5+
import { inspectHdrAutoPromotion } from "./hdrPromotion.js";
6+
7+
describe("inspectHdrAutoPromotion", () => {
8+
it("reports the local HDR asset that promotes automatic output", async () => {
9+
const dir = mkdtempSync(join(tmpdir(), "hyperframes-hdr-check-"));
10+
const indexPath = join(dir, "index.html");
11+
const assetPath = join(dir, "assets", "source-hdr.mp4");
12+
const inactiveAssetPath = join(dir, "assets", "inactive-hdr.mp4");
13+
mkdirSync(join(dir, "assets"));
14+
writeFileSync(
15+
indexPath,
16+
`<video data-start="1" data-end="1"><source src="assets/inactive-hdr.mp4"></video>
17+
<video><source src="https://media.example/remote.mp4"><source src="assets/source-hdr.mp4?token=secret#preview"></video>`,
18+
);
19+
writeFileSync(assetPath, "fixture");
20+
writeFileSync(inactiveAssetPath, "fixture");
21+
const extractMetadata = vi.fn(async () => ({
22+
durationSeconds: 1,
23+
videoStreamDurationSeconds: 1,
24+
width: 1920,
25+
height: 1080,
26+
fps: 30,
27+
videoCodec: "hevc",
28+
hasAudio: false,
29+
isVFR: false,
30+
hasAlpha: false,
31+
colorSpace: {
32+
colorTransfer: "smpte2084",
33+
colorPrimaries: "bt2020",
34+
colorSpace: "bt2020nc",
35+
},
36+
}));
37+
38+
try {
39+
await expect(
40+
inspectHdrAutoPromotion({ dir, name: "hdr-check", indexPath }, extractMetadata),
41+
).resolves.toEqual({
42+
triggeringAsset: "assets/source-hdr.mp4",
43+
output: { colorSpace: "BT.2020", codec: "HEVC Main10" },
44+
});
45+
expect(extractMetadata).toHaveBeenCalledOnce();
46+
expect(extractMetadata).toHaveBeenCalledWith(assetPath);
47+
} finally {
48+
rmSync(dir, { recursive: true, force: true });
49+
}
50+
});
51+
});
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import { existsSync, readFileSync } from "node:fs";
2+
import {
3+
extractMediaMetadata,
4+
findHdrAutoPromotion,
5+
parseImageElements,
6+
parseVideoElements,
7+
resolveProjectRelativeSrc,
8+
type HdrAutoPromotion,
9+
} from "@hyperframes/engine";
10+
import type { ProjectDir } from "./project.js";
11+
12+
type ExtractMetadata = typeof extractMediaMetadata;
13+
14+
function mediaSources(html: string): string[] {
15+
return [
16+
...parseVideoElements(html).map(({ src }) => src),
17+
...parseImageElements(html).map(({ src }) => src),
18+
];
19+
}
20+
21+
export async function inspectHdrAutoPromotion(
22+
project: ProjectDir,
23+
extractMetadata: ExtractMetadata = extractMediaMetadata,
24+
): Promise<HdrAutoPromotion | null> {
25+
const assets: Array<{
26+
asset: string;
27+
colorSpace: Awaited<ReturnType<typeof extractMediaMetadata>>["colorSpace"];
28+
}> = [];
29+
for (const src of mediaSources(readFileSync(project.indexPath, "utf8"))) {
30+
if (/^(?:https?:|data:|\/\/)/i.test(src)) continue;
31+
const path = resolveProjectRelativeSrc(src, project.dir);
32+
if (!existsSync(path)) continue;
33+
try {
34+
assets.push({
35+
asset: src,
36+
colorSpace: (await extractMetadata(path)).colorSpace,
37+
});
38+
} catch {
39+
continue;
40+
}
41+
}
42+
return findHdrAutoPromotion(assets);
43+
}

‎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";

‎packages/engine/src/utils/hdr.test.ts‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ import {
44
detectTransfer,
55
getHdrEncoderColorParams,
66
analyzeCompositionHdr,
7+
findHdrAutoPromotion,
8+
formatHdrAutoPromotionWarning,
9+
sanitizeHdrAutoPromotionAsset,
710
DEFAULT_HDR10_MASTERING,
811
} from "./hdr.js";
912
import type { VideoColorSpace } from "./ffprobe.js";
@@ -189,3 +192,35 @@ describe("analyzeCompositionHdr", () => {
189192
});
190193
});
191194
});
195+
196+
describe("HDR auto-promotion reporting", () => {
197+
const pq: VideoColorSpace = {
198+
colorTransfer: "smpte2084",
199+
colorPrimaries: "bt2020",
200+
colorSpace: "bt2020nc",
201+
};
202+
203+
it("reports the first HDR asset and the promoted output pipeline", () => {
204+
const promotion = findHdrAutoPromotion([
205+
{
206+
asset: "assets/intro.mp4",
207+
colorSpace: { colorTransfer: "bt709", colorPrimaries: "bt709", colorSpace: "bt709" },
208+
},
209+
{ asset: "assets/hero-hdr.mp4?token=secret#preview", colorSpace: pq },
210+
]);
211+
212+
expect(promotion).toEqual({
213+
triggeringAsset: "assets/hero-hdr.mp4",
214+
output: { colorSpace: "BT.2020", codec: "HEVC Main10" },
215+
});
216+
expect(formatHdrAutoPromotionWarning(promotion!)).toBe(
217+
'[Render] HDR auto-promotion triggered by "assets/hero-hdr.mp4" — output: BT.2020 / HEVC Main10',
218+
);
219+
});
220+
221+
it("removes line breaks before an asset reaches logs", () => {
222+
expect(sanitizeHdrAutoPromotionAsset("assets/hero.mp4\r\n[ERROR] forged")).toBe(
223+
"assets/hero.mp4",
224+
);
225+
});
226+
});

‎packages/engine/src/utils/hdr.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,37 @@ export interface CompositionHdrInfo {
111111
dominantTransfer: HdrTransfer | null;
112112
}
113113

114+
export const HDR_AUTO_PROMOTION_PIPELINE = {
115+
colorSpace: "BT.2020",
116+
codec: "HEVC Main10",
117+
} as const;
118+
119+
export interface HdrAutoPromotion {
120+
triggeringAsset: string;
121+
output: typeof HDR_AUTO_PROMOTION_PIPELINE;
122+
}
123+
124+
export function sanitizeHdrAutoPromotionAsset(asset: string): string {
125+
return asset.split(/[\r\n?#]/, 1)[0] ?? "";
126+
}
127+
128+
export function findHdrAutoPromotion(
129+
sources: readonly { asset: string; colorSpace: VideoColorSpace | null }[],
130+
): HdrAutoPromotion | null {
131+
const source = sources.find(({ colorSpace }) => isHdrColorSpace(colorSpace));
132+
return source
133+
? {
134+
triggeringAsset: sanitizeHdrAutoPromotionAsset(source.asset),
135+
output: HDR_AUTO_PROMOTION_PIPELINE,
136+
}
137+
: null;
138+
}
139+
140+
export function formatHdrAutoPromotionWarning(promotion: HdrAutoPromotion): string {
141+
const asset = sanitizeHdrAutoPromotionAsset(promotion.triggeringAsset);
142+
return `[Render] HDR auto-promotion triggered by "${asset}" — output: ${promotion.output.colorSpace} / ${promotion.output.codec}`;
143+
}
144+
114145
/**
115146
* Analyze a set of video color spaces to determine if the composition
116147
* contains HDR content and what the dominant transfer function is.

0 commit comments

Comments
 (0)