Skip to content

Commit 7ca7b40

Browse files
feat(producer): report browser-computed reference backgrounds
Preserve one initial root/page reference across local, streamed and distributed render results without guessing from film pixels. — Jerrai
1 parent 5e50ac1 commit 7ca7b40

23 files changed

Lines changed: 763 additions & 22 deletions

‎docs/packages/producer.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,41 @@ to retain `render.log` in the render's working directory. Its
113113
expected frame count whenever this check is skipped. Normal output stays quiet;
114114
a custom `logger` can also collect the event through its `debug` method.
115115

116+
## Reference background
117+
118+
Completed jobs expose `reference_background`. In-process local render results, blocking and
119+
streaming producer responses, and distributed plan and assembly results carry
120+
this same additive field:
121+
122+
```json
123+
{"reference_background":{"kind":"solid","rgb":[10,46,138]}}
124+
```
125+
126+
The value describes the composition root and its surrounding page background at
127+
the canonical initial film state. It is read from Chromium's computed styles
128+
before transparent capture changes those styles, not inferred from rendered
129+
frames or an inner panel. Distributed chunks preserve the plan's reference;
130+
they do not choose a different reference at each chunk boundary.
131+
132+
| Kind | Meaning |
133+
| --- | --- |
134+
| `solid` | An opaque computed background, with three integer sRGB components from 0 to 255. |
135+
| `none` | A positively established `background: none` declaration with no effective paint. |
136+
| `unsupported_non_solid` | An effective background image or gradient. |
137+
| `unknown` | Missing, unresolved, changing, translucent, or otherwise indeterminate background. |
138+
139+
A transparent computed color alone does **not** establish `none`. An undeclared
140+
background, an authored transparent color, or an inaccessible stylesheet that
141+
prevents proving absence remains `unknown`. Gradients and images are never
142+
replaced with their underlying color. Consumers must preserve indeterminate
143+
results instead of treating them as a default color or proof of a blank frame.
144+
145+
In-process local rendering reads from a session it already opens. The Docker CLI
146+
wrapper does not currently return the child process's result metadata. Distributed planning
147+
initializes one browser session even for a composition whose duration was
148+
resolved statically, so it can freeze the same browser-computed reference before
149+
any chunk starts.
150+
116151
## Cancel a render
117152

118153
Pass an abort signal to the final argument:

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ const browserManagerState = vi.hoisted(() => ({
101101

102102
vi.mock("../utils/producer.js", () => ({
103103
loadProducer: vi.fn(async () => ({
104+
...(await import("../../../engine/src/services/referenceBackground.js")),
104105
createConsoleLogger: vi.fn((level: string) => {
105106
producerState.loggerLevels.push(level);
106107
return { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() };
@@ -534,6 +535,28 @@ describe("renderLocal browser GPU config", () => {
534535
expect(cpuSamplerState.samplers.map((s) => s.stopped)).toEqual([true, true]);
535536
});
536537

538+
it.each([
539+
{ kind: "solid", rgb: [10, 46, 138] },
540+
{ kind: "none" },
541+
{ kind: "unsupported_non_solid" },
542+
{ kind: "unknown" },
543+
])("returns the same $kind background object as the remote receipt", async (background) => {
544+
producerState.executeImpl = async (job) => {
545+
job.reference_background = background;
546+
};
547+
const result = await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
548+
fps: { num: 30, den: 1 },
549+
quality: "standard",
550+
format: "mp4",
551+
gpu: false,
552+
browserGpuMode: "software",
553+
hdrMode: "auto",
554+
quiet: true,
555+
throwOnError: true,
556+
});
557+
expect(result?.reference_background).toEqual(background);
558+
});
559+
537560
it("warns that the whole mix was lowered, and the render still completes", async () => {
538561
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
539562
producerState.executeImpl = async (job: { audioLoweredDb?: number }) => {

‎packages/cli/src/commands/render.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { ReferenceBackgroundResult } from "@hyperframes/producer";
12
import { captureArtifactRevision } from "../utils/artifactCapture.js";
23
import { recordRenderSuccess, registerRenderOutput } from "@hyperframes/studio-server/history";
34
import { failCommand, requestCliExit, scheduleCliExit } from "../utils/commandResult.js";
@@ -495,7 +496,7 @@ export default defineCommand({
495496
},
496497
});
497498

498-
export interface SingleRenderResult {
499+
export interface SingleRenderResult extends Partial<ReferenceBackgroundResult> {
499500
durationMs?: number;
500501
renderTimeMs: number;
501502
outcome?: "completed" | "completed_with_warnings";
@@ -1290,6 +1291,7 @@ async function executeLocalRender(
12901291
const outcome =
12911292
job.outcome === "completed_with_warnings" ? "completed_with_warnings" : "completed";
12921293
return {
1294+
...producer.referenceBackgroundResult(job[producer.REFERENCE_BACKGROUND_FIELD]),
12931295
renderTimeMs: elapsed,
12941296
durationMs,
12951297
outcome,
@@ -1314,17 +1316,20 @@ async function renderRange(input: {
13141316
}): Promise<SingleRenderResult> {
13151317
const { producer, options } = input;
13161318
let framesEncoded = 0;
1319+
let reference = producer.referenceBackgroundResult(undefined);
13171320
try {
13181321
const config = producer.distributedConfigFromRequest(input.request, {
13191322
logger: input.logger,
13201323
abortSignal: input.signal,
13211324
});
1322-
({ framesEncoded } = await producer.renderSpan(
1325+
const spanResult = await producer.renderSpan(
13231326
input.projectDir,
13241327
config,
13251328
input.range,
13261329
input.outputPath,
1327-
));
1330+
);
1331+
framesEncoded = spanResult.framesEncoded;
1332+
reference = producer.referenceBackgroundResult(spanResult[producer.REFERENCE_BACKGROUND_FIELD]);
13281333
} catch (error: unknown) {
13291334
handleRenderError(error, options, input.startTime, input.cpu, false, "");
13301335
}
@@ -1342,6 +1347,7 @@ async function renderRange(input: {
13421347
if (options.exitAfterComplete) scheduleCliExit();
13431348
return {
13441349
renderTimeMs: elapsed,
1350+
...reference,
13451351
durationMs: Math.round((framesEncoded / fpsToNumber(options.fps)) * 1000),
13461352
outcome: "completed",
13471353
warnings: [],

‎packages/engine/src/index.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,15 @@
3030
*
3131
*/
3232

33+
export {
34+
REFERENCE_BACKGROUND_FIELD,
35+
referenceBackgroundResult,
36+
createReferenceBackgroundRecorder,
37+
readReferenceBackground,
38+
type ReferenceBackground,
39+
type ReferenceBackgroundResult,
40+
} from "./services/referenceBackground.js";
41+
3342
// ── Protocol types ─────────────────────────────────────────────────────────────
3443
export type {
3544
HfProtocol,

‎packages/engine/src/services/frameCapture.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ import {
3232
type RawAuthoredTiming,
3333
} from "@hyperframes/core";
3434

35+
import { readReferenceBackground } from "./referenceBackground.js";
3536
import { holdRenderFrameVideos } from "./renderFrameVideoHold.js";
3637
import { recordWebglContexts, releaseEndedWebglContexts } from "./webglRelease.js";
3738
import { asDrawElementCaptureFailure, DrawElementCaptureError } from "./drawElementCaptureError.js";
@@ -965,6 +966,7 @@ async function initDrawElementOrTransparentBackground(
965966
page: Page,
966967
logInitPhase: (phase: string) => void,
967968
): Promise<void> {
969+
await session.options.recordReferenceBackground?.(() => readReferenceBackground(page));
968970
const supersampling = (session.options.deviceScaleFactor ?? 1) !== 1;
969971
// forceScreenshot is an explicit routing decision made upstream (render-mode
970972
// compat hints like raw requestAnimationFrame, alpha formats, low-memory) —
Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
import { afterAll, beforeAll, describe, expect, it } from "vitest";
2+
import type { Browser } from "puppeteer-core";
3+
import { resolveHeadlessShellPath } from "./browserManager.js";
4+
import { closeTestChrome, launchTestChrome } from "./__fixtures__/loopback.js";
5+
import { readReferenceBackground } from "./referenceBackground.js";
6+
import { initTransparentBackground } from "./screenshotService.js";
7+
8+
const chromePath = process.env.HF_REFERENCE_TEST_CHROME ?? resolveHeadlessShellPath();
9+
10+
describe.skipIf(!chromePath)("browser-computed reference background", () => {
11+
let browser: Browser;
12+
beforeAll(async () => {
13+
browser = await launchTestChrome(chromePath);
14+
});
15+
afterAll(() => closeTestChrome(browser));
16+
17+
it.each([
18+
["body { background: rgb(10 46 138); }", { kind: "solid", rgb: [10, 46, 138] }],
19+
[
20+
"body { background: blue !important; } #film { background: rgb(10 46 138); }",
21+
{ kind: "solid", rgb: [10, 46, 138] },
22+
],
23+
[
24+
"body { --film-bg: rgb(10 46 138); background: var(--film-bg); }",
25+
{ kind: "solid", rgb: [10, 46, 138] },
26+
],
27+
[
28+
"#film { background: red !important; } [data-composition-id] { background: blue !important; }",
29+
{ kind: "solid", rgb: [255, 0, 0] },
30+
],
31+
["body { background: none; }", { kind: "none" }],
32+
["", { kind: "unknown" }],
33+
["body { background-color: transparent; }", { kind: "unknown" }],
34+
[
35+
"body { background: linear-gradient(red, blue); background-color: white; }",
36+
{ kind: "unsupported_non_solid" },
37+
],
38+
[
39+
"body { background-image: url(data:image/png;base64,broken); background-color: white; }",
40+
{ kind: "unsupported_non_solid" },
41+
],
42+
["body { background-color: var(--unresolved); }", { kind: "unknown" }],
43+
])("reads the real cascade: %s", async (css, expected) => {
44+
const page = await browser.newPage();
45+
try {
46+
await page.setContent(
47+
`<style>${css}</style><body><div id="film" data-composition-id="film" data-duration="1"></div></body>`,
48+
);
49+
expect(await readReferenceBackground(page)).toEqual(expected);
50+
} finally {
51+
await page.close();
52+
}
53+
});
54+
55+
it("does not call a known animated background stable", async () => {
56+
const page = await browser.newPage();
57+
try {
58+
await page.setContent(`<body style="background:blue"><div data-composition-id="film"></div><script>
59+
window.__timelines = { film: { getChildren: () => [{ vars: { backgroundColor: 'red' }, targets: () => [document.body] }] } };
60+
</script></body>`);
61+
expect(await readReferenceBackground(page)).toEqual({ kind: "unknown" });
62+
} finally {
63+
await page.close();
64+
}
65+
});
66+
67+
it("uses the canonical initial JS state before transparent capture changes it", async () => {
68+
const page = await browser.newPage();
69+
try {
70+
await page.setContent(`<body style="background: red"><div data-composition-id="film"></div><script>
71+
window.__hf = { seek: (t) => { document.body.style.background = t === 0 ? 'rgb(10 46 138)' : 'yellow'; } };
72+
</script></body>`);
73+
const reference = await readReferenceBackground(page);
74+
await initTransparentBackground(page);
75+
expect(reference).toEqual({ kind: "solid", rgb: [10, 46, 138] });
76+
expect(await readReferenceBackground(page)).toEqual({ kind: "unknown" });
77+
} finally {
78+
await page.close();
79+
}
80+
});
81+
});
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
import { describe, expect, it, vi } from "vitest";
2+
import {
3+
classifyReferenceBackground,
4+
createReferenceBackgroundRecorder,
5+
referenceBackgroundResult,
6+
type BackgroundLayer,
7+
type ReferenceBackgroundResult,
8+
} from "./referenceBackground.js";
9+
10+
const layer = (overrides: Partial<BackgroundLayer> = {}): BackgroundLayer => ({
11+
rgba: [10, 46, 138, 255],
12+
image: "none",
13+
opacity: "1",
14+
filter: "none",
15+
blend: "normal",
16+
varying: false,
17+
...overrides,
18+
});
19+
20+
describe("reference background", () => {
21+
it("returns opaque browser-resolved RGB, not a named/default color", () => {
22+
expect(classifyReferenceBackground({ layers: [layer()], explicitNone: false })).toEqual({
23+
kind: "solid",
24+
rgb: [10, 46, 138],
25+
});
26+
});
27+
it.each(["linear-gradient(red, blue)", 'url("film.png")'])(
28+
"never coerces %s to its background color",
29+
(image) => {
30+
expect(
31+
classifyReferenceBackground({ layers: [layer({ image })], explicitNone: false }),
32+
).toEqual({ kind: "unsupported_non_solid" });
33+
},
34+
);
35+
it("requires positive absence proof, not merely transparent computed color", () => {
36+
const layers = [layer({ rgba: [0, 0, 0, 0] })];
37+
expect(classifyReferenceBackground({ layers, explicitNone: false })).toEqual({
38+
kind: "unknown",
39+
});
40+
expect(classifyReferenceBackground({ layers, explicitNone: true })).toEqual({ kind: "none" });
41+
});
42+
it("does not use a hidden ancestor image behind an opaque root", () => {
43+
expect(
44+
classifyReferenceBackground({
45+
layers: [layer(), layer({ image: "url(image.png)" })],
46+
explicitNone: false,
47+
}),
48+
).toEqual({ kind: "solid", rgb: [10, 46, 138] });
49+
});
50+
it.each([
51+
null,
52+
{ layers: [], explicitNone: false },
53+
{ layers: [layer({ rgba: [NaN, 0, 0, 255] })], explicitNone: false },
54+
{ layers: [layer({ rgba: [0, 0, 0, 128] }), layer()], explicitNone: false },
55+
{ layers: [layer({ varying: true })], explicitNone: false },
56+
])("leaves unavailable, malformed, translucent or varying paint unknown", (observation) => {
57+
expect(classifyReferenceBackground(observation)).toEqual({ kind: "unknown" });
58+
});
59+
it.each([
60+
undefined,
61+
{},
62+
{ kind: "solid", rgb: [1, 2, 256] },
63+
{ kind: "solid", rgb: [1, 2.5, 3] },
64+
{ kind: "solid", rgb: [1, 2] },
65+
])("normalizes malformed receipts to unknown", (value) => {
66+
expect(referenceBackgroundResult(value)).toEqual({ reference_background: { kind: "unknown" } });
67+
});
68+
it("reserves exactly one initial read across concurrent and later sessions", async () => {
69+
const records: ReferenceBackgroundResult[] = [];
70+
const record = createReferenceBackgroundRecorder((value) => {
71+
records.push(value);
72+
});
73+
const first = vi.fn(async () => ({
74+
kind: "solid" as const,
75+
rgb: [10, 46, 138] as [number, number, number],
76+
}));
77+
const later = vi.fn(async () => ({ kind: "unsupported_non_solid" as const }));
78+
await Promise.all([record(first), record(later)]);
79+
await record(later);
80+
expect(first).toHaveBeenCalledTimes(1);
81+
expect(later).not.toHaveBeenCalled();
82+
expect(records).toEqual([{ reference_background: { kind: "solid", rgb: [10, 46, 138] } }]);
83+
});
84+
it("does not replace an indeterminate canonical read with a chunk-local fallback", async () => {
85+
const records: ReferenceBackgroundResult[] = [];
86+
const record = createReferenceBackgroundRecorder((value) => {
87+
records.push(value);
88+
});
89+
await record(async () => {
90+
throw new Error("page closed");
91+
});
92+
const fallback = vi.fn(async () => ({ kind: "none" as const }));
93+
await record(fallback);
94+
expect(fallback).not.toHaveBeenCalled();
95+
expect(records).toEqual([{ reference_background: { kind: "unknown" } }]);
96+
});
97+
});

0 commit comments

Comments
 (0)