Skip to content

Commit eb16510

Browse files
fix(producer): seed random values in every render so re-renders give the same film (#7410)
* fix(producer): every render draws the same random values, at any worker count * fix(producer): run the random-stagger fixture in CI and say what seeding covers
1 parent 070b964 commit eb16510

10 files changed

Lines changed: 106 additions & 135 deletions

File tree

‎packages/producer/src/services/distributed/planFrameCost.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import {
88
} from "@hyperframes/engine";
99
import type { ProducerLogger } from "../../logger.js";
1010
import {
11-
buildVirtualTimeShim,
11+
VIRTUAL_TIME_SHIM,
1212
closeFileServerSafely,
1313
createFileServer,
1414
resolveRenderFpsConfig,
@@ -73,7 +73,7 @@ export async function measurePlanSecondsPerFrame(input: {
7373
projectDir: compiledDir,
7474
compiledDir,
7575
port: 0,
76-
preHeadScripts: [buildVirtualTimeShim({ seedRandomFromFrame: true })],
76+
preHeadScripts: [VIRTUAL_TIME_SHIM],
7777
fps: fpsRatio,
7878
});
7979
let session: Awaited<ReturnType<typeof createCaptureSession>> | null = null;

‎packages/producer/src/services/distributed/renderChunk.ts‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,16 +21,15 @@
2121
* - Browser is launched with `browserGpuMode: "software"` and verified
2222
* against `chrome://gpu` via `assertSwiftShader` — a non-SwiftShader
2323
* backend trips a non-retryable `BROWSER_GPU_NOT_SOFTWARE`.
24-
* - The file server serves with the seeded-random shim
25-
* (`buildVirtualTimeShim({ seedRandomFromFrame: true })`) so any
24+
* - The file server serves `VIRTUAL_TIME_SHIM`, as every render path does, so any
2625
* composition that uses `Math.random` / `crypto.getRandomValues`
2726
* produces byte-identical pixels per `(planDir, chunkIndex)`.
2827
* - No `lastFrameCache` priming: every frame seeks fresh DOM so the
2928
* cache is never read, and priming would deadlock the compositor.
3029
* - The chunk's encode runs with `lockGopForChunkConcat: true` and
3130
* `gopSize === framesInChunk` so concat-copy at assemble time is safe.
3231
*
33-
* Every determinism toggle above is opt-in — only this primitive enables them.
32+
* Every other determinism toggle above is opt-in — only this primitive enables them.
3433
* In-process renders (`executeRenderJob`) leave them off.
3534
*/
3635

@@ -86,7 +85,7 @@ import {
8685
import { sha256Hex } from "../render/stages/planHash.js";
8786
import { applyRuntimeEnvSnapshot } from "../render/runtimeEnvSnapshot.js";
8887
import {
89-
buildVirtualTimeShim,
88+
VIRTUAL_TIME_SHIM,
9089
closeFileServerSafely,
9190
createFileServer,
9291
resolveRenderFpsConfig,
@@ -723,12 +722,12 @@ export async function renderChunk(
723722

724723
// ── File server with the seeded-random shim ──
725724
// `Math.random` / `crypto.getRandomValues` are seeded from virtual
726-
// time so retries are pixel-identical. Only distributed renders flip this.
725+
// time so retries are pixel-identical.
727726
const fileServer: FileServerHandle = await createFileServer({
728727
projectDir: compiledDir,
729728
compiledDir,
730729
port: 0,
731-
preHeadScripts: [buildVirtualTimeShim({ seedRandomFromFrame: true })],
730+
preHeadScripts: [VIRTUAL_TIME_SHIM],
732731
// These dimensions are frozen by the controller from the render job, so
733732
// chunk runtime seek quantization stays on the same fps grid as capture.
734733
fps: { num: plan.dimensions.fpsNum, den: plan.dimensions.fpsDen },

‎packages/producer/src/services/fileServer-seededRandom.test.ts‎

Lines changed: 21 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,13 @@
11
/**
2-
* Tests for the `seedRandomFromFrame` gate on `buildVirtualTimeShim`.
3-
*
4-
* 1. Backwards compatibility — `buildVirtualTimeShim({
5-
* seedRandomFromFrame: false })` returns a string byte-identical to the
6-
* legacy `VIRTUAL_TIME_SHIM`. Existing in-process callers see no
7-
* difference.
8-
*
9-
* 2. Distributed determinism — with `seedRandomFromFrame: true`, the shim's
10-
* `seekToTime(ms)` reseeds a Mulberry32 PRNG keyed by the virtual time
11-
* and replaces `Math.random` / `crypto.getRandomValues` with that PRNG.
12-
* `seekToTime(N)` → N `Math.random()` calls is a deterministic
13-
* sequence; reseeking to the same time restarts the sequence.
2+
* Tests for the seeded `Math.random` / `crypto.getRandomValues` in `VIRTUAL_TIME_SHIM`.
143
*
154
* The shim is executed inside `node:vm` with a synthetic `window`/`Math` so
165
* tests don't need real Chrome.
176
*/
187

198
import { describe, expect, it } from "bun:test";
209
import { Script, createContext, type Context } from "node:vm";
21-
import { buildVirtualTimeShim, VIRTUAL_TIME_SHIM } from "./fileServer.js";
10+
import { VIRTUAL_TIME_SHIM } from "./fileServer.js";
2211

2312
/**
2413
* Build a fresh VM context with its own globals (its own Math, its own
@@ -62,50 +51,16 @@ function runShim(shimSource: string): {
6251
return ctx;
6352
}
6453

65-
describe("buildVirtualTimeShim — backwards compatibility", () => {
66-
it("default (seedRandomFromFrame: false) is byte-identical to VIRTUAL_TIME_SHIM", () => {
67-
// The const that existing call sites import:
68-
// renderOrchestrator.ts: preHeadScripts: [VIRTUAL_TIME_SHIM]
69-
// probeStage.ts: preHeadScripts: [VIRTUAL_TIME_SHIM]
70-
// Must continue to emit the same script.
71-
const built = buildVirtualTimeShim({ seedRandomFromFrame: false });
72-
expect(built).toBe(VIRTUAL_TIME_SHIM);
73-
});
74-
75-
it("default shim does not mention any seeded-RNG identifiers", () => {
76-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: false });
77-
expect(shim).not.toContain("mulberry32");
78-
expect(shim).not.toContain("reseedRngFromTime");
79-
expect(shim).not.toContain("__seededGetRandomValues");
80-
expect(shim).not.toContain("Math.random = ");
81-
});
82-
83-
it("default shim leaves Math.random pointing at the VM's native function", () => {
84-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: false });
85-
const { run } = runShim(shim);
86-
// toString() of native Math.random is `function random() { [native code] }`
87-
const isNative = run<boolean>(`/\\[native code\\]/.test(Math.random.toString())`);
88-
expect(isNative).toBe(true);
89-
});
90-
});
91-
92-
describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
93-
it("emits the seeded-RNG block", () => {
94-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
95-
expect(shim).toContain("mulberry32");
96-
expect(shim).toContain("reseedRngFromTime");
97-
expect(shim).toContain("__seededGetRandomValues");
98-
});
99-
54+
describe("VIRTUAL_TIME_SHIM seeded randomness", () => {
10055
it("replaces Math.random with a non-native PRNG", () => {
101-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
56+
const shim = VIRTUAL_TIME_SHIM;
10257
const { run } = runShim(shim);
10358
const isNative = run<boolean>(`/\\[native code\\]/.test(Math.random.toString())`);
10459
expect(isNative).toBe(false);
10560
});
10661

10762
it("produces identical Math.random sequences across two fresh VMs at the same time", () => {
108-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
63+
const shim = VIRTUAL_TIME_SHIM;
10964
const drawSequence = `(() => {
11065
window.__HF_VIRTUAL_TIME__.seekToTime(1234);
11166
const seq = [];
@@ -126,7 +81,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
12681
it("re-seeking to the same time produces the same Math.random sequence", () => {
12782
// The core determinism contract for retries: same (planDir, chunkIndex) →
12883
// same frame N → same seekToTime(t_N) → same Math.random outputs.
129-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
84+
const shim = VIRTUAL_TIME_SHIM;
13085
const { run } = runShim(shim);
13186
const observed = run<{ first: number[]; second: number[] }>(`(() => {
13287
window.__HF_VIRTUAL_TIME__.seekToTime(42);
@@ -141,7 +96,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
14196
});
14297

14398
it("different times produce different Math.random sequences", () => {
144-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
99+
const shim = VIRTUAL_TIME_SHIM;
145100
const { run } = runShim(shim);
146101
const observed = run<{ t0: number[]; t1: number[] }>(`(() => {
147102
window.__HF_VIRTUAL_TIME__.seekToTime(0);
@@ -154,7 +109,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
154109
});
155110

156111
it("seeded crypto.getRandomValues writes deterministic bytes", () => {
157-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
112+
const shim = VIRTUAL_TIME_SHIM;
158113
const drawBytes = `(() => {
159114
window.__HF_VIRTUAL_TIME__.seekToTime(7);
160115
const buf = new Uint8Array(64);
@@ -168,7 +123,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
168123
});
169124

170125
it("seeded crypto.getRandomValues handles odd byte lengths", () => {
171-
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
126+
const shim = VIRTUAL_TIME_SHIM;
172127
const { run } = runShim(shim);
173128
const lengths = run<number[]>(`(() => {
174129
window.__HF_VIRTUAL_TIME__.seekToTime(3);
@@ -182,4 +137,16 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
182137
})()`);
183138
expect(lengths).toEqual([1, 2, 3, 4, 5, 7, 31, 33]);
184139
});
140+
141+
it("draws the same Math.random sequence at page load in two fresh pages", () => {
142+
// A GSAP stagger { from: "random" } draws its order when the page script runs, before any seek.
143+
const drawAtLoad = `(() => {
144+
const seq = [];
145+
for (let i = 0; i < 16; i++) seq.push(Math.random());
146+
return seq;
147+
})()`;
148+
const seqA = runShim(VIRTUAL_TIME_SHIM).run<number[]>(drawAtLoad);
149+
const seqB = runShim(VIRTUAL_TIME_SHIM).run<number[]>(drawAtLoad);
150+
expect(seqA).toEqual(seqB);
151+
});
185152
});

‎packages/producer/src/services/fileServer-virtualTimers.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { describe, expect, it } from "bun:test";
22
import { createContext, Script } from "node:vm";
3-
import { buildVirtualTimeShim } from "./fileServer.js";
3+
import { VIRTUAL_TIME_SHIM } from "./fileServer.js";
44

55
type Page = { run: <T = unknown>(code: string) => T };
66

@@ -17,7 +17,7 @@ function page(): Page {
1717
globalThis.performance = { now: () => 0 };
1818
globalThis.__renderReady = true;
1919
`).runInContext(context);
20-
new Script(buildVirtualTimeShim({ seedRandomFromFrame: false })).runInContext(context);
20+
new Script(VIRTUAL_TIME_SHIM).runInContext(context);
2121
return { run: <T>(code: string) => new Script(code).runInContext(context) as T };
2222
}
2323

‎packages/producer/src/services/fileServer.ts‎

Lines changed: 23 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -206,47 +206,29 @@ export function parseRangeHeader(
206206
}
207207

208208
/**
209-
* Options for {@link buildVirtualTimeShim}.
209+
* Page-side virtual-time shim, installed before page scripts on every render path.
210+
* Holds Date.now, performance.now, rAF and later timers at the seek time, and seeds Math.random and
211+
* crypto.getRandomValues from it, so a re-render repeats. Draws at page load or inside a frame also match
212+
* across worker counts; a value resolved on a tween's first render depends on the frame a worker reaches first.
210213
*/
211-
export interface VirtualTimeShimOptions {
212-
/**
213-
* When `true`, the shim additionally replaces `Math.random` and
214-
* `crypto.getRandomValues` with a Mulberry32-seeded PRNG keyed by the
215-
* current frame's virtual time. Compositions that call `Math.random()`
216-
* during render then produce byte-identical pixels across machines and
217-
* across replays of the same `(planDir, chunkIndex)` pair.
218-
*
219-
* Default `false`: leaves `Math.random` / `crypto.getRandomValues` native,
220-
* preserving the in-process renderer's non-deterministic behavior for
221-
* compositions that rely on it.
222-
*/
223-
seedRandomFromFrame: boolean;
224-
}
214+
const VIRTUAL_TIME_SHIM = String.raw`(function() {
215+
if (window.__HF_VIRTUAL_TIME__) return;
216+
217+
var virtualNowMs = 0;
218+
var rafId = 1;
219+
var rafQueue = [];
220+
var OriginalDate = Date;
221+
var originalSetTimeout = window.setTimeout.bind(window);
222+
var originalClearTimeout = window.clearTimeout.bind(window);
223+
var originalSetInterval = window.setInterval.bind(window);
224+
var originalClearInterval = window.clearInterval.bind(window);
225+
var originalRequestAnimationFrame = window.requestAnimationFrame
226+
? window.requestAnimationFrame.bind(window)
227+
: null;
228+
var originalCancelAnimationFrame = window.cancelAnimationFrame
229+
? window.cancelAnimationFrame.bind(window)
230+
: null;
225231
226-
/**
227-
* Build the page-side virtual-time shim script.
228-
*
229-
* The shim freezes `Date.now`, `performance.now`, rAF, and the timers set
230-
* after the first seek, so a render seek can deterministically advance the
231-
* page's notion of "now". The renderer issues `__HF_VIRTUAL_TIME__.seekToTime(ms)`
232-
* before every frame capture; everything timing-related on the page sees
233-
* exactly `ms` until the next seek.
234-
*
235-
* When `options.seedRandomFromFrame` is `true`, the returned script also
236-
* installs a seeded `Math.random` / `crypto.getRandomValues` keyed by the
237-
* current virtual time — so compositions with stochastic visuals retry
238-
* identically. When `false`, the shim emits no random-override code; the
239-
* page's native `Math.random` is left alone (the in-process default).
240-
*/
241-
export function buildVirtualTimeShim(options: VirtualTimeShimOptions): string {
242-
const seedRandomFromFrame = options.seedRandomFromFrame === true;
243-
// The seeded-RNG block is gated at build time so the unlocked shim is
244-
// byte-identical to the pre-flag form. Producer regression baselines
245-
// compare on rendered pixels — but the file-server unit tests in
246-
// `fileServer.test.ts` also string-match `VIRTUAL_TIME_SHIM`, and we want
247-
// those matches to remain stable.
248-
const seededRandomBlock = seedRandomFromFrame
249-
? String.raw`
250232
// Seeded Math.random / crypto.getRandomValues, keyed by virtual time.
251233
// Mulberry32: single uint32 state, deterministic, fast.
252234
var rngState = 0;
@@ -288,30 +270,7 @@ export function buildVirtualTimeShim(options: VirtualTimeShimOptions): string {
288270
window.crypto.getRandomValues = __seededGetRandomValues;
289271
} catch (e) {}
290272
}
291-
`
292-
: "";
293-
// The seekToTime hook reseeds when seeding is on; under seedRandomFromFrame=false
294-
// we emit no extra call so the function body is byte-identical to the
295-
// unseeded shim.
296-
const seekToTimeReseedCall = seedRandomFromFrame ? "reseedRngFromTime(safeTimeMs);\n " : "";
297-
return String.raw`(function() {
298-
if (window.__HF_VIRTUAL_TIME__) return;
299273
300-
var virtualNowMs = 0;
301-
var rafId = 1;
302-
var rafQueue = [];
303-
var OriginalDate = Date;
304-
var originalSetTimeout = window.setTimeout.bind(window);
305-
var originalClearTimeout = window.clearTimeout.bind(window);
306-
var originalSetInterval = window.setInterval.bind(window);
307-
var originalClearInterval = window.clearInterval.bind(window);
308-
var originalRequestAnimationFrame = window.requestAnimationFrame
309-
? window.requestAnimationFrame.bind(window)
310-
: null;
311-
var originalCancelAnimationFrame = window.cancelAnimationFrame
312-
? window.cancelAnimationFrame.bind(window)
313-
: null;
314-
${seededRandomBlock}
315274
function flushAnimationFrame() {
316275
if (!rafQueue.length) return;
317276
var current = rafQueue.slice();
@@ -442,7 +401,8 @@ ${seededRandomBlock}
442401
// page starts there keep the schedule a one-worker render gives them.
443402
if (safeTimeMs > 0) seekToTime(0);
444403
}
445-
${seekToTimeReseedCall}fireDueTimers(safeTimeMs);
404+
reseedRngFromTime(safeTimeMs);
405+
fireDueTimers(safeTimeMs);
446406
virtualNowMs = safeTimeMs;
447407
flushAnimationFrame();
448408
return virtualNowMs;
@@ -461,14 +421,6 @@ ${seededRandomBlock}
461421
},
462422
};
463423
})();`;
464-
}
465-
466-
/**
467-
* Default in-process virtual-time shim — `seedRandomFromFrame: false`.
468-
* Existing call sites (`renderOrchestrator`, `probeStage`) import this
469-
* constant. Distributed callers build their own with seeding enabled.
470-
*/
471-
const VIRTUAL_TIME_SHIM = buildVirtualTimeShim({ seedRandomFromFrame: false });
472424

473425
/**
474426
* Render mode extension -- adds renderSeek() for frame-accurate seeking
Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"name": "random-stagger-workers",
3+
"description": "Regression test for Math.random during render. A 100-cell grid fades out with a GSAP stagger from \"random\", whose order GSAP draws from Math.random when the page loads. Rendered with 2 workers, both workers and every re-render must draw the same order, so the film matches the golden frame for frame.",
4+
"tags": ["regression", "parallel", "render-compat"],
5+
"minPsnr": 30,
6+
"maxFrameFailures": 0,
7+
"minAudioCorrelation": 0,
8+
"maxAudioLagWindows": 1,
9+
"renderConfig": {
10+
"fps": 30,
11+
"workers": 2
12+
}
13+
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
version https://git-lfs.github.com/spec/v1
2+
oid sha256:2d5665bb78e6cf9a065322ddcaef3f56f13d8b72d0b3c841734c15ce6b867160
3+
size 74536
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
version https://git-lfs.github.com/spec/v1
2+
oid sha256:6946b7491232166b7d0408f2a30e79a8cd60b3cfda2acf97a9515ebf7940228d
3+
size 72084
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=1080, height=1080">
6+
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js" integrity="sha384-d+vyQ0dYcymoP8ndq2hW7FGC50nqGdXUEgoOUGxbbkAJwZqL7h+jKN0GGgn9hFDS" crossorigin="anonymous"></script>
7+
<style>
8+
body { margin: 0; background: #0d1117; width: 1080px; height: 1080px; overflow: hidden; }
9+
#grid {
10+
position: absolute; left: 140px; top: 140px; width: 800px; height: 800px;
11+
display: grid; grid-template-columns: repeat(10, 1fr); grid-template-rows: repeat(10, 1fr); gap: 8px;
12+
}
13+
.cell { background: #e6edf3; border-radius: 6px; }
14+
</style>
15+
</head>
16+
<body>
17+
<div id="root" data-composition-id="root" data-width="1080" data-height="1080" data-duration="2"
18+
style="position:absolute;width:1080px;height:1080px;">
19+
<div id="grid"></div>
20+
</div>
21+
<script>
22+
const grid = document.getElementById("grid");
23+
for (let i = 0; i < 100; i++) {
24+
const cell = document.createElement("div");
25+
cell.className = "cell";
26+
grid.appendChild(cell);
27+
}
28+
const tl = gsap.timeline({ paused: true });
29+
tl.fromTo(".cell", { opacity: 1 }, { opacity: 0.1, duration: 0.1, ease: "none", stagger: { amount: 1.6, from: "random" } }, 0.2);
30+
window.__timelines["root"] = tl;
31+
</script>
32+
</body>
33+
</html>

0 commit comments

Comments
 (0)