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
This commit is contained in:
Miguel Ángel
2026-11-08 16:16:15 +00:00
committed by GitHub
parent 070b964d7b
commit eb16510a10
10 changed files with 106 additions and 135 deletions
@@ -8,7 +8,7 @@ import {
} from "@hyperframes/engine";
import type { ProducerLogger } from "../../logger.js";
import {
buildVirtualTimeShim,
VIRTUAL_TIME_SHIM,
closeFileServerSafely,
createFileServer,
resolveRenderFpsConfig,
@@ -73,7 +73,7 @@ export async function measurePlanSecondsPerFrame(input: {
projectDir: compiledDir,
compiledDir,
port: 0,
preHeadScripts: [buildVirtualTimeShim({ seedRandomFromFrame: true })],
preHeadScripts: [VIRTUAL_TIME_SHIM],
fps: fpsRatio,
});
let session: Awaited<ReturnType<typeof createCaptureSession>> | null = null;
@@ -21,8 +21,7 @@
* - Browser is launched with `browserGpuMode: "software"` and verified
* against `chrome://gpu` via `assertSwiftShader` — a non-SwiftShader
* backend trips a non-retryable `BROWSER_GPU_NOT_SOFTWARE`.
* - The file server serves with the seeded-random shim
* (`buildVirtualTimeShim({ seedRandomFromFrame: true })`) so any
* - The file server serves `VIRTUAL_TIME_SHIM`, as every render path does, so any
* composition that uses `Math.random` / `crypto.getRandomValues`
* produces byte-identical pixels per `(planDir, chunkIndex)`.
* - No `lastFrameCache` priming: every frame seeks fresh DOM so the
@@ -30,7 +29,7 @@
* - The chunk's encode runs with `lockGopForChunkConcat: true` and
* `gopSize === framesInChunk` so concat-copy at assemble time is safe.
*
* Every determinism toggle above is opt-in — only this primitive enables them.
* Every other determinism toggle above is opt-in — only this primitive enables them.
* In-process renders (`executeRenderJob`) leave them off.
*/
@@ -86,7 +85,7 @@ import {
import { sha256Hex } from "../render/stages/planHash.js";
import { applyRuntimeEnvSnapshot } from "../render/runtimeEnvSnapshot.js";
import {
buildVirtualTimeShim,
VIRTUAL_TIME_SHIM,
closeFileServerSafely,
createFileServer,
resolveRenderFpsConfig,
@@ -723,12 +722,12 @@ export async function renderChunk(
// ── File server with the seeded-random shim ──
// `Math.random` / `crypto.getRandomValues` are seeded from virtual
// time so retries are pixel-identical. Only distributed renders flip this.
// time so retries are pixel-identical.
const fileServer: FileServerHandle = await createFileServer({
projectDir: compiledDir,
compiledDir,
port: 0,
preHeadScripts: [buildVirtualTimeShim({ seedRandomFromFrame: true })],
preHeadScripts: [VIRTUAL_TIME_SHIM],
// These dimensions are frozen by the controller from the render job, so
// chunk runtime seek quantization stays on the same fps grid as capture.
fps: { num: plan.dimensions.fpsNum, den: plan.dimensions.fpsDen },
@@ -1,16 +1,5 @@
/**
* Tests for the `seedRandomFromFrame` gate on `buildVirtualTimeShim`.
*
* 1. Backwards compatibility — `buildVirtualTimeShim({
* seedRandomFromFrame: false })` returns a string byte-identical to the
* legacy `VIRTUAL_TIME_SHIM`. Existing in-process callers see no
* difference.
*
* 2. Distributed determinism — with `seedRandomFromFrame: true`, the shim's
* `seekToTime(ms)` reseeds a Mulberry32 PRNG keyed by the virtual time
* and replaces `Math.random` / `crypto.getRandomValues` with that PRNG.
* `seekToTime(N)` → N `Math.random()` calls is a deterministic
* sequence; reseeking to the same time restarts the sequence.
* Tests for the seeded `Math.random` / `crypto.getRandomValues` in `VIRTUAL_TIME_SHIM`.
*
* The shim is executed inside `node:vm` with a synthetic `window`/`Math` so
* tests don't need real Chrome.
@@ -18,7 +7,7 @@
import { describe, expect, it } from "bun:test";
import { Script, createContext, type Context } from "node:vm";
import { buildVirtualTimeShim, VIRTUAL_TIME_SHIM } from "./fileServer.js";
import { VIRTUAL_TIME_SHIM } from "./fileServer.js";
/**
* Build a fresh VM context with its own globals (its own Math, its own
@@ -62,50 +51,16 @@ function runShim(shimSource: string): {
return ctx;
}
describe("buildVirtualTimeShim — backwards compatibility", () => {
it("default (seedRandomFromFrame: false) is byte-identical to VIRTUAL_TIME_SHIM", () => {
// The const that existing call sites import:
// renderOrchestrator.ts: preHeadScripts: [VIRTUAL_TIME_SHIM]
// probeStage.ts: preHeadScripts: [VIRTUAL_TIME_SHIM]
// Must continue to emit the same script.
const built = buildVirtualTimeShim({ seedRandomFromFrame: false });
expect(built).toBe(VIRTUAL_TIME_SHIM);
});
it("default shim does not mention any seeded-RNG identifiers", () => {
const shim = buildVirtualTimeShim({ seedRandomFromFrame: false });
expect(shim).not.toContain("mulberry32");
expect(shim).not.toContain("reseedRngFromTime");
expect(shim).not.toContain("__seededGetRandomValues");
expect(shim).not.toContain("Math.random = ");
});
it("default shim leaves Math.random pointing at the VM's native function", () => {
const shim = buildVirtualTimeShim({ seedRandomFromFrame: false });
const { run } = runShim(shim);
// toString() of native Math.random is `function random() { [native code] }`
const isNative = run<boolean>(`/\\[native code\\]/.test(Math.random.toString())`);
expect(isNative).toBe(true);
});
});
describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
it("emits the seeded-RNG block", () => {
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
expect(shim).toContain("mulberry32");
expect(shim).toContain("reseedRngFromTime");
expect(shim).toContain("__seededGetRandomValues");
});
describe("VIRTUAL_TIME_SHIM seeded randomness", () => {
it("replaces Math.random with a non-native PRNG", () => {
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
const shim = VIRTUAL_TIME_SHIM;
const { run } = runShim(shim);
const isNative = run<boolean>(`/\\[native code\\]/.test(Math.random.toString())`);
expect(isNative).toBe(false);
});
it("produces identical Math.random sequences across two fresh VMs at the same time", () => {
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
const shim = VIRTUAL_TIME_SHIM;
const drawSequence = `(() => {
window.__HF_VIRTUAL_TIME__.seekToTime(1234);
const seq = [];
@@ -126,7 +81,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
it("re-seeking to the same time produces the same Math.random sequence", () => {
// The core determinism contract for retries: same (planDir, chunkIndex) →
// same frame N → same seekToTime(t_N) → same Math.random outputs.
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
const shim = VIRTUAL_TIME_SHIM;
const { run } = runShim(shim);
const observed = run<{ first: number[]; second: number[] }>(`(() => {
window.__HF_VIRTUAL_TIME__.seekToTime(42);
@@ -141,7 +96,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
});
it("different times produce different Math.random sequences", () => {
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
const shim = VIRTUAL_TIME_SHIM;
const { run } = runShim(shim);
const observed = run<{ t0: number[]; t1: number[] }>(`(() => {
window.__HF_VIRTUAL_TIME__.seekToTime(0);
@@ -154,7 +109,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
});
it("seeded crypto.getRandomValues writes deterministic bytes", () => {
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
const shim = VIRTUAL_TIME_SHIM;
const drawBytes = `(() => {
window.__HF_VIRTUAL_TIME__.seekToTime(7);
const buf = new Uint8Array(64);
@@ -168,7 +123,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
});
it("seeded crypto.getRandomValues handles odd byte lengths", () => {
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
const shim = VIRTUAL_TIME_SHIM;
const { run } = runShim(shim);
const lengths = run<number[]>(`(() => {
window.__HF_VIRTUAL_TIME__.seekToTime(3);
@@ -182,4 +137,16 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
})()`);
expect(lengths).toEqual([1, 2, 3, 4, 5, 7, 31, 33]);
});
it("draws the same Math.random sequence at page load in two fresh pages", () => {
// A GSAP stagger { from: "random" } draws its order when the page script runs, before any seek.
const drawAtLoad = `(() => {
const seq = [];
for (let i = 0; i < 16; i++) seq.push(Math.random());
return seq;
})()`;
const seqA = runShim(VIRTUAL_TIME_SHIM).run<number[]>(drawAtLoad);
const seqB = runShim(VIRTUAL_TIME_SHIM).run<number[]>(drawAtLoad);
expect(seqA).toEqual(seqB);
});
});
@@ -1,6 +1,6 @@
import { describe, expect, it } from "bun:test";
import { createContext, Script } from "node:vm";
import { buildVirtualTimeShim } from "./fileServer.js";
import { VIRTUAL_TIME_SHIM } from "./fileServer.js";
type Page = { run: <T = unknown>(code: string) => T };
@@ -17,7 +17,7 @@ function page(): Page {
globalThis.performance = { now: () => 0 };
globalThis.__renderReady = true;
`).runInContext(context);
new Script(buildVirtualTimeShim({ seedRandomFromFrame: false })).runInContext(context);
new Script(VIRTUAL_TIME_SHIM).runInContext(context);
return { run: <T>(code: string) => new Script(code).runInContext(context) as T };
}
+23 -71
View File
@@ -206,47 +206,29 @@ export function parseRangeHeader(
}
/**
* Options for {@link buildVirtualTimeShim}.
* Page-side virtual-time shim, installed before page scripts on every render path.
* Holds Date.now, performance.now, rAF and later timers at the seek time, and seeds Math.random and
* crypto.getRandomValues from it, so a re-render repeats. Draws at page load or inside a frame also match
* across worker counts; a value resolved on a tween's first render depends on the frame a worker reaches first.
*/
export interface VirtualTimeShimOptions {
/**
* When `true`, the shim additionally replaces `Math.random` and
* `crypto.getRandomValues` with a Mulberry32-seeded PRNG keyed by the
* current frame's virtual time. Compositions that call `Math.random()`
* during render then produce byte-identical pixels across machines and
* across replays of the same `(planDir, chunkIndex)` pair.
*
* Default `false`: leaves `Math.random` / `crypto.getRandomValues` native,
* preserving the in-process renderer's non-deterministic behavior for
* compositions that rely on it.
*/
seedRandomFromFrame: boolean;
}
const VIRTUAL_TIME_SHIM = String.raw`(function() {
if (window.__HF_VIRTUAL_TIME__) return;
var virtualNowMs = 0;
var rafId = 1;
var rafQueue = [];
var OriginalDate = Date;
var originalSetTimeout = window.setTimeout.bind(window);
var originalClearTimeout = window.clearTimeout.bind(window);
var originalSetInterval = window.setInterval.bind(window);
var originalClearInterval = window.clearInterval.bind(window);
var originalRequestAnimationFrame = window.requestAnimationFrame
? window.requestAnimationFrame.bind(window)
: null;
var originalCancelAnimationFrame = window.cancelAnimationFrame
? window.cancelAnimationFrame.bind(window)
: null;
/**
* Build the page-side virtual-time shim script.
*
* The shim freezes `Date.now`, `performance.now`, rAF, and the timers set
* after the first seek, so a render seek can deterministically advance the
* page's notion of "now". The renderer issues `__HF_VIRTUAL_TIME__.seekToTime(ms)`
* before every frame capture; everything timing-related on the page sees
* exactly `ms` until the next seek.
*
* When `options.seedRandomFromFrame` is `true`, the returned script also
* installs a seeded `Math.random` / `crypto.getRandomValues` keyed by the
* current virtual time — so compositions with stochastic visuals retry
* identically. When `false`, the shim emits no random-override code; the
* page's native `Math.random` is left alone (the in-process default).
*/
export function buildVirtualTimeShim(options: VirtualTimeShimOptions): string {
const seedRandomFromFrame = options.seedRandomFromFrame === true;
// The seeded-RNG block is gated at build time so the unlocked shim is
// byte-identical to the pre-flag form. Producer regression baselines
// compare on rendered pixels — but the file-server unit tests in
// `fileServer.test.ts` also string-match `VIRTUAL_TIME_SHIM`, and we want
// those matches to remain stable.
const seededRandomBlock = seedRandomFromFrame
? String.raw`
// Seeded Math.random / crypto.getRandomValues, keyed by virtual time.
// Mulberry32: single uint32 state, deterministic, fast.
var rngState = 0;
@@ -288,30 +270,7 @@ export function buildVirtualTimeShim(options: VirtualTimeShimOptions): string {
window.crypto.getRandomValues = __seededGetRandomValues;
} catch (e) {}
}
`
: "";
// The seekToTime hook reseeds when seeding is on; under seedRandomFromFrame=false
// we emit no extra call so the function body is byte-identical to the
// unseeded shim.
const seekToTimeReseedCall = seedRandomFromFrame ? "reseedRngFromTime(safeTimeMs);\n " : "";
return String.raw`(function() {
if (window.__HF_VIRTUAL_TIME__) return;
var virtualNowMs = 0;
var rafId = 1;
var rafQueue = [];
var OriginalDate = Date;
var originalSetTimeout = window.setTimeout.bind(window);
var originalClearTimeout = window.clearTimeout.bind(window);
var originalSetInterval = window.setInterval.bind(window);
var originalClearInterval = window.clearInterval.bind(window);
var originalRequestAnimationFrame = window.requestAnimationFrame
? window.requestAnimationFrame.bind(window)
: null;
var originalCancelAnimationFrame = window.cancelAnimationFrame
? window.cancelAnimationFrame.bind(window)
: null;
${seededRandomBlock}
function flushAnimationFrame() {
if (!rafQueue.length) return;
var current = rafQueue.slice();
@@ -442,7 +401,8 @@ ${seededRandomBlock}
// page starts there keep the schedule a one-worker render gives them.
if (safeTimeMs > 0) seekToTime(0);
}
${seekToTimeReseedCall}fireDueTimers(safeTimeMs);
reseedRngFromTime(safeTimeMs);
fireDueTimers(safeTimeMs);
virtualNowMs = safeTimeMs;
flushAnimationFrame();
return virtualNowMs;
@@ -461,14 +421,6 @@ ${seededRandomBlock}
},
};
})();`;
}
/**
* Default in-process virtual-time shim — `seedRandomFromFrame: false`.
* Existing call sites (`renderOrchestrator`, `probeStage`) import this
* constant. Distributed callers build their own with seeding enabled.
*/
const VIRTUAL_TIME_SHIM = buildVirtualTimeShim({ seedRandomFromFrame: false });
/**
* Render mode extension -- adds renderSeek() for frame-accurate seeking
@@ -0,0 +1,13 @@
{
"name": "random-stagger-workers",
"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.",
"tags": ["regression", "parallel", "render-compat"],
"minPsnr": 30,
"maxFrameFailures": 0,
"minAudioCorrelation": 0,
"maxAudioLagWindows": 1,
"renderConfig": {
"fps": 30,
"workers": 2
}
}
@@ -0,0 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:2d5665bb78e6cf9a065322ddcaef3f56f13d8b72d0b3c841734c15ce6b867160
size 74536
@@ -0,0 +1,3 @@
version https://git-lfs.github.com/spec/v1
oid sha256:6946b7491232166b7d0408f2a30e79a8cd60b3cfda2acf97a9515ebf7940228d
size 72084
@@ -0,0 +1,33 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=1080, height=1080">
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js" integrity="sha384-d+vyQ0dYcymoP8ndq2hW7FGC50nqGdXUEgoOUGxbbkAJwZqL7h+jKN0GGgn9hFDS" crossorigin="anonymous"></script>
<style>
body { margin: 0; background: #0d1117; width: 1080px; height: 1080px; overflow: hidden; }
#grid {
position: absolute; left: 140px; top: 140px; width: 800px; height: 800px;
display: grid; grid-template-columns: repeat(10, 1fr); grid-template-rows: repeat(10, 1fr); gap: 8px;
}
.cell { background: #e6edf3; border-radius: 6px; }
</style>
</head>
<body>
<div id="root" data-composition-id="root" data-width="1080" data-height="1080" data-duration="2"
style="position:absolute;width:1080px;height:1080px;">
<div id="grid"></div>
</div>
<script>
const grid = document.getElementById("grid");
for (let i = 0; i < 100; i++) {
const cell = document.createElement("div");
cell.className = "cell";
grid.appendChild(cell);
}
const tl = gsap.timeline({ paused: true });
tl.fromTo(".cell", { opacity: 1 }, { opacity: 0.1, duration: 0.1, ease: "none", stagger: { amount: 1.6, from: "random" } }, 0.2);
window.__timelines["root"] = tl;
</script>
</body>
</html>
@@ -38,6 +38,7 @@
"png-sequence": 3,
"portrait-edge-bleed": 6,
"raf-ball-render-compat": 10,
"random-stagger-workers": 8,
"timers-on-film-time": 8,
"render-symlinked-assets": 6,
"static-volume-future-set": 9,