Files
hyperframes/packages/cli/src/commands/cloud/render.ts
T
WaterrrForeverandClaude Opus 5.5 d4e4b07e3c fix(cli): a wedged render trips its 60 s watchdog, one local render at a time, and fonts the cloud can't resolve are flagged (#7168)
* fix(producer): a wedged effect scan or screenshot-session open trips the 60 s stall watchdog

The sequential streaming watchdog raced only the capture call. Session init
(where the fast-capture effect scan runs) and opening the screenshot session
for effect frames waited on CDP's protocol timeout instead, which scales with
output area up to 30 minutes, so a starved page hung a render for ~25 minutes
before the watchdog saw the next frame. The effect scan now gives up when a
chunk outlasts its 120 s budget, opening the effect-frame session gets its own
no-progress window, and session init gets a 300 s one; each trip retries on a
fresh session like any other stall.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(cli): one local render at a time per machine; a second waits and says for whom

Renders started side by side from different sessions starve each other until
frames stop landing. `hyperframes render` now takes a machine-wide slot (a lock
file in the HyperFrames cache directory, held by pid) after its preflight and
holds it for the render or the whole batch. A second render waits and prints
the pid and project it is waiting behind; `--no-wait` fails at once instead.
A holder whose process is gone is taken over, and HYPERFRAMES_RENDER_LOCK=off
restores side-by-side renders. `--workers` is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(lint): flag fonts a cloud render cannot resolve, including the font shorthand

Lint read only `font-family`, so `font: 500 16px "PingFang SC", sans-serif`
passed while the renderer, which reads the shorthand too, drew the installed
Mac font locally and the cloud refused it. The shorthand now counts for
font_family_without_font_face (its parser moves to @hyperframes/parsers so
core and lint share one), and a new font_face_local_only warning names an
@font-face whose only sources are local(): it renders here and falls back in
the cloud. The rule's hint and the format reference stop recommending local()
for OS fonts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a cloud render that refuses a font says which project files use it

The cloud's "fonts that could not be resolved: PingFang SC" named no
composition. For a render submitted from a local project, the failure now
lists each refused family with the project files that name it, and says how
to ship the font so the cloud can use it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(cli): keep comment shares and exports within the gates, and split the single-render notes out of executeHeldRender

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(parsers): read a spaced line-height slash and var() before the size in the font shorthand

`font: 16px / 1.5 Inter` was read as the family `/ 1.5 Inter`, and
`font: var(--weight) 16px Inter` as `16px Inter`, because a var() counted as
the size. The parser now follows the shorthand grammar: optional style,
variant, weight and width keywords (or var()), then a length, percentage,
keyword or calc() size, then a `/ line-height` in any spacing. When no size can
be told apart from a var(), it says so: lint skips that declaration instead of
reporting a missing font, and the renderer keeps its best guess.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): say the render slot is one per user account, not per machine

The lock lives in the account's HyperFrames cache folder, so renders by two
user accounts never queued behind each other while the messages, flag help and
docs said "this machine". They now say "per user account" and that
HYPERFRAMES_CACHE_DIR set to a shared folder shares the slot across accounts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): reclaim a render lock or takeover file left half-written

A lock or `.break` file that exists but cannot be parsed (a crash mid-write
where hard links are unavailable) was never reclaimed: a waiting render waited
forever and --no-wait refused forever. Once such a file is older than any real
write (5 s by mtime) it counts as abandoned: the lock goes through the same
`.break` takeover as a dead holder's, and a takeover file is removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(producer): opening the capture session counts against the setup stall budget

The sequential streaming attempt opened its own capture session (Chrome launch
and new page) before the setup watchdog and outside the attempt's cleanup, so a
wedged launch still waited for the protocol timeout. Opening now shares the
300 s setup window with session initialisation, a trip fails the attempt like
any other sequential stall, and a session that finishes opening after its
attempt gave up is closed instead of leaking a browser.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(parsers): keep the shorthand result type module-private

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): reclaim an unreadable render lock only when its writer is provably gone

Where hard links are unavailable the lock is created by an exclusive open and
then written, so a contender paused between the two leaves an unreadable lock
while it is still alive. The 5 s mtime grace took such a lock over, and both
processes then held the slot. Each contender now writes an owner marker under
a name only it can take (pid plus random suffix, holding its process identity)
before it creates the lock, keeps it while it holds the slot, and removes it
otherwise. An unreadable lock or `.break` is reclaimed only when no other
contender's marker belongs to a live process; markers of dead processes, or of
a reused pid, are deleted. No reclaim is decided by time alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor: split acquireRenderLock and the streaming-stage session stub under the complexity gate

acquireRenderLock hands contender setup and a single marked claim to their own
functions, and the test stub for createCaptureSession splits its held-open
cases from the fake session it builds, so neither exceeds Fallow's cognitive
or CRAP thresholds. Behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(ci): raise the CLI and engine size budgets for the watchdog, lock and font-lint additions

Main's CLI unpacked size was already ~0.99% over its budget; the render lock and
owner markers push it past the 1% tolerance. The CLI unpacked budget takes the same
value as #7169 and #7170 (25,159,107) so the PRs merge cleanly. The engine's packed
size grows by about 4.7 KB for the effect-scan and session-open watchdogs; its packed
budget moves to 5% above the measured 467,097, as the budget file's headroom rule sets it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(parsers): a var() size glued to its line height is the shorthand's size

`font: 700 var(--size)/1.1 "Inter"` read as no family at all: the token was
tested whole against var(), and the slash after it hid that it was the size,
so the renderer injected no face for Inter. A var() followed by `/ line-height`
(glued or spaced) can only be the size, and is now read as one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(parsers): split the shorthand size search out of parseFontShorthand

Keeps parseFontShorthand under Fallow's cognitive-complexity gate; behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): render lock never removes another render's takeover, knows a reused pid, works in a shared folder and on Windows

- A `.break` takeover file is removed only by the render that wrote it. One
  whose writer is gone stops the render with the file to delete, instead of
  being removed on an earlier reading, which could remove a live `.break`
  written since and let two renders hold the slot. The takeover re-reads the
  lock under its own `.break` right before replacing it.
- The lock record keeps its holder's process start time, so a pid that now
  belongs to another process (an OOM-killed render in a container with a
  persisted cache) no longer holds the slot forever.
- The `locks` folder is created writable for every account, so accounts
  sharing HYPERFRAMES_CACHE_DIR take turns instead of the second failing with
  EACCES; a folder this account cannot write in says how to fix it, and
  another account's file that cannot be removed is left, not fatal.
- Windows: no PowerShell start-time lookup per check (pid liveness only), a
  file another handle holds (EPERM/EBUSY/EACCES) reads as held, a lock that
  vanished is retried once instead of in a tight loop, and a wait stops when
  its signal aborts. The tests end every acquire they start before removing
  their folder, and the paused contender writes through its open descriptor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(ci): raise the lint packed size budget for the font-shorthand rule

With main's audio-attribute rule (#7169) merged in, the font-shorthand and
local()-only font findings take @hyperframes/lint's packed tarball to
181925 bytes, over the 179338 budget. The new budget is that measurement
plus the usual 5% headroom.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 18:41:56 +00:00

1082 lines
39 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { failCommand, failUsage } from "../../utils/commandResult.js";
/**
* `hyperframes cloud render` — orchestrate a cloud-rendered HyperFrames
* composition end-to-end:
*
* 1. Resolve the project (or reuse a pre-uploaded `--asset-id` /
* `--url`).
* 2. Zip the project (reuses `createPublishArchive` so the
* file-ignore set matches the existing `publish` command exactly).
* 3. Upload the zip via the direct-to-S3 flow: `POST /v3/assets/
* direct-uploads` returns a presigned URL, we PUT the zip bytes
* to it, then `POST /v3/assets/{asset_id}/complete` finalizes.
* Cap: 200 MB. See `../../cloud/upload.ts` for the three-step
* contract. (The legacy `POST /v3/assets` proxy path was 32 MB.)
* 4. Submit the render via `POST /v3/hyperframes/renders` with a
* `project: {type:"asset_id", asset_id}` shape.
* 5. If `--no-wait`: print the `render_id` and exit immediately.
* Otherwise poll `GET /v3/hyperframes/renders/{id}` every
* `--poll-interval` (default 2s, max 60min). `--callback-url`
* can be combined with either mode: the webhook always fires when
* the server-side render terminates, independent of whether the
* CLI is still polling.
* 6. On `completed`: stream the signed `video_url` to disk.
* 7. On `failed`: print `failure_message` and exit 1.
*
* Auth comes from the existing `cli/src/auth/` chain via `cloud/auth.ts`.
* The cloud HTTP client (`cloud/_gen/client.ts`) is generated from
* HeyGen's external API OpenAPI spec; never hand-edit it.
*/
import { defineCommand } from "../../utils/defineCommand.js";
import {
ASPECT_RATIO_MATCH_TOLERANCE,
detectAspectRatioFromHtml,
type AspectRatioDetection,
type SupportedAspectRatio,
} from "../../cloud/detectAspectRatio.js";
import {
CANVAS_DIMENSIONS,
checkOutputResolutionCompatibility,
type CanvasResolution,
} from "@hyperframes/core";
import { c } from "../../ui/colors.js";
import { errorBox, formatBytes, formatDuration } from "../../ui/format.js";
import { describeUnresolvedFontUse } from "../../cloud/fontFailure.js";
import { resolveDefaultFpsArg } from "../../utils/renderArgs.js";
import { resolveProject, type ProjectDir } from "../../utils/project.js";
import { readProjectConfig } from "../../utils/projectConfig.js";
import { normalizeErrorMessage } from "../../utils/errorMessage.js";
import {
readStaged,
type StagedFile,
stagedSize,
stagePublishFiles,
type PublishArchiveResult,
zipPublishFileMap,
} from "../../utils/publishProject.js";
import {
reportVariableIssues,
resolveVariablesArg,
validateVariablesAgainstProject,
} from "../../utils/variables.js";
import { withMeta } from "../../utils/updateCheck.js";
import type { Example } from "../_examples.js";
import {
DEFAULT_MAX_WAIT_MS,
DEFAULT_POLL_INTERVAL_MS,
PollTimeoutError,
createCloudClient,
downloadToFile,
pollUntilTerminal,
} from "../../cloud/index.js";
import { reportApiError } from "../../cloud/errors.js";
import { describeUnresolvedFonts, embedSystemFonts } from "../../cloud/fontPreflight.js";
import { parseEnumFlag, parseIntFlag, parseNumericFlag } from "../../cloud/parsing.js";
import { uploadAssetViaDirectUpload, uploadZipViaDirectUpload } from "../../cloud/upload.js";
import {
OFFLOAD_MIN_BYTES,
offloadHeavyMedia,
type OffloadedMedia,
type OffloadOptions,
} from "../../cloud/offload.js";
import { resolveCloudBaseUrl } from "../../cloud/auth.js";
import { colorStatus } from "../../cloud/statusColor.js";
import type {
CreateHyperframesRenderRequest,
HyperframesCloudClient,
HyperframesRenderDetail,
} from "../../cloud/index.js";
import { isAbsolute, relative, resolve as resolvePath } from "node:path";
import { statSync } from "node:fs";
import {
compositionEntryErrorMessage,
parseCompositionEntryArg,
} from "../../utils/compositionEntry.js";
const VALID_QUALITY = ["draft", "standard", "high"] as const;
const VALID_FORMAT = ["mp4", "webm", "mov"] as const;
const VALID_RESOLUTION = ["1080p", "4k"] as const;
const VALID_ASPECT_RATIO = ["16:9", "9:16", "1:1"] as const;
// Mirrors the binary-byte max_bytes contract used by direct asset uploads.
const DIRECT_UPLOAD_LIMIT_BYTES = 200 * 1024 * 1024;
const ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES = 150 * 1024 * 1024;
const LARGEST_FILE_COUNT = 10;
const FORMAT_EXT: Record<string, string> = { mp4: ".mp4", webm: ".webm", mov: ".mov" };
export const examples: Example[] = [
["Render the current directory in the cloud", "hyperframes cloud render"],
["Inspect archive size without uploading", "hyperframes cloud render --dry-run"],
[
"Pick a specific composition + output path",
"hyperframes cloud render . --composition compositions/intro.html -o ./renders/intro.mp4",
],
["Higher quality, 60fps", "hyperframes cloud render --quality high --fps 60"],
[
"Submit and exit; webhook fires when the render terminates",
"hyperframes cloud render --callback-url https://example.com/hook --no-wait",
],
[
"Override variables (parametrized render)",
'hyperframes cloud render --variables \'{"title":"Q4 Recap","theme":"dark"}\'',
],
["Re-render an already-uploaded zip", "hyperframes cloud render --asset-id asst_abc123"],
];
export default defineCommand({
meta: { name: "render", description: "Render a HyperFrames composition in the cloud" },
args: {
dir: { type: "positional", required: false, description: "Project directory (default: .)" },
fps: {
type: "string",
description: "Frames per second (1-240). Default: the composition's root data-fps, else 30.",
},
quality: { type: "string", description: "draft | standard | high (default: standard)" },
format: { type: "string", description: "mp4 | webm | mov (default: mp4)" },
resolution: {
type: "string",
description: "Resolution tier: 1080p | 4k (default: 1080p; 4k is billed at 1.5x)",
},
"aspect-ratio": {
type: "string",
description:
"W:H; detected from the composition, so rarely needed. The render keeps the composition's own size; 4k needs 16:9, 9:16 or 1:1",
},
composition: {
type: "string",
alias: "c",
description: "Entry HTML file inside the zip (default: index.html)",
},
variables: {
type: "string",
description:
'Inline JSON object overriding data-composition-variables. Example: --variables \'{"title":"X"}\'',
},
"variables-file": {
type: "string",
description: "Path to a JSON file with variable values (alternative to --variables)",
},
"strict-variables": {
type: "boolean",
description: "Fail when --variables keys are undeclared or have the wrong type",
default: false,
},
title: {
type: "string",
description: "Free-text label echoed back in detail responses",
},
"callback-url": {
type: "string",
description:
"HTTPS webhook fired when the render terminates. Fires regardless of whether the CLI is still polling — combine with --no-wait for true fire-and-forget.",
},
"callback-id": {
type: "string",
description: "Opaque tracking ID echoed in webhook payloads",
},
"asset-id": {
type: "string",
description:
"Skip zip+upload and submit an already-uploaded composition. Mutually exclusive with --url and the project dir.",
},
url: {
type: "string",
description:
"Public HTTPS URL of a composition zip. Mutually exclusive with --asset-id and the project dir.",
},
// Citty parses `--no-FOO` as `--FOO=false`. A flag literally named
// "no-wait" gets routed as `args.wait=false`, leaving
// `args["no-wait"]` undefined and the early-return for
// fire-and-forget mode unreachable. Named the arg `wait` so the
// user-facing `--no-wait` flag works via citty's negation; the
// run() body checks `if (!args.wait)`.
wait: {
type: "boolean",
description:
"Poll until completion and download the video (default: true). Pass `--no-wait` for fire-and-forget — submits and exits with the render_id.",
default: true,
},
output: {
type: "string",
alias: "o",
description: "Destination path for the downloaded video (default: renders/<render_id>.<ext>)",
},
"poll-interval": {
type: "string",
description: `Poll cadence in seconds (default: ${DEFAULT_POLL_INTERVAL_MS / 1000})`,
},
"max-wait": {
type: "string",
description: `Max poll duration in minutes (default: ${DEFAULT_MAX_WAIT_MS / 60_000})`,
},
json: {
type: "boolean",
description: "Emit machine-readable JSON instead of human-friendly progress",
default: false,
},
"dry-run": {
type: "boolean",
description: "Build and inspect the project zip without authenticating or uploading",
default: false,
},
"idempotency-key": {
type: "string",
description: "Optional Idempotency-Key for safe retries (1-255 chars from [A-Za-z0-9_:.-])",
},
},
// fallow-ignore-next-line complexity
async run({ args }) {
const asJson = Boolean(args.json);
const quality = parseEnumFlag(args.quality, VALID_QUALITY, { flag: "--quality" });
const format = parseEnumFlag(args.format, VALID_FORMAT, { flag: "--format" });
const resolution = parseEnumFlag(args.resolution, VALID_RESOLUTION, {
flag: "--resolution",
});
const explicitAspectRatio = parseAspectRatioFlag(args["aspect-ratio"]);
const pollIntervalMs = parsePollIntervalMs(args["poll-interval"]);
const maxWaitMs = parseMaxWaitMs(args["max-wait"]);
validateIdempotencyKey(args["idempotency-key"]);
// Project resolution runs BEFORE variables resolution so a user
// passing conflicting inputs (`dir + --asset-id`) sees the
// structural error before any variable parsing errors.
const project = resolveProjectInput({
dir: args.dir,
assetId: args["asset-id"],
url: args.url,
});
validateDryRunSource(project, args["dry-run"] ?? false);
const fps = parseIntFlag(resolveCloudFpsArg(project, args.fps, args.composition), {
flag: "--fps",
min: 1,
max: 240,
});
// Aspect ratio is derived from the composition's authored dimensions: for
// a local dir we parse the entry HTML and auto-detect, so the user rarely
// needs --aspect-ratio at all. When they DO pass it, we validate it
// matches the composition (the renderer can't reshape, only supersample to
// a matching ratio) and fail fast on a mismatch. This also fails fast when
// the --composition entry file is missing, rather than uploading a zip the
// render rejects with a generic server-side error.
const aspectRatio = resolveAspectRatioForSubmit(
project,
args.composition,
explicitAspectRatio,
asJson,
resolution,
);
if (args["dry-run"]) {
if (project.kind !== "dir") throw new Error("Dry-run project must be a local directory");
reportDryRun(await prepareLocalArchive(project, args.composition, asJson), asJson);
return;
}
const variables = resolveVariablesAndValidateIfLocal(
args.variables,
args["variables-file"],
args["strict-variables"] ?? false,
project,
args.composition,
);
const client = await createCloudClient();
const preparedArchive =
project.kind === "dir"
? await prepareLocalArchive(
project,
args.composition,
asJson,
(file) => uploadAssetViaDirectUpload({ client, ...file }),
variables && JSON.stringify(variables),
)
: undefined;
const upload = await maybeUploadProject(
client,
project,
preparedArchive,
asJson,
args["idempotency-key"],
);
const submitted = await submitRender(client, {
projectInput: upload.projectInput,
fps,
quality,
format,
resolution,
aspectRatio,
composition: args.composition,
variables,
title: args.title,
callbackUrl: args["callback-url"],
callbackId: args["callback-id"],
idempotencyKey: args["idempotency-key"],
reverseSessionId: reverseSessionIdOf(project),
});
const renderId = submitted.render_id;
if (!args.wait) {
if (asJson) {
console.log(
JSON.stringify(
withMeta({ render: { render_id: renderId, status: "queued" as const } }),
null,
2,
),
);
} else {
console.log("");
console.log(`${c.success("✓")} Submitted ${c.accent(renderId)}`);
console.log(c.dim(` Poll with: hyperframes cloud get ${renderId}`));
}
return;
}
if (!asJson) {
console.log("");
console.log(c.dim(` Polling ${renderId} every ${pollIntervalMs / 1000}s …`));
}
const detail = await pollWithProgress(client, renderId, asJson, {
intervalMs: pollIntervalMs,
maxWaitMs,
});
if (detail.status === "failed") {
handleFailedRender(detail, asJson, project.kind === "dir" ? (project.dir ?? ".") : undefined);
}
if (!detail.video_url) {
errorBox(
"Render completed but returned no video_url",
`render_id: ${renderId}. Try \`hyperframes cloud get ${renderId}\` to inspect raw fields.`,
);
failCommand();
}
const outputPath = resolveOutputPath(args.output, renderId, detail.format);
const downloadResult = await streamVideo(detail.video_url, outputPath, asJson);
if (asJson) {
console.log(
JSON.stringify(
withMeta({
render: detail,
output_path: outputPath,
bytes_written: downloadResult.bytes,
}),
null,
2,
),
);
}
},
});
// ---------------------------------------------------------------------------
// Argument parsing — defers to cloud/parsing.ts for strict validators
// ---------------------------------------------------------------------------
function parsePollIntervalMs(raw: string | undefined): number {
const n = parseNumericFlag(raw, { flag: "--poll-interval", min: 1 });
return n === undefined ? DEFAULT_POLL_INTERVAL_MS : Math.round(n * 1000);
}
function parseMaxWaitMs(raw: string | undefined): number {
const n = parseNumericFlag(raw, { flag: "--max-wait", min: 0.0001 });
return n === undefined ? DEFAULT_MAX_WAIT_MS : Math.round(n * 60_000);
}
const IDEMPOTENCY_KEY_RE = /^[A-Za-z0-9_:.-]{1,255}$/;
function validateIdempotencyKey(key: string | undefined): void {
if (key === undefined) return;
if (!IDEMPOTENCY_KEY_RE.test(key)) {
errorBox("Invalid --idempotency-key", `Got "${key}". Must be 1-255 chars from [A-Za-z0-9_:.-]`);
failUsage();
}
}
export function validateDryRunSource(source: ProjectInputSource, dryRun: boolean): void {
if (!dryRun || source.kind === "dir") return;
errorBox(
"Invalid --dry-run input",
"--dry-run inspects a local project directory and cannot be combined with --asset-id or --url.",
);
failUsage();
}
// ---------------------------------------------------------------------------
// Project resolution (dir | asset-id | url) — exactly one source
// ---------------------------------------------------------------------------
export interface ProjectInputSource {
kind: "dir" | "asset_id" | "url";
dir?: string;
assetId?: string;
url?: string;
}
// fallow-ignore-next-line complexity
function resolveProjectInput(opts: {
dir: string | undefined;
assetId: string | undefined;
url: string | undefined;
}): ProjectInputSource {
// Count every source the user explicitly supplied. The positional
// `dir` defaults to `undefined` when omitted (not to "."), so we
// can detect "user actually typed something" vs. "default to cwd".
const explicit = {
dir: opts.dir !== undefined && opts.dir !== "",
assetId: opts.assetId !== undefined && opts.assetId !== "",
url: opts.url !== undefined && opts.url !== "",
};
const count = Number(explicit.dir) + Number(explicit.assetId) + Number(explicit.url);
if (count > 1) {
errorBox("Conflicting inputs", "Pass only one of: project dir, --asset-id, --url.");
failUsage();
}
if (explicit.assetId) return { kind: "asset_id", assetId: opts.assetId };
if (explicit.url) return { kind: "url", url: opts.url };
return { kind: "dir", dir: opts.dir ?? "." };
}
/**
* Resolve the aspect ratio for the submit body, validating local inputs.
*
* Aspect ratio is a property of the composition (its `data-width`/`data-height`), not a render knob: at 1080p the
* cloud renders at the composition's own size whatever `aspect_ratio` says, and a 4k render scales it up to a 16:9,
* 9:16 or 1:1 preset, the only values the API accepts. So:
*
* - a detected 16:9 / 9:16 / 1:1 is sent;
* - any other ratio (2:1, 4:5, …) is not sent at 1080p, where the output keeps the composition's size, and is
* refused before upload at 4k, where no preset fits it;
* - an explicit `--aspect-ratio W:H` that contradicts the composition is refused before upload.
*
* Logs are suppressed in `--json` mode so machine output stays clean.
*/
// fallow-ignore-next-line complexity
export function resolveAspectRatioForSubmit(
project: ProjectInputSource,
compositionArg: string | undefined,
explicit: string | undefined,
asJson: boolean,
resolution: "1080p" | "4k" = "1080p",
): SupportedAspectRatio | undefined {
if (project.kind !== "dir") {
if (explicit && isSupportedAspectRatio(explicit)) return explicit;
if (explicit) refuseUnsupportedAt4k(resolution, `--aspect-ratio ${explicit}`);
const reason = project.kind === "asset_id" ? "--asset-id" : "--url";
logDetection(asJson, `Auto-detect skipped (project is ${reason}); ${KEEPS_OWN_SIZE}`);
return undefined;
}
const dir = project.dir ?? ".";
const entry = parseCompositionEntryArg(compositionArg ?? "index.html", dir, statSync);
if (!entry.ok) {
const { title, message, hint } = compositionEntryErrorMessage(entry.error);
errorBox(title, message, hint);
failCommand();
}
const entryRelative = entry.value ?? "index.html";
const detection = detectAspectRatioFromHtml(resolvePath(dir, entryRelative));
const dims = detection.kind === "matched" || detection.kind === "no-match" ? detection : null;
if (explicit && dims && !sameRatio(explicit, dims.width / dims.height)) {
errorBox(
"Aspect ratio mismatch",
`--aspect-ratio ${explicit} doesn't match the composition (${dims.width}×${dims.height}, ${ratioLabel(dims.width, dims.height)}).`,
"The renderer keeps the composition's authored aspect ratio; it can't reshape it. Drop --aspect-ratio (it's auto-detected) or re-author the composition at the target ratio.",
);
failCommand();
}
if (detection.kind === "matched") {
if (resolution === "4k") refuseUnfit4kPreset(detection);
logDetection(asJson, summarizeDetection(detection, entryRelative));
return detection.aspectRatio;
}
if (detection.kind === "no-match") {
refuseUnsupportedAt4k(
resolution,
`This composition (${detection.width}×${detection.height}, ${ratioLabel(detection.width, detection.height)})`,
`Render it at 1080p, which keeps ${detection.width}×${detection.height}, or re-author it at a supported ratio.`,
);
logDetection(asJson, summarizeDetection(detection, entryRelative));
return undefined;
}
if (explicit && isSupportedAspectRatio(explicit)) return explicit;
if (explicit) refuseUnsupportedAt4k(resolution, `--aspect-ratio ${explicit}`);
logDetection(asJson, `${summarizeDetection(detection, entryRelative)}; ${KEEPS_OWN_SIZE}`);
return undefined;
}
const KEEPS_OWN_SIZE = "the render keeps the composition's own size.";
const isSupportedAspectRatio = (value: string): value is SupportedAspectRatio =>
(VALID_ASPECT_RATIO as readonly string[]).includes(value);
function sameRatio(aspect: string, ratio: number): boolean {
const [w, h] = aspect.split(":").map(Number);
return Math.abs(w! / h! - ratio) <= ASPECT_RATIO_MATCH_TOLERANCE;
}
function ratioLabel(width: number, height: number): string {
if (!Number.isInteger(width) || !Number.isInteger(height)) return (width / height).toFixed(2);
const gcd = (a: number, b: number): number => (b === 0 ? a : gcd(b, a % b));
const d = gcd(width, height);
return `${width / d}:${height / d}`;
}
const PRESET_4K: Record<SupportedAspectRatio, CanvasResolution> = {
"16:9": "landscape-4k",
"9:16": "portrait-4k",
"1:1": "square-4k",
};
/** The detector matches a ratio within a tolerance; the renderer's 4K preset has to fit the exact size. */
function refuseUnfit4kPreset(detection: {
aspectRatio: SupportedAspectRatio;
width: number;
height: number;
}): void {
const preset = PRESET_4K[detection.aspectRatio];
const compat = checkOutputResolutionCompatibility({
compositionWidth: detection.width,
compositionHeight: detection.height,
outputResolution: preset,
});
if (compat.ok) return;
const exact = CANVAS_DIMENSIONS[preset];
errorBox(
"No 4K preset fits this composition",
`${detection.width}×${detection.height} cannot render at 4K as ${detection.aspectRatio}: ${compat.message}`,
`Render it at 1080p, which keeps ${detection.width}×${detection.height}, or re-author it at ${exact.width / 2}×${exact.height / 2}.`,
);
failCommand();
}
function refuseUnsupportedAt4k(
resolution: "1080p" | "4k",
subject: string,
fix = "Render at 1080p, which keeps the composition's own size.",
): void {
if (resolution !== "4k") return;
errorBox(
"No 4K preset for this aspect ratio",
`${subject} is not 16:9, 9:16 or 1:1, the only ratios a 4K cloud render can scale to.`,
fix,
);
failCommand();
}
/** `--aspect-ratio` takes any `W:H`; only 16:9, 9:16 and 1:1 are sent, the rest are checked against the composition. */
export function parseAspectRatioFlag(raw: string | undefined): string | undefined {
if (raw === undefined) return undefined;
const match = /^([1-9]\d*):([1-9]\d*)$/.exec(raw.trim());
if (match) return `${match[1]}:${match[2]}`;
errorBox("Invalid --aspect-ratio", `Got "${raw}". Use W:H, such as 16:9, 9:16, 1:1 or 2:1.`);
failUsage();
}
function logDetection(asJson: boolean, message: string): void {
if (asJson) return;
console.log(c.dim(` ${message}`));
}
// fallow-ignore-next-line complexity
function summarizeDetection(detection: AspectRatioDetection, entryRelative: string): string {
switch (detection.kind) {
case "matched":
return `Detected aspect ratio: ${detection.aspectRatio} (from ${entryRelative} dims ${detection.width}×${detection.height})`;
case "no-root-div":
return `No <div data-composition-id> found in ${entryRelative}`;
case "no-dims":
return `${entryRelative} root composition has no data-width / data-height`;
case "invalid-dims":
return `${entryRelative} root has invalid dims (${detection.width}×${detection.height})`;
case "no-match":
return `Detected aspect ratio: ${ratioLabel(detection.width, detection.height)} (from ${entryRelative} dims ${detection.width}×${detection.height}); the cloud render keeps that size`;
case "read-error":
return `Couldn't read ${entryRelative} for aspect-ratio detection (${detection.error})`;
}
}
function resolveVariablesAndValidateIfLocal(
inline: string | undefined,
filePath: string | undefined,
strict: boolean,
source: ProjectInputSource,
composition: string | undefined,
): Record<string, unknown> | undefined {
const variables = resolveVariablesArg(inline, filePath);
if (!variables || Object.keys(variables).length === 0) return variables;
// Only validate against the local composition when we actually have
// a local project on disk. For --asset-id / --url paths the schema
// lives on the server side, so we send the variables as-is and let
// the API surface any mismatch via `hyperframes_project_invalid`.
if (source.kind !== "dir") return variables;
const project = resolveProject(source.dir);
const entryPath = resolvePath(project.dir, composition ?? "index.html");
const issues = validateVariablesAgainstProject(entryPath, variables);
reportVariableIssues(issues, { strict, quiet: false });
return variables;
}
// ---------------------------------------------------------------------------
// Upload step (only when project is a local dir)
// ---------------------------------------------------------------------------
interface UploadResult {
projectInput: CreateHyperframesRenderRequest["project"];
}
export interface ArchiveFileSummary {
path: string;
size_bytes: number;
}
interface PreparedLocalArchive {
project: ProjectDir;
/** Absent when the files left on disk alone are over the upload limit: they are never read. */
archive?: PublishArchiveResult;
sizeBytes: number;
fileCount: number;
largestFiles: ArchiveFileSummary[];
offloaded: OffloadedMedia[];
}
function summarizeLargestFiles(fileMap: Map<string, StagedFile>): ArchiveFileSummary[] {
return [...fileMap.entries()]
.map(([path, content]) => ({ path, size_bytes: stagedSize(content) }))
.sort((a, b) => b.size_bytes - a.size_bytes || a.path.localeCompare(b.path))
.slice(0, LARGEST_FILE_COUNT);
}
async function prepareLocalArchive(
source: ProjectInputSource,
composition: string | undefined,
asJson: boolean,
upload?: OffloadOptions["upload"],
variablesText?: string,
): Promise<PreparedLocalArchive> {
const project = resolveProject(source.dir);
if (!asJson) {
console.log("");
console.log(`${c.accent("◆")} Zipping ${c.accent(project.name)}`);
}
const { fileMap, entryPath } = stageProjectFiles(project, composition);
const missingFonts = await embedSystemFonts({
dir: project.dir,
entryFile: composition,
entryPath,
fileMap,
});
if (missingFonts.length > 0) {
errorBox("Fonts not on this computer", describeUnresolvedFonts(missingFonts));
failCommand();
}
const offloaded = await offloadMedia(project, fileMap, entryPath, asJson, upload, variablesText);
// Media left on disk barely compresses: past the limit, its size is the report and nothing is read.
const onDiskBytes = [...fileMap.values()]
.filter((file) => !Buffer.isBuffer(file))
.reduce((sum, file) => sum + stagedSize(file), 0);
const archive =
onDiskBytes > DIRECT_UPLOAD_LIMIT_BYTES
? undefined
: zipPublishFileMap(new Map([...fileMap].map(([path, file]) => [path, readStaged(file)])));
const sizeBytes = archive?.buffer.byteLength ?? onDiskBytes;
if (!asJson) {
console.log(c.dim(` ${fileMap.size} files · ${formatBytes(sizeBytes)}`));
}
const largestFiles = summarizeLargestFiles(fileMap);
const prepared = {
project,
archive,
sizeBytes,
fileCount: fileMap.size,
largestFiles,
offloaded,
};
if (upload) assertArchiveFits(sizeBytes, largestFiles);
if (!asJson && sizeBytes >= ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES) {
reportLargestFiles(prepared);
}
return prepared;
}
function stageProjectFiles(
project: ProjectDir,
composition: string | undefined,
): { fileMap: Map<string, StagedFile>; entryPath: string } {
try {
const fileMap = stagePublishFiles(project.dir, OFFLOAD_MIN_BYTES);
const entryPath = relative(
project.dir,
resolvePath(project.dir, composition ?? "index.html"),
).replaceAll("\\", "/");
if (!fileMap.has(entryPath)) {
throw new Error(
`Composition "${composition ?? "index.html"}" is excluded from the archive. Check .hyperframesignore.`,
);
}
return { fileMap, entryPath };
} catch (err) {
const msg = normalizeErrorMessage(err);
errorBox("Zip failed", msg, "Check the project and .hyperframesignore for missing files.");
failCommand();
}
}
async function offloadMedia(
project: ProjectDir,
fileMap: Map<string, StagedFile>,
entryPath: string,
asJson: boolean,
upload: OffloadOptions["upload"],
variablesText?: string,
): Promise<OffloadedMedia[]> {
let offloaded: OffloadedMedia[];
try {
offloaded = await offloadHeavyMedia(project.dir, fileMap, {
apiBaseUrl: resolveCloudBaseUrl(),
upload,
entryPath,
variablesText,
onFile: (item) =>
(asJson ? console.error : console.log)(c.dim(` ${describeOffload(item, !upload)}`)),
});
} catch (err) {
reportApiError("Media upload failed", err);
}
if (!asJson) {
for (const item of offloaded.filter((entry) => entry.kept_in_archive)) {
console.log(
c.dim(
` ${item.path} also stays in the zip: a script builds its path in a way that cannot be rewritten`,
),
);
}
}
return offloaded;
}
/** --fps, else the entry's root data-fps (the owner local render uses), else the server default. */
export function resolveCloudFpsArg(
source: ProjectInputSource,
fps: string | undefined,
composition: string | undefined,
): string | undefined {
if (source.kind !== "dir") return fps;
const { dir } = resolveProject(source.dir);
const resolved = resolveDefaultFpsArg(fps, dir, resolvePath(dir, "index.html"), composition);
// The cloud API takes whole frame rates; a fractional data-fps (29.97) leaves it to the server.
return resolved !== undefined && /^\d+$/.test(resolved) ? resolved : fps;
}
export function assertArchiveFits(sizeBytes: number, largestFiles: ArchiveFileSummary[]): void {
if (sizeBytes <= DIRECT_UPLOAD_LIMIT_BYTES) return;
errorBox(
"Project too large for cloud render",
`The zip is ${formatBytes(sizeBytes)} after moving media to HeyGen assets, over the ${formatBytes(DIRECT_UPLOAD_LIMIT_BYTES)} upload limit. Largest files left in it:\n${largestFiles
.map((file) => ` ${formatBytes(file.size_bytes).padStart(9)} ${file.path}`)
.join("\n")}`,
"Exclude files the render does not need with .hyperframesignore.",
);
failCommand();
}
function describeOffload(item: OffloadedMedia, dryRun: boolean): string {
const verb =
item.action === "cached"
? "already uploaded"
: item.action === "reencode"
? dryRun
? "would re-encode and upload"
: "re-encoded and uploaded"
: dryRun
? "would upload"
: "uploaded";
return `${formatBytes(item.size_bytes).padStart(9)} ${item.path} · ${verb}`;
}
function reportLargestFiles(prepared: PreparedLocalArchive): void {
console.log(c.dim(" Largest included files:"));
for (const file of prepared.largestFiles) {
console.log(c.dim(` ${formatBytes(file.size_bytes).padStart(9)} ${file.path}`));
}
console.log(c.dim(" Exclude verified-unneeded files with .hyperframesignore."));
}
function reportDryRun(prepared: PreparedLocalArchive, asJson: boolean): void {
const { sizeBytes } = prepared;
if (asJson) {
console.log(
JSON.stringify(
withMeta({
archive: {
project: prepared.project.name,
file_count: prepared.fileCount,
size_bytes: sizeBytes,
upload_limit_bytes: DIRECT_UPLOAD_LIMIT_BYTES,
exceeds_upload_limit: sizeBytes > DIRECT_UPLOAD_LIMIT_BYTES,
largest_files: prepared.largestFiles,
offloaded_media: prepared.offloaded,
},
}),
null,
2,
),
);
return;
}
if (sizeBytes < ARCHIVE_DIAGNOSTIC_THRESHOLD_BYTES) reportLargestFiles(prepared);
console.log("");
console.log(`${c.success("✓")} Dry run complete — nothing uploaded`);
if (sizeBytes > DIRECT_UPLOAD_LIMIT_BYTES) {
console.log(c.warn(` Archive exceeds the 200 MB direct-upload limit.`));
}
}
// fallow-ignore-next-line complexity
async function maybeUploadProject(
client: HyperframesCloudClient,
source: ProjectInputSource,
preparedArchive: PreparedLocalArchive | undefined,
asJson: boolean,
idempotencyKey: string | undefined,
): Promise<UploadResult> {
if (source.kind === "asset_id") {
return { projectInput: { type: "asset_id", asset_id: source.assetId! } };
}
if (source.kind === "url") {
return { projectInput: { type: "url", url: source.url! } };
}
if (!preparedArchive) throw new Error("Local project archive was not prepared");
const { project, archive } = preparedArchive;
if (!archive) throw new Error("Local project archive is over the upload limit");
if (!asJson) {
console.log("");
console.log(`${c.accent("◆")} Uploading (direct-to-S3)`);
}
const uploadStart = Date.now();
let uploaded;
try {
uploaded = await uploadZipViaDirectUpload({
client,
bytes: archive.buffer,
filename: `${project.name}.zip`,
idempotencyKey,
onProgress: !asJson
? (ev) => {
if (ev.phase === "initialize") {
console.log(c.dim(` initializing…`));
} else if (ev.phase === "upload" && ev.percent === 0) {
console.log(c.dim(` uploading to S3…`));
} else if (ev.phase === "complete") {
console.log(c.dim(` finalizing…`));
}
}
: undefined,
});
} catch (err) {
reportApiError("Upload failed", err);
}
if (!asJson) {
console.log(
c.dim(
` asset_id: ${c.accent(uploaded.asset_id)} · ${formatDuration(Date.now() - uploadStart)}`,
),
);
}
return { projectInput: { type: "asset_id", asset_id: uploaded.asset_id } };
}
// ---------------------------------------------------------------------------
// Submit step
// ---------------------------------------------------------------------------
interface SubmitOptions {
projectInput: CreateHyperframesRenderRequest["project"];
fps: number | undefined;
quality: "draft" | "standard" | "high" | undefined;
format: "mp4" | "webm" | "mov" | undefined;
resolution: CreateHyperframesRenderRequest["resolution"] | undefined;
aspectRatio: CreateHyperframesRenderRequest["aspect_ratio"] | undefined;
composition: string | undefined;
variables: Record<string, unknown> | undefined;
title: string | undefined;
callbackUrl: string | undefined;
callbackId: string | undefined;
idempotencyKey: string | undefined;
reverseSessionId: string | undefined;
}
type RenderRequestBody = CreateHyperframesRenderRequest & { reverse_session_id?: string };
function reverseSessionIdOf(project: ProjectInputSource): string | undefined {
return project.kind === "dir"
? readProjectConfig(project.dir ?? ".")?.reverseSessionId
: undefined;
}
async function submitRender(
client: HyperframesCloudClient,
opts: SubmitOptions,
): Promise<{ render_id: string }> {
const body = buildRenderBody(opts);
try {
return await client.createRender({ body, idempotencyKey: opts.idempotencyKey });
} catch (err) {
reportApiError("Submit failed", err);
}
}
// fallow-ignore-next-line complexity
function buildRenderBody(opts: SubmitOptions): RenderRequestBody {
const body: RenderRequestBody = { project: opts.projectInput };
if (opts.fps !== undefined) body.fps = opts.fps;
if (opts.quality !== undefined) body.quality = opts.quality;
if (opts.format !== undefined) body.format = opts.format;
if (opts.resolution !== undefined) body.resolution = opts.resolution;
if (opts.aspectRatio !== undefined) body.aspect_ratio = opts.aspectRatio;
if (opts.composition !== undefined) body.composition = opts.composition;
if (opts.variables !== undefined) body.variables = opts.variables;
if (opts.title !== undefined) body.title = opts.title;
if (opts.callbackUrl !== undefined) body.callback_url = opts.callbackUrl;
if (opts.callbackId !== undefined) body.callback_id = opts.callbackId;
if (opts.reverseSessionId !== undefined) body.reverse_session_id = opts.reverseSessionId;
return body;
}
// ---------------------------------------------------------------------------
// Poll + progress
// ---------------------------------------------------------------------------
// fallow-ignore-next-line complexity
async function pollWithProgress(
client: HyperframesCloudClient,
renderId: string,
asJson: boolean,
poll: { intervalMs: number; maxWaitMs: number },
): Promise<HyperframesRenderDetail> {
// ANSI carriage-return redraws only make sense on a TTY. CI logs and
// file redirects get one append per status change instead, and JSON
// mode stays silent altogether.
const interactive = !asJson && process.stdout.isTTY === true;
let lastStatus = "";
try {
return await pollUntilTerminal(client, renderId, {
intervalMs: poll.intervalMs,
maxWaitMs: poll.maxWaitMs,
// fallow-ignore-next-line complexity
onTick: (detail, elapsedMs) => {
if (asJson) return;
if (interactive) {
if (detail.status === lastStatus) {
process.stdout.write(`\r\x1b[2K ${formatTickLine(detail, elapsedMs)}`);
} else {
if (lastStatus) process.stdout.write("\n");
process.stdout.write(` ${formatTickLine(detail, elapsedMs)}`);
lastStatus = detail.status;
}
} else if (detail.status !== lastStatus) {
// Non-TTY: one line per status transition, no carriage returns.
console.log(` ${formatTickLine(detail, elapsedMs)}`);
lastStatus = detail.status;
}
},
});
} catch (err) {
if (!asJson && lastStatus && interactive) process.stdout.write("\n");
if (err instanceof PollTimeoutError) {
errorBox(
"Poll timed out",
err.message,
`The render may still complete. Resume with: hyperframes cloud get ${renderId}`,
);
failCommand();
}
return reportApiError("API error during poll", err, {
suggestion: `The render may still be running. Resume with: hyperframes cloud get ${renderId}`,
});
} finally {
if (!asJson && lastStatus && interactive) process.stdout.write("\n");
}
}
function formatTickLine(detail: HyperframesRenderDetail, elapsedMs: number): string {
const status = colorStatus(detail.status);
return `${status} ${c.dim(formatDuration(elapsedMs))}`;
}
// ---------------------------------------------------------------------------
// Terminal handlers
// ---------------------------------------------------------------------------
function handleFailedRender(
detail: HyperframesRenderDetail,
asJson: boolean,
projectDir?: string,
): never {
if (asJson) {
console.log(JSON.stringify(withMeta({ render: detail }), null, 2));
failCommand();
}
const fontUse =
projectDir && detail.failure_message
? describeUnresolvedFontUse(detail.failure_message, projectDir)
: undefined;
errorBox(
"Render failed",
[detail.failure_message ?? "(no failure_message returned)", fontUse].filter(Boolean).join("\n"),
`Inspect: hyperframes cloud get ${detail.render_id}`,
);
failCommand();
}
function resolveOutputPath(output: string | undefined, renderId: string, format: string): string {
if (output) {
return isAbsolute(output) ? output : resolvePath(process.cwd(), output);
}
const ext = FORMAT_EXT[format] ?? `.${format}`;
return resolvePath(process.cwd(), "renders", `${renderId}${ext}`);
}
// fallow-ignore-next-line complexity
async function streamVideo(
url: string,
destPath: string,
asJson: boolean,
): Promise<{ bytes: number }> {
// `downloadToFile` creates the parent directory and preserves existing output on failure.
if (!asJson) {
console.log("");
console.log(`${c.accent("◆")} Downloading to ${c.accent(destPath)}`);
}
try {
const result = await downloadToFile(url, destPath);
if (!asJson) {
console.log(c.dim(` ${formatBytes(result.bytes)} written`));
}
return { bytes: result.bytes };
} catch (err) {
const message = normalizeErrorMessage(err);
errorBox(
"Download failed",
message,
"The presigned URL is short-lived; re-fetch with `hyperframes cloud get`.",
);
failCommand();
}
}