Skip to content

Write HTML. Render video. Built for agents.

35.2 KB
Raw Blame
import { failCommand } 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 "citty";

import {
  detectAspectRatioFromHtml,
  type AspectRatioDetection,
} from "../../cloud/detectAspectRatio.js";
import { c } from "../../ui/colors.js";
import { errorBox, formatBytes, formatDuration } from "../../ui/format.js";
import { resolveProject, type ProjectDir } from "../../utils/project.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 { 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 { existsSync } from "node:fs";

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: 30." },
    quality: { type: "string", description: "draft | standard | high (default: standard)" },
    format: { type: "string", description: "mp4 | webm | mov (default: mp4)" },
    "page-motion-blur": {
      type: "string",
      description:
        "Set off to disable authored page motion blur. Omit to keep the current cloud behavior.",
    },
    resolution: {
      type: "string",
      description: "Resolution tier: 1080p | 4k (default: 1080p; 4k is billed at 1.5x)",
    },
    "aspect-ratio": {
      type: "string",
      description: "Aspect ratio: 16:9 | 9:16 | 1:1 (default: 16:9)",
    },
    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 fps = parseIntFlag(args.fps, { flag: "--fps", min: 1, max: 240 });
    const quality = parseEnumFlag(args.quality, VALID_QUALITY, { flag: "--quality" });
    const format = parseEnumFlag(args.format, VALID_FORMAT, { flag: "--format" });
    const pageMotionBlur = parseEnumFlag(args["page-motion-blur"], ["off"] as const, {
      flag: "--page-motion-blur",
    });
    const resolution = parseEnumFlag(args.resolution, VALID_RESOLUTION, {
      flag: "--resolution",
    });
    const explicitAspectRatio = parseEnumFlag(args["aspect-ratio"], VALID_ASPECT_RATIO, {
      flag: "--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);

    // 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,
    );

    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,
    );

    const client = await createCloudClient();
    const preparedArchive =
      project.kind === "dir"
        ? await prepareLocalArchive(project, args.composition, asJson, (file) =>
            uploadAssetViaDirectUpload({ client, ...file }),
          )
        : undefined;

    const upload = await maybeUploadProject(
      client,
      project,
      preparedArchive,
      asJson,
      args["idempotency-key"],
    );
    const submitted = await submitRender(client, {
      projectInput: upload.projectInput,
      fps,
      quality,
      format,
      resolution,
      pageMotionBlur,
      aspectRatio,
      composition: args.composition,
      variables,
      title: args.title,
      callbackUrl: args["callback-url"],
      callbackId: args["callback-id"],
      idempotencyKey: args["idempotency-key"],
    });

    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);
    }

    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_:.-]`);
    failCommand();
  }
}

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.",
  );
  failCommand();
}

// ---------------------------------------------------------------------------
// 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.");
    failCommand();
  }
  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 an independent render knob — the pipeline supersamples
 * to a *matching* ratio and can't reshape. So for a local dir we auto-detect
 * from the entry HTML and the user rarely needs `--aspect-ratio`. Behaviour:
 *
 *   - Local dir, no explicit flag → auto-detect and log the result.
 *   - Local dir, explicit flag that conflicts with the detected dims → hard
 *     error (the render would otherwise fail or silently ignore the request).
 *   - Local dir with a missing `--composition` entry → hard error before
 *     upload, instead of a generic server-side render failure.
 *   - `--asset-id` / `--url` → the zip isn't on disk; trust an explicit flag,
 *     otherwise let the server default (16:9) apply.
 *
 * 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: "16:9" | "9:16" | "1:1" | undefined,
  asJson: boolean,
): "16:9" | "9:16" | "1:1" | undefined {
  if (project.kind !== "dir") {
    if (!explicit) {
      const reason = project.kind === "asset_id" ? "--asset-id" : "--url";
      logDetection(asJson, `Auto-detect skipped (project is ${reason})`);
    }
    return explicit;
  }

  const dir = project.dir ?? ".";
  const entryRelative = compositionArg ?? "index.html";
  const entryPath = resolvePath(dir, entryRelative);

  if (!existsSync(entryPath)) {
    errorBox(
      "Composition not found",
      `Entry file "${entryRelative}" does not exist in ${dir}.`,
      "Pass --composition with a path that exists inside the project, or omit it to use index.html.",
    );
    failCommand();
  }

  const detection = detectAspectRatioFromHtml(entryPath);

  if (explicit) {
    // The renderer matches the composition's authored aspect ratio — it can't
    // reshape. Both a `matched` ratio that differs from `explicit` AND a
    // `no-match` (dims are known but the ratio isn't 16:9/9:16/1:1, so it can
    // never equal the requested supported ratio) are definite conflicts.
    // Other kinds (no-dims / no-root-div / invalid-dims / read-error) leave the
    // ratio unknown, so we can't prove a conflict and forward the explicit value.
    const conflictDetail =
      detection.kind === "matched" && detection.aspectRatio !== explicit
        ? `${detection.width}×${detection.height} → ${detection.aspectRatio}`
        : detection.kind === "no-match"
          ? `${detection.width}×${detection.height}, ratio ${detection.ratio.toFixed(2)} — not a supported ratio`
          : undefined;
    if (conflictDetail) {
      errorBox(
        "Aspect ratio mismatch",
        `--aspect-ratio ${explicit} doesn't match the composition (${conflictDetail}).`,
        "The renderer matches 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();
    }
    return explicit;
  }

  logDetection(asJson, summarizeDetection(detection, entryRelative));
  return detection.kind === "matched" ? detection.aspectRatio : undefined;
}

const ASPECT_FALLBACK_HINT =
  "server will default aspect_ratio to 16:9. Pass --aspect-ratio to override.";

function logDetection(asJson: boolean, message: string): void {
  if (asJson) return;
  // `matched` is the only branch with its own affirmative phrasing; the
  // rest share the fallback hint to keep the user oriented after a miss.
  const suffix = message.startsWith("Detected aspect ratio") ? "" : `; ${ASPECT_FALLBACK_HINT}`;
  console.log(c.dim(`   ${message}${suffix}`));
}

// 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 `${entryRelative} dims ${detection.width}×${detection.height} (ratio ${detection.ratio.toFixed(2)}) don't match 16:9, 9:16, or 1:1`;
    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,
): 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;
  // `resolveProject` calls process.exit on a missing/invalid dir, so
  // there's no need to wrap this in try/catch — if it returns, the
  // index.html is present. The earlier impl had a dead try/catch.
  const { indexPath } = resolveProject(source.dir);
  const issues = validateVariablesAgainstProject(indexPath, 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"],
): 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 offloaded = await offloadMedia(project, fileMap, entryPath, asJson, upload);

  // 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"],
): Promise<OffloadedMedia[]> {
  let offloaded: OffloadedMedia[];
  try {
    offloaded = await offloadHeavyMedia(project.dir, fileMap, {
      apiBaseUrl: resolveCloudBaseUrl(),
      upload,
      entryPath,
      onFile: asJson
        ? undefined
        : (item) => 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;
}

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;
  pageMotionBlur: NonNullable<CreateHyperframesRenderRequest["page_motion_blur"]> | 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;
}

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): CreateHyperframesRenderRequest {
  const body: CreateHyperframesRenderRequest = { 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.pageMotionBlur !== undefined) body.page_motion_blur = opts.pageMotionBlur;
  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;
  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): never {
  if (asJson) {
    console.log(JSON.stringify(withMeta({ render: detail }), null, 2));
    failCommand();
  }
  errorBox(
    "Render failed",
    detail.failure_message ?? "(no failure_message returned)",
    `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();
  }
}