@@ -90,6 +90,7 @@ import {
9090} from "@hyperframes/engine" ;
9191import {
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 */
11691209export 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 } ) ;
0 commit comments