Skip to content

Write HTML. Render video. Built for agents.

83.0 KB
Raw Blame
import { captureArtifactRevision } from "../utils/artifactCapture.js";
import { recordRenderSuccess, registerRenderOutput } from "@hyperframes/studio-server/history";
import { failCommand, requestCliExit, scheduleCliExit } from "../utils/commandResult.js";
import { defineCommand } from "citty";
import type { Example } from "./_examples.js";
import { mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
import { createRenderPlan, resolveBrowserGpuForCli, type RenderFormat } from "./render/plan.js";
import { seedProjectAuthoringSkill } from "../utils/projectConfig.js";
import type { CatalogUsage } from "../utils/catalogUsage.js";
import { presentRenderPlan } from "./render/present.js";
import { executeRenderPlan, renderLintContinuationHint, runRenderLint } from "./render/execute.js";
// Test-only seams retained at the command boundary for render behavior tests.
export { resolveBrowserGpuForCli, renderLintContinuationHint, runRenderLint };

export const examples: Example[] = [
  ["Render to MP4", "hyperframes render --output output.mp4"],
  ["Render a specific composition", "hyperframes render -c compositions/intro.html -o intro.mp4"],
  [
    "Upsample any composition to 4K (supersamples via Chrome DPR)",
    "hyperframes render --resolution 4k --output 4k.mp4",
  ],
  ["Render transparent overlay (ProRes)", "hyperframes render --format mov --output overlay.mov"],
  ["Render transparent WebM overlay", "hyperframes render --format webm --output overlay.webm"],
  [
    "Render animated GIF for PRs/docs",
    "hyperframes render --format gif --fps 15 --gif-loop 0 --output demo.gif",
  ],
  [
    "Render PNG sequence (RGBA frames for AE/Nuke/Fusion)",
    "hyperframes render --format png-sequence --output frames/",
  ],
  [
    "Render HLS VOD (master playlist + MPEG-TS segments in a directory)",
    "hyperframes render --format hls --output stream/",
  ],
  ["High quality at 60fps", "hyperframes render --fps 60 --quality high --output hd.mp4"],
  ["Deterministic render via Docker", "hyperframes render --docker --output deterministic.mp4"],
  ["Parallel rendering with 6 workers", "hyperframes render --workers 6 --output fast.mp4"],
  ["Opt out of browser GPU render", "hyperframes render --no-browser-gpu --output cpu.mp4"],
  [
    "Show full lint findings instead of the summary line",
    "hyperframes render --lint-verbose --output out.mp4",
  ],
  [
    "Relocate frame cache off C: (Windows) or another small partition",
    "hyperframes render --frames-cache-dir D:/hf-cache --output out.mp4",
  ],
  ["HDR output (auto-detected)", "hyperframes render --output hdr-output.mp4"],
  [
    "Override composition variables (parametrized render)",
    'hyperframes render --variables \'{"title":"Q4 Report","theme":"dark"}\' --output q4.mp4',
  ],
  [
    "Variables from a JSON file",
    "hyperframes render --variables-file ./vars.json --output out.mp4",
  ],
  [
    "Batch render one output per variables row",
    'hyperframes render --batch rows.json --output "renders/{name}.mp4"',
  ],
];
import { freemem, tmpdir } from "node:os";
import { resolve, dirname, join, basename } from "node:path";
import { execFileSync, spawn } from "node:child_process";
import { loadProducer } from "../utils/producer.js";
import { c } from "../ui/colors.js";
import { desktopHint } from "../utils/desktopApp.js";
import {
  formatBytes,
  formatRenderSummaryDetail,
  formatRenderPipelineDetail,
  formatScreenshotFallbackHint,
  resolvePrintedCaptureMode,
  errorBox,
} from "../ui/format.js";
import { warnIfWebmAlphaDropped } from "../utils/webmAlphaCheck.js";
import { renderFailureDiagnostic } from "../ui/renderDiagnostic.js";
import { renderProgress, renderMachineProgress } from "../ui/progress.js";
import {
  trackRenderComplete,
  trackRenderError,
  trackRenderObservation,
  type RenderOutputShapeTelemetryPayload,
  type RenderEnvironmentTelemetryPayload,
} from "../telemetry/events.js";
import { maybePromptRenderFeedback } from "../telemetry/feedback.js";
import {
  readConfigFresh,
  recordRecentRender,
  writeConfig,
  writeConfigWithResult,
  type HyperframesConfig,
} from "../telemetry/config.js";
import { renderJobObservabilityTelemetryPayload } from "../telemetry/renderObservability.js";
import {
  startRenderCpuSampler,
  type RenderCpuSampler,
  type RenderCpuTelemetryPayload,
} from "../telemetry/renderCpu.js";
import { bytesToMb } from "../telemetry/system.js";
import { VERSION } from "../version.js";
import { isDevMode } from "../utils/env.js";
import { buildDockerRunArgs, resolveDockerPlatform } from "../utils/dockerRunArgs.js";
import { createStderrTail, DockerRenderExitError } from "../utils/dockerStderrTail.js";
import type { BrowserInstallFacts } from "../browser/installFacts.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import {
  DOCKER_BUILD_TIMEOUT_MINUTES,
  describeDockerBuildFailure,
} from "../utils/dockerBuildFailure.js";
import { runEnvironmentChecks } from "../browser/preflight.js";
import {
  detectH264EncoderModeForRender,
  getFFmpegInstallHint,
  H264EncoderUnavailableError,
  type H264EncoderMode,
} from "../browser/ffmpeg.js";
import { chromeLaunchRemediation } from "../browser/linuxDeps.js";
import { macosOldChromeCrashRemediation } from "../browser/macosOldChromeCrash.js";
import { windowsChromeCrashRemediation } from "../browser/windowsCrash.js";
import { sandboxDeniedRemediation } from "../browser/sandboxDenied.js";
import { killOrphanedProcessesForRender } from "../utils/orphanCleanup.js";
import { createRenderCancellationScope } from "../utils/renderCancellation.js";
import {
  markRenderSucceeded,
  runPostRenderStep,
  runPostRenderStepAsync,
} from "../utils/render-success-state.js";
import type { ProducerLogger, RenderJob, RenderPerfSummary } from "@hyperframes/producer";
import { EXTRACT_CACHE_DIR_DISABLED_ALIASES, type VideoFrameFormat } from "@hyperframes/engine";
import {
  checkOutputResolutionCompatibility,
  suggestMatchingPreset,
  fpsToNumber,
  type CanvasResolution,
  type OutputResolutionIssueKind,
  type Fps,
} from "@hyperframes/core";

export default defineCommand({
  meta: {
    name: "render",
    description: "Render a composition to MP4, WebM, MOV, GIF, HLS, or a PNG sequence",
  },
  args: {
    dir: {
      type: "positional",
      description: "Project directory",
      required: false,
    },
    composition: {
      type: "string",
      alias: "c",
      description:
        "Render a specific composition file instead of index.html (e.g. compositions/intro.html). " +
        "Sub-compositions using <template> wrappers must be referenced from index.html via data-composition-src. " +
        "Pass `.` (or omit the flag) to render the project's index.html.",
    },
    output: {
      type: "string",
      alias: "o",
      description: "Output path (default: renders/<name>.mp4)",
    },
    fps: {
      type: "string",
      alias: "f",
      description:
        "Frame rate. Accepts integer (24, 25, 30, 50, 60, 120, 240) or " +
        "ffmpeg-style rational (30000/1001 for NTSC 29.97, 24000/1001 for " +
        "23.976, 60000/1001 for 59.94). Range 1-240. " +
        "Defaults to the composition's root data-fps, else 30.",
      // No `default` here on purpose: citty would set args.fps="30" on
      // omission, which would make explicitFps always non-null and short-
      // circuit the data-fps resolution below (resolveDefaultFpsArg). The
      // "30" fallback lives at the parseFps(fpsArg ?? "30") call instead.
    },
    quality: {
      type: "string",
      alias: "q",
      description:
        "Quality: draft, looks, delivery, or standard/high. looks is the default (CRF 16). delivery is high. MOV always uses the fixed alpha-preserving ProRes 4444 profile.",
      default: "looks",
    },
    skill: {
      type: "string",
      description:
        "Authoring skill that initiated this render (e.g. hyperframes). " +
        "Recorded on anonymous render telemetry for per-skill usage breakdowns; ignored unless it is a slug.",
    },
    format: {
      type: "string",
      description:
        "Output format: mp4, webm, mov, gif, png-sequence, hls " +
        "(MOV/WebM render with transparency; png-sequence writes RGBA frames " +
        "to a directory for AE/Nuke/Fusion ingest; gif is best at 15fps for PRs/docs; " +
        "hls writes a VOD playlist directory — H.264/AAC, SDR only, no GPU encoding)",
      default: "mp4",
    },
    "gif-loop": {
      type: "string",
      description: "GIF loop count, 0 = infinite. Range: 0-65535. Only used with --format gif.",
    },
    "hls-segment-seconds": {
      type: "string",
      description:
        "HLS target segment length in whole seconds (default: 4). Range: 1-60. " +
        "Also fixes the encoder GOP at segment x fps frames so every segment " +
        "starts on a keyframe. Only used with --format hls.",
    },
    "video-frame-format": {
      type: "string",
      description:
        "Source video frame extraction format: auto, jpg, png (default: auto). " +
        "Use png for UI recordings, screen captures, and color-sensitive source videos; " +
        "alpha-capable sources always extract as PNG.",
      default: "auto",
    },
    "page-motion-blur": {
      type: "string",
      description:
        "Set off to disable authored page motion blur. Omit to keep the composition's setting.",
    },
    workers: {
      type: "string",
      alias: "w",
      description:
        "Parallel render workers (number or 'auto'). Default: auto. " +
        "Each worker launches a separate Chrome process (~256 MB RAM).",
    },
    docker: {
      type: "boolean",
      description: "Use Docker for deterministic render",
      default: false,
    },
    hdr: {
      type: "boolean",
      description: "Force HDR output even if no HDR sources are detected",
      default: false,
    },
    sdr: {
      type: "boolean",
      description: "Force SDR output even if HDR sources are detected",
      default: false,
    },
    crf: {
      type: "string",
      description:
        "Override MP4/WebM encoder CRF. Mutually exclusive with --video-bitrate; unsupported for MOV.",
    },
    "video-bitrate": {
      type: "string",
      description:
        "Target MP4/WebM video bitrate such as 10M. Mutually exclusive with --crf; unsupported for MOV.",
    },
    "vp9-cpu-used": {
      type: "string",
      description:
        "libvpx-vp9 -cpu-used value for WebM encodes (-8 to 8). Higher is faster with a larger quality/size tradeoff. Env: PRODUCER_VP9_CPU_USED.",
    },
    gpu: { type: "boolean", description: "Use GPU encoding", default: false },
    "browser-gpu": {
      type: "boolean",
      description:
        "Force host GPU acceleration for Chrome/WebGL capture. Default: auto (probe on first launch; fall back to software if no GPU). Use --no-browser-gpu to force software (SwiftShader).",
    },
    quiet: {
      type: "boolean",
      description: "Suppress verbose output",
      default: false,
    },
    "lint-verbose": {
      type: "boolean",
      description: "Show full lint findings instead of the summary line",
      default: false,
    },
    debug: {
      type: "boolean",
      description:
        "Write full render diagnostics and keep intermediate artifacts under the producer .debug directory.",
      default: false,
    },
    "best-effort": {
      type: "boolean",
      description:
        "Allow output with structured capture-readiness warnings (default). Use --no-best-effort to fail on missing or unready media.",
      default: true,
    },
    strict: {
      type: "boolean",
      description: "Fail render on lint errors",
      default: false,
    },
    "strict-all": {
      type: "boolean",
      description: "Fail render on lint errors AND warnings",
      default: false,
    },
    "max-concurrent-renders": {
      type: "string",
      description: "Max concurrent renders when using the producer server (1-10). Default: 2.",
    },
    variables: {
      type: "string",
      description:
        'JSON object of variable values, merged over the composition\'s data-composition-variables defaults. Example: --variables \'{"title":"Hello"}\'. Read inside the composition via window.__hyperframes.getVariables().',
    },
    "variables-file": {
      type: "string",
      description:
        "Path to a JSON file with variable values (alternative to --variables). The file must contain a single JSON object.",
    },
    "strict-variables": {
      type: "boolean",
      description:
        "Fail render if any --variables key is undeclared or has a wrong type vs the composition's data-composition-variables. Without this flag, mismatches are warnings.",
      default: false,
    },
    batch: {
      type: "string",
      description:
        'Path to a JSON array of variable rows (or {"rows":[...]}). Renders one output per row.',
    },
    "batch-concurrency": {
      type: "string",
      description:
        "Maximum number of batch rows to render at once. Default: 1, because each render already parallelizes across workers.",
    },
    "batch-fail-fast": {
      type: "boolean",
      description: "Stop launching new batch rows after the first row failure.",
      default: false,
    },
    json: {
      type: "boolean",
      description: "With --batch, emit exactly one final JSON result document.",
      default: false,
    },
    resolution: {
      type: "string",
      description:
        "Output resolution preset: landscape (1920x1080), portrait (1080x1920), landscape-4k (3840x2160), portrait-4k (2160x3840), square (1080x1080), square-4k (2160x2160). Aliases: 1080p, 4k, uhd, 1080p-square, square-1080p, 4k-square. The composition is unchanged — Chrome renders at higher DPR (deviceScaleFactor) so the captured screenshot lands at the requested dimensions. Aspect ratio must match the composition; the scale must be an integer multiple. Not yet supported with --hdr.",
    },
    "page-side-compositing": {
      type: "boolean",
      description:
        "Run shader transitions on a page-side WebGL canvas inside Chrome " +
        "instead of the Node-side layered blend. ~6× faster for SDR " +
        "shader-transition renders. Used for mp4, hls and gif output without " +
        "HDR content; for mp4 and hls it usually turns off under --experimental-fast-capture. " +
        "webm and mov output take the layered path. --no-page-side-compositing forces " +
        "the layered path for mp4 and hls; gif always uses the page-side canvas.",
      default: true,
    },
    "browser-timeout": {
      type: "string",
      description:
        "Puppeteer page-navigation timeout in SECONDS for the entry HTML. " +
        "Increase when heavy compositions (many videos / fonts / asset " +
        "requests) cannot reach domcontentloaded within the 60s default " +
        "(see issue #1199). Accepts 0.001-86400 (24h cap). " +
        "Note: this controls page.goto only — very heavy compositions may " +
        "also need PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS / " +
        "PRODUCER_PLAYER_READY_TIMEOUT_MS bumped (the post-goto window.__hf " +
        "readiness poll has its own 45s budget). " +
        "Env fallback: PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS (MILLISECONDS).",
    },
    "protocol-timeout": {
      type: "string",
      description:
        "CDP protocol timeout in ms. Increase on slow/low-memory machines " +
        "where Chrome operations time out. Default: 300000 (5 min). " +
        "Env: PRODUCER_PUPPETEER_PROTOCOL_TIMEOUT_MS.",
    },
    "player-ready-timeout": {
      type: "string",
      description:
        "Timeout in ms for the composition player to become ready. " +
        "Increase for complex compositions on slow hardware. Default: 45000 (45 s). " +
        "Env: PRODUCER_PLAYER_READY_TIMEOUT_MS.",
    },
    resume: {
      type: "boolean",
      description:
        "Segmented capture only (HF_SEGMENTED_CAPTURE=true): reuse segments a " +
        "previous run of the same composition and settings already finished, " +
        "recorded in renders/.hf-segments/<hash>/segments.json. Each reused " +
        "segment is re-validated before it is skipped.",
      default: false,
    },
    "keep-segments": {
      type: "boolean",
      description:
        "Segmented capture only: keep renders/.hf-segments/<hash> after a " +
        "successful render instead of deleting it.",
      default: false,
    },
    "low-memory-mode": {
      type: "boolean",
      description:
        "Force the low-memory safe render profile on (--low-memory-mode) or " +
        "off (--no-low-memory-mode). Safe mode pins to 1 worker, uses " +
        "screenshot capture, and skips auto-worker calibration to avoid " +
        "memory thrash on constrained machines. Default: auto-detected from " +
        "total RAM (<= 8 GB). Env: PRODUCER_LOW_MEMORY_MODE.",
    },
    "experimental-fast-capture": {
      type: "boolean",
      description:
        "Capture frames via Chrome's drawElementImage API instead of " +
        "Page.captureScreenshot — reads DOM paint records directly, ~2x faster. " +
        "Default: on where it can engage (macOS + hardware-GPU browser); " +
        "incompatible compositions and self-verification failures fall back to " +
        "screenshot capture automatically. Pass =false to disable. " +
        "Env: PRODUCER_EXPERIMENTAL_FAST_CAPTURE.",
      // No `default` — an omitted flag must stay `undefined` so the `!= null`
      // guard below leaves PRODUCER_EXPERIMENTAL_FAST_CAPTURE untouched and the
      // env fallback survives (matches the --low-memory-mode idiom).
    },
    "frames-cache-dir": {
      type: "string",
      description:
        "Directory for the content-addressed extracted-frame cache. " +
        "Use to relocate the cache off the system drive when the OS temp " +
        "directory lives on a small partition (e.g. Windows C: exhaustion " +
        `during long renders). Pass ${EXTRACT_CACHE_DIR_DISABLED_ALIASES.map((a) => `"${a}"`).join(" / ")} to ` +
        "disable caching entirely (frames extract into the render's workDir " +
        "and are cleaned up when the render ends). Default: " +
        "<tmpdir>/hyperframes-extract-cache-<uid>. " +
        "Env: HYPERFRAMES_EXTRACT_CACHE_DIR.",
    },
  },
  // Keep the transport adapter thin: each phase has one ownership boundary.
  async run({ args }) {
    const plan = createRenderPlan(args);
    const cancellation = plan.useDocker ? undefined : createRenderCancellationScope();
    try {
      // Teach the project its owning skill from an explicit --skill so every
      // later flag-less render (re-render, `npm run render`, batch) inherits it.
      seedProjectAuthoringSkill(plan.project.dir, args.skill);
      await presentRenderPlan(plan);
      await executeRenderPlan(
        plan,
        {
          renderDocker,
          renderLocal,
          checkResolution: checkRenderResolutionPreflight,
        },
        cancellation,
      );
    } catch (error) {
      if (cancellation?.signal.aborted) {
        const reason = cancellation.signal.reason;
        const message = reason instanceof Error ? reason.message : String(reason);
        process.stderr.write(`Render cancelled: ${message}\n`);
        requestCliExit(1);
      }
      throw error;
    } finally {
      cancellation?.dispose();
    }
  },
});

export interface SingleRenderResult {
  durationMs?: number;
  renderTimeMs: number;
  outcome?: "completed" | "completed_with_warnings";
  warnings?: Array<{ code: string; message: string }>;
}

export interface RenderOptions {
  fps: Fps;
  quality: "draft" | "standard" | "high";
  /** Authoring workflow skill that drove this render (telemetry attribution). */
  authoringSkill?: string;
  /** Which step resolved authoringSkill: an explicit --skill flag, or the project's own config. */
  authoringSkillSource?: "flag" | "project-config";
  /** Raw --skill value when it failed normalizeSkillSlug (an unrecognized skill name was passed). */
  authoringSkillInvalid?: string;
  /** Names of HF_-/HYPERFRAMES_-prefixed env vars present at plan time (never values), capped at 20. */
  hfEnvOverrides?: readonly string[];
  /**
   * Catalog items installed in this project and those the rendered composition
   * reaches. Resolved once in the render plan; absent on programmatic callers
   * that build options by hand, which simply omit the catalog properties.
   */
  catalogUsage?: CatalogUsage;
  format: RenderFormat;
  gifLoop?: number;
  /** True when `createRenderPlan` clamped a requested `--fps` above 30 to 30 for `--format gif`. */
  gifFpsCapped?: boolean;
  /** Major FFmpeg/Chrome version from local preflight (telemetry only); absent on Docker renders. */
  ffmpegVersionMajor?: number;
  browserVersionMajor?: number;
  browserInstall?: BrowserInstallFacts;
  /** HLS target segment length in seconds; ignored unless `format` is `"hls"`. */
  hlsSegmentSeconds?: number;
  workers?: number;
  gpu: boolean;
  /**
   * Chrome WebGL backend mode. "auto" probes on first launch and falls back
   * to "software" if no usable GPU. Defaults to "software" when omitted to
   * stay backwards-compatible with callers that pre-date the tri-state.
   */
  browserGpuMode?: "auto" | "hardware" | "software";
  hdrMode: "auto" | "force-hdr" | "force-sdr";
  crf?: number;
  vp9CpuUsed?: number;
  videoBitrate?: string;
  videoFrameFormat?: VideoFrameFormat;
  pageMotionBlur?: "off";
  quiet: boolean;
  debug?: boolean;
  /** Segmented capture: reuse a prior run's validated segments. */
  resumeSegments?: boolean;
  /** Segmented capture: keep the segment directory after success. */
  keepSegments?: boolean;
  bestEffort?: boolean;
  browserPath?: string;
  variables?: Record<string, unknown>;
  entryFile?: string;
  exitAfterComplete?: boolean;
  /** Output resolution preset; see `resolveDeviceScaleFactor` for constraints. */
  outputResolution?: CanvasResolution;
  /** Whether the resolution names a tier without fixing an orientation. */
  outputResolutionAspectAgnostic?: boolean;
  /** Raw resolution flag retained for the in-container CLI. */
  outputResolutionRaw?: string;
  pageSideCompositing?: boolean;
  /** EXPERIMENTAL. drawElementImage frame capture (--experimental-fast-capture). */
  experimentalFastCapture?: boolean;
  /**
   * Puppeteer `page.goto()` timeout for the entry HTML, in milliseconds.
   * When omitted, the engine default (60s) applies. Surfaced as
   * `--browser-timeout <seconds>` at the CLI and threaded through to the
   * producer's EngineConfig override.
   */
  pageNavigationTimeoutMs?: number;
  /** CDP protocol timeout override (ms). */
  protocolTimeout?: number;
  /** Player-ready timeout override (ms). */
  playerReadyTimeout?: number;
  /** Throw render failures to the caller instead of printing and exiting. */
  throwOnError?: boolean;
  /** Skip the interactive feedback prompt after a successful render. */
  skipFeedback?: boolean;
  /** False for a batch row: one line about the desktop app per batch is noise, not a pointer. */
  desktopHint?: boolean;
  /**
   * OPT IN to managing the DE parallel-router circuit breaker
   * (`applyDeParallelRouterCircuitBreaker`) for this render. Default OFF —
   * only the top-level CLI render command's own call sites should ever set
   * this (review): the mechanism shares one process-wide env var and two
   * module-level flags across every `renderLocal` call in the process,
   * which is safe for SEQUENTIAL calls (single render, single-concurrency
   * batch rows) but not for genuinely concurrent ones — racing invocations
   * could tear down or misattribute each other's outcome. Programmatic
   * consumers importing `renderLocal` (a future studio-server path, test
   * harnesses, distributed runners) therefore do not manage the breaker
   * unless they explicitly opt in AND guarantee sequential invocation. The
   * CLI sets this for single renders and for `--batch` at concurrency 1; it
   * leaves it unset for `--batch-concurrency N>=2`.
   *
   * NOTE the asymmetry: the ROUTER itself is default-on for every consumer
   * (the producer decides that). This flag only governs whether we
   * additionally enforce the per-install breaker, because that is the part
   * with process-wide state.
   */
  manageDeParallelRouterBreaker?: boolean;
}

/**
 * Read a composition's dimensions from the SAME source the producer's compiler
 * uses — `data-width` / `data-height` on the `[data-composition-id]` root (see
 * htmlCompiler.ts). Returns `undefined` when they can't be determined (no root,
 * missing/invalid attrs, unparseable HTML). Note the producer *defaults* a
 * missing attr to 1080; this pre-flight deliberately defers instead (returns
 * `undefined`) rather than guess a dimension the author didn't declare, so it
 * never false-aborts — the producer's defense-in-depth still catches that case.
 *
 * Deriving dims any other way (e.g. `data-resolution` or a `#stage` heuristic)
 * risks disagreeing with the actual render: most compositions (all registry
 * blocks) carry `data-width/height` and no `data-resolution`, so a parallel
 * heuristic could false-abort a valid render. `DOMParser` isn't shipped by
 * Node — the CLI polyfills it via linkedom, imported lazily so the heavy DOM
 * library stays out of `render.js`'s module-load graph (it cold-imports at
 * >5 s already; a static linkedom import tips the render test suite's import
 * hook over its timeout — see the note on `renderLocal browser GPU config`).
 */
async function readCompositionDimensions(
  compositionHtml: string,
): Promise<{ width: number; height: number } | undefined> {
  try {
    const { ensureDOMParser } = await import("../utils/dom.js");
    ensureDOMParser();
    const doc = new DOMParser().parseFromString(compositionHtml, "text/html");
    const rootEl = doc.querySelector("[data-composition-id]");
    const width = parseInt(rootEl?.getAttribute("data-width") ?? "", 10);
    const height = parseInt(rootEl?.getAttribute("data-height") ?? "", 10);
    if (width > 0 && height > 0) return { width, height };
  } catch {
    // Unreadable / unparseable composition — fall through to `undefined`.
  }
  return undefined;
}

/**
 * Render pre-flight: return an actionable message when the chosen
 * `outputResolution` preset is incompatible with the composition's
 * orientation/aspect ratio, or with the alpha/HDR mode — or `undefined` when
 * the combination is fine (or can't be determined statically).
 *
 * Extracted (and exported) so the CLI wiring around `process.exit` stays a
 * thin adapter and the branch logic is unit-testable. See render-reliability
 * workstream P1-3.
 */
export async function checkRenderResolutionPreflight(
  compositionHtml: string,
  outputResolution: CanvasResolution | undefined,
  modes: { alphaRequested: boolean; hdrRequested: boolean; aspectAgnostic?: boolean },
): Promise<{ message: string; kind: OutputResolutionIssueKind } | undefined> {
  if (!outputResolution) return undefined;
  const dims = await readCompositionDimensions(compositionHtml);
  // Couldn't determine the composition's actual dimensions — defer to the
  // pipeline's own defense-in-depth check rather than guess.
  if (!dims) return undefined;
  const effective =
    modes.aspectAgnostic === true
      ? (suggestMatchingPreset(dims.width, dims.height, outputResolution) ?? outputResolution)
      : outputResolution;
  const compat = checkOutputResolutionCompatibility({
    compositionWidth: dims.width,
    compositionHeight: dims.height,
    outputResolution: effective,
    alphaRequested: modes.alphaRequested,
    hdrRequested: modes.hdrRequested,
  });
  // Narrow to the incompatible case; `message`/`kind` are always set there.
  if (compat.ok || !compat.message || !compat.kind) return undefined;
  return { message: compat.message, kind: compat.kind };
}

const DOCKER_IMAGE_PREFIX = "hyperframes-renderer";

function dockerImageTag(version: string): string {
  return `${DOCKER_IMAGE_PREFIX}:${version}`;
}

function resolveDockerfilePath(): string {
  // Built CLI: dist/docker/Dockerfile.render
  const builtPath = resolve(__dirname, "docker", "Dockerfile.render");
  // Dev mode: src/docker/Dockerfile.render
  const devPath = resolve(__dirname, "..", "src", "docker", "Dockerfile.render");
  for (const p of [builtPath, devPath]) {
    try {
      statSync(p);
      return p;
    } catch {
      continue;
    }
  }
  throw new Error("Dockerfile.render not found — CLI package may be corrupted");
}

function dockerImageExists(tag: string): boolean {
  try {
    execFileSync("docker", ["image", "inspect", tag], { stdio: "pipe", timeout: 10_000 });
    return true;
  } catch {
    return false;
  }
}

function dockerImageTagForPlatform(version: string, platform: string): string {
  // Suffix the tag with the arch so amd64 and arm64 images of the same
  // hyperframes version coexist in the local cache (a developer who flips
  // between hosts shouldn't have to rebuild).
  const archSuffix = platform === "linux/arm64" ? "-arm64" : "";
  return `${dockerImageTag(version)}${archSuffix}`;
}

function ensureDockerImage(version: string, platform: string, quiet: boolean): string {
  const tag = dockerImageTagForPlatform(version, platform);

  if (dockerImageExists(tag)) {
    if (!quiet) console.log(c.dim(`  Docker image: ${tag} (cached)`));
    return tag;
  }

  if (!quiet) console.log(c.dim(`  Building Docker image: ${tag} (${platform})...`));

  const dockerfilePath = resolveDockerfilePath();

  // Copy Dockerfile to a temp build context so docker build has a clean context.
  // mkdtempSync (not a `Date.now()`-derived name) so the path is unpredictable
  // and created 0o700 by the kernel — a guessable temp dir in a world-writable
  // tmpdir is pre-creatable by another local user, who could then swap in their
  // own Dockerfile or symlink the path (CodeQL js/insecure-temporary-file).
  const tmpDir = mkdtempSync(join(tmpdir(), "hyperframes-docker-"));
  writeFileSync(join(tmpDir, "Dockerfile"), readFileSync(dockerfilePath));

  // Platform is now derived from the host arch (see resolveDockerPlatform).
  // Apple Silicon and other arm64 hosts get a native linux/arm64 build; the
  // Dockerfile installs a pinned arm64 chrome-headless-shell from Playwright
  // (chrome-for-testing publishes no linux-arm64 build).
  //
  // TARGETARCH is passed explicitly rather than relying on BuildKit's
  // automatic platform args because the legacy builder (and some BuildKit
  // configurations like colima 0.6.x) leaves it unset, which would defeat
  // the arch conditional in the Dockerfile.
  const targetArch = platform === "linux/arm64" ? "arm64" : "amd64";
  try {
    execFileSync(
      "docker",
      [
        "build",
        "--platform",
        platform,
        "--build-arg",
        `HYPERFRAMES_VERSION=${version}`,
        "--build-arg",
        `TARGETARCH=${targetArch}`,
        "-t",
        tag,
        tmpDir,
      ],
      { stdio: quiet ? "pipe" : "inherit", timeout: DOCKER_BUILD_TIMEOUT_MINUTES * 60_000 },
    );
  } catch (error: unknown) {
    const message = normalizeErrorMessage(error);
    throw new Error(`Failed to build Docker image: ${message}`, { cause: error });
  } finally {
    rmSync(tmpDir, { recursive: true, force: true });
  }

  if (!quiet) console.log(c.dim(`  Docker image: ${tag} (built)`));
  return tag;
}

/**
 * Resolves the Docker `--platform` for this host and enforces the constraints
 * that come with it — keeping that policy out of `renderDocker` so the
 * orchestrator stays focused on build/run wiring. May terminate the process
 * via errorBox on unrecoverable mismatches (e.g. --gpu on arm64).
 */
function resolveDockerHostPlatform(options: RenderOptions): string {
  const platform = resolveDockerPlatform();

  // Docker Desktop on Apple Silicon (and colima with VZ) doesn't implement
  // the `--gpus` host-passthrough flag, so requesting `--gpu` on a linux/arm64
  // container fails at `docker run` with an opaque device-driver error. Catch
  // it early with actionable guidance.
  if (options.gpu && platform === "linux/arm64") {
    errorBox(
      "--gpu is not supported with --docker on arm64 hosts",
      "Docker Desktop/colima on Apple Silicon doesn't expose --gpus host passthrough to linux/arm64 containers.",
      "Drop --gpu, or run a native (non-Docker) render on this host, or set HYPERFRAMES_DOCKER_PLATFORM=linux/amd64 if you need GPU encoding (slow under qemu but works).",
    );
    failCommand();
  }

  if (!options.quiet && platform === "linux/arm64") {
    // The arm64 image uses Playwright's pinned linux-arm64 chrome-headless-shell
    // (chrome-for-testing has no arm64 build). It's a different Chromium build
    // than amd64's chrome-for-testing binary, so output isn't byte-identical to
    // an amd64 golden baseline — fine for end-user output. Set
    // HYPERFRAMES_DOCKER_PLATFORM=linux/amd64 to force parity (qemu-emulated,
    // slower).
    console.log(
      c.dim(
        "  Host is arm64 — using linux/arm64 image with Playwright's " +
          "chrome-headless-shell (output won't be byte-identical to amd64 " +
          "renders; set HYPERFRAMES_DOCKER_PLATFORM=linux/amd64 to force parity).",
      ),
    );
  }

  return platform;
}

async function registerRenderOutputOrWarn(projectDir: string, outputPath: string): Promise<void> {
  await registerRenderOutput(projectDir, outputPath).catch((error: unknown) =>
    console.warn(`Render output was not registered: ${normalizeErrorMessage(error)}`),
  );
}

// Inherited minor finding (CRAP 37.1, cyclomatic 11). This PR only added
// `pageNavigationTimeoutMs` to the options forwarded to `buildDockerRunArgs`.
// fallow-ignore-next-line complexity
async function renderDocker(
  projectDir: string,
  outputPath: string,
  options: RenderOptions,
): Promise<SingleRenderResult> {
  await registerRenderOutputOrWarn(projectDir, outputPath);
  const capture = await captureArtifactRevision(projectDir).catch(() => undefined);
  const startTime = Date.now();
  const cpu = startRenderCpuSampler();

  // Dev mode (tsx/ts-node) uses "latest" since the local version isn't on npm
  const dockerVersion = isDevMode() ? "latest" : VERSION;
  if (!options.quiet && isDevMode()) {
    console.log(c.dim("  Dev mode: using hyperframes@latest in Docker image"));
  }

  const platform = resolveDockerHostPlatform(options);

  let imageTag: string;
  try {
    imageTag = ensureDockerImage(dockerVersion, platform, options.quiet);
  } catch (error: unknown) {
    cpu.stop();
    const failure = describeDockerBuildFailure(error);
    errorBox(failure.title, failure.message, failure.hint);
    failCommand();
  }

  const outputDir = dirname(outputPath);
  const outputFilename = basename(outputPath);
  const dockerArgs = buildDockerRunArgs({
    imageTag,
    projectDir: resolve(projectDir),
    outputDir: resolve(outputDir),
    outputFilename,
    platform,
    hostStdoutIsTty: process.stdout.isTTY === true,
    options: {
      fps: options.fps,
      quality: options.quality,
      format: options.format,
      gifLoop: options.gifLoop,
      hlsSegmentSeconds: options.hlsSegmentSeconds,
      workers: options.workers,
      gpu: options.gpu,
      browserGpu: options.browserGpuMode === "hardware",
      hdrMode: options.hdrMode,
      crf: options.crf,
      vp9CpuUsed: options.vp9CpuUsed,
      videoBitrate: options.videoBitrate,
      videoFrameFormat: options.videoFrameFormat,
      pageMotionBlur: options.pageMotionBlur,
      quiet: options.quiet,
      variables: options.variables,
      entryFile: options.entryFile,
      outputResolution: options.outputResolutionRaw ?? options.outputResolution,
      pageSideCompositing: options.pageSideCompositing,
      debug: options.debug,
      bestEffort: options.bestEffort,
      experimentalFastCapture: options.experimentalFastCapture,
      pageNavigationTimeoutMs: options.pageNavigationTimeoutMs,
      protocolTimeoutMs: options.protocolTimeout,
      playerReadyTimeoutMs: options.playerReadyTimeout,
    },
  });

  if (!options.quiet) {
    console.log(c.dim("  Running render in Docker container..."));
    console.log("");
  }

  try {
    await new Promise<void>((resolvePromise, reject) => {
      const stderrTail = createStderrTail();
      // stderr is piped so the failure can name its cause; it is still echoed live.
      const child = spawn("docker", dockerArgs, {
        stdio: options.quiet ? ["pipe", "ignore", "pipe"] : ["inherit", "inherit", "pipe"],
      });
      child.stderr?.on("data", (chunk: Buffer) => {
        process.stderr.write(chunk);
        stderrTail.push(chunk.toString());
      });
      child.on("close", (code) => {
        if (code === 0) resolvePromise();
        else reject(new DockerRenderExitError(code, stderrTail.tail()));
      });
      child.on("error", (err) => reject(err));
    });
  } catch (error: unknown) {
    handleRenderError(error, options, startTime, cpu, true, "Check Docker is running: docker info");
  }

  const elapsed = Date.now() - startTime;
  const cpuUsage = cpu.stop();

  // Docker child exited 0 → the containerized producer already validated
  // AND committed the artifact. Mirror renderLocal's post-success guarantee
  // so any late throw here (telemetry flush, feedback prompt) cannot flip
  // the exit code.
  markRenderSucceeded();
  await runPostRenderStepAsync("recordRenderSuccess", () =>
    recordRenderSuccess(projectDir, outputPath, "completed", capture).then(() => {}),
  );

  // Track metrics (no job object available from Docker — use a minimal stub)
  runPostRenderStep("trackRenderComplete", () =>
    trackRenderComplete({
      durationMs: elapsed,
      fps: fpsToNumber(options.fps),
      quality: options.quality,
      workers: options.workers,
      docker: true,
      gpu: options.gpu,
      authoringSkill: options.authoringSkill,
      authoringSkillSource: options.authoringSkillSource,
      authoringSkillInvalid: options.authoringSkillInvalid,
      hfEnvOverrides: options.hfEnvOverrides,
      catalogUsage: options.catalogUsage,
      ...renderOutputShapeTelemetryPayload(options),
      ...renderEnvironmentTelemetryPayload(options),
      ...getMemorySnapshot(),
      ...cpuUsage,
    }),
  );

  // ponytail: Docker runs the producer in a child process, so no perfSummary is
  // threaded back here; the summary shows render time only (never a wrong video
  // length). Probe the output with ffprobe if a duration figure is wanted here.
  runPostRenderStep("printRenderComplete", () =>
    printRenderComplete({
      outputPath,
      projectDir,
      desktopHint: wantsDesktopHint(options),
      elapsedMs: elapsed,
      quiet: options.quiet,
      format: options.format,
    }),
  );
  runPostRenderStep("warnIfWebmAlphaDropped", () =>
    warnIfWebmAlphaDropped(outputPath, options.format, options.quiet),
  );
  if (options.exitAfterComplete) scheduleCliExit();
  return { renderTimeMs: elapsed };
}

export async function renderLocal(
  projectDir: string,
  outputPath: string,
  options: RenderOptions,
  commandCancellation?: ReturnType<typeof createRenderCancellationScope>,
): Promise<SingleRenderResult> {
  const cancellation = commandCancellation ?? createRenderCancellationScope();
  try {
    return await executeLocalRender(projectDir, outputPath, options, cancellation);
  } finally {
    if (!commandCancellation) cancellation.dispose();
  }
}

// fallow-ignore-next-line complexity
async function executeLocalRender(
  projectDir: string,
  outputPath: string,
  options: RenderOptions,
  cancellation: ReturnType<typeof createRenderCancellationScope>,
): Promise<SingleRenderResult> {
  await registerRenderOutputOrWarn(projectDir, outputPath);
  const capture = await captureArtifactRevision(projectDir).catch(() => undefined);
  cancellation.checkAncestors();
  cancellation.signal.throwIfAborted();
  let recoveredOrphanTrees = 0;
  try {
    recoveredOrphanTrees = await killOrphanedProcessesForRender(cancellation.signal);
  } catch {
    if (cancellation.signal.aborted) cancellation.signal.throwIfAborted();
  }
  cancellation.checkAncestors();
  cancellation.signal.throwIfAborted();
  if (recoveredOrphanTrees > 0 && !options.quiet) {
    console.warn(
      c.warn(
        `  Recovered ${recoveredOrphanTrees} orphaned browser process ${recoveredOrphanTrees === 1 ? "tree" : "trees"} from an interrupted render.`,
      ),
    );
  }

  const preflight = await runEnvironmentChecks({
    projectDir,
    diskPaths: [tmpdir(), dirname(outputPath)],
    browserPath: options.browserPath,
    includeBrowser: true,
    includeDisk: true,
    includeWindowsUnc: true,
    signal: cancellation.signal,
  });
  options = {
    ...options,
    ffmpegVersionMajor: preflight.ffmpegVersionMajor,
    browserVersionMajor: preflight.browserVersionMajor,
    browserInstall: preflight.browserInstall,
  };
  cancellation.checkAncestors();
  cancellation.signal.throwIfAborted();
  const failedChecks = preflight.outcomes.filter((outcome) => !outcome.ok);
  if (failedChecks.length > 0) {
    for (const check of failedChecks) {
      errorBox(check.title ?? `${check.name} check failed`, check.detail, check.hint);
    }
    failCommand();
  }
  if (!options.quiet) {
    for (const outcome of preflight.outcomes) {
      if (outcome.level === "warn") {
        console.warn(c.warn(`  ${outcome.name}: ${outcome.detail}`));
        if (outcome.hint) console.warn(c.dim(`  ${outcome.hint}`));
      }
    }
  }

  if (preflight.ffmpegPath) process.env.HYPERFRAMES_FFMPEG_PATH = preflight.ffmpegPath;
  if (preflight.ffprobePath) process.env.HYPERFRAMES_FFPROBE_PATH = preflight.ffprobePath;
  if (preflight.browser?.executablePath && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
    process.env.PRODUCER_HEADLESS_SHELL_PATH = preflight.browser.executablePath;
  }

  // HLS shares the H.264 encode path but cannot take the GPU fallback below:
  // its fixed-length segments need the software encoder's forced-keyframe lock.
  const isHls = options.format === "hls";
  if ((options.format === "mp4" || isHls) && preflight.ffmpegPath) {
    const gpuRequested = options.gpu && !isHls;
    let encoderMode: H264EncoderMode = gpuRequested ? "gpu" : "software";
    try {
      encoderMode = await detectH264EncoderModeForRender(
        preflight.ffmpegPath,
        gpuRequested,
        cancellation.signal,
      );
    } catch (error) {
      if (cancellation.signal.aborted) cancellation.signal.throwIfAborted();
      // HDR MP4 uses HEVC; auto mode cannot resolve the codec until sources are
      // inspected. Forced SDR, HLS, or no libx265 either: nothing here can encode.
      if (
        error instanceof H264EncoderUnavailableError &&
        (options.hdrMode === "force-sdr" || isHls || !error.hevcEncoderAvailable)
      ) {
        errorBox(
          `${isHls ? "HLS" : "MP4"} H.264 encoder unavailable`,
          error.message,
          `Install an FFmpeg build with libx264 support (${getFFmpegInstallHint()})` +
            (isHls
              ? "."
              : ", or render WebM instead: hyperframes render --format webm --output output.webm"),
        );
        failCommand();
      }
      // Capability probing is advisory. Let the real encode surface the
      // authoritative FFmpeg error instead of failing here with a bare stack.
      if (!options.quiet) {
        const detail = error instanceof Error ? error.message : String(error);
        console.warn(c.warn(`  Unable to probe H.264 encoder capabilities: ${detail}`));
      }
    }
    if (encoderMode === "gpu" && isHls) {
      errorBox(
        "HLS H.264 encoder unavailable",
        "FFmpeg does not include libx264, and HLS cannot fall back to VideoToolbox: fixed-length segments require the software encoder's forced-keyframe lock.",
        `Install an FFmpeg build with libx264 support (${getFFmpegInstallHint()}).`,
      );
      failCommand();
    }
    if (encoderMode === "gpu" && !gpuRequested) {
      console.warn(
        c.warn("  FFmpeg does not include libx264; falling back to GPU H.264 encoding."),
      );
      options = { ...options, gpu: true };
    }
    if (encoderMode === "software" && gpuRequested && !options.quiet) {
      console.warn(c.warn("  No GPU encoder works on this machine; encoding with libx264."));
    }
  }

  cancellation.checkAncestors();
  cancellation.signal.throwIfAborted();
  const producer = await loadProducer();
  const deParallelRouterActive =
    options.manageDeParallelRouterBreaker === true
      ? applyDeParallelRouterCircuitBreaker(options.quiet)
      : // Not managing the breaker: the router still runs (producer default),
        // we just don't enforce or record the per-install trip.
        false;

  const startTime = Date.now();
  const cpu = startRenderCpuSampler();
  const logger = createRenderTelemetryLogger(
    producer.createConsoleLogger?.(options.debug ? "debug" : options.quiet ? "warn" : "info") ??
      createNoopProducerLogger(),
  );

  const engineConfig = producer.resolveConfig({
    browserGpuMode: options.browserGpuMode ?? "software",
    // Local auto opts out of the software-GPU screenshot clamp. Docker and
    // --no-browser-gpu request software; --resolution supersamples via screenshot.
    ...(options.browserGpuMode === "auto" &&
    options.outputResolution == null &&
    process.env.PRODUCER_FORCE_SCREENSHOT !== "true"
      ? { forceScreenshot: false }
      : {}),
    ...(options.pageNavigationTimeoutMs != null
      ? { pageNavigationTimeout: options.pageNavigationTimeoutMs }
      : {}),
    ...(options.protocolTimeout != null && { protocolTimeout: options.protocolTimeout }),
    ...(options.playerReadyTimeout != null && { playerReadyTimeout: options.playerReadyTimeout }),
    ...(options.vp9CpuUsed != null ? { vp9CpuUsed: options.vp9CpuUsed } : {}),
  });
  const request = producer.createRenderRequest({
    projectDir,
    outputPath,
    engineConfig,
    options: {
      fps: options.fps,
      quality: options.quality,
      format: options.format,
      gifLoop: options.gifLoop,
      hlsSegmentSeconds: options.hlsSegmentSeconds,
      workers: options.workers,
      useGpu: options.gpu,
      hdrMode: options.hdrMode,
      crf: options.crf,
      videoBitrate: options.videoBitrate,
      videoFrameFormat: options.videoFrameFormat,
      pageMotionBlur: options.pageMotionBlur,
      variables: options.variables,
      entryFile: options.entryFile,
      outputResolution: options.outputResolution,
      outputResolutionAspectAgnostic: options.outputResolutionAspectAgnostic,
      debug: options.debug,
      resumeSegments: options.resumeSegments,
      keepSegments: options.keepSegments,
      strictness: options.bestEffort === false ? "strict" : "best-effort",
    },
  });
  const job = producer.createRenderJob(producer.renderConfigFromRequest(request, { logger }));

  const onProgress = options.quiet
    ? undefined
    : (progressJob: Pick<RenderJob, "progress" | "stageProgress">, message: string) => {
        renderProgress(progressJob.progress, message);
        renderMachineProgress(progressJob.progress, progressJob.stageProgress);
      };

  try {
    cancellation.checkAncestors();
    await producer.executeRenderJob(
      job,
      projectDir,
      outputPath,
      onProgress,
      cancellation.signal,
      cancellation.checkAncestors,
    );
  } catch (error: unknown) {
    maybeConsumeDeParallelRouterTrial(deParallelRouterActive, job, options.quiet);
    // The render container sets `ENV CONTAINER=true`; suggesting `--docker`
    // from inside it is a misdirection (heygen-com/hyperframes#3370).
    const inContainer = process.env.CONTAINER === "true";
    handleRenderError(
      error,
      options,
      startTime,
      cpu,
      false,
      inContainer ? "" : "Try --docker for containerized rendering",
      job.failedStage,
      job,
    );
  }

  // Render resolved without throwing → producer's `artifact validated`
  // checkpoint fired AND the artifact was committed to disk. From this
  // point on, ANY thrown teardown error must not be allowed to override
  // the exit code. Field signal ts=1784169760 / ts=1784171150 / ts=1784172467
  // (win32/x64, CLI 0.7.58): valid MP4 on disk, exited 1 with no error print.
  markRenderSucceeded();
  await runPostRenderStepAsync("recordRenderSuccess", () =>
    recordRenderSuccess(
      projectDir,
      outputPath,
      job.outcome === "completed_with_warnings" ? "completed_with_warnings" : "completed",
      capture,
    ).then(() => {}),
  );

  maybeConsumeDeParallelRouterTrial(deParallelRouterActive, job, options.quiet);
  const elapsed = Date.now() - startTime;
  const cpuUsage = cpu.stop();
  if (job.outcome === "completed_with_warnings") {
    for (const warning of job.warnings) {
      console.warn(c.warn(`  [${warning.code}] ${warning.message}`));
    }
  }
  runPostRenderStep("trackRenderMetrics", () =>
    trackRenderMetrics(job, elapsed, options, false, cpuUsage),
  );
  runPostRenderStep("printRenderComplete", () =>
    printRenderComplete({
      outputPath,
      projectDir,
      desktopHint: wantsDesktopHint(options),
      elapsedMs: elapsed,
      quiet: options.quiet,
      format: options.format,
      perf: job.perfSummary,
      requestedGpuMode: options.browserGpuMode,
    }),
  );
  runPostRenderStep("warnIfWebmAlphaDropped", () =>
    warnIfWebmAlphaDropped(outputPath, options.format, options.quiet),
  );
  if (!options.skipFeedback) {
    await runPostRenderStepAsync("maybePromptRenderFeedback", () =>
      maybePromptRenderFeedback({
        renderDurationMs: elapsed,
        quiet: options.quiet,
      }),
    );
  }
  if (options.exitAfterComplete) scheduleCliExit();
  const durationMs = job.perfSummary
    ? Math.round(job.perfSummary.compositionDurationSeconds * 1000)
    : undefined;
  const outcome =
    job.outcome === "completed_with_warnings" ? "completed_with_warnings" : "completed";
  return {
    renderTimeMs: elapsed,
    durationMs,
    outcome,
    warnings: job.warnings.map((warning) => ({ code: warning.code, message: warning.message })),
  };
}

function getMemorySnapshot() {
  return {
    peakMemoryMb: bytesToMb(process.memoryUsage.rss()),
    memoryFreeMb: bytesToMb(freemem()),
  };
}

/** Output-shape request facts, resolved before the pipeline starts (survives a pre-perfSummary render_error). */
function renderOutputShapeTelemetryPayload(
  options: RenderOptions,
): RenderOutputShapeTelemetryPayload {
  return {
    outputResolutionPreset: options.outputResolution,
    outputFormat: options.format,
    hdrMode: options.hdrMode,
    videoFrameFormat: options.videoFrameFormat,
    gifFpsCapped: options.gifFpsCapped,
  };
}

/** Toolchain facts from local preflight; undefined on Docker renders (the container runs its own). */
function renderEnvironmentTelemetryPayload(
  options: RenderOptions,
): RenderEnvironmentTelemetryPayload {
  return {
    ffmpegVersionMajor: options.ffmpegVersionMajor,
    browserVersionMajor: options.browserVersionMajor,
    browserInstall: options.browserInstall,
  };
}

function metaString(meta: Record<string, unknown> | undefined, key: string): string | undefined {
  const value = meta?.[key];
  return typeof value === "string" ? value : undefined;
}

function metaNumber(meta: Record<string, unknown> | undefined, key: string): number | undefined {
  const value = meta?.[key];
  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
}

function metaBoolean(meta: Record<string, unknown> | undefined, key: string): boolean | undefined {
  const value = meta?.[key];
  return typeof value === "boolean" ? value : undefined;
}

function trackRenderTraceFromLog(message: string, meta: Record<string, unknown> | undefined): void {
  if (message !== "[Render:trace]") return;
  const status = metaString(meta, "status");
  if (status !== "start" && status !== "end" && status !== "checkpoint" && status !== "error") {
    return;
  }
  trackRenderObservation({
    source: "cli",
    renderJobId: metaString(meta, "renderJobId"),
    phase: metaString(meta, "phase"),
    status,
    compositionHash: metaString(meta, "compositionHash"),
    elapsedMs: metaNumber(meta, "elapsedMs"),
    durationMs: metaNumber(meta, "durationMs"),
    message: metaString(meta, "message"),
    workerCount: metaNumber(meta, "workerCount"),
    forceScreenshot: metaBoolean(meta, "forceScreenshot"),
    useStreamingEncode: metaBoolean(meta, "useStreamingEncode"),
    useLayeredComposite: metaBoolean(meta, "useLayeredComposite"),
    usePageSideCompositing: metaBoolean(meta, "usePageSideCompositing"),
    hasHdrContent: metaBoolean(meta, "hasHdrContent"),
    captureMode: metaString(meta, "captureMode"),
    captureOperation: metaString(meta, "captureOperation"),
    framesCompleted: metaNumber(meta, "framesCompleted"),
    totalFrames: metaNumber(meta, "totalFrames"),
    heartbeatIndex: metaNumber(meta, "heartbeatIndex"),
    stageElapsedMs: metaNumber(meta, "stageElapsedMs"),
    videoCount: metaNumber(meta, "videoCount"),
    extractedVideoCount: metaNumber(meta, "extractedVideoCount"),
    totalFramesExtracted: metaNumber(meta, "totalFramesExtracted"),
    maxFramesPerVideo: metaNumber(meta, "maxFramesPerVideo"),
    avgFramesPerExtractedVideo: metaNumber(meta, "avgFramesPerExtractedVideo"),
    vfrPreflightCount: metaNumber(meta, "vfrPreflightCount"),
    vfrPreflightMs: metaNumber(meta, "vfrPreflightMs"),
    cacheHits: metaNumber(meta, "cacheHits"),
    cacheMisses: metaNumber(meta, "cacheMisses"),
  });
}

function createRenderTelemetryLogger(base: ProducerLogger): ProducerLogger {
  return {
    error(message, meta) {
      base.error(message, meta);
      trackRenderTraceFromLog(message, meta);
    },
    warn(message, meta) {
      base.warn(message, meta);
      trackRenderTraceFromLog(message, meta);
    },
    info(message, meta) {
      base.info(message, meta);
      trackRenderTraceFromLog(message, meta);
    },
    debug(message, meta) {
      base.debug(message, meta);
      trackRenderTraceFromLog(message, meta);
    },
    isLevelEnabled(level) {
      return base.isLevelEnabled?.(level) ?? true;
    },
  };
}

function createNoopProducerLogger(): ProducerLogger {
  return {
    error() {},
    warn() {},
    info() {},
    debug() {},
    isLevelEnabled() {
      return true;
    },
  };
}

/**
 * The 25-render exposure cap that bounded the old opt-in TRIAL is gone: the
 * router is default-ON as of 2026-07-27, so "stop offering it after N
 * renders" would mean switching a shipped default off behind the user's
 * back. What survives is the half that was always safety rather than
 * sampling — the per-install circuit breaker below, which latches the router
 * off for good the first time a render has to fall back.
 */

/**
 * The user set `HF_DE_PARALLEL_ROUTER` themselves (either polarity), latched
 * once at first observation. Their choice wins over the circuit breaker in
 * BOTH directions: we never overwrite an explicit opt-in with `"false"` on a
 * fallback, and never overwrite an explicit opt-out either. Latched rather
 * than re-read because the breaker itself writes the var — after the first
 * write a live `process.env` read could no longer tell "the user set this"
 * from "we set this" (the same distinction the old trial needed for
 * `--batch` rows sharing one process).
 */
let deParallelRouterUserManaged = false;
let deParallelRouterUserManagedResolved = false;

/**
 * In-process latch mirroring the persisted `deParallelRouterTrialFired`: set
 * the moment the breaker trips, independent of whether persisting that to
 * `~/.hyperframes/config.json` succeeds. `writeConfig` swallows all fs
 * errors (by design — telemetry must never break the CLI), so on an
 * unwritable config (root-owned file, disk full) the flag can never stick on
 * disk; without this latch the router would re-enable and re-fail on every
 * subsequent render in this process. Later processes re-arm — disk is the
 * only cross-process channel — but each process now stops after at most one
 * failure it couldn't record.
 */
let deParallelRouterBreakerTrippedThisProcess = false;

/**
 * Test-only reset for the module-level trial state — a real CLI process
 * only ever runs one `--batch` sequence, so this state never needs
 * resetting outside a test process where many independent test cases share
 * one imported module instance.
 */
export function __resetDeParallelRouterTrialStateForTests(): void {
  deParallelRouterBreakerTrippedThisProcess = false;
  deParallelRouterUserManaged = false;
  deParallelRouterUserManagedResolved = false;
}

/**
 * Has this install's router circuit breaker already tripped — on disk, or via
 * this process's in-memory latch?
 *
 * Deliberately does NOT consider telemetry state. The old opt-in trial did:
 * there was no point running an experimental path if the resulting signal
 * couldn't be recorded. Now that the router is a shipped default, gating it
 * on telemetry would mean users who opted out of analytics silently get a
 * slower renderer — punishing a privacy choice with a performance penalty
 * (review finding). Telemetry state governs REPORTING, never behavior.
 */
function hasDeParallelRouterBreakerTripped(config: HyperframesConfig): boolean {
  return deParallelRouterBreakerTrippedThisProcess || Boolean(config.deParallelRouterTrialFired);
}

/**
 * Latch the router OFF for the rest of this process by writing an explicit
 * `"false"`.
 *
 * Under the old default-OFF flag this deleted the var, because absent meant
 * off. With the router default-ON, deleting means ON — the same call would
 * silently RE-ENABLE the router on exactly the host that just failed
 * (review finding). Writing the explicit value is what makes the breaker a
 * breaker. No-op when the user set the var themselves: their choice wins in
 * both directions.
 */
/**
 * Mirror of the producer's `isDeParallelRouterEnabled`. Deliberately
 * duplicated rather than imported: `@hyperframes/producer` is lazily loaded
 * (`loadProducer()`) to keep CLI startup fast, and this runs on the startup
 * path. Keep the two in sync — the producer copy is the source of truth.
 */
function userValueEnablesDeParallelRouter(): boolean {
  const raw = process.env.HF_DE_PARALLEL_ROUTER?.trim().toLowerCase();
  if (raw === undefined || raw === "") return true;
  return !(raw === "false" || raw === "0" || raw === "off" || raw === "no");
}

function applyDeParallelRouterBreaker(): void {
  if (deParallelRouterUserManaged) return;
  process.env.HF_DE_PARALLEL_ROUTER = "false";
}

/**
 * Apply this install's router circuit breaker before a render.
 *
 * The router is default-ON, so the normal path does NOTHING here — the
 * producer's own default takes over. This exists for the one case that must
 * survive a shipped default: an install that already had a render fall back
 * stays off, permanently, across processes (the verdict is persisted to
 * `~/.hyperframes/config.json`). See `maybeConsumeDeParallelRouterTrial` for
 * what trips it.
 *
 * Returns whether the router is active for this render, so the caller knows
 * to inspect the outcome afterward.
 */
function applyDeParallelRouterCircuitBreaker(quiet: boolean): boolean {
  // Latch the user's own choice on first observation, BEFORE the breaker can
  // write the var itself and make the two indistinguishable.
  //
  // Ownership uses the SAME normalization as the two parsers: a set-but-empty
  // (or whitespace) value means "unset / default ON", so it is NOT a user
  // choice and must stay breaker-managed. Treating any defined value as
  // user-managed would let `HF_DE_PARALLEL_ROUTER=` route the render (empty
  // parses as ON) while exempting that install from the breaker — it would
  // keep retrying a failing router forever, losing exactly the first-fallback
  // protection this PR exists to provide (review finding).
  if (!deParallelRouterUserManagedResolved) {
    deParallelRouterUserManaged = (process.env.HF_DE_PARALLEL_ROUTER ?? "").trim() !== "";
    deParallelRouterUserManagedResolved = true;
  }
  if (deParallelRouterUserManaged) {
    // Explicit choice, either polarity — report whether it enables the
    // router so outcomes are still consumed, but never override it.
    return userValueEnablesDeParallelRouter();
  }

  // The in-process latch decides once set — short-circuit before the disk
  // read so post-trip batch rows don't pay a config read + parse per row for
  // an answer module state already knows.
  if (deParallelRouterBreakerTrippedThisProcess) {
    applyDeParallelRouterBreaker();
    return false;
  }
  // readConfigFresh, NOT readConfig: the cached read is process-lifetime, so
  // another process persisting a trip mid-`--batch` would never be observed.
  if (hasDeParallelRouterBreakerTripped(readConfigFresh())) {
    deParallelRouterBreakerTrippedThisProcess = true;
    applyDeParallelRouterBreaker();
    if (!quiet) {
      console.log(
        c.dim(
          "  Parallel drawElement capture stays off for this install (a previous render " +
            "had to fall back). Re-enable with HF_DE_PARALLEL_ROUTER=true.",
        ),
      );
    }
    return false;
  }

  // Nothing left to gate: the router is a shipped default for every install,
  // so leave the var unset and let the producer's default-ON apply. The
  // breaker above is the only thing that turns it off, per install, and only
  // after a real fallback. `HF_DE_PARALLEL_ROUTER=false` remains the user-
  // facing kill switch.
  //
  // The `de-parallel-router` canary that used to sit here was removed with its
  // registry entry (they had to go together — at >=100 the evaluator
  // short-circuits ahead of the CI/seedless exclusions, so deleting only the
  // entry would have flipped whatever still resolved false at deletion time).
  //
  // Two claims from the ramp's rationale were wrong, recorded so they are not
  // reintroduced: "~17x jump in exposure onto <=4 CPUs / Docker" overstated
  // the reach — Docker renders never use drawElement at all (0 of 4,281
  // measured) and the router requires it, so no percentage ever exposed
  // Docker. And "~11% of installs already route" was an OUTCOME (the share
  // clearing eligibility and the old 25-render cap), not an exposure setting;
  // read as a rollout knob it inverted the arithmetic, which is how gating at
  // 5% came to CUT fleet exposure ~25x rather than ramp it.
  return true;
}

/**
 * The router outcome for this render, or undefined when the router never
 * engaged. `perfSummary.drawElement.parallelRouter` is NEVER undefined on
 * the success path — aggregateDrawElement (perfSummary.ts) defaults it to
 * the string "none" for every render, whether or not drawElement/the router
 * ever engaged. Normalizing "none" to undefined here is required, not
 * optional: without it, ordinary renders below the router's own frame
 * threshold (the common case) would tick the render-count backstop on every
 * single render and trip DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS after 25
 * completely unrelated renders that never touched the router (review
 * finding).
 */
function resolveDeParallelRouterOutcome(job: RenderJob): string | undefined {
  const outcome =
    job.perfSummary?.drawElement?.parallelRouter ??
    job.errorDetails?.observability?.capture.deParallelRouter;
  return outcome === "none" ? undefined : outcome;
}

/**
 * Persist `deParallelRouterTrialFired: true`, verifying against a fresh
 * disk read that it actually stuck, and re-asserting if a concurrent
 * writer's stale snapshot clobbered it. ONLY the fired flag is retried —
 * re-asserting a boolean is idempotent, so retries can't corrupt anything,
 * unlike the render counter (a re-applied increment double-counts the
 * render when our write landed but a later concurrent write raced our
 * verify read — review finding). Returns false as soon as `writeConfig`
 * reports an fs failure (unwritable `~/.hyperframes` — retrying a failed
 * write is pointless, so the retries are reserved for genuine concurrent
 * clobbers, where the write landed but a racing writer's stale snapshot
 * overwrote it — review finding).
 */
function persistDeParallelRouterTrialFired(): boolean {
  const MAX_ATTEMPTS = 3;
  let mirrored = false;
  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
    const config = readConfigFresh();
    // Both stores must carry the latch, not just config.json. Checking only
    // the config let a run stop early after a failed mirror — and config.json
    // is the copy a stale writer or a re-mint can erase, so the durable one
    // is exactly the one that was missing. The read side merges install-state
    // back in, so the two together are what make the trip survive.
    if (config.deParallelRouterTrialFired && mirrored) return true;
    config.deParallelRouterTrialFired = true;
    const result = writeConfigWithResult(config);
    if (!result.ok) return false;
    mirrored = result.mirrored !== false;
    if (mirrored) return true;
    // Config landed but the mirror did not — retry rather than report success.
  }
  return false;
}

/**
 * After a trial-armed render, persist that the router's OWN bet actually
 * failed — its self-verify/generic-failure safety net fired (recorded as
 * anything other than a clean `"routed"`, e.g. `"reverted"`, or a stall/hang
 * outcome — heygen-com/hyperframes#3441) — or that the render-count backstop
 * (`DE_PARALLEL_ROUTER_TRIAL_MAX_RENDERS`) was reached, so it's never
 * enabled again for this install. A clean "routed" (the render succeeded
 * with no fallback) does NOT consume the trial by itself — the whole point
 * is to keep trying on every eligible render until we see a real failure
 * signal (bounded by the render cap), maximizing successful-routing
 * telemetry volume rather than stopping at the first data point. Checks
 * both the success path (`perfSummary`) and the failure path
 * (`errorDetails.observability.capture`, mutated in place before a hard
 * failure throws) — a render that still failed even after the fallback
 * retry counts too. A render that crashed for an unrelated reason while
 * merely "routed" (never reached "reverted" — e.g. cancellation) does NOT
 * count as a router failure and does not turn the trial off. No-ops if the
 * router never became eligible for this render (e.g. too few frames): the
 * trial stays available for a future run either way, uncounted.
 *
 * Cross-process race semantics (no file locking exists here): the render
 * COUNTER is written exactly once, unverified — a lost increment under a
 * concurrent-writer race just under-counts the exposure cap by one
 * (benign), whereas retrying it would double-count this render whenever our
 * write actually landed but another writer raced the verify read (trips the
 * cap early, killing the trial prematurely — review finding). The FIRED
 * flag is the safety-critical bit and IS verified/re-asserted — see
 * `persistDeParallelRouterTrialFired`.
 */
function maybeConsumeDeParallelRouterTrial(
  routerActive: boolean,
  job: RenderJob,
  quiet: boolean,
): void {
  if (!routerActive) return;
  const outcome = resolveDeParallelRouterOutcome(job);
  if (outcome === undefined) return;

  const config = readConfigFresh();
  const renderCount = (config.deParallelRouterTrialRenderCount ?? 0) + 1;
  config.deParallelRouterTrialRenderCount = renderCount;
  // Trip on any recorded non-success, not only the literal string
  // "reverted". The old trial also tripped at a 25-render exposure cap,
  // which was sampling logic: bound how long an experiment force-enables
  // itself. Under a shipped default that would switch the feature off
  // behind the user's back after 25 good renders — so a clean "routed" (no
  // fallback needed) must NOT trip. But narrowing the positive check to the
  // single string "reverted" (heygen-com/hyperframes#3441) meant any other
  // non-success signal the observability layer might ever record — a stall,
  // a timeout, a future outcome value — would silently fall through to "not
  // fired" instead of tripping. `outcome` is `undefined`-filtered above, so
  // by this point it is a real recorded outcome; the only one that means
  // "no fallback happened" is "routed" itself.
  const fired = outcome !== "routed";
  if (fired) {
    config.deParallelRouterTrialFired = true;
    // Latch BEFORE attempting persistence — the decision holds for this
    // process even if the disk write never sticks (unwritable config).
    deParallelRouterBreakerTrippedThisProcess = true;
    applyDeParallelRouterBreaker();
  }
  writeConfig(config);
  // Only announce a trip the breaker could actually act on. With an explicit
  // user opt-in the breaker is a no-op, so "now off for this install" would
  // be false — and would reprint on every subsequent revert, since the user's
  // value keeps the router active (review finding).
  if (fired && !deParallelRouterUserManaged) reportDeParallelRouterBreakerTrip(quiet);
}

/**
 * Tell the user the breaker tripped, and warn if the verdict couldn't be
 * persisted. All output is `!quiet`-gated: quiet/batch-json renders must
 * produce no unexpected terminal output — CI wrappers asserting empty stderr
 * would misread a warning as a render failure (review finding). The
 * in-process latch guarantees the safety behavior either way.
 */
function reportDeParallelRouterBreakerTrip(quiet: boolean): void {
  const persisted = persistDeParallelRouterTrialFired();
  if (quiet) return;
  console.log(
    c.dim(
      "  A frame failed verification, so parallel drawElement capture fell back to the " +
        "screenshot path and is now off for this install. Re-enable: " +
        "HF_DE_PARALLEL_ROUTER=true",
    ),
  );
  if (persisted) return;
  console.warn(
    c.warn(
      "  Could not persist the parallel drawElement circuit breaker to " +
        "~/.hyperframes/config.json (unwritable?). It stays off for this process; " +
        "future runs may retry it. Set HF_DE_PARALLEL_ROUTER=false to opt out for good.",
    ),
  );
}

/**
 * `job.currentStage`/`failedStage` are free-text progress labels
 * (`updateJobStatus`'s callers each pass their own human sentence — "Compiling
 * composition", "Extracting video frames", …), which makes an exact string
 * property unbounded in a telemetry event. This maps the known set to a
 * stable snake_case code, and slugifies anything unrecognized instead of
 * bucketing it into a single opaque "unknown" — a future stage string still
 * gets a distinct, readable code without needing this map updated first.
 */
const KNOWN_STAGE_CODES: Readonly<Record<string, string>> = {
  Queued: "queued",
  "Compiling composition": "compiling_composition",
  "Extracting video frames": "extracting_video_frames",
  "Processing audio tracks": "processing_audio_tracks",
  "Starting frame capture": "starting_frame_capture",
  "Render complete": "render_complete",
  "Render cancelled": "render_cancelled",
  pipeline: "pipeline",
  "Starting browsers": "starting_browsers",
  // Was "Encoding video" before encode reported frames; keeps the same bucket.
  "Encoding frame": "encoding_video",
};

// Live counts in a progress label ("Capturing frame 120/600 (6 workers)") would make a code per render.
const STAGE_COUNTS = /\([^)]*\)|\d+\/\d+/g;

export function normalizeStageCode(stage: string): string {
  const base = stage.replace(STAGE_COUNTS, "").trim();
  const known = KNOWN_STAGE_CODES[base];
  if (known) return known;
  const slug = base
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "_")
    .replace(/^_+|_+$/g, "");
  return slug || "unknown";
}

function handleRenderError(
  error: unknown,
  options: RenderOptions,
  startTime: number,
  cpu: RenderCpuSampler,
  docker: boolean,
  hint: string,
  failedStage?: string,
  job?: RenderJob,
): never {
  const message = normalizeErrorMessage(error);
  renderFailureDiagnostic(job, error, options.quiet);
  trackRenderError({
    fps: fpsToNumber(options.fps),
    quality: options.quality,
    docker,
    workers: options.workers,
    gpu: options.gpu,
    authoringSkill: options.authoringSkill,
    authoringSkillSource: options.authoringSkillSource,
    authoringSkillInvalid: options.authoringSkillInvalid,
    hfEnvOverrides: options.hfEnvOverrides,
    elapsedMs: Date.now() - startTime,
    errorMessage: message,
    failedStage,
    ...renderOutputShapeTelemetryPayload(options),
    ...renderEnvironmentTelemetryPayload(options),
    // A bucketable failure taxonomy alongside the free-text error_message
    // above: error.name is one of ~20 typed producer error classes
    // (CaptureFailure, DrawElementCaptureError, SwiftShaderAssertionError, …);
    // failed_stage_code is the same job.currentStage value normalized to a
    // stable code. Error-conditional by nature — there is no equivalent on
    // the render_complete success path, since nothing failed to name.
    errorName: error instanceof Error ? error.name : "unknown",
    failedStageCode: normalizeStageCode(failedStage || "pipeline"),
    ...renderJobObservabilityTelemetryPayload(job),
    ...getMemorySnapshot(),
    ...cpu.stop(),
  });
  // Failed renders join the recent-renders ring too — a bug report filed via
  // `hyperframes feedback` is MOST likely to be about a failed render.
  if (job?.id) recordRecentRender(job.id, false);
  if (options.throwOnError) {
    throw new Error(message);
  }
  // A `Failed to launch the browser process` / `libnss3.so cannot open ...`
  // failure on Linux/WSL is an environment problem, not a composition bug.
  // Replace the generic "Try --docker" hint with the exact per-distro
  // remediation and a pointer at `doctor`.
  const sandboxRemediation = sandboxDeniedRemediation(message);
  if (sandboxRemediation) {
    errorBox("Render failed — Chrome could not launch", message, sandboxRemediation);
    failCommand();
  }
  const remediation = chromeLaunchRemediation(message);
  if (remediation) {
    errorBox("Render failed — Chrome could not launch", message, remediation);
    failCommand();
  }
  // macOS <13 dyld Symbol-not-found on the pinned chrome-headless-shell
  // build. Different remediation shape (older shell + env-var override)
  // than the Linux shared-lib install, so it lives in its own detector.
  const macosRemediation = macosOldChromeCrashRemediation(message);
  if (macosRemediation) {
    errorBox("Render failed — Chrome could not launch", message, macosRemediation);
    failCommand();
  }
  // Windows chrome-headless-shell can crash at launch with
  // STATUS_STACK_BUFFER_OVERRUN (exit 0xC0000409 / 3221225595). Same
  // HYPERFRAMES_BROWSER_PATH remediation as the download-time hint (#2443)
  // and the closed-with-invite arm64 macOS sibling (#2078). Field feedback
  // ts=1784116246.
  const windowsRemediation = windowsChromeCrashRemediation(message);
  if (windowsRemediation) {
    errorBox(
      "Render failed — chrome-headless-shell crashed at launch",
      message,
      windowsRemediation,
    );
    failCommand();
  }
  errorBox("Render failed", message, hint);
  failCommand();
}

/**
 * Extract rich metrics from the completed render job and send to telemetry.
 * speed_ratio = composition_duration / render_time — higher is better, >1 means faster than realtime.
 */
// Inherited CRITICAL (CRAP 148.4, cyclomatic 24): exhaustive nullish-fallback
// chain across 30+ telemetry fields. Not touched by this PR.
// fallow-ignore-next-line complexity
function trackRenderMetrics(
  job: RenderJob,
  elapsedMs: number,
  options: RenderOptions,
  docker: boolean,
  cpuUsage: RenderCpuTelemetryPayload,
): void {
  // Successful render → recent-renders ring, so a later `hyperframes
  // feedback` can attach this render's telemetry id to the report.
  recordRecentRender(job.id, true);
  const perf = job.perfSummary;
  const compositionDurationMs = perf
    ? Math.round(perf.compositionDurationSeconds * 1000)
    : undefined;
  const speedRatio =
    compositionDurationMs && compositionDurationMs > 0 && elapsedMs > 0
      ? Math.round((compositionDurationMs / elapsedMs) * 100) / 100
      : undefined;

  const stages = perf?.stages ?? {};
  const extract = perf?.videoExtractBreakdown;

  trackRenderComplete({
    durationMs: elapsedMs,
    fps: fpsToNumber(options.fps),
    quality: options.quality,
    workers: options.workers ?? perf?.workers,
    workersBoundBy: perf?.workerSizing?.boundBy,
    workersCpuBased: perf?.workerSizing?.cpuBasedWorkers,
    workersMemoryBased: perf?.workerSizing?.memoryBasedWorkers,
    workersHeapBased: perf?.workerSizing?.heapBasedWorkers,
    workersFrameBased: perf?.workerSizing?.frameBasedWorkers,
    workersHeapLimitMb: perf?.workerSizing?.heapLimitMb,
    workersExceedHeapAdvisory: perf?.workerSizing?.exceedsHeapAdvisory,
    docker,
    gpu: options.gpu,
    authoringSkill: options.authoringSkill,
    authoringSkillSource: options.authoringSkillSource,
    authoringSkillInvalid: options.authoringSkillInvalid,
    hfEnvOverrides: options.hfEnvOverrides,
    catalogUsage: options.catalogUsage,
    ...renderOutputShapeTelemetryPayload(options),
    ...renderEnvironmentTelemetryPayload(options),
    chromeBrowserRssPeakMb: perf?.chromeMemory?.browserRssPeakMb,
    chromeRendererRssPeakMb: perf?.chromeMemory?.rendererRssPeakMb,
    chromeRssLastMb: perf?.chromeMemory?.rssLastMb,
    chromeGpuProcessSeenLastSample: perf?.chromeMemory?.gpuProcessSeenLastSample,
    chromeMemorySamples: perf?.chromeMemory?.samples,
    staticDedupEnabled: perf?.staticDedup?.enabled,
    staticDedupArmed: perf?.staticDedup?.armed,
    staticDedupSkipReason: perf?.staticDedup?.skipReason,
    staticDedupPredictedFrames: perf?.staticDedup?.predictedFrames,
    staticDedupReusedFrames: perf?.staticDedup?.reusedFrames,
    beginFrameNoDamageFrames: perf?.beginFrameReuse?.noDamageFrames,
    beginFrameHasDamageFrames: perf?.beginFrameReuse?.hasDamageFrames,
    deCaptureMode: perf?.drawElement?.mode,
    vfxHostCount: perf?.drawElement?.vfxHostCount,
    vfxCapture: perf?.drawElement?.vfxCapture,
    vfxTypes: perf?.drawElement?.vfxTypes,
    deCompileGate: perf?.drawElement?.compileGate,
    deClampReason: perf?.drawElement?.clampReason,
    deWorkerInversion: perf?.drawElement?.workerInversion,
    dePreInversionWorkers: perf?.drawElement?.preInversionWorkers,
    compositionElementCount: perf?.drawElement?.compositionElementCount,
    compositionElementCountSource: perf?.drawElement?.compositionElementCountSource,
    compositionElementTags: perf?.drawElement?.compositionElementTags,
    arollVideoCount: perf?.drawElement?.arollVideoCount,
    heygenVideoCount: perf?.drawElement?.heygenVideoCount,
    adaptersUsed: perf?.drawElement?.adaptersUsed,
    audioCount: perf?.drawElement?.audioCount,
    imageCount: perf?.drawElement?.imageCount,
    subCompositionCount: perf?.drawElement?.subCompositionCount,
    audioGroupCount: perf?.drawElement?.audioGroupCount,
    colorGradingCount: perf?.drawElement?.colorGradingCount,
    hasLut: perf?.drawElement?.hasLut,
    rootBodyMismatch: perf?.drawElement?.rootBodyMismatch,
    rootBodyDeltaPxBucket: perf?.drawElement?.rootBodyDeltaPxBucket,
    deShortBand: perf?.drawElement?.shortBand,
    deParallelRouter: perf?.drawElement?.parallelRouter,
    dePreRouterWorkers: perf?.drawElement?.preRouterWorkers,
    deGateReason: perf?.drawElement?.gateReason,
    gpuRenderer: perf?.drawElement?.gpuRenderer,
    deWorkerEncode: perf?.drawElement?.workerEncode,
    deVerifyArmed: perf?.drawElement?.verifyArmed,
    deVerifyChecked: perf?.drawElement?.verifyChecked,
    deVerifyMinDb: perf?.drawElement?.verifyMinDb,
    deVerifyInitMs: perf?.drawElement?.verifyInitMs,
    deSelfVerifyFallback: perf?.drawElement?.selfVerifyFallback,
    deFallbackReason: perf?.drawElement?.fallbackReason,
    deFallbackFailedDb: perf?.drawElement?.fallbackFailedDb,
    deFallbackFrameIndex: perf?.drawElement?.fallbackFrameIndex,
    deFallbackThresholdDb: perf?.drawElement?.fallbackThresholdDb,
    deBlankSuspects: perf?.drawElement?.blankSuspects,
    deBlankDeterministicAccepts: perf?.drawElement?.blankDeterministicAccepts,
    deBlankRecaptures: perf?.drawElement?.blankRecaptures,
    deBoundaryFrames: perf?.drawElement?.boundaryFrames,
    deNcprFallbacks: perf?.drawElement?.ncprFallbacks,
    deFrameTimeouts: perf?.drawElement?.frameTimeouts,
    compositionDurationMs,
    compositionWidth: perf?.resolution.width,
    compositionHeight: perf?.resolution.height,
    totalFrames: perf?.totalFrames,
    speedRatio,
    captureAvgMs: perf?.captureAvgMs,
    captureP50Ms: perf?.captureP50Ms,
    subTimelineWait: perf?.subTimelineWait,
    videoCount: perf?.videoCount,
    capturePeakMs: perf?.capturePeakMs,
    tmpPeakBytes: perf?.tmpPeakBytes,
    stageCompileMs: stages.compileMs,
    stageVideoExtractMs: stages.videoExtractMs,
    stageAudioProcessMs: stages.audioProcessMs,
    stageCaptureMs: stages.captureMs,
    stageCaptureSetupMs: stages.captureSetupMs,
    stageCaptureFrameMs: stages.captureFrameMs,
    stageEncodeMs: stages.encodeMs,
    stageAssembleMs: stages.assembleMs,
    extractResolveMs: extract?.resolveMs,
    extractHdrProbeMs: extract?.hdrProbeMs,
    extractHdrPreflightMs: extract?.hdrPreflightMs,
    extractHdrPreflightCount: extract?.hdrPreflightCount,
    extractVfrProbeMs: extract?.vfrProbeMs,
    extractVfrPreflightMs: extract?.vfrPreflightMs,
    extractVfrPreflightCount: extract?.vfrPreflightCount,
    extractPhase3Ms: extract?.extractMs,
    extractCacheHits: extract?.cacheHits,
    extractCacheMisses: extract?.cacheMisses,
    ...renderJobObservabilityTelemetryPayload(job),
    ...getMemorySnapshot(),
    ...cpuUsage,
  });
}

function readOutputFootprint(outputPath: string): { fileSize: string; isDirectory: boolean } {
  try {
    const stat = statSync(outputPath);
    if (!stat.isDirectory()) return { fileSize: formatBytes(stat.size), isDirectory: false };
    // png-sequence and hls write a directory; sum contained file sizes so the
    // user sees the deliverable footprint, not the directory inode size.
    let total = 0;
    for (const entry of readdirSync(outputPath, { withFileTypes: true })) {
      if (!entry.isFile()) continue;
      try {
        total += statSync(join(outputPath, entry.name)).size;
      } catch {
        // skip unreadable entries
      }
    }
    return { fileSize: formatBytes(total), isDirectory: true };
  } catch {
    return { fileSize: "unknown", isDirectory: false };
  }
}

/** A render points to the desktop app; a batch row does not. Drafts do too. */
export function wantsDesktopHint(options: Pick<RenderOptions, "desktopHint">): boolean {
  return options.desktopHint !== false;
}

function printRenderComplete(input: {
  outputPath: string;
  projectDir: string;
  /** Print the desktop-app line: a delivered render, never a draft or a batch row. */
  desktopHint: boolean;
  elapsedMs: number;
  quiet: boolean;
  format: RenderFormat;
  perf?: RenderPerfSummary;
  requestedGpuMode?: "auto" | "hardware" | "software";
}): void {
  if (input.quiet) return;
  const { outputPath, elapsedMs, perf } = input;
  const { fileSize, isDirectory } = readOutputFootprint(outputPath);
  const detail = formatRenderSummaryDetail({
    elapsedMs,
    outputDurationSeconds: perf?.compositionDurationSeconds,
    isDirectory,
    frameCount: perf?.totalFrames,
    playlistDirectory: input.format === "hls",
  });
  console.log("");
  console.log(c.success("\u25C7") + "  " + c.accent(outputPath));
  console.log("   " + c.bold(fileSize) + c.dim(" \u00B7 " + detail));
  if (perf) printRenderPipeline(perf, input.requestedGpuMode);
  const hint = input.desktopHint ? desktopHint(input.projectDir) : null;
  if (hint) console.log("   " + c.dim(hint));
}

function printRenderPipeline(
  perf: RenderPerfSummary,
  requestedGpuMode?: "auto" | "hardware" | "software",
): void {
  // aggregateDrawElement reports "unknown" when no session recorded a mode.
  const capture = {
    captureMode: resolvePrintedCaptureMode(
      perf.drawElement?.mode,
      perf.observability?.capture.captureMode,
    ),
    browserGpuMode: perf.observability?.capture.browserGpuMode,
  };
  const pipeline = formatRenderPipelineDetail({
    ...capture,
    streamingEncode: perf.observability?.capture.useStreamingEncode,
    stages: perf.stages,
  });
  if (pipeline) console.log("   " + c.dim(pipeline));
  const hint = formatScreenshotFallbackHint({
    ...capture,
    requestedGpuMode,
    platform: process.platform,
  });
  if (hint) console.log("   " + c.dim(hint));
}