Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* Shared `--output-resolution` / `--resolution` normalizer for the distributed
* render entrypoints (`hyperframes cloudrun render{,-batch}`, `hyperframes
* lambda render{,-batch}`) plus the local `hyperframes render` command.
*
* The one field this helper carries that the previous per-surface copies
* were dropping is `outputResolutionAspectAgnostic`: `true` when the raw
* flag was a tier-only alias (`1080p` / `hd` / `4k` / `uhd`). Passing it
* through into `SerializableDistributedRenderConfig` is what lets the
* remote worker's compile stage remap `landscape` → `portrait` when the
* composition demands it. Dropping the flag at any single entrypoint
* reproduces the portrait-1080p regression this helper prevents (see
* PR #2529 R2 CHANGES_REQUESTED and the sibling-surface enumeration in
* Miga + Rames's reviews).
*
* The strict-throw contract (unknown values raise instead of silently
* degrading to `outputResolution: undefined`) is preserved so a typo like
* `--output-resolution 8k` fails fast rather than falling back to
* composition dimensions.
*/
import { type CanvasResolution, resolveResolutionFlagPair } from "@hyperframes/core";
import { VALID_CANVAS_RESOLUTIONS } from "@hyperframes/core";
/**
* Free-text prefix the thrown error is scoped to (e.g. `"[cloudrun render]"`,
* `"[lambda render]"`). Kept as a caller-supplied string rather than a
* fixed enum so future surfaces (Studio Server, an SDK wrapper, …) can
* opt in without editing this file.
*/
export interface OutputResolutionParseOptions {
surfaceLabel: string;
/**
* Optional per-surface hint appended to the error message. Defaults to a
* generic tier-alias hint; the Lambda surface exposes additional
* orientation-suffixed aliases the CLI accepts (`1080p-portrait`, `4k-portrait`,
* …) — pass a custom hint to keep the error text faithful.
*/
aliasHint?: string;
}
/**
* Parse the user-supplied resolution flag into the pair the distributed
* wire config needs. Returns `{ outputResolution: undefined,
* outputResolutionAspectAgnostic: false }` when the flag is absent so the
* caller can spread the result unconditionally.
*
* Throws (not exits) on an unknown value — CLI callers wrap that in their
* own errorBox / process.exit; SDK callers surface the error to their own
* user.
*/
export function parseOutputResolutionFlag(
raw: unknown,
options: OutputResolutionParseOptions,
): { outputResolution: CanvasResolution | undefined; outputResolutionAspectAgnostic: boolean } {
if (raw == null || raw === "") {
return { outputResolution: undefined, outputResolutionAspectAgnostic: false };
}
const asString = String(raw);
const { outputResolution, outputResolutionAspectAgnostic } = resolveResolutionFlagPair(asString);
if (outputResolution) return { outputResolution, outputResolutionAspectAgnostic };
const aliasHint = options.aliasHint ?? "1080p, 4k, uhd, hd, …";
throw new Error(
`${options.surfaceLabel} --output-resolution must be one of ${VALID_CANVAS_RESOLUTIONS.join("|")} ` +
`(or an alias: ${aliasHint}); got ${asString}`,
);
}