fix(render): pre-flight aspect-ratio / alpha preset mismatch with actionable guidance (#1843)

Users pick an --resolution preset whose orientation/aspect ratio (or alpha/HDR mode) conflicts with the composition; the render fails deep in the compiler with a cryptic message. ~8K err / ~1K users.

- New shared pure helper checkOutputResolutionCompatibility in @hyperframes/parsers — single source of truth for aspect/alpha/HDR/downsample/non-integer-scale constraints; suggests the matching-orientation, tier-preserving preset.
- CLI render pre-flight aborts early (before browser/ffmpeg) with an actionable, fix-suggesting message; resolveDeviceScaleFactor delegates to the same helper for identical defense-in-depth messages.
- Suggest (not auto-select); defers when dims can't be determined rather than guessing.
- suggestMatchingPreset keys tier off the -4k suffix so square-family swaps (square + landscape-4k -> square-4k) aren't downgraded to HD.
- render.js DOM polyfill made a lazy import; render.test cold-import beforeAll hooks given a 30s timeout to absorb CI contention.

Render-reliability workstream P1-3. Success measured on PostHog dashboard 1783183.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-07-01 19:27:08 -07:00
committed by GitHub
co-authored by Claude Opus 4.8
parent c0c3abf0f1
commit 6be46813a2
10 changed files with 554 additions and 53 deletions
+5
View File
@@ -179,6 +179,7 @@ export {
CANVAS_DIMENSIONS,
VALID_CANVAS_RESOLUTIONS,
normalizeResolutionFlag,
checkOutputResolutionCompatibility,
COMPOSITION_VARIABLE_TYPES,
TIMELINE_COLORS,
DEFAULT_DURATIONS,
@@ -187,3 +188,7 @@ export {
isMediaElement,
isCompositionElement,
} from "@hyperframes/parsers";
export type {
OutputResolutionCompatibility,
OutputResolutionIssueKind,
} from "@hyperframes/parsers";
+3
View File
@@ -35,6 +35,8 @@ export type {
CompositionVariable,
CompositionSpec,
WaveformData,
OutputResolutionCompatibility,
OutputResolutionIssueKind,
} from "./core.types";
export type {
@@ -53,6 +55,7 @@ export {
CANVAS_DIMENSIONS,
VALID_CANVAS_RESOLUTIONS,
normalizeResolutionFlag,
checkOutputResolutionCompatibility,
parseFps,
parseFpsWithDefault,
toFps,