fix(producer): keep layered observation opt-in and non-fatal

This commit is contained in:
Miguel Ángel
2026-10-22 11:43:48 -04:00
parent fac056233c
commit fc89da2764
6 changed files with 147 additions and 48 deletions
@@ -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);
@@ -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,
@@ -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(
"",
'<div style="position:absolute;z-index:2;--progress:0;transform:scale(calc(1 / var(--progress)))">bad transform</div>',
);
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",
@@ -1,4 +1,5 @@
export type LayeredFallbackReason =
| "observation_error"
| "unsupported_sampling"
| "scene_complexity"
| "no_video"
@@ -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");
@@ -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)) {