diff --git a/packages/producer/src/services/distributed/layeredEligibility.test.ts b/packages/producer/src/services/distributed/layeredEligibility.test.ts
index a51f3ed44c..9590c1d53d 100644
--- a/packages/producer/src/services/distributed/layeredEligibility.test.ts
+++ b/packages/producer/src/services/distributed/layeredEligibility.test.ts
@@ -1,10 +1,16 @@
import { describe, expect, it } from "bun:test";
-import { createLayeredChunkClassifier } from "./layeredEligibility.js";
+import { createLayeredChunkObserver, createLayeredChunkClassifier } from "./layeredEligibility.js";
import type { LayeredFrame } from "./layeredFrameState.js";
const frame: LayeredFrame = { kind: "candidate", signature: "video-rect-A", videoCount: 2 };
describe("whole-chunk layered eligibility", () => {
+ it("preserves a null injector without observing the page", () => {
+ const observer = createLayeredChunkObserver({ startFrame: 20, endFrame: 23 }, 25);
+ expect(observer.wrap(null)).toBeNull();
+ expect(observer.decision()).toEqual({ kind: "fallback", reason: "no_video", frameIndex: null });
+ });
+
it("requires every absolute frame, independently of worker completion order", () => {
const classifier = createLayeredChunkClassifier({ startFrame: 20, endFrame: 23 });
classifier.observe(22, frame);
diff --git a/packages/producer/src/services/distributed/layeredEligibility.ts b/packages/producer/src/services/distributed/layeredEligibility.ts
index b30644dd76..8c38075e30 100644
--- a/packages/producer/src/services/distributed/layeredEligibility.ts
+++ b/packages/producer/src/services/distributed/layeredEligibility.ts
@@ -32,6 +32,9 @@ export function createLayeredChunkClassifier({ startFrame, endFrame }: ChunkFram
}
return {
+ excludeNoVideo(): void {
+ failure = { kind: "fallback", reason: "no_video", frameIndex: null };
+ },
observe(frameIndex: number, frame: LayeredFrame): void {
if (!inRange(frameIndex)) return;
observed.add(frameIndex);
@@ -58,9 +61,13 @@ export function createLayeredChunkObserver(range: ChunkFrameRange, fps: number)
const classifier = createLayeredChunkClassifier({ startFrame, endFrame });
if (!Number.isFinite(fps) || fps <= 0) throw new Error("Invalid layered chunk FPS");
return {
- wrap(inject: BeforeCaptureHook | null): BeforeCaptureHook {
+ wrap(inject: BeforeCaptureHook | null): BeforeCaptureHook | null {
+ if (inject === null) {
+ classifier.excludeNoVideo();
+ return null;
+ }
return async (page, time, heldVideoTime) => {
- await inject?.(page, time, heldVideoTime);
+ await inject(page, time, heldVideoTime);
const frameIndex = Math.round(time * fps);
const decision = classifier.decision();
if (
@@ -74,7 +81,13 @@ export function createLayeredChunkObserver(range: ChunkFrameRange, fps: number)
return;
}
await waitForPendingSeekCompletion(page);
- classifier.observe(frameIndex, await readLayeredFrame(page));
+ let frame: LayeredFrame;
+ try {
+ frame = await readLayeredFrame(page);
+ } catch {
+ frame = { kind: "fallback", reason: "observation_error" };
+ }
+ classifier.observe(frameIndex, frame);
};
},
decision: classifier.decision,
diff --git a/packages/producer/src/services/distributed/layeredFrame.integration.test.ts b/packages/producer/src/services/distributed/layeredFrame.integration.test.ts
index ebd5abbc24..4c74e05798 100644
--- a/packages/producer/src/services/distributed/layeredFrame.integration.test.ts
+++ b/packages/producer/src/services/distributed/layeredFrame.integration.test.ts
@@ -126,6 +126,7 @@ describe("browser layered frame facts", () => {
document.querySelector("img")!.style.transform = t === 0.04 ? "rotate(5deg)" : "none";
}, time);
});
+ if (hook === null) throw new Error("Expected video hook");
for (const time of [0, 0.04, 0.08]) await hook(page, time);
expect(observer.decision()).toEqual({
kind: "fallback",
@@ -141,6 +142,7 @@ describe("browser layered frame facts", () => {
const hook = observer.wrap(async (_page, time, held) => {
calls.push([time, held ?? -1]);
});
+ if (hook === null) throw new Error("Expected video hook");
for (const frame of [10, 12, 11]) await hook(page, frame / 25, 0);
expect(calls).toEqual([
[0.4, 0],
@@ -170,7 +172,9 @@ describe("browser layered frame facts", () => {
it("does not certify fractional frame samples as complete integer frames", async () => {
await fixture();
const observer = createLayeredChunkObserver({ startFrame: 0, endFrame: 1 }, 25);
- await observer.wrap(null)(page, 0.01);
+ const hook = observer.wrap(async () => {});
+ if (hook === null) throw new Error("Expected video hook");
+ await hook(page, 0.01);
expect(observer.decision()).toEqual({
kind: "fallback",
reason: "unsupported_sampling",
@@ -178,14 +182,58 @@ describe("browser layered frame facts", () => {
});
});
+ it("falls back on the infinite CSS transform that still screenshots successfully", async () => {
+ await fixture(
+ "",
+ '
bad transform
',
+ );
+ const before = Buffer.from(await page.screenshot());
+ const observer = createLayeredChunkObserver({ startFrame: 0, endFrame: 1 }, 25);
+ const hook = observer.wrap(async () => {});
+ if (hook === null) throw new Error("Expected video hook");
+ await expect(readLayeredFrame(page)).rejects.toThrow("DOMMatrix");
+ await hook(page, 0);
+ expect(observer.decision()).toEqual({
+ kind: "fallback",
+ reason: "observation_error",
+ frameIndex: 0,
+ });
+ expect(Buffer.from(await page.screenshot()).equals(before)).toBe(true);
+ });
+
+ it("propagates seek completion failure outside the observation boundary", async () => {
+ await fixture();
+ await page.evaluate(() =>
+ Object.defineProperty(window, "__hfWaitForSeekCompletion", {
+ configurable: true,
+ value: async () => {
+ throw new Error("seek failed");
+ },
+ }),
+ );
+ try {
+ const observer = createLayeredChunkObserver({ startFrame: 0, endFrame: 1 }, 25);
+ const hook = observer.wrap(async () => {});
+ if (hook === null) throw new Error("Expected video hook");
+ await expect(hook(page, 0)).rejects.toThrow("seek failed");
+ expect(observer.decision()).toEqual({
+ kind: "fallback",
+ reason: "incomplete_frames",
+ frameIndex: null,
+ });
+ } finally {
+ await page.evaluate(() => Reflect.deleteProperty(window, "__hfWaitForSeekCompletion"));
+ }
+ });
+
it("propagates injector failure without claiming eligibility", async () => {
await fixture();
const observer = createLayeredChunkObserver({ startFrame: 0, endFrame: 1 }, 25);
- await expect(
- observer.wrap(async () => {
- throw new Error("inject failed");
- })(page, 0),
- ).rejects.toThrow("inject failed");
+ const hook = observer.wrap(async () => {
+ throw new Error("inject failed");
+ });
+ if (hook === null) throw new Error("Expected video hook");
+ await expect(hook(page, 0)).rejects.toThrow("inject failed");
expect(observer.decision()).toEqual({
kind: "fallback",
reason: "incomplete_frames",
diff --git a/packages/producer/src/services/distributed/layeredFrameState.ts b/packages/producer/src/services/distributed/layeredFrameState.ts
index b93f037ff7..dbb95df9ef 100644
--- a/packages/producer/src/services/distributed/layeredFrameState.ts
+++ b/packages/producer/src/services/distributed/layeredFrameState.ts
@@ -1,4 +1,5 @@
export type LayeredFallbackReason =
+ | "observation_error"
| "unsupported_sampling"
| "scene_complexity"
| "no_video"
diff --git a/packages/producer/src/services/distributed/renderChunk.test.ts b/packages/producer/src/services/distributed/renderChunk.test.ts
index 1158e78d3f..7ef63aaac6 100644
--- a/packages/producer/src/services/distributed/renderChunk.test.ts
+++ b/packages/producer/src/services/distributed/renderChunk.test.ts
@@ -40,6 +40,7 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import {
type CaptureOptions,
+ type CaptureSession,
extractVideoFramesRange,
VideoSourceExtractionError,
} from "@hyperframes/engine";
@@ -199,6 +200,56 @@ describe("renderChunk()", () => {
// on slower CI workers.
const TIMEOUT_MS = 60_000;
+ it.each([false, true])(
+ "keeps the null capture hook with layered observation requested=%s",
+ async (requested) => {
+ if (!hasChrome) throw new Error("Chrome required for layered observation wiring proof");
+ const sessions: CaptureSession[] = [];
+ const original = distributedCaptureSessionDependencies.createCaptureSession;
+ const create = spyOn(
+ distributedCaptureSessionDependencies,
+ "createCaptureSession",
+ ).mockImplementation(async (...args) => {
+ const session = await original(...args);
+ sessions.push(session);
+ return session;
+ });
+ const info = spyOn(defaultLogger, "info");
+ try {
+ const options = requested ? { observeLayeredEligibility: true } : undefined;
+ const result = await renderChunk(
+ planDir,
+ 0,
+ join(runRoot, `observation-${requested}`),
+ options,
+ );
+ expect(result.framesEncoded).toBeGreaterThan(0);
+ expect(sessions.length).toBeGreaterThan(0);
+ expect(sessions.every((session) => session.onBeforeCapture === null)).toBe(true);
+ const decisions = info.mock.calls
+ .filter(([message]) => message === "[renderChunk] layered eligibility")
+ .map(([, meta]) => meta);
+ if (requested) {
+ expect(decisions).toEqual([
+ {
+ chunkIndex: 0,
+ kind: "fallback",
+ reason: "no_video",
+ frameIndex: null,
+ renderPath: "existing",
+ },
+ ]);
+ } else {
+ expect(decisions).toEqual([]);
+ }
+ } finally {
+ create.mockRestore();
+ info.mockRestore();
+ }
+ },
+ TIMEOUT_MS,
+ );
+
it(
"produces a byte-identical chunk on a second invocation (byte-identical-retry contract)",
async () => {
@@ -219,12 +270,10 @@ describe("renderChunk()", () => {
// there against an image where chrome://gpu works.
const outA = join(runRoot, "chunk-a");
const outB = join(runRoot, "chunk-b");
- const info = spyOn(defaultLogger, "info");
let a, b;
try {
a = await renderChunk(planDir, 0, outA);
} catch (err) {
- info.mockRestore();
const message = err instanceof Error ? err.message : String(err);
if (HOST_CHROME_FAILURE_PATTERNS.test(message)) {
console.warn(
@@ -236,31 +285,7 @@ describe("renderChunk()", () => {
}
throw err;
}
- try {
- b = await renderChunk(planDir, 0, outB);
- expect(
- info.mock.calls
- .filter(([message]) => message === "[renderChunk] layered eligibility")
- .map(([, meta]) => meta),
- ).toEqual([
- {
- chunkIndex: 0,
- kind: "fallback",
- reason: "no_video",
- frameIndex: 0,
- renderPath: "existing",
- },
- {
- chunkIndex: 0,
- kind: "fallback",
- reason: "no_video",
- frameIndex: 0,
- renderPath: "existing",
- },
- ]);
- } finally {
- info.mockRestore();
- }
+ b = await renderChunk(planDir, 0, outB);
// png-sequence chunks produce a directory of frames, not a single file.
expect(a.outputKind).toBe("frame-dir");
diff --git a/packages/producer/src/services/distributed/renderChunk.ts b/packages/producer/src/services/distributed/renderChunk.ts
index 19f944d807..7235423781 100644
--- a/packages/producer/src/services/distributed/renderChunk.ts
+++ b/packages/producer/src/services/distributed/renderChunk.ts
@@ -199,6 +199,7 @@ export interface ChunkFrameRange {
}
export interface RenderChunkOptions {
+ observeLayeredEligibility?: boolean;
/**
* Render only these frames of the chunk, e.g. to retry a slow chunk as
* parts rendered in parallel. Must be a non-empty range inside the chunk's
@@ -841,10 +842,14 @@ export async function renderChunk(
forceScreenshot: forceScreenshotForChunk,
// fallow-ignore-next-line complexity
run: async (forceScreenshot) => {
- const layeredObserver = createLayeredChunkObserver(
- range,
- resolveRenderFpsConfig(job.config.fps).value,
- );
+ const layeredObserver =
+ options?.observeLayeredEligibility === true
+ ? createLayeredChunkObserver(range, resolveRenderFpsConfig(job.config.fps).value)
+ : null;
+ const createCaptureInjector =
+ layeredObserver === null
+ ? createChunkVideoFrameInjector
+ : () => layeredObserver.wrap(createChunkVideoFrameInjector());
const captureCfg: EngineConfig =
cfg.forceScreenshot === forceScreenshot
? cfg
@@ -893,18 +898,19 @@ export async function renderChunk(
// fallback remains observable to adapters and smoke tests.
dedupPerfs: capturePerfs,
buildCaptureOptions: () => captureOptions,
- createRenderVideoFrameInjector: () =>
- layeredObserver.wrap(createChunkVideoFrameInjector()),
+ createRenderVideoFrameInjector: createCaptureInjector,
abortSignal: undefined,
assertNotAborted: () => {},
frameRange: range,
});
- log.info("[renderChunk] layered eligibility", {
- chunkIndex,
- ...layeredObserver.decision(),
- renderPath: "existing",
- });
+ if (layeredObserver !== null) {
+ log.info("[renderChunk] layered eligibility", {
+ chunkIndex,
+ ...layeredObserver.decision(),
+ renderPath: "existing",
+ });
+ }
const observedModes = new Set(capturePerfs.map((perf) => perf.captureMode));
if (observedModes.size !== 1 || ![...observedModes].every(isCaptureMode)) {