feat(cli): add --resolution flag to hyperframes render for one-line 4k

packages/producer/src/services/renderOrchestrator.test.ts

@@ -20,6 +20,7 @@ import {
   isRecoverableParallelCaptureError,
   materializeExtractedFramesForCompiledDir,
   projectBrowserEndToCompositionTimeline,
+  resolveDeviceScaleFactor,
   resolveRenderWorkerCount,
   resolveCompositeTransfer,
   selectCaptureCalibrationFrames,
@@ -749,3 +750,82 @@ describe("projectBrowserEndToCompositionTimeline", () => {
     expect(projectBrowserEndToCompositionTimeline(21.5, 1.5, 5.5)).toBe(25.5);
   });
 });
+
+describe("resolveDeviceScaleFactor", () => {
+  const defaults = {
+    compositionWidth: 1920,
+    compositionHeight: 1080,
+    hdrRequested: false,
+  } as const;
+
+  it("returns 1 when no outputResolution is set (default behavior)", () => {
+    expect(resolveDeviceScaleFactor({ ...defaults, outputResolution: undefined })).toBe(1);
+  });
+
+  it("returns 2 for the canonical 1080p → 4K supersample", () => {
+    expect(resolveDeviceScaleFactor({ ...defaults, outputResolution: "landscape-4k" })).toBe(2);
+  });
+
+  it("returns 2 for portrait 1080p → portrait-4k", () => {
+    expect(
+      resolveDeviceScaleFactor({
+        ...defaults,
+        compositionWidth: 1080,
+        compositionHeight: 1920,
+        outputResolution: "portrait-4k",
+      }),
+    ).toBe(2);
+  });
+
+  it("returns 1 when the composition already matches the requested resolution", () => {
+    expect(
+      resolveDeviceScaleFactor({
+        compositionWidth: 3840,
+        compositionHeight: 2160,
+        outputResolution: "landscape-4k",
+        hdrRequested: false,
+      }),
+    ).toBe(1);
+  });
+
+  it("rejects HDR + outputResolution with a clear message", () => {
+    expect(() =>
+      resolveDeviceScaleFactor({
+        ...defaults,
+        outputResolution: "landscape-4k",
+        hdrRequested: true,
+      }),
+    ).toThrow(/hdrMode='force-hdr'/);
+  });
+
+  it("rejects orientation mismatch (landscape comp → portrait-4k)", () => {
+    expect(() =>
+      resolveDeviceScaleFactor({ ...defaults, outputResolution: "portrait-4k" }),
+    ).toThrow(/aspect ratio/);
+  });
+
+  it("rejects downsampling (4K composition → 1080p output)", () => {
+    expect(() =>
+      resolveDeviceScaleFactor({
+        compositionWidth: 3840,
+        compositionHeight: 2160,
+        outputResolution: "landscape",
+        hdrRequested: false,
+      }),
+    ).toThrow(/Downsampling/);
+  });
+
+  it("rejects non-integer scale factors", () => {
+    // 1280×720 → 3840×2160 would be 3×, but width 1280 → 3840 is also 3× — that's actually integer.
+    // Use 1280×720 → 2160×3840 (mismatched orientation triggers aspect first), so use a real
+    // non-integer: 1500×844 → 3840×2160 = 2.56×.
+    expect(() =>
+      resolveDeviceScaleFactor({
+        compositionWidth: 1500,
+        compositionHeight: 844,
+        outputResolution: "landscape-4k",
+        hdrRequested: false,
+      }),
+    ).toThrow(/aspect ratio|non-integer/);
+  });
+});

packages/producer/src/services/renderOrchestrator.ts

@@ -29,6 +29,7 @@ import {
   symlinkSync,
 } from "fs";
 import { parseHTML } from "linkedom";
+import { CANVAS_DIMENSIONS, type CanvasResolution } from "@hyperframes/core";
 import {
   type EngineConfig,
   resolveConfig,
@@ -279,6 +280,24 @@ export interface RenderConfig {
    * `--variables-file <path>`. Must be a JSON-serializable plain object.
    */
   variables?: Record<string, unknown>;
+  /**
+   * Override the output resolution. The composition's intrinsic
+   * `data-width` / `data-height` continue to drive page layout (Chrome
+   * viewport), and supersampling is achieved by setting Chrome's
+   * `deviceScaleFactor` so the captured screenshot lands at the requested
+   * dimensions. Passing a 4K preset on a 1080p composition therefore
+   * produces a 4K output without rewriting any composition HTML.
+   *
+   * Constraint: the requested dimensions must be an integer multiple of
+   * the composition's intrinsic dimensions (so DPR is a clean integer).
+   * Non-integer scales are rejected with an explanatory error before any
+   * frames are captured.
+   *
+   * Not yet supported with HDR (the layered HDR compositor processes
+   * pixel buffers at composition dimensions and would need parallel
+   * scaling); the orchestrator errors when both are set.
+   */
+  outputResolution?: CanvasResolution;
 }
 
 export interface RenderPerfSummary {
@@ -563,6 +582,68 @@ export function projectBrowserEndToCompositionTimeline(
   return browserEnd + (existingStart - browserStart);
 }
 
+/**
+ * Translate the user-facing `--resolution` flag into a Chrome
+ * `deviceScaleFactor`. The composition's intrinsic dimensions stay the
+ * page-layout viewport; the screenshot lands at output dims via DPR.
+ *
+ * The scale must be a positive integer ≥ 1 — fractional DPRs introduce
+ * visible aliasing and we'd rather fail loudly than produce a blurry
+ * 4K render. Downsampling (output < composition) is rejected because
+ * the user is unlikely to have intended it; if the use case appears
+ * we can plumb a separate flag.
+ *
+ * Throws on:
+ *   - HDR + outputResolution combination (HDR layered compositor would
+ *     need parallel scaling for its raw pixel buffers).
+ *   - Non-integer scale (e.g. 720p composition, 4K output → 3× height
+ *     but the width ratio is also 3× ✓; 1080p portrait → 4K landscape
+ *     would mismatch).
+ *   - Output dimensions smaller than composition dimensions.
+ */
+export function resolveDeviceScaleFactor(input: {
+  compositionWidth: number;
+  compositionHeight: number;
+  outputResolution: CanvasResolution | undefined;
+  hdrRequested: boolean;
+}): number {
+  if (!input.outputResolution) return 1;
+  if (input.hdrRequested) {
+    throw new Error(
+      "outputResolution cannot be combined with hdrMode='force-hdr'. " +
+        "HDR rendering composites at composition dimensions and does not yet " +
+        "support supersampling. Pick one or render in two passes.",
+    );
+  }
+  const target = CANVAS_DIMENSIONS[input.outputResolution];
+  const widthRatio = target.width / input.compositionWidth;
+  const heightRatio = target.height / input.compositionHeight;
+  if (widthRatio !== heightRatio) {
+    throw new Error(
+      `outputResolution ${input.outputResolution} (${target.width}×${target.height}) ` +
+        `does not match the aspect ratio of the composition ` +
+        `(${input.compositionWidth}×${input.compositionHeight}). ` +
+        `Pick a preset whose orientation matches.`,
+    );
+  }
+  if (widthRatio < 1) {
+    throw new Error(
+      `outputResolution ${input.outputResolution} (${target.width}×${target.height}) ` +
+        `is smaller than the composition (${input.compositionWidth}×${input.compositionHeight}). ` +
+        `Downsampling via --resolution is not supported.`,
+    );
+  }
+  if (!Number.isInteger(widthRatio)) {
+    throw new Error(
+      `outputResolution ${input.outputResolution} requires a non-integer ` +
+        `device scale factor (${widthRatio}×) to upsample from ` +
+        `${input.compositionWidth}×${input.compositionHeight}. ` +
+        `Pick a preset that's an integer multiple, or rescale the composition.`,
+    );
+  }
+  return widthRatio;
+}
+
 function updateJobStatus(
   job: RenderJob,
   status: RenderStatus,
@@ -2053,6 +2134,22 @@ export async function executeRenderJob(
       height: compiled.height,
     };
     const { width, height } = composition;
+    const deviceScaleFactor = resolveDeviceScaleFactor({
+      compositionWidth: width,
+      compositionHeight: height,
+      outputResolution: job.config.outputResolution,
+      hdrRequested: job.config.hdrMode === "force-hdr",
+    });
+    if (deviceScaleFactor > 1) {
+      log.info("Supersampling composition via deviceScaleFactor", {
+        compositionWidth: width,
+        compositionHeight: height,
+        outputResolution: job.config.outputResolution,
+        outputWidth: width * deviceScaleFactor,
+        outputHeight: height * deviceScaleFactor,
+        deviceScaleFactor,
+      });
+    }
 
     const probeStart = Date.now();
     const needsBrowser = composition.duration <= 0 || compiled.unresolvedCompositions.length > 0;
@@ -2077,6 +2174,7 @@ export async function executeRenderJob(
         fps: job.config.fps,
         format: needsAlpha ? "png" : "jpeg",
         quality: needsAlpha ? undefined : 80,
+        deviceScaleFactor,
       };
       probeSession = await createCaptureSession(
         fileServer.url,
@@ -2543,6 +2641,7 @@ export async function executeRenderJob(
       format: needsAlpha ? "png" : "jpeg",
       quality: needsAlpha ? undefined : job.config.quality === "draft" ? 80 : 95,
       variables: job.config.variables,
+      deviceScaleFactor,
     };
 
     // Capture sessions do not need native browser metadata for videos whose
@@ -3915,7 +4014,7 @@ export async function executeRenderJob(
       chunkSizeFrames: enableChunkedEncode ? chunkedEncodeSize : null,
       compositionDurationSeconds: composition.duration,
       totalFrames: totalFrames,
-      resolution: { width, height },
+      resolution: { width: width * deviceScaleFactor, height: height * deviceScaleFactor },
       videoCount: composition.videos.length,
       audioCount: composition.audios.length,
       stages: perfStages,