feat(cli): warn when lambda --width/--height conflicts with composition

jrusso1020 · claude · jrusso1020 · commit b67ce681c44d · 2026-05-21T22:32:47.000Z
`--width 3840 --height 2160` against a composition with
`data-width="1920"` silently produces a 1080p output because the
runtime lays out the page at the composition's authored dimensions —
real footgun we hit during a cost-analysis sweep. Warn early and point
at `--output-resolution` (the supersampling escape hatch) so the user
doesn't burn a 30-minute render learning the override rule.

Skipped when `--output-resolution` is set (the supported supersampling
path — the user is opting in), when `--json` is set (machine consumers),
or when `index.html` isn't on disk (typical with `--site-id`).

Helper lives in a shared module so render + render-batch agree on the
parse + message. Tests cover both attribute orders, single/double
quotes, the silent paths, and the warning path. Best-effort regex over
the canonical attr shape — malformed HTML falls through to no warning
rather than blocking the render.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/cli/src/commands/lambda/_dimensions.test.ts b/packages/cli/src/commands/lambda/_dimensions.test.ts
@@ -0,0 +1,129 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { readCompositionDimensions, warnOnDimensionMismatch } from "./_dimensions.js";
+
+describe("readCompositionDimensions", () => {
+  it("parses width-first attribute order", () => {
+    const html =
+      '<!doctype html><html><body data-width="1920" data-height="1080" data-duration="5"></body></html>';
+    expect(readCompositionDimensions(html)).toEqual({ width: 1920, height: 1080 });
+  });
+
+  it("parses height-first attribute order", () => {
+    const html =
+      '<!doctype html><html><body data-duration="5" data-height="2160" data-width="3840"></body></html>';
+    expect(readCompositionDimensions(html)).toEqual({ width: 3840, height: 2160 });
+  });
+
+  it("tolerates single quotes", () => {
+    const html = "<body data-width='1080' data-height='1920'></body>";
+    expect(readCompositionDimensions(html)).toEqual({ width: 1080, height: 1920 });
+  });
+
+  it("returns null when an attribute is missing", () => {
+    expect(readCompositionDimensions('<body data-width="1920"></body>')).toBeNull();
+  });
+
+  it("returns null on empty HTML", () => {
+    expect(readCompositionDimensions("")).toBeNull();
+  });
+});
+
+describe("warnOnDimensionMismatch", () => {
+  let dir: string;
+  let warnSpy: ReturnType<typeof vi.fn>;
+  let originalWarn: typeof console.warn;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "hf-dim-mismatch-"));
+    originalWarn = console.warn;
+    warnSpy = vi.fn();
+    console.warn = warnSpy as unknown as typeof console.warn;
+  });
+
+  afterEach(() => {
+    console.warn = originalWarn;
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  function writeIndex(html: string): void {
+    writeFileSync(join(dir, "index.html"), html);
+  }
+
+  it("warns when the CLI dimensions don't match the composition", () => {
+    writeIndex('<body data-width="1920" data-height="1080"></body>');
+    warnOnDimensionMismatch({
+      projectDir: dir,
+      cliWidth: 3840,
+      cliHeight: 2160,
+      outputResolution: undefined,
+      quiet: false,
+    });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const call = (warnSpy.mock.calls[0]?.[0] as string) ?? "";
+    expect(call).toContain("3840×2160");
+    expect(call).toContain("1920×1080");
+    expect(call).toContain("--output-resolution");
+  });
+
+  it("is silent when CLI and composition agree", () => {
+    writeIndex('<body data-width="1920" data-height="1080"></body>');
+    warnOnDimensionMismatch({
+      projectDir: dir,
+      cliWidth: 1920,
+      cliHeight: 1080,
+      outputResolution: undefined,
+      quiet: false,
+    });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("is silent when --output-resolution is set (the supported supersampling path)", () => {
+    writeIndex('<body data-width="1920" data-height="1080"></body>');
+    warnOnDimensionMismatch({
+      projectDir: dir,
+      cliWidth: 3840,
+      cliHeight: 2160,
+      outputResolution: "landscape-4k",
+      quiet: false,
+    });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("is silent when quiet=true (--json)", () => {
+    writeIndex('<body data-width="1920" data-height="1080"></body>');
+    warnOnDimensionMismatch({
+      projectDir: dir,
+      cliWidth: 3840,
+      cliHeight: 2160,
+      outputResolution: undefined,
+      quiet: true,
+    });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("is silent when index.html is missing (typical with --site-id)", () => {
+    warnOnDimensionMismatch({
+      projectDir: dir,
+      cliWidth: 3840,
+      cliHeight: 2160,
+      outputResolution: undefined,
+      quiet: false,
+    });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("is silent when the composition has no data-width/data-height", () => {
+    writeIndex("<body><h1>just a comp</h1></body>");
+    warnOnDimensionMismatch({
+      projectDir: dir,
+      cliWidth: 3840,
+      cliHeight: 2160,
+      outputResolution: undefined,
+      quiet: false,
+    });
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/cli/src/commands/lambda/_dimensions.ts b/packages/cli/src/commands/lambda/_dimensions.ts
@@ -0,0 +1,88 @@
+/**
+ * Shared dimension-mismatch warning for `hyperframes lambda render` and
+ * `hyperframes lambda render-batch`. The Lambda renderer lays the page out
+ * at the composition's authored `data-width` / `data-height` — passing
+ * `--width 3840 --height 2160` against a composition with
+ * `data-width="1920"` silently produces a 1080p output. Warn early and
+ * point at `--output-resolution` (the supersampling escape hatch).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { CanvasResolution } from "@hyperframes/core";
+import { c } from "../../ui/colors.js";
+
+export interface DimensionMismatchArgs {
+  projectDir: string;
+  cliWidth: number;
+  cliHeight: number;
+  outputResolution: CanvasResolution | undefined;
+  /** Suppress the warning when stdout is reserved for machine output (--json). */
+  quiet: boolean;
+}
+
+/**
+ * Print a warning when `--width`/`--height` disagrees with the
+ * composition's `data-width`/`data-height`. Best-effort regex parse —
+ * robust enough for the canonical shape that every composition in the
+ * wild uses; malformed HTML silently falls through.
+ *
+ * Skipped when `--output-resolution` is set (the intended supersampling
+ * path) or when the project dir isn't on disk (typical with --site-id
+ * pointing at a pre-uploaded site packaged on another machine).
+ */
+// fallow-ignore-next-line complexity
+export function warnOnDimensionMismatch(args: DimensionMismatchArgs): void {
+  if (args.quiet) return;
+  if (args.outputResolution) return;
+  const indexPath = join(args.projectDir, "index.html");
+  if (!existsSync(indexPath)) return;
+  const html = safeReadFile(indexPath);
+  if (!html) return;
+  const composition = readCompositionDimensions(html);
+  if (!composition) return;
+  const widthMismatch = composition.width !== args.cliWidth;
+  const heightMismatch = composition.height !== args.cliHeight;
+  if (!widthMismatch && !heightMismatch) return;
+  console.warn(
+    c.warn(
+      `--width/--height (${args.cliWidth}×${args.cliHeight}) disagrees with the composition's ` +
+        `data-width/data-height (${composition.width}×${composition.height}). The runtime lays out ` +
+        `the page at the composition's authored dimensions, so your output will be ` +
+        `${composition.width}×${composition.height}, not ${args.cliWidth}×${args.cliHeight}.\n` +
+        `  To supersample to a higher resolution, pass --output-resolution (e.g. \`--output-resolution=4k\`).\n` +
+        `  To truly change layout dimensions, edit the composition's data-width/data-height in index.html.`,
+    ),
+  );
+}
+
+function safeReadFile(path: string): string | null {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pull `data-width` + `data-height` from the document's first element
+ * carrying both. Canonical shape is the outermost `<body>` or wrapper
+ * `<div>`. Match either attribute order and any quote style (or none).
+ * Exported so the warning helper has a unit-testable seam without going
+ * through the I/O path.
+ */
+export function readCompositionDimensions(html: string): { width: number; height: number } | null {
+  const widthFirst = html.match(
+    /data-width\s*=\s*["']?(\d+)["']?[^>]*?data-height\s*=\s*["']?(\d+)["']?/,
+  );
+  if (widthFirst) {
+    return { width: Number(widthFirst[1]), height: Number(widthFirst[2]) };
+  }
+  const heightFirst = html.match(
+    /data-height\s*=\s*["']?(\d+)["']?[^>]*?data-width\s*=\s*["']?(\d+)["']?/,
+  );
+  if (heightFirst) {
+    return { width: Number(heightFirst[2]), height: Number(heightFirst[1]) };
+  }
+  return null;
+}
diff --git a/packages/cli/src/commands/lambda/render-batch.ts b/packages/cli/src/commands/lambda/render-batch.ts
@@ -36,6 +36,7 @@ import {
   reportVariableIssues,
   validateVariablesAgainstSchema,
 } from "../../utils/variables.js";
+import { warnOnDimensionMismatch } from "./_dimensions.js";
 import { requireStack } from "./state.js";
 
 // Dynamic-import the SDK so tsup keeps it out of the static-import head of
@@ -165,6 +166,18 @@ export async function runRenderBatch(args: RenderBatchArgs): Promise<void> {
     process.exit(1);
   }
 
+  // Catch the --width/--height vs composition data-width/data-height
+  // footgun once before fanning out N executions (a 1000-row batch with
+  // the wrong dimensions burns the same per-render cost across every
+  // row). Skipped under --json / --dry-run quiet expectations.
+  warnOnDimensionMismatch({
+    projectDir,
+    cliWidth: args.width,
+    cliHeight: args.height,
+    outputResolution: args.outputResolution,
+    quiet: args.json,
+  });
+
   // Pre-validate every entry's variables against the composition's
   // schema. Mismatches print as warnings; strict mode aborts before any
   // AWS call. Schema is loaded once and reused across entries — a 10k-row
diff --git a/packages/cli/src/commands/lambda/render.ts b/packages/cli/src/commands/lambda/render.ts
@@ -17,6 +17,7 @@ import {
   resolveVariablesArg,
   validateVariablesAgainstProject,
 } from "../../utils/variables.js";
+import { warnOnDimensionMismatch } from "./_dimensions.js";
 import { requireStack, stateFilePath } from "./state.js";
 
 // Dynamic-import the SDK so tsup keeps it out of the static-import head of
@@ -72,6 +73,23 @@ export async function runRender(args: RenderArgs): Promise<void> {
   const stack = requireStack(args.stackName);
   const projectDir = resolvePath(args.projectDir);
 
+  // Cheap up-front dimension-mismatch check. The composition's
+  // `data-width`/`data-height` attrs override `Config.width`/`Config.height`
+  // at runtime, so passing `--width 3840 --height 2160` against a
+  // composition authored at 1920×1080 silently produces a 1080p output —
+  // a real footgun we hit during the cost-analysis sweep. Warn early and
+  // point at `--output-resolution` (the supported supersampling path) so
+  // the user doesn't burn a 30-minute render learning this. Suppressed
+  // when `--json` is set so machine consumers can parse the manifest, and
+  // skipped when the project dir isn't on disk (typical with --site-id).
+  warnOnDimensionMismatch({
+    projectDir,
+    cliWidth: args.width,
+    cliHeight: args.height,
+    outputResolution: args.outputResolution,
+    quiet: args.json,
+  });
+
   // Resolve --variables / --variables-file using the same parser the local
   // `hyperframes render` uses. `resolveVariablesArg` exits(1) with a friendly
   // errorBox on parse errors so callers don't have to.
