fix(cli): expose render debug mode

Adds the render --debug CLI flag, forwards it through Docker/local render paths, and captures full producer debug artifacts from pipeline start.

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

@@ -171,6 +171,7 @@ describe("buildDockerRunArgs", () => {
         videoBitrate: undefined,
         videoFrameFormat: "png",
         quiet: true,
+        debug: true,
         entryFile: "compositions/intro.html",
       },
     });
@@ -188,6 +189,7 @@ describe("buildDockerRunArgs", () => {
     expect(args).toContain("--video-frame-format");
     expect(args).toContain("png");
     expect(args).toContain("--quiet");
+    expect(args).toContain("--debug");
     expect(args).toContain("--gpu");
     expect(args).toContain("--no-browser-gpu");
     expect(args).toContain("--hdr");
@@ -352,6 +354,18 @@ describe("buildDockerRunArgs", () => {
     expect(args).toContain("--no-page-side-compositing");
   });
 
+  it("keeps Docker debug artifacts under the mounted output directory", () => {
+    const args = buildDockerRunArgs({
+      ...FIXED_INPUT,
+      options: { ...BASE, debug: true },
+    });
+    const envIdx = args.indexOf("PRODUCER_RENDERS_DIR=/output/renders");
+    const imageIdx = args.indexOf(FIXED_INPUT.imageTag);
+    expect(envIdx).toBeGreaterThan(-1);
+    expect(envIdx).toBeLessThan(imageIdx);
+    expect(args).toContain("--debug");
+  });
+
   it("omits --no-page-side-compositing when pageSideCompositing is not explicitly false", () => {
     const args = buildDockerRunArgs({ ...FIXED_INPUT, options: BASE });
     expect(args).not.toContain("--no-page-side-compositing");

packages/cli/src/utils/dockerRunArgs.ts

@@ -50,6 +50,7 @@ export interface DockerRenderOptions {
   videoBitrate?: string;
   videoFrameFormat?: "auto" | "jpg" | "png";
   quiet: boolean;
+  debug?: boolean;
   variables?: Record<string, unknown>;
   entryFile?: string;
   /** Output resolution preset (e.g. "landscape-4k"). Forwarded as `--resolution`. */
@@ -109,6 +110,10 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
     `${projectDir}:/project:ro`,
     "-v",
     `${outputDir}:/output`,
+    // Keep debug artifacts on the mounted host output path. The producer roots
+    // `.debug` at dirname(PRODUCER_RENDERS_DIR), so `/output/renders` maps to
+    // `/output/.debug/<job id>` instead of a disposable container path.
+    ...(options.debug ? ["-e", "PRODUCER_RENDERS_DIR=/output/renders"] : []),
     imageTag,
     "/project",
     "--output",
@@ -128,6 +133,7 @@ export function buildDockerRunArgs(input: DockerRunArgsInput): string[] {
       ? ["--video-frame-format", options.videoFrameFormat]
       : []),
     ...(options.quiet ? ["--quiet"] : []),
+    ...(options.debug ? ["--debug"] : []),
     ...(options.gpu ? ["--gpu"] : []),
     ...(options.browserGpu ? [] : ["--no-browser-gpu"]),
     ...(options.hdrMode === "force-hdr" ? ["--hdr"] : []),