Skip to content

Commit 46e9ecf

Browse files
committed
fix(cli): accept portrait aspects for --resolution alias flag
The aspect-agnostic resolution aliases (`--resolution 1080p` / `hd` / `4k` / `uhd`) previously all normalized to a landscape preset, which rejected portrait 1080x1920 compositions with 'Output resolution incompatible'. Users had to specify the orientation-bearing alias (`1080p-portrait`) or render at native. This threads two new fields (`outputResolutionAspectAgnostic` + `outputResolutionRaw`) through the render pipeline. At the CLI layer we detect whether the user's flag was an aspect-agnostic alias; at the compile stage we re-map the preset to the composition's orientation via the existing `suggestMatchingPreset` sibling-lookup (formerly private). Explicit orientation-bearing aliases and canonical presets stay strict. Field signal: ts=1784176662 (darwin/arm64, CLI 0.7.59, `--resolution 1080p` on a 1080x1920 portrait comp). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> — Via
1 parent 9ed255c commit 46e9ecf

13 files changed

Lines changed: 460 additions & 15 deletions

File tree

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1170,6 +1170,81 @@ describe("checkRenderResolutionPreflight", () => {
11701170
await checkRenderResolutionPreflight("<html><body></body></html>", "landscape", noModes),
11711171
).toBeUndefined();
11721172
});
1173+
1174+
// Aspect-agnostic aliases (`--resolution 1080p` / `hd` / `4k` / `uhd`) name a
1175+
// resolution tier without pinning an orientation. When the flag is
1176+
// aspect-agnostic the pre-flight must NOT block on an aspect-ratio mismatch —
1177+
// the compile stage adapts the preset to the composition's orientation
1178+
// downstream (see `outputResolutionAspectAgnostic` on RenderConfig).
1179+
// Field signal ts=1784176662 (darwin/arm64, CLI 0.7.59):
1180+
// "--resolution 1080p rejects a 1080x1920 portrait comp"
1181+
describe("aspect-agnostic (--resolution 1080p / hd / 4k / uhd)", () => {
1182+
const agnostic = { ...noModes, aspectAgnostic: true } as const;
1183+
1184+
it("clears a landscape preset on a portrait composition (the field-signal scenario)", async () => {
1185+
// The bug: --resolution 1080p normalized to `landscape` (1920×1080),
1186+
// then errored on a 1080×1920 portrait comp with "Output resolution
1187+
// incompatible." With aspectAgnostic=true the pre-flight steps aside
1188+
// and the compile stage re-maps landscape → portrait.
1189+
expect(
1190+
await checkRenderResolutionPreflight(portraitHtml, "landscape", agnostic),
1191+
).toBeUndefined();
1192+
});
1193+
1194+
it("clears a landscape-4k preset on a portrait composition (4K tier)", async () => {
1195+
// `--resolution 4k` → normalized `landscape-4k`. Portrait comp is fine
1196+
// when aspect-agnostic.
1197+
expect(
1198+
await checkRenderResolutionPreflight(portraitHtml, "landscape-4k", agnostic),
1199+
).toBeUndefined();
1200+
});
1201+
1202+
it("clears a landscape preset on a square composition", async () => {
1203+
// aspect > 1 → landscape, aspect = 1 → square. Both self-heal.
1204+
expect(
1205+
await checkRenderResolutionPreflight(comp(1080, 1080), "landscape", agnostic),
1206+
).toBeUndefined();
1207+
});
1208+
1209+
it("still flags alpha + aspect-agnostic (orientation isn't the issue)", async () => {
1210+
// alpha-incompatible is orthogonal to aspect: the alpha capture path
1211+
// can't apply deviceScaleFactor regardless of orientation. The
1212+
// aspect-agnostic downgrade must NOT swallow this.
1213+
const result = await checkRenderResolutionPreflight(portraitHtml, "landscape", {
1214+
aspectAgnostic: true,
1215+
alphaRequested: true,
1216+
hdrRequested: false,
1217+
});
1218+
expect(result?.kind).toBe("alpha-incompatible");
1219+
});
1220+
1221+
it("still flags HDR + aspect-agnostic", async () => {
1222+
const result = await checkRenderResolutionPreflight(landscapeHtml, "landscape", {
1223+
aspectAgnostic: true,
1224+
alphaRequested: false,
1225+
hdrRequested: true,
1226+
});
1227+
expect(result?.kind).toBe("hdr-incompatible");
1228+
});
1229+
1230+
it("still flags downsampling + aspect-agnostic (same-orientation, smaller preset)", async () => {
1231+
// 3840×2160 comp with `--resolution 1080p` → `landscape` (1920×1080).
1232+
// Same orientation, but tier smaller than comp — user asked for a
1233+
// downsample. That's a real incompatibility, not an orientation swap.
1234+
const result = await checkRenderResolutionPreflight(comp(3840, 2160), "landscape", agnostic);
1235+
expect(result?.kind).toBe("downsampling");
1236+
});
1237+
1238+
it("does NOT auto-clear when the flag was explicit (orientation-locked preset stays strict)", async () => {
1239+
// The negative case: `--resolution landscape` on a portrait comp — the
1240+
// user explicitly asked for landscape orientation, and the mismatch is
1241+
// a genuine mistake. Pre-flight must still block with the actionable
1242+
// "did you mean --resolution portrait?" suggestion.
1243+
const result = await checkRenderResolutionPreflight(portraitHtml, "landscape", noModes);
1244+
expect(result?.kind).toBe("aspect-mismatch");
1245+
expect(result?.message).toContain("--resolution portrait");
1246+
});
1247+
});
11731248
});
11741249

11751250
describe("render fps arg definition", () => {

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

Lines changed: 56 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ import {
9090
} from "@hyperframes/engine";
9191
import {
9292
normalizeResolutionFlag,
93+
isAspectAgnosticResolutionAlias,
9394
checkOutputResolutionCompatibility,
9495
parseFps,
9596
fpsToNumber,
@@ -481,6 +482,15 @@ export default defineCommand({
481482

482483
// ── Validate resolution ────────────────────────────────────────────────
483484
let outputResolution: CanvasResolution | undefined;
485+
// Aspect-agnostic aliases (`--resolution 1080p` / `hd` / `4k` / `uhd`) name
486+
// a resolution *tier* without pinning an orientation. Historically they
487+
// all normalize to a `landscape` preset, which rejects portrait/square
488+
// compositions at `resolveDeviceScaleFactor` time. Track the raw-input
489+
// shape so the compile stage can re-map the preset to the composition's
490+
// orientation (see `outputResolutionAspectAgnostic` on RenderConfig).
491+
// Explicit orientation-bearing aliases (`1080p-portrait`, `4k-square`, …)
492+
// and canonical presets (`landscape`, `portrait`, …) stay strict.
493+
let outputResolutionAspectAgnostic = false;
484494
if (args.resolution !== undefined) {
485495
outputResolution = normalizeResolutionFlag(args.resolution);
486496
if (!outputResolution) {
@@ -491,6 +501,7 @@ export default defineCommand({
491501
);
492502
process.exit(1);
493503
}
504+
outputResolutionAspectAgnostic = isAspectAgnosticResolutionAlias(args.resolution);
494505
// Reject the --resolution + --hdr combination at the CLI layer so the
495506
// user sees the friendly errorBox before any work directories or
496507
// ffmpeg processes spin up. The orchestrator also enforces this via
@@ -860,6 +871,7 @@ export default defineCommand({
860871
{
861872
alphaRequested: format === "webm" || format === "mov" || format === "png-sequence",
862873
hdrRequested: args.hdr ?? false,
874+
aspectAgnostic: outputResolutionAspectAgnostic,
863875
},
864876
);
865877
} catch {
@@ -906,6 +918,8 @@ export default defineCommand({
906918
browserPath,
907919
entryFile,
908920
outputResolution,
921+
outputResolutionAspectAgnostic,
922+
outputResolutionRaw: args.resolution,
909923
pageNavigationTimeoutMs,
910924
protocolTimeout,
911925
playerReadyTimeout,
@@ -973,6 +987,8 @@ export default defineCommand({
973987
variables,
974988
entryFile,
975989
outputResolution,
990+
outputResolutionAspectAgnostic,
991+
outputResolutionRaw: args.resolution,
976992
pageSideCompositing: args["page-side-compositing"] !== false,
977993
experimentalFastCapture: args["experimental-fast-capture"] === true,
978994
pageNavigationTimeoutMs,
@@ -1002,6 +1018,8 @@ export default defineCommand({
10021018
variables,
10031019
entryFile,
10041020
outputResolution,
1021+
outputResolutionAspectAgnostic,
1022+
outputResolutionRaw: args.resolution,
10051023
pageNavigationTimeoutMs,
10061024
protocolTimeout,
10071025
playerReadyTimeout,
@@ -1056,6 +1074,20 @@ interface RenderOptions {
10561074
exitAfterComplete?: boolean;
10571075
/** Output resolution preset; see `resolveDeviceScaleFactor` for constraints. */
10581076
outputResolution?: CanvasResolution;
1077+
/**
1078+
* True when `outputResolution` came from an aspect-agnostic alias
1079+
* (`--resolution 1080p` / `hd` / `4k` / `uhd`). The compile stage adapts
1080+
* the preset to the composition's orientation instead of rejecting
1081+
* portrait/square comps as an aspect-ratio mismatch.
1082+
*/
1083+
outputResolutionAspectAgnostic?: boolean;
1084+
/**
1085+
* Raw `--resolution` string as typed by the user. Preserved so Docker mode
1086+
* can forward the pre-normalized flag to the in-container CLI, which
1087+
* re-runs the aspect-agnostic detection on its own side — otherwise we'd
1088+
* lose the "1080p was ambiguous" signal at the process boundary.
1089+
*/
1090+
outputResolutionRaw?: string;
10591091
pageSideCompositing?: boolean;
10601092
/** EXPERIMENTAL. drawElementImage frame capture (--experimental-fast-capture). */
10611093
experimentalFastCapture?: boolean;
@@ -1165,11 +1197,19 @@ async function readCompositionDimensions(
11651197
* Extracted (and exported) so the CLI wiring around `process.exit` stays a
11661198
* thin adapter and the branch logic is unit-testable. See render-reliability
11671199
* workstream P1-3.
1200+
*
1201+
* `aspectAgnostic` reflects whether `outputResolution` was normalized from an
1202+
* aspect-agnostic alias like `--resolution 1080p` / `hd` / `4k` / `uhd`.
1203+
* When true, an aspect-ratio mismatch is *not* an error at the CLI layer:
1204+
* the compile stage will re-map the preset to the composition's orientation
1205+
* (a portrait 1080×1920 composition with `--resolution 1080p` renders at
1206+
* 1080×1920, not 1920×1080). Alpha / HDR / downsampling / non-integer-scale
1207+
* checks still block, because those failures are not orientation-fixable.
11681208
*/
11691209
export async function checkRenderResolutionPreflight(
11701210
compositionHtml: string,
11711211
outputResolution: CanvasResolution | undefined,
1172-
modes: { alphaRequested: boolean; hdrRequested: boolean },
1212+
modes: { alphaRequested: boolean; hdrRequested: boolean; aspectAgnostic?: boolean },
11731213
): Promise<{ message: string; kind: OutputResolutionIssueKind } | undefined> {
11741214
if (!outputResolution) return undefined;
11751215
const dims = await readCompositionDimensions(compositionHtml);
@@ -1185,6 +1225,11 @@ export async function checkRenderResolutionPreflight(
11851225
});
11861226
// Narrow to the incompatible case; `message`/`kind` are always set there.
11871227
if (compat.ok || !compat.message || !compat.kind) return undefined;
1228+
// Aspect-agnostic aliases delegate orientation to the composition — a
1229+
// landscape-vs-portrait mismatch is expected and self-heals in the compile
1230+
// stage. Only *aspect-mismatch* is downgraded; other issue kinds still
1231+
// block (see the `aspectAgnostic` note above).
1232+
if (modes.aspectAgnostic && compat.kind === "aspect-mismatch") return undefined;
11881233
return { message: compat.message, kind: compat.kind };
11891234
}
11901235

@@ -1381,7 +1426,15 @@ async function renderDocker(
13811426
quiet: options.quiet,
13821427
variables: options.variables,
13831428
entryFile: options.entryFile,
1384-
outputResolution: options.outputResolution,
1429+
// Forward the RAW `--resolution` flag (falling back to the canonical
1430+
// preset name when raw wasn't captured, e.g. programmatic callers).
1431+
// The in-container CLI re-runs `normalizeResolutionFlag` +
1432+
// `isAspectAgnosticResolutionAlias`, so aspect-agnostic aliases
1433+
// (`1080p`, `hd`, `4k`, `uhd`) retain their orientation-adaptive
1434+
// behavior inside Docker; passing the normalized `landscape` preset
1435+
// would silently lose that signal at the process boundary and
1436+
// reject portrait/square comps.
1437+
outputResolution: options.outputResolutionRaw ?? options.outputResolution,
13851438
pageSideCompositing: options.pageSideCompositing,
13861439
debug: options.debug,
13871440
bestEffort: options.bestEffort,
@@ -1534,6 +1587,7 @@ export async function renderLocal(
15341587
variables: options.variables,
15351588
entryFile: options.entryFile,
15361589
outputResolution: options.outputResolution,
1590+
outputResolutionAspectAgnostic: options.outputResolutionAspectAgnostic,
15371591
debug: options.debug,
15381592
strictness: options.bestEffort === false ? "strict" : "best-effort",
15391593
});

‎packages/core/src/core.types.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,9 @@ export {
179179
CANVAS_DIMENSIONS,
180180
VALID_CANVAS_RESOLUTIONS,
181181
normalizeResolutionFlag,
182+
isAspectAgnosticResolutionAlias,
182183
checkOutputResolutionCompatibility,
184+
suggestMatchingPreset,
183185
COMPOSITION_VARIABLE_TYPES,
184186
TIMELINE_COLORS,
185187
DEFAULT_DURATIONS,

‎packages/core/src/index.test.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,30 @@ describe("@hyperframes/core public API exports", () => {
3939
expect(core.normalizeResolutionFlag(undefined)).toBeUndefined();
4040
});
4141

42+
it("exports isAspectAgnosticResolutionAlias for tier-only aliases", () => {
43+
// Tier-only aliases → true (orientation follows the composition).
44+
expect(core.isAspectAgnosticResolutionAlias("1080p")).toBe(true);
45+
expect(core.isAspectAgnosticResolutionAlias("hd")).toBe(true);
46+
expect(core.isAspectAgnosticResolutionAlias("4k")).toBe(true);
47+
expect(core.isAspectAgnosticResolutionAlias("uhd")).toBe(true);
48+
// Case-insensitive.
49+
expect(core.isAspectAgnosticResolutionAlias("1080P")).toBe(true);
50+
expect(core.isAspectAgnosticResolutionAlias("UHD")).toBe(true);
51+
// Orientation-suffixed aliases → false (user picked an orientation).
52+
expect(core.isAspectAgnosticResolutionAlias("1080p-portrait")).toBe(false);
53+
expect(core.isAspectAgnosticResolutionAlias("portrait-1080p")).toBe(false);
54+
expect(core.isAspectAgnosticResolutionAlias("4k-square")).toBe(false);
55+
expect(core.isAspectAgnosticResolutionAlias("1080p-square")).toBe(false);
56+
// Canonical presets → false.
57+
expect(core.isAspectAgnosticResolutionAlias("landscape")).toBe(false);
58+
expect(core.isAspectAgnosticResolutionAlias("portrait")).toBe(false);
59+
expect(core.isAspectAgnosticResolutionAlias("landscape-4k")).toBe(false);
60+
// Unknown / empty / undefined → false.
61+
expect(core.isAspectAgnosticResolutionAlias("8k")).toBe(false);
62+
expect(core.isAspectAgnosticResolutionAlias("")).toBe(false);
63+
expect(core.isAspectAgnosticResolutionAlias(undefined)).toBe(false);
64+
});
65+
4266
it("exports TIMELINE_COLORS", () => {
4367
expect(core.TIMELINE_COLORS).toBeDefined();
4468
expect(core.TIMELINE_COLORS.video).toBeDefined();

‎packages/core/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,9 @@ export {
5555
CANVAS_DIMENSIONS,
5656
VALID_CANVAS_RESOLUTIONS,
5757
normalizeResolutionFlag,
58+
isAspectAgnosticResolutionAlias,
5859
checkOutputResolutionCompatibility,
60+
suggestMatchingPreset,
5961
parseFps,
6062
parseFpsWithDefault,
6163
toFps,

‎packages/parsers/src/outputResolutionCompatibility.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,13 @@ const OK: OutputResolutionCompatibility = { ok: true };
5959
* Returns `undefined` when no preset matches the composition's aspect ratio
6060
* (e.g. a custom, non-preset composition aspect ratio) — in that case there
6161
* is no unambiguous swap to suggest.
62+
*
63+
* Exported so that consumers with permission to auto-apply the swap (see the
64+
* `--resolution 1080p` aspect-agnostic path in the CLI/producer) can share the
65+
* same sibling-lookup logic as this module's user-facing "did you mean?" hint,
66+
* without duplicating the tier-preserving fallback rules.
6267
*/
63-
function suggestMatchingPreset(
68+
export function suggestMatchingPreset(
6469
compositionWidth: number,
6570
compositionHeight: number,
6671
chosen: CanvasResolution,

‎packages/parsers/src/types.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,26 @@ const RESOLUTION_ALIASES: Record<string, CanvasResolution> = {
5151
"4k-square": "square-4k",
5252
};
5353

54+
/**
55+
* Aliases that name a resolution *tier* (1080p / 4K) without also nailing an
56+
* orientation. Historically they all normalize to the `landscape` preset
57+
* (`normalizeResolutionFlag("1080p") === "landscape"`), which then rejects
58+
* portrait / square compositions with a cryptic "aspect ratio does not match"
59+
* error deep inside the render pipeline. Consumers that know the composition's
60+
* dimensions can consult this set to decide whether to auto-adapt the preset's
61+
* orientation instead — see `resolveResolutionForComposition`.
62+
*
63+
* Orientation-suffixed aliases (`1080p-portrait`, `4k-square`, …) are absent
64+
* on purpose: the user *did* pick an orientation, and honoring it is important
65+
* for the "you asked for landscape but composed portrait" error to still fire.
66+
*/
67+
const ASPECT_AGNOSTIC_RESOLUTION_ALIASES: ReadonlySet<string> = new Set([
68+
"1080p",
69+
"hd",
70+
"4k",
71+
"uhd",
72+
]);
73+
5474
/**
5575
* Map a user-facing resolution string (canonical name or alias) to a
5676
* `CanvasResolution`. Returns undefined for unknown values so callers
@@ -65,6 +85,25 @@ export function normalizeResolutionFlag(input: string | undefined): CanvasResolu
6585
return RESOLUTION_ALIASES[lowered];
6686
}
6787

88+
/**
89+
* True when `input` names a resolution *tier* without nailing an orientation
90+
* (`1080p`, `hd`, `4k`, `uhd`). Case-insensitive.
91+
*
92+
* The `--resolution` CLI flag treats these as "target this size; keep the
93+
* composition's orientation" — a portrait 1080×1920 comp with `--resolution
94+
* 1080p` should land at 1080×1920, not blow up on aspect mismatch. Explicit
95+
* canonical presets (`landscape`, `portrait`, …) and orientation-suffixed
96+
* aliases (`1080p-portrait`) stay strict — the user picked an orientation.
97+
*
98+
* Consumers pair this signal with the composition's dimensions (in a
99+
* follow-up pass after HTML parse) to pick the right preset via
100+
* `resolveResolutionForComposition`.
101+
*/
102+
export function isAspectAgnosticResolutionAlias(input: string | undefined): boolean {
103+
if (!input) return false;
104+
return ASPECT_AGNOSTIC_RESOLUTION_ALIASES.has(input.toLowerCase());
105+
}
106+
68107
export interface TimelineElementBase {
69108
id: string;
70109
type: TimelineElementType;

0 commit comments

Comments
 (0)