Skip to content

Commit 050fad6

Browse files
committed
fix(render): surface structured outcomes
1 parent 16942c0 commit 050fad6

23 files changed

Lines changed: 880 additions & 184 deletions

File tree

‎.fallowrc.jsonc‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -211,7 +211,12 @@
211211
// Exported for render.test.ts (exported-for-tests pattern).
212212
{
213213
"file": "packages/cli/src/commands/render.ts",
214-
"exports": ["resolveBrowserGpuForCli", "renderLocal", "checkRenderResolutionPreflight"],
214+
"exports": [
215+
"resolveBrowserGpuForCli",
216+
"renderLocal",
217+
"checkRenderResolutionPreflight",
218+
"renderLintContinuationHint",
219+
],
215220
},
216221
// initThreeDProjectionInPage: passed to page.evaluate() for browser-side execution —
217222
// Puppeteer serializes it at runtime, not an import-graph consumer.

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

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ vi.mock("../utils/producer.js", () => ({
8080
}),
8181
createRenderJob: vi.fn((config: Record<string, unknown>) => {
8282
producerState.createdJobs.push(config);
83-
return { config, progress: 100 };
83+
return { config, progress: 100, outcome: "completed", warnings: [] };
8484
}),
8585
executeRenderJob: vi.fn(async (job: Record<string, unknown>) => producerState.executeImpl(job)),
8686
})),
@@ -413,6 +413,21 @@ describe("renderLocal browser GPU config", () => {
413413
expect(producerState.createdJobs[0]?.debug).toBe(true);
414414
});
415415

416+
it("defaults to strict readiness and forwards explicit best-effort mode", async () => {
417+
await renderLocal("/tmp/project", "/tmp/out.mp4", {
418+
fps: { num: 30, den: 1 },
419+
quality: "standard",
420+
format: "mp4",
421+
gpu: false,
422+
browserGpuMode: "software",
423+
hdrMode: "auto",
424+
quiet: true,
425+
bestEffort: true,
426+
});
427+
428+
expect(producerState.createdJobs[0]?.strictness).toBe("best-effort");
429+
});
430+
416431
it("omits variables from createRenderJob when not provided", async () => {
417432
await renderLocal("/tmp/project", "/tmp/out.mp4", {
418433
fps: { num: 30, den: 1 },

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

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,12 @@ export default defineCommand({
267267
"Write full render diagnostics and keep intermediate artifacts under the producer .debug directory.",
268268
default: false,
269269
},
270+
"best-effort": {
271+
type: "boolean",
272+
description:
273+
"Allow output with structured capture-readiness warnings. By default missing or unready media fails the render.",
274+
default: false,
275+
},
270276
strict: {
271277
type: "boolean",
272278
description: "Fail render on lint errors",
@@ -622,6 +628,7 @@ export default defineCommand({
622628
const browserGpuMode = resolveBrowserGpuForCli(useDocker, browserGpuArg);
623629
const quiet = args.quiet ?? false;
624630
const debug = args.debug ?? false;
631+
const bestEffort = args["best-effort"] ?? false;
625632
const batchJson = args.json ?? false;
626633
const effectiveQuiet = quiet || (batchPath != null && batchJson);
627634
const strictAll = args["strict-all"] ?? false;
@@ -902,6 +909,7 @@ export default defineCommand({
902909
protocolTimeout,
903910
playerReadyTimeout,
904911
debug,
912+
bestEffort,
905913
exitAfterComplete: false,
906914
throwOnError: true,
907915
skipFeedback: true,
@@ -960,6 +968,7 @@ export default defineCommand({
960968
videoFrameFormat,
961969
quiet,
962970
debug,
971+
bestEffort,
963972
variables,
964973
entryFile,
965974
outputResolution,
@@ -988,6 +997,7 @@ export default defineCommand({
988997
quiet,
989998
browserPath,
990999
debug,
1000+
bestEffort,
9911001
variables,
9921002
entryFile,
9931003
outputResolution,
@@ -1006,6 +1016,8 @@ export default defineCommand({
10061016
export interface SingleRenderResult {
10071017
durationMs?: number;
10081018
renderTimeMs: number;
1019+
outcome?: "completed" | "completed_with_warnings";
1020+
warnings?: Array<{ code: string; message: string }>;
10091021
}
10101022

10111023
export function renderLintContinuationHint(strictErrors: boolean): string {
@@ -1036,6 +1048,7 @@ interface RenderOptions {
10361048
videoFrameFormat?: VideoFrameFormat;
10371049
quiet: boolean;
10381050
debug?: boolean;
1051+
bestEffort?: boolean;
10391052
browserPath?: string;
10401053
variables?: Record<string, unknown>;
10411054
entryFile?: string;
@@ -1370,6 +1383,7 @@ async function renderDocker(
13701383
outputResolution: options.outputResolution,
13711384
pageSideCompositing: options.pageSideCompositing,
13721385
debug: options.debug,
1386+
bestEffort: options.bestEffort,
13731387
experimentalFastCapture: options.experimentalFastCapture,
13741388
pageNavigationTimeoutMs: options.pageNavigationTimeoutMs,
13751389
},
@@ -1490,6 +1504,7 @@ export async function renderLocal(
14901504
entryFile: options.entryFile,
14911505
outputResolution: options.outputResolution,
14921506
debug: options.debug,
1507+
strictness: options.bestEffort ? "best-effort" : "strict",
14931508
});
14941509

14951510
const onProgress = options.quiet
@@ -1515,6 +1530,11 @@ export async function renderLocal(
15151530

15161531
maybeConsumeDeParallelRouterTrial(deParallelRouterTrialArmed, job, options.quiet);
15171532
const elapsed = Date.now() - startTime;
1533+
if (job.outcome === "completed_with_warnings") {
1534+
for (const warning of job.warnings) {
1535+
console.warn(c.warn(` [${warning.code}] ${warning.message}`));
1536+
}
1537+
}
15181538
trackRenderMetrics(job, elapsed, options, false);
15191539
printRenderComplete(
15201540
outputPath,
@@ -1534,7 +1554,14 @@ export async function renderLocal(
15341554
const durationMs = job.perfSummary
15351555
? Math.round(job.perfSummary.compositionDurationSeconds * 1000)
15361556
: undefined;
1537-
return { renderTimeMs: elapsed, durationMs };
1557+
const outcome =
1558+
job.outcome === "completed_with_warnings" ? "completed_with_warnings" : "completed";
1559+
return {
1560+
renderTimeMs: elapsed,
1561+
durationMs,
1562+
outcome,
1563+
warnings: job.warnings.map((warning) => ({ code: warning.code, message: warning.message })),
1564+
};
15381565
}
15391566

15401567
type UnrefableTimer = {

‎packages/cli/src/server/studioRenderTelemetry.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,7 @@ describe("studioRenderTelemetry", () => {
280280
progress: 25,
281281
currentStage: "Starting frame capture",
282282
createdAt: new Date(),
283+
warnings: [],
283284
errorDetails: {
284285
message: "Navigation timeout of 60000 ms exceeded",
285286
elapsedMs: 60_001,

‎packages/cli/src/utils/dockerRunArgs.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@ describe("buildDockerRunArgs", () => {
172172
videoFrameFormat: "png",
173173
quiet: true,
174174
debug: true,
175+
bestEffort: true,
175176
entryFile: "compositions/intro.html",
176177
experimentalFastCapture: true,
177178
},
@@ -191,6 +192,7 @@ describe("buildDockerRunArgs", () => {
191192
expect(args).toContain("png");
192193
expect(args).toContain("--quiet");
193194
expect(args).toContain("--debug");
195+
expect(args).toContain("--best-effort");
194196
expect(args).toContain("--gpu");
195197
expect(args).toContain("--no-browser-gpu");
196198
expect(args).toContain("--hdr");

‎packages/cli/src/utils/dockerRunArgs.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ export interface DockerRenderOptions {
5151
videoFrameFormat?: "auto" | "jpg" | "png";
5252
quiet: boolean;
5353
debug?: boolean;
54+
bestEffort?: boolean;
5455
variables?: Record<string, unknown>;
5556
entryFile?: string;
5657
/** Output resolution preset (e.g. "landscape-4k"). Forwarded as `--resolution`. */
@@ -136,6 +137,7 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
136137
: []),
137138
...(options.quiet ? ["--quiet"] : []),
138139
...(options.debug ? ["--debug"] : []),
140+
...(options.bestEffort ? ["--best-effort"] : []),
139141
...(options.gpu ? ["--gpu"] : []),
140142
...(options.browserGpu ? [] : ["--no-browser-gpu"]),
141143
...(options.hdrMode === "force-hdr" ? ["--hdr"] : []),

‎packages/engine/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ export type {
4040
CaptureResult,
4141
CaptureBufferResult,
4242
CapturePerfSummary,
43+
CaptureWarning,
44+
CaptureWarningCode,
4345
SubTimelineWaitOutcome,
4446
} from "./types.js";
4547

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
import { describe, expect, it } from "vitest";
2+
import type { Page } from "puppeteer-core";
3+
import { collectMediaReadinessWarnings } from "./frameCapture.js";
4+
5+
function makePage(input: {
6+
images?: Array<{ src: string; complete: boolean; naturalWidth: number }>;
7+
media?: Array<{
8+
id?: string;
9+
tagName: "VIDEO" | "AUDIO";
10+
src: string;
11+
readyState: number;
12+
networkState?: number;
13+
error?: unknown;
14+
}>;
15+
}): Page {
16+
return {
17+
evaluate: async (fn: (skipIds: readonly string[]) => unknown, skipIds: readonly string[]) => {
18+
const previousDocument = Reflect.get(globalThis, "document");
19+
const previousMedia = Reflect.get(globalThis, "HTMLMediaElement");
20+
Reflect.set(globalThis, "HTMLMediaElement", {
21+
NETWORK_NO_SOURCE: 3,
22+
HAVE_CURRENT_DATA: 2,
23+
});
24+
Reflect.set(globalThis, "document", {
25+
querySelectorAll: (selector: string) => {
26+
if (selector === "img") {
27+
return (input.images ?? []).map((image) => ({
28+
...image,
29+
getAttribute: (name: string) => (name === "src" ? image.src : null),
30+
}));
31+
}
32+
const media =
33+
selector === "video"
34+
? (input.media ?? []).filter((element) => element.tagName === "VIDEO")
35+
: (input.media ?? []);
36+
return media.map((media) => ({
37+
id: media.id ?? "",
38+
tagName: media.tagName,
39+
currentSrc: media.src,
40+
readyState: media.readyState,
41+
networkState: media.networkState ?? 1,
42+
error: media.error ?? null,
43+
getAttribute: (name: string) => (name === "src" ? media.src : null),
44+
}));
45+
},
46+
});
47+
try {
48+
return await fn(skipIds);
49+
} finally {
50+
Reflect.set(globalThis, "document", previousDocument);
51+
Reflect.set(globalThis, "HTMLMediaElement", previousMedia);
52+
}
53+
},
54+
} as unknown as Page;
55+
}
56+
57+
describe("collectMediaReadinessWarnings", () => {
58+
it("returns stable warnings for visual media and ignores out-of-band audio", async () => {
59+
const page = makePage({
60+
images: [
61+
{ src: "/pending.png", complete: false, naturalWidth: 0 },
62+
{ src: "/broken.png", complete: true, naturalWidth: 0 },
63+
],
64+
media: [
65+
{ tagName: "VIDEO", src: "/broken.mp4", readyState: 0, error: new Error("decode") },
66+
{ tagName: "AUDIO", src: "/pending.mp3", readyState: 1 },
67+
{ id: "injected", tagName: "VIDEO", src: "/injected.mp4", readyState: 0 },
68+
],
69+
});
70+
71+
const warnings = await collectMediaReadinessWarnings(page, ["injected"], 45000);
72+
73+
expect(warnings.map((warning) => [warning.code, warning.details?.mediaType])).toEqual([
74+
["media_readiness_timeout", "image"],
75+
["media_load_failed", "image"],
76+
["media_load_failed", "video"],
77+
]);
78+
expect(warnings.every((warning) => warning.details?.timeoutMs === 45000)).toBe(true);
79+
});
80+
81+
it("returns no warnings when every relevant resource is ready", async () => {
82+
const page = makePage({
83+
images: [{ src: "/ready.png", complete: true, naturalWidth: 100 }],
84+
media: [
85+
{ tagName: "VIDEO", src: "/ready.mp4", readyState: 2 },
86+
{ tagName: "AUDIO", src: "/ready.mp3", readyState: 2 },
87+
],
88+
});
89+
90+
await expect(collectMediaReadinessWarnings(page, [], 1000)).resolves.toEqual([]);
91+
});
92+
});

0 commit comments

Comments
 (0)