fix(render): surface structured outcomes (#2153)

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

@@ -172,6 +172,7 @@ describe("buildDockerRunArgs", () => {
         videoFrameFormat: "png",
         quiet: true,
         debug: true,
+        bestEffort: false,
         entryFile: "compositions/intro.html",
         experimentalFastCapture: true,
       },
@@ -191,6 +192,7 @@ describe("buildDockerRunArgs", () => {
     expect(args).toContain("png");
     expect(args).toContain("--quiet");
     expect(args).toContain("--debug");
+    expect(args).toContain("--no-best-effort");
     expect(args).toContain("--gpu");
     expect(args).toContain("--no-browser-gpu");
     expect(args).toContain("--hdr");
@@ -199,6 +201,21 @@ describe("buildDockerRunArgs", () => {
     expect(args).toContain("--experimental-fast-capture");
   });
 
+  it("forwards only an explicit strict-readiness opt-in", () => {
+    const compatible = buildDockerRunArgs({
+      ...FIXED_INPUT,
+      options: { ...BASE, bestEffort: true },
+    });
+    expect(compatible).not.toContain("--best-effort");
+    expect(compatible).not.toContain("--no-best-effort");
+
+    const strict = buildDockerRunArgs({
+      ...FIXED_INPUT,
+      options: { ...BASE, bestEffort: false },
+    });
+    expect(strict).toContain("--no-best-effort");
+  });
+
   it("forwards --experimental-fast-capture only when enabled", () => {
     const on = buildDockerRunArgs({
       ...FIXED_INPUT,

packages/cli/src/utils/dockerRunArgs.ts

@@ -51,6 +51,7 @@ export interface DockerRenderOptions {
   videoFrameFormat?: "auto" | "jpg" | "png";
   quiet: boolean;
   debug?: boolean;
+  bestEffort?: boolean;
   variables?: Record<string, unknown>;
   entryFile?: string;
   /** Output resolution preset (e.g. "landscape-4k"). Forwarded as `--resolution`. */
@@ -136,6 +137,9 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
       : []),
     ...(options.quiet ? ["--quiet"] : []),
     ...(options.debug ? ["--debug"] : []),
+    // The in-container CLI is best-effort by default. Only forward the
+    // explicit strict opt-in so Docker and local renders cannot drift.
+    ...(options.bestEffort === false ? ["--no-best-effort"] : []),
     ...(options.gpu ? ["--gpu"] : []),
     ...(options.browserGpu ? [] : ["--no-browser-gpu"]),
     ...(options.hdrMode === "force-hdr" ? ["--hdr"] : []),