Skip to content

Write HTML. Render video. Built for agents.

82.8 KB
Raw Blame
// fallow-ignore-file code-duplication
import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { spawn } from "node:child_process";

const producerState = vi.hoisted(() => ({
  createdJobs: [] as Array<Record<string, unknown>>,
  resolveConfigCalls: [] as Array<Record<string, unknown>>,
  loggerLevels: [] as string[],
  // Overridable per-test hook so the DE-parallel-router-trial tests can
  // mutate the job (perfSummary/errorDetails) or throw, without perturbing
  // every other test in this file that expects a plain no-op resolve.
  executeImpl: async (
    _job: Record<string, unknown>,
    _abortSignal?: AbortSignal,
    _assertRenderActive?: () => void,
  ): Promise<void> => undefined,
}));

// Defaults to "trial already fired" so the pre-existing renderLocal tests
// below (which predate the DE-parallel-router trial and don't expect
// HF_DE_PARALLEL_ROUTER to be touched) keep their exact prior behavior.
//
// `disk` is the authoritative "file"; `cache` models config.ts's real
// process-lifetime cachedConfig. Modeling them SEPARATELY matters: a mock
// where readConfig/readConfigFresh both read one live object hides exactly
// the class of bug where production code reads the stale cache when it
// needed a fresh disk read (review finding). `failWrites` simulates the
// real writeConfig's silent fs-error swallowing (unwritable ~/.hyperframes):
// the next N writes are recorded but never reach `disk`.
const configState = vi.hoisted(
  (): {
    disk: Record<string, unknown>;
    cache: Record<string, unknown> | null;
    writeConfigCalls: Array<Record<string, unknown>>;
    failWrites: number;
    /** Config write lands but the install-state mirror does not. */
    failMirrors: number;
  } => ({
    disk: { telemetryEnabled: true, deParallelRouterTrialFired: true },
    cache: null,
    writeConfigCalls: [],
    failWrites: 0,
    failMirrors: 0,
  }),
);

const trackingState = vi.hoisted(() => ({
  // maybeEnableDeParallelRouterTrial gates on the real shouldTrack(), which
  // (via isDevMode()) always returns false when this file itself runs as
  // `.ts` source under vitest — mocked here so the CLI-trial tests can
  // control it directly instead of inheriting that environment quirk.
  shouldTrack: true,
  renderObservations: [] as Array<Record<string, unknown>>,
}));

const preflightState = vi.hoisted(() => ({
  onRun: undefined as (() => void) | undefined,
  result: {
    outcomes: [
      { name: "FFmpeg", ok: true, level: "ok", detail: "/usr/bin/ffmpeg", path: "/usr/bin/ffmpeg" },
      {
        name: "FFprobe",
        ok: true,
        level: "ok",
        detail: "/usr/bin/ffprobe",
        path: "/usr/bin/ffprobe",
      },
      {
        name: "Chrome",
        ok: true,
        level: "ok",
        detail: "cache: /mock/chrome",
        path: "/mock/chrome",
      },
    ],
    ffmpegPath: "/usr/bin/ffmpeg",
    ffprobePath: "/usr/bin/ffprobe",
    browser: { executablePath: "/mock/chrome", source: "cache" },
  },
}));

const ffmpegEncoderState = vi.hoisted(() => ({
  mode: "software" as "software" | "gpu",
  error: null as Error | null,
  encoders: null as string | null,
  usableGpu: false,
}));
const orphanCleanupState = vi.hoisted(() => ({
  calls: 0,
  killed: 0,
  parentPid: (_pid: number): number | null => null,
  identity: (_pid: number): string | null => null,
}));
const browserManagerState = vi.hoisted(() => ({
  onEnsure: undefined as ((signal?: AbortSignal) => Promise<void> | void) | undefined,
}));

vi.mock("../utils/producer.js", () => ({
  loadProducer: vi.fn(async () => ({
    createConsoleLogger: vi.fn((level: string) => {
      producerState.loggerLevels.push(level);
      return { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() };
    }),
    resolveConfig: vi.fn((overrides: Record<string, unknown>) => {
      producerState.resolveConfigCalls.push(overrides);
      return { ...overrides, resolved: true };
    }),
    createRenderRequest: vi.fn(
      (input: {
        projectDir: string;
        outputPath: string;
        engineConfig: unknown;
        options: object;
      }) => ({
        version: 1,
        projectDir: input.projectDir,
        outputPath: input.outputPath,
        options: { ...input.options, engineConfig: input.engineConfig },
      }),
    ),
    renderConfigFromRequest: vi.fn(
      (request: { options: Record<string, unknown> }, runtime: { logger?: unknown }) => {
        const { engineConfig, ...options } = request.options;
        return { ...options, producerConfig: engineConfig, logger: runtime.logger };
      },
    ),
    createRenderJob: vi.fn((config: Record<string, unknown>) => {
      producerState.createdJobs.push(config);
      return { config, progress: 100, outcome: "completed", warnings: [] };
    }),
    executeRenderJob: vi.fn(
      async (
        job: Record<string, unknown>,
        _projectDir: string,
        _outputPath: string,
        _onProgress: unknown,
        abortSignal?: AbortSignal,
        assertRenderActive?: () => void,
      ) => producerState.executeImpl(job, abortSignal, assertRenderActive),
    ),
  })),
}));

vi.mock("../telemetry/config.js", () => ({
  readConfig: vi.fn(() => {
    if (!configState.cache) configState.cache = { ...configState.disk };
    return { ...configState.cache };
  }),
  readConfigFresh: vi.fn(() => {
    configState.cache = { ...configState.disk };
    return { ...configState.disk };
  }),
  recordRecentRender: vi.fn((id: string, ok: boolean) => {
    // Mirrors the real ring update (readConfigFresh → append, cap 5 → write)
    // against the mock's disk state, so a render's recent-renders write is
    // modeled like every other config mutation here. Fixed timestamp keeps it
    // deterministic (tests never assert on `at`).
    const disk = configState.disk as Record<string, unknown>;
    const ring = [
      ...((disk.recentRenders as unknown[]) ?? []),
      { id, at: "2026-01-01T00:00:00Z", ok },
    ];
    const next = { ...disk, recentRenders: ring.slice(-5) };
    configState.disk = next;
    configState.cache = { ...next };
  }),
  writeConfig: vi.fn((config: Record<string, unknown>) => {
    configState.writeConfigCalls.push({ ...config });
    if (configState.failWrites > 0) {
      configState.failWrites--;
      return false; // swallowed silently, like the real writeConfig's catch {}
    }
    configState.disk = { ...config };
    configState.cache = { ...config };
    return true;
  }),
  // The breaker's safety path uses this rather than writeConfig, so it can
  // see a mirror failure instead of having it collapsed into `true`.
  writeConfigWithResult: vi.fn((config: Record<string, unknown>) => {
    configState.writeConfigCalls.push({ ...config });
    if (configState.failWrites > 0) {
      configState.failWrites--;
      return { ok: false, error: "mock write failure" };
    }
    configState.disk = { ...config };
    configState.cache = { ...config };
    if (configState.failMirrors > 0) {
      configState.failMirrors--;
      return { ok: true, mirrored: false };
    }
    return { ok: true };
  }),
}));

vi.mock("../telemetry/client.js", () => ({
  shouldTrack: vi.fn(() => trackingState.shouldTrack),
}));

vi.mock("../telemetry/events.js", () => ({
  trackRenderComplete: vi.fn(),
  trackRenderError: vi.fn(),
  trackRenderObservation: vi.fn((props: Record<string, unknown>) => {
    trackingState.renderObservations.push(props);
  }),
}));

vi.mock("../browser/ffmpeg.js", async (importOriginal) => {
  const actual = await importOriginal<typeof import("../browser/ffmpeg.js")>();
  return {
    ...actual,
    detectH264EncoderModeForRender: vi.fn(async (_path: string, gpuRequested: boolean) => {
      if (ffmpegEncoderState.error) throw ffmpegEncoderState.error;
      if (ffmpegEncoderState.encoders !== null)
        return actual.resolveH264EncoderMode(
          ffmpegEncoderState.encoders,
          gpuRequested,
          ffmpegEncoderState.usableGpu,
        );
      return ffmpegEncoderState.mode;
    }),
    findFFmpeg: vi.fn(() => "/usr/bin/ffmpeg"),
    getFFmpegInstallHint: vi.fn(() => "brew install ffmpeg"),
  };
});

vi.mock("../browser/preflight.js", () => ({
  checkDisk: vi.fn(() => ({ name: "Disk", ok: true, level: "ok", detail: "mock" })),
  runEnvironmentChecks: vi.fn(async () => {
    preflightState.onRun?.();
    return preflightState.result;
  }),
}));

// The "render command explicit composition" test below drives the real
// `render.js` command handler, which takes the plan-based `execute.ts` path
// (not the `renderLocal` unit under test above) — that path calls
// `ensureBrowser` directly instead of going through the mocked preflight.
// Unmocked, it performs a real network download of chrome-headless-shell into
// the shared `~/.cache/hyperframes/chrome`, racing other packages' browser
// tests in CI.
vi.mock("../browser/manager.js", () => ({
  sweepKilledInstalls: vi.fn(async () => {}),
  ensureBrowser: vi.fn(async (options?: { signal?: AbortSignal }) => {
    await browserManagerState.onEnsure?.(options?.signal);
    return { executablePath: "/mock/chrome", source: "cache" };
  }),
}));

vi.mock("../utils/orphanCleanup.js", () => ({
  killOrphanedProcesses: vi.fn(() => {
    orphanCleanupState.calls += 1;
    return orphanCleanupState.killed;
  }),
  killOrphanedProcessesForRender: vi.fn(async () => {
    orphanCleanupState.calls += 1;
    return orphanCleanupState.killed;
  }),
  processIdentity: vi.fn((pid: number) => orphanCleanupState.identity(pid)),
  processAncestorSnapshot: vi.fn((pid: number) => {
    const parent = orphanCleanupState.parentPid(pid);
    if (parent === null) return [];
    const identity = orphanCleanupState.identity(parent);
    return identity === null ? [] : [{ pid: parent, identity }];
  }),
  processParentPid: vi.fn((pid: number) => orphanCleanupState.parentPid(pid)),
}));

const cpuSamplerState = vi.hoisted(() => ({
  samplers: [] as { requesterOptedIn: boolean; stopped: boolean }[],
}));
vi.mock("../telemetry/renderCpu.js", () => ({
  startRenderCpuSampler: (requesterOptedIn = true) => {
    const sampler = { requesterOptedIn, stopped: false };
    cpuSamplerState.samplers.push(sampler);
    return {
      stop: () => {
        sampler.stopped = true;
        return { cpuBusyAvgPct: 57, cpuBusyPeakPct: 90 };
      },
    };
  },
}));

// Collect the heavy render module once, after Vitest has hoisted the mocks
// above. Keeping this import out of a hook means parallel monorepo contention
// cannot turn module collection into a `beforeAll` timeout.
const renderModule = await import("./render.js");

// A private folder, never a fixed /tmp path: a render writes history into its project.
const PROJECT_DIR = mkdtempSync(join(tmpdir(), "hf-render-project-"));
afterAll(() => rmSync(PROJECT_DIR, { recursive: true, force: true }));

describe("renderLocal browser GPU config", () => {
  const savedEnv = new Map<string, string | undefined>();
  const {
    renderLocal,
    resolveBrowserGpuForCli,
    renderLintContinuationHint,
    runRenderLint,
    __resetDeParallelRouterTrialStateForTests: resetTrialState,
  } = renderModule;

  it("points strict warning-only renders to --strict-all", () => {
    expect(renderLintContinuationHint(true)).toContain("--strict-all");
    expect(renderLintContinuationHint(true)).not.toContain("Use --strict to block");
  });

  it("points non-strict renders to --strict for lint errors", () => {
    expect(renderLintContinuationHint(false)).toContain("Use --strict to block errors");
  });

  it("aborts the real render lint preflight on a default-entry mismatch without --strict", async () => {
    const lintResult = {
      results: [
        {
          file: "index.html",
          contentHash: "abc",
          result: {
            ok: false,
            errorCount: 1,
            warningCount: 0,
            infoCount: 0,
            findings: [
              {
                code: "blank_root_with_standalone_composition",
                severity: "error" as const,
                message: "wrong entry",
              },
            ],
          },
        },
      ],
      totalErrors: 1,
      totalWarnings: 0,
      totalInfos: 0,
    };

    await expect(
      runRenderLint(
        {
          project: { dir: PROJECT_DIR },
          entryFile: undefined,
          renderTarget: join(PROJECT_DIR, "index.html"),
          strictErrors: false,
          strictAll: false,
          effectiveQuiet: true,
        } as never,
        async () => lintResult,
      ),
    ).rejects.toMatchObject({ name: "CliRuntimeError" });
  });

  it("prints the full finding on a default-entry-mismatch abort even without --lint-verbose", async () => {
    const lintResult = {
      results: [
        {
          file: "index.html",
          contentHash: "abc",
          result: {
            ok: false,
            errorCount: 1,
            warningCount: 0,
            infoCount: 0,
            findings: [
              {
                code: "blank_root_with_standalone_composition",
                severity: "error" as const,
                message: "The default index.html composition has no renderable content",
                fixHint: "Move the authored composition into index.html",
              },
            ],
          },
        },
      ],
      totalErrors: 1,
      totalWarnings: 0,
      totalInfos: 0,
    };
    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});

    await expect(
      runRenderLint(
        {
          project: { dir: PROJECT_DIR },
          entryFile: undefined,
          renderTarget: join(PROJECT_DIR, "index.html"),
          strictErrors: false,
          strictAll: false,
          effectiveQuiet: false,
          lintVerbose: false,
        } as never,
        async () => lintResult,
      ),
    ).rejects.toMatchObject({ name: "CliRuntimeError" });

    const output = logSpy.mock.calls.map((c) => c[0]).join("\n");
    expect(output).toContain("blank_root_with_standalone_composition");
    expect(output).toContain("The default index.html composition has no renderable content");
    logSpy.mockRestore();
  });

  it("prints a one-line summary by default, and full findings when lintVerbose is set", async () => {
    const lintResult = {
      results: [
        {
          file: "index.html",
          contentHash: "abc",
          result: {
            ok: true,
            errorCount: 0,
            warningCount: 1,
            infoCount: 0,
            findings: [
              { code: "some_warning", severity: "warning" as const, message: "a warning" },
            ],
          },
        },
      ],
      totalErrors: 0,
      totalWarnings: 1,
      totalInfos: 0,
    };
    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});

    await runRenderLint(
      {
        project: { dir: PROJECT_DIR },
        entryFile: undefined,
        renderTarget: join(PROJECT_DIR, "index.html"),
        strictErrors: false,
        strictAll: false,
        effectiveQuiet: false,
        lintVerbose: false,
      } as never,
      async () => lintResult,
    );
    const summaryOutput = logSpy.mock.calls.map((c) => c[0]).join("\n");
    expect(summaryOutput).toContain("1 warning(s)");
    expect(summaryOutput).not.toContain("some_warning");

    logSpy.mockClear();
    await runRenderLint(
      {
        project: { dir: PROJECT_DIR },
        entryFile: undefined,
        renderTarget: join(PROJECT_DIR, "index.html"),
        strictErrors: false,
        strictAll: false,
        effectiveQuiet: false,
        lintVerbose: true,
      } as never,
      async () => lintResult,
    );
    const verboseOutput = logSpy.mock.calls.map((c) => c[0]).join("\n");
    expect(verboseOutput).toContain("some_warning");

    logSpy.mockRestore();
  });

  function setEnv(key: string, value: string) {
    if (!savedEnv.has(key)) savedEnv.set(key, process.env[key]);
    process.env[key] = value;
  }

  beforeEach(() => {
    producerState.createdJobs = [];
    producerState.resolveConfigCalls = [];
    producerState.loggerLevels = [];
    producerState.executeImpl = async () => undefined;
    preflightState.onRun = undefined;
    configState.disk = { telemetryEnabled: true, deParallelRouterTrialFired: true };
    configState.cache = null;
    configState.failWrites = 0;
    configState.failMirrors = 0;
    configState.writeConfigCalls = [];
    trackingState.shouldTrack = true;
    trackingState.renderObservations = [];
    ffmpegEncoderState.mode = "software";
    ffmpegEncoderState.error = null;
    ffmpegEncoderState.encoders = null;
    ffmpegEncoderState.usableGpu = false;
    orphanCleanupState.calls = 0;
    orphanCleanupState.killed = 0;
    orphanCleanupState.parentPid = () => null;
    orphanCleanupState.identity = () => null;
    browserManagerState.onEnsure = undefined;
    resetTrialState();
    savedEnv.clear();
    savedEnv.set("HYPERFRAMES_FFMPEG_PATH", process.env.HYPERFRAMES_FFMPEG_PATH);
    savedEnv.set("HYPERFRAMES_FFPROBE_PATH", process.env.HYPERFRAMES_FFPROBE_PATH);
    savedEnv.set("PRODUCER_HEADLESS_SHELL_PATH", process.env.PRODUCER_HEADLESS_SHELL_PATH);
    savedEnv.set("HF_DE_PARALLEL_ROUTER", process.env.HF_DE_PARALLEL_ROUTER);
    delete process.env.HYPERFRAMES_FFMPEG_PATH;
    delete process.env.HYPERFRAMES_FFPROBE_PATH;
    delete process.env.PRODUCER_HEADLESS_SHELL_PATH;
    delete process.env.HF_DE_PARALLEL_ROUTER;
  });

  it("reports the render's CPU use on render_complete and render_error and stops measuring", async () => {
    const { trackRenderComplete, trackRenderError } = await import("../telemetry/events.js");
    vi.mocked(trackRenderComplete).mockClear();
    vi.mocked(trackRenderError).mockClear();
    cpuSamplerState.samplers = [];
    const options = {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      throwOnError: true,
    } as const;

    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", options);
    producerState.executeImpl = async () => {
      throw new Error("capture failed");
    };
    await expect(renderLocal(PROJECT_DIR, "/tmp/out.mp4", options)).rejects.toThrow(
      "capture failed",
    );

    const cpu = { cpuBusyAvgPct: 57, cpuBusyPeakPct: 90 };
    expect(vi.mocked(trackRenderComplete).mock.calls[0]?.[0]).toMatchObject(cpu);
    expect(vi.mocked(trackRenderError).mock.calls[0]?.[0]).toMatchObject(cpu);
    expect(cpuSamplerState.samplers.map((s) => s.stopped)).toEqual([true, true]);
  });

  it("cleans orphaned browser trees before starting a local render", async () => {
    orphanCleanupState.killed = 1;

    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(orphanCleanupState.calls).toBe(1);
  });

  it("owns cancellation before preflight so an early wrapper loss cannot start rendering", async () => {
    const priorListeners = new Set(process.listeners("SIGTERM"));
    let rendererStarted = false;
    preflightState.onRun = () => {
      const cancellationListener = process
        .listeners("SIGTERM")
        .find((listener) => !priorListeners.has(listener));
      expect(cancellationListener).toBeDefined();
      cancellationListener?.("SIGTERM");
    };
    producerState.executeImpl = async (_job, abortSignal) => {
      if (!abortSignal?.aborted) rendererStarted = true;
      throw abortSignal?.reason;
    };

    await expect(
      renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
        fps: { num: 30, den: 1 },
        quality: "standard",
        format: "mp4",
        gpu: false,
        browserGpuMode: "software",
        hdrMode: "auto",
        quiet: true,
        throwOnError: true,
      }),
    ).rejects.toThrow("render_cancelled_by_sigterm");

    expect(rendererStarted).toBe(false);
    expect(
      process.listeners("SIGTERM").filter((listener) => !priorListeners.has(listener)),
    ).toEqual([]);
  });

  it.each(["SIGINT", "SIGTERM", "SIGHUP"] as const)(
    "wires %s to the producer AbortSignal and removes render-scoped listeners",
    async (signal) => {
      let markExecutionStarted!: () => void;
      const executionStarted = new Promise<void>((resolve) => {
        markExecutionStarted = resolve;
      });
      let producerSignal: AbortSignal | undefined;
      producerState.executeImpl = async (_job, abortSignal) => {
        producerSignal = abortSignal;
        markExecutionStarted();
        await new Promise<void>((_resolve, reject) => {
          abortSignal?.addEventListener("abort", () => reject(abortSignal.reason), { once: true });
        });
      };
      const priorListeners = new Set(process.listeners(signal));

      const render = renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
        fps: { num: 30, den: 1 },
        quality: "standard",
        format: "mp4",
        gpu: false,
        browserGpuMode: "software",
        hdrMode: "auto",
        quiet: true,
        throwOnError: true,
      });
      await executionStarted;

      const cancellationListener = process
        .listeners(signal)
        .find((listener) => !priorListeners.has(listener));
      expect(cancellationListener).toBeDefined();
      cancellationListener?.(signal);
      expect(process.listeners(signal)).toContain(cancellationListener);
      cancellationListener?.(signal);

      await expect(render).rejects.toThrow(`render_cancelled_by_${signal.toLowerCase()}`);
      expect(producerSignal).toBeInstanceOf(AbortSignal);
      expect(producerSignal?.aborted).toBe(true);
      expect(process.listeners(signal).filter((listener) => !priorListeners.has(listener))).toEqual(
        [],
      );
    },
  );

  it("checks ancestors again at producer artifact finalization", async () => {
    const controller = new AbortController();
    let parentExited = false;
    const cancellation = {
      signal: controller.signal,
      checkAncestors: vi.fn(() => {
        if (parentExited) controller.abort(new Error("render_cancelled_parent_exited"));
      }),
      dispose: vi.fn(),
    };
    producerState.executeImpl = async (_job, abortSignal, assertRenderActive) => {
      parentExited = true;
      assertRenderActive?.();
      abortSignal?.throwIfAborted();
    };

    await expect(
      renderLocal(
        PROJECT_DIR,
        "/tmp/out.mp4",
        {
          fps: { num: 30, den: 1 },
          quality: "standard",
          format: "mp4",
          gpu: false,
          browserGpuMode: "software",
          hdrMode: "auto",
          quiet: true,
          throwOnError: true,
        },
        cancellation,
      ),
    ).rejects.toThrow("render_cancelled_parent_exited");

    expect(cancellation.checkAncestors).toHaveBeenLastCalledWith();
  });

  afterEach(() => {
    for (const [key, value] of savedEnv) {
      if (value === undefined) {
        delete process.env[key];
      } else {
        process.env[key] = value;
      }
    }
    vi.clearAllMocks();
    vi.useRealTimers();
    vi.restoreAllMocks();
  });

  it.each([
    { quiet: false, interrupted: false, emits: true },
    { quiet: false, interrupted: true, emits: true },
    { quiet: true, interrupted: false, emits: false },
  ])("writes the failure diagnostic only for piped non-JSON output: %j", async (mode) => {
    const projectDir = mkdtempSync(join(tmpdir(), "hf-render-diagnostic-"));
    const failures = [
      {
        stage: "prepare",
        reason: "ffmpeg_failed",
        owner: "system",
        retryable: false,
        subprocess: { exitCode: 7, terminationReason: "exit" },
        detail: "private-detail",
        elementId: "private-id",
      },
    ];
    producerState.executeImpl = async (job) => {
      if (mode.interrupted) throw Object.assign(new Error("failed"), { audioFailures: failures });
      job.warnings = [
        {
          code: "audio_processing_failed",
          message: "private-warning",
          details: { audioFailures: failures },
        },
      ];
      throw new Error("failed");
    };
    const originalIsTTY = process.stdout.isTTY;
    Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
    let output = "";
    vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
      output += String(chunk);
      return true;
    });
    try {
      await expect(
        renderLocal(projectDir, join(projectDir, "out.mp4"), {
          fps: { num: 30, den: 1 },
          quality: "standard",
          format: "mp4",
          gpu: false,
          browserGpuMode: "software",
          hdrMode: "auto",
          quiet: mode.quiet,
          throwOnError: true,
        }),
      ).rejects.toThrow("failed");
      const lines = output.split("\n").filter((line) => line.startsWith("@hf-diagnostic "));
      expect(lines).toHaveLength(mode.emits ? 1 : 0);
      if (mode.emits) {
        expect(
          JSON.parse((lines[0] ?? "").slice("@hf-diagnostic ".length)).audioFailures[0].subprocess
            .exitCode,
        ).toBe(7);
        expect(lines[0] ?? "").not.toMatch(/private-/);
      }
    } finally {
      Object.defineProperty(process.stdout, "isTTY", { value: originalIsTTY, configurable: true });
      rmSync(projectDir, { recursive: true, force: true });
    }
  });

  it("logs only warnings and errors from the producer under --quiet", async () => {
    const options = {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
    } as const;
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: true });
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: false });
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: true, debug: true });

    expect(producerState.loggerLevels).toEqual(["warn", "info", "debug"]);
  });

  it("passes an explicit software override for --no-browser-gpu even when env requests hardware", async () => {
    setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware");

    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "software" });
    expect(producerState.createdJobs[0]?.producerConfig).toMatchObject({
      browserGpuMode: "software",
      resolved: true,
    });
  }, 15_000);

  it("forwards render stage start and end lifecycle events to telemetry", async () => {
    producerState.executeImpl = async (job) => {
      const logger = (job.config as { logger: { info: (message: string, meta: object) => void } })
        .logger;
      logger.info("[Render:trace]", {
        renderJobId: "render-lifecycle",
        phase: "capture_streaming",
        status: "start",
        elapsedMs: 100,
        workerCount: 1,
        captureMode: "screenshot",
        captureOperation: "captureScreenshot",
        framesCompleted: 12,
        totalFrames: 900,
      });
      logger.info("[Render:trace]", {
        renderJobId: "render-lifecycle",
        phase: "capture_streaming",
        status: "end",
        elapsedMs: 250,
        durationMs: 150,
      });
    };

    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      skipFeedback: true,
    });

    expect(trackingState.renderObservations).toEqual([
      expect.objectContaining({
        renderJobId: "render-lifecycle",
        phase: "capture_streaming",
        status: "start",
        captureOperation: "captureScreenshot",
        framesCompleted: 12,
        totalFrames: 900,
      }),
      expect.objectContaining({
        renderJobId: "render-lifecycle",
        phase: "capture_streaming",
        status: "end",
        durationMs: 150,
      }),
    ]);
  });

  it("forwards browserGpuMode='auto' into producer config (probe-then-choose)", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "auto",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.resolveConfigCalls).toContainEqual({
      browserGpuMode: "auto",
      forceScreenshot: false,
    });
    expect(producerState.createdJobs[0]?.producerConfig).toMatchObject({
      browserGpuMode: "auto",
      resolved: true,
    });
  });

  it("honors PRODUCER_FORCE_SCREENSHOT=true even on local auto GPU", async () => {
    const prev = process.env.PRODUCER_FORCE_SCREENSHOT;
    process.env.PRODUCER_FORCE_SCREENSHOT = "true";
    try {
      await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
        fps: { num: 30, den: 1 },
        quality: "standard",
        format: "mp4",
        gpu: false,
        browserGpuMode: "auto",
        hdrMode: "auto",
        quiet: true,
      });
      expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "auto" });
      expect(producerState.resolveConfigCalls[0]).not.toHaveProperty("forceScreenshot");
    } finally {
      if (prev === undefined) delete process.env.PRODUCER_FORCE_SCREENSHOT;
      else process.env.PRODUCER_FORCE_SCREENSHOT = prev;
    }
  });

  it("keeps the screenshot clamp when --resolution supersamples", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "auto",
      hdrMode: "auto",
      quiet: true,
      outputResolution: "landscape",
    });

    expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "auto" });
    expect(producerState.resolveConfigCalls[0]).not.toHaveProperty("forceScreenshot");
  });

  it("passes an explicit hardware override for default local browser GPU", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "hardware",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "hardware" });
    expect(producerState.createdJobs[0]?.producerConfig).toMatchObject({
      browserGpuMode: "hardware",
      resolved: true,
    });
  });

  it("passes preflight-resolved FFmpeg, FFprobe, and browser paths through env", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(process.env.HYPERFRAMES_FFMPEG_PATH).toBe("/usr/bin/ffmpeg");
    expect(process.env.HYPERFRAMES_FFPROBE_PATH).toBe("/usr/bin/ffprobe");
    expect(process.env.PRODUCER_HEADLESS_SHELL_PATH).toBe("/mock/chrome");
  });

  it("falls back to hardware encoding when FFmpeg omits libx264", async () => {
    ffmpegEncoderState.mode = "gpu";

    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "high",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "force-sdr",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.useGpu).toBe(true);
  });

  it("rejects confirmed unsupported SDR MP4 before loading the producer", async () => {
    ffmpegEncoderState.encoders = " V....D h264_vaapi H.264/AVC (VAAPI)\n";
    const { loadProducer } = await import("../utils/producer.js");
    vi.mocked(loadProducer).mockClear();
    const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);

    await expect(
      renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
        fps: { num: 30, den: 1 },
        quality: "high",
        format: "mp4",
        gpu: false,
        browserGpuMode: "software",
        hdrMode: "force-sdr",
        quiet: true,
      }),
    ).rejects.toMatchObject({ name: "CliRuntimeError" });

    expect(loadProducer).not.toHaveBeenCalled();
    expect(producerState.createdJobs).toHaveLength(0);
    expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");
  });

  it("refuses a --gpu MP4 before capture when no GPU encoder works and FFmpeg lacks libx264", async () => {
    ffmpegEncoderState.encoders = " V....D libopenh264 OpenH264\n V....D h264_videotoolbox H.264\n";
    const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);

    await expect(
      renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
        fps: { num: 30, den: 1 },
        quality: "high",
        format: "mp4",
        gpu: true,
        browserGpuMode: "software",
        hdrMode: "auto",
        quiet: true,
      }),
    ).rejects.toMatchObject({ name: "CliRuntimeError" });

    expect(producerState.createdJobs).toHaveLength(0);
    expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");
  });

  it.each(["webm", "mov", "png-sequence"] as const)(
    "does not require H.264 for %s",
    async (format) => {
      ffmpegEncoderState.encoders = " V....D libvpx-vp9 VP9\n";
      await renderLocal(PROJECT_DIR, `/tmp/out.${format}`, {
        fps: { num: 30, den: 1 },
        quality: "high",
        format,
        gpu: false,
        browserGpuMode: "software",
        hdrMode: "force-sdr",
        quiet: true,
      });
      expect(producerState.createdJobs).toHaveLength(1);
    },
  );

  it.each(["auto", "force-hdr"] as const)(
    "does not reject potential HEVC output in %s mode",
    async (hdrMode) => {
      ffmpegEncoderState.encoders = " V....D libx265 HEVC\n";
      await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
        fps: { num: 30, den: 1 },
        quality: "high",
        format: "mp4",
        gpu: false,
        browserGpuMode: "software",
        hdrMode,
        quiet: true,
      });
      expect(producerState.createdJobs).toHaveLength(1);
    },
  );

  it("lets the encoder surface its own error when capability detection fails", async () => {
    ffmpegEncoderState.error = new Error("encoder probe timed out");
    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);

    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "high",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "force-sdr",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.useGpu).toBe(false);
    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("encoder probe timed out"));
  });

  it("diagnoses advisory encoder probe failures unless quiet", async () => {
    ffmpegEncoderState.error = new Error("encoder probe timed out");
    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);

    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "high",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "force-sdr",
      quiet: false,
    });

    expect(producerState.createdJobs[0]?.useGpu).toBe(false);
    expect(warn).toHaveBeenCalledWith(expect.stringContaining("encoder probe timed out"));
  });

  it("resolves browser GPU from CLI flags, Docker mode, and env fallback", () => {
    // Default (no flag, no env): auto — engine probes and chooses.
    expect(resolveBrowserGpuForCli(false, undefined, undefined)).toBe("auto");
    // Env override
    expect(resolveBrowserGpuForCli(false, undefined, "hardware")).toBe("hardware");
    expect(resolveBrowserGpuForCli(false, undefined, "software")).toBe("software");
    expect(resolveBrowserGpuForCli(false, undefined, "auto")).toBe("auto");
    // Explicit CLI flag wins over env
    expect(resolveBrowserGpuForCli(false, true, "software")).toBe("hardware");
    expect(resolveBrowserGpuForCli(false, false, "hardware")).toBe("software");
    // Docker forces software regardless of flags/env
    expect(resolveBrowserGpuForCli(true, undefined, "hardware")).toBe("software");
    expect(resolveBrowserGpuForCli(true, undefined, "auto")).toBe("software");
  });

  it("forwards parsed --variables payload to createRenderJob", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      variables: { title: "Hello", count: 3 },
    });

    expect(producerState.createdJobs[0]?.variables).toEqual({ title: "Hello", count: 3 });
  });

  it("forwards format: png-sequence through to createRenderJob", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/frames", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "png-sequence",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.format).toBe("png-sequence");
  });

  it("forwards format: hls and hlsSegmentSeconds through to createRenderJob", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/stream", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "hls",
      hlsSegmentSeconds: 6,
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.format).toBe("hls");
    expect(producerState.createdJobs[0]?.hlsSegmentSeconds).toBe(6);
  });

  // HLS refuses the VideoToolbox fallback MP4 takes: fixed-length segments need
  // the software encoder's forced-keyframe lock.
  it("fails an HLS render instead of falling back to GPU H.264", async () => {
    ffmpegEncoderState.encoders = " V....D h264_videotoolbox H.264 (VideoToolbox)\n";
    ffmpegEncoderState.usableGpu = true;
    const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);

    await expect(
      renderLocal(PROJECT_DIR, "/tmp/stream", {
        fps: { num: 30, den: 1 },
        quality: "standard",
        format: "hls",
        gpu: false,
        browserGpuMode: "software",
        hdrMode: "auto",
        quiet: true,
      }),
    ).rejects.toMatchObject({ name: "CliRuntimeError" });

    expect(producerState.createdJobs).toHaveLength(0);
    expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");
  });

  it("forwards format: gif and gifLoop through to createRenderJob", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/demo.gif", {
      fps: { num: 15, den: 1 },
      quality: "standard",
      format: "gif",
      gifLoop: 3,
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.format).toBe("gif");
    expect(producerState.createdJobs[0]?.gifLoop).toBe(3);
  });

  it("forwards videoFrameFormat to createRenderJob", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      videoFrameFormat: "png",
    });

    expect(producerState.createdJobs[0]?.videoFrameFormat).toBe("png");
  });

  it("forwards debug mode to createRenderJob", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      debug: true,
    });

    expect(producerState.createdJobs[0]?.debug).toBe(true);
  });

  it("defaults to best-effort readiness", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.strictness).toBe("best-effort");
  });

  it("forwards an explicit strict readiness opt-in", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      bestEffort: false,
    });

    expect(producerState.createdJobs[0]?.strictness).toBe("strict");
  });

  it("omits variables from createRenderJob when not provided", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.variables).toBeUndefined();
  });

  it.each([undefined, "off"] as const)(
    "preserves page motion blur %s in the producer request",
    async (pageMotionBlur) => {
      await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
        fps: { num: 30, den: 1 },
        quality: "standard",
        format: "mp4",
        gpu: false,
        browserGpuMode: "software",
        hdrMode: "auto",
        quiet: true,
        pageMotionBlur,
      });
      expect(producerState.createdJobs[0]?.pageMotionBlur).toBe(pageMotionBlur);
    },
  );

  it("forwards entryFile to createRenderJob when --composition is set", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      entryFile: "compositions/intro.html",
    });

    expect(producerState.createdJobs[0]?.entryFile).toBe("compositions/intro.html");
  });

  it("omits entryFile from createRenderJob when --composition is not set", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.entryFile).toBeUndefined();
  });

  it("forwards --browser-timeout into resolveConfig as pageNavigationTimeout (ms)", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      pageNavigationTimeoutMs: 180_000,
    });

    expect(producerState.resolveConfigCalls[0]).toMatchObject({
      pageNavigationTimeout: 180_000,
    });
  });

  it("forwards vp9CpuUsed into resolveConfig when set", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.webm", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "webm",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      vp9CpuUsed: 2,
    });

    expect(producerState.resolveConfigCalls[0]).toMatchObject({
      vp9CpuUsed: 2,
    });
  });

  it("omits pageNavigationTimeout from resolveConfig when --browser-timeout is not set", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    // Issue #1199: when the flag is omitted, the engine's DEFAULT_CONFIG must
    // own the navigation timeout. Forwarding `undefined` would override
    // `pageNavigationTimeout: 60_000` to `undefined` and re-introduce the
    // bug in a different shape.
    expect(producerState.resolveConfigCalls[0]).not.toHaveProperty("pageNavigationTimeout");
  });

  it("forwards outputResolution to createRenderJob when --resolution is set", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
      outputResolution: "landscape-4k",
    });

    expect(producerState.createdJobs[0]?.outputResolution).toBe("landscape-4k");
  });

  it("omits outputResolution from createRenderJob by default", async () => {
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "software",
      hdrMode: "auto",
      quiet: true,
    });

    expect(producerState.createdJobs[0]?.outputResolution).toBeUndefined();
  });

  it("requests a root-owned CLI exit after a successful local render", async () => {
    vi.useFakeTimers();
    const { consumeCommandResult } = await import("../utils/commandResult.js");
    consumeCommandResult();

    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
      fps: { num: 30, den: 1 },
      quality: "standard",
      format: "mp4",
      gpu: false,
      browserGpuMode: "hardware",
      hdrMode: "auto",
      quiet: true,
      exitAfterComplete: true,
    });

    vi.advanceTimersByTime(100);
    expect(consumeCommandResult().exitCode).toBe(0);
  });

  it("still completes the render when the output registry cannot be written", async () => {
    const project = mkdtempSync(join(tmpdir(), "hf-render-unrecorded-"));
    mkdirSync(join(project, ".hyperframes"));
    writeFileSync(join(project, ".hyperframes", "render-outputs.json"), "{");
    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
    try {
      await renderLocal(project, join(project, "out.mp4"), {
        fps: { num: 30, den: 1 },
        quality: "standard",
        format: "mp4",
        gpu: false,
        browserGpuMode: "hardware",
        hdrMode: "auto",
        quiet: true,
      });
      expect(
        warn.mock.calls.some((call) =>
          String(call[0]).includes("Render output was not registered"),
        ),
      ).toBe(true);
    } finally {
      warn.mockRestore();
      rmSync(project, { recursive: true, force: true });
    }
  });
});

// Suite renamed with the breaker work: this is no longer an opt-in trial. The
// bindings come from main's shared top-level `renderModule` import rather than
// this suite's own beforeAll — same module instance every other suite uses, so
// module-scope arm/consume state resets through the one `resetTrialState()`.
describe("renderLocal — DE parallel-router circuit breaker", () => {
  const { renderLocal, __resetDeParallelRouterTrialStateForTests: resetTrialState } = renderModule;
  const savedEnv = new Map<string, string | undefined>();

  beforeEach(() => {
    producerState.createdJobs = [];
    producerState.executeImpl = async () => undefined;
    configState.cache = null;
    configState.failWrites = 0;
    configState.writeConfigCalls = [];
    trackingState.shouldTrack = true;
    // The "managed by us" flag lives at module scope in render.ts (real CLI
    // processes only ever run one --batch sequence, so it never needs
    // resetting there) — reset explicitly here so tests don't leak arm/
    // consume state into each other via shared module instance + test order.
    resetTrialState();
    savedEnv.clear();
    savedEnv.set("HF_DE_PARALLEL_ROUTER", process.env.HF_DE_PARALLEL_ROUTER);
    savedEnv.set("HYPERFRAMES_FFMPEG_PATH", process.env.HYPERFRAMES_FFMPEG_PATH);
    savedEnv.set("HYPERFRAMES_FFPROBE_PATH", process.env.HYPERFRAMES_FFPROBE_PATH);
    savedEnv.set("PRODUCER_HEADLESS_SHELL_PATH", process.env.PRODUCER_HEADLESS_SHELL_PATH);
    delete process.env.HF_DE_PARALLEL_ROUTER;
    delete process.env.HYPERFRAMES_FFMPEG_PATH;
    delete process.env.HYPERFRAMES_FFPROBE_PATH;
    delete process.env.PRODUCER_HEADLESS_SHELL_PATH;
  });

  afterEach(() => {
    for (const [key, value] of savedEnv) {
      if (value === undefined) delete process.env[key];
      else process.env[key] = value;
    }
    vi.clearAllMocks();
  });

  const baseOptions = {
    fps: { num: 30, den: 1 },
    quality: "standard" as const,
    format: "mp4" as const,
    gpu: false,
    browserGpuMode: "software" as const,
    hdrMode: "auto" as const,
    quiet: true,
    // Breaker management is OPT-IN (review): only the CLI's own sequential
    // call sites set it. These tests simulate those call sites.
    manageDeParallelRouterBreaker: true,
  };

  // The canary that used to gate this is gone (registry entry + guard removed
  // together). The router is now a shipped default for every install, so the
  // guarantee worth pinning is the inverse of the old one: an ordinary install
  // must come out of the breaker with the var UNSET, so the producer's
  // default-ON applies. Writing "false" here would silently disarm the fleet —
  // that is exactly what gating at 5% did.
  it("leaves the var unset for an ordinary install so the producer default applies", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    delete process.env.HF_DE_PARALLEL_ROUTER;
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
  });

  // An explicit user choice outranks enrolment in both directions — the
  // documented escalation path for anyone who wants the router regardless.
  it("never overrides an explicit user value", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    process.env.HF_DE_PARALLEL_ROUTER = "true";
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
  });

  it("leaves the env var untouched on a fresh install — the router is default-ON", async () => {
    // Under the old opt-in trial this armed HF_DE_PARALLEL_ROUTER="true".
    // The router now ships on, so the breaker's job is to stay out of the
    // way until something actually fails.
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
  });

  it("does not override an env var the user already set themselves", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    process.env.HF_DE_PARALLEL_ROUTER = "false";
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
  });

  it("writes an explicit false once the breaker has tripped for this install", async () => {
    // THE regression this rework exists for: the old code disabled the
    // router by DELETING the var. With a default-ON router, absent means ON,
    // so deleting would silently re-enable it on the very host that just
    // failed. Only an explicit "false" is a real off-switch.
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: true,
      telemetryNoticeShown: true,
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
  });

  for (const emptyish of ["", "   "]) {
    it(`treats a set-but-empty env var (${JSON.stringify(emptyish)}) as default, not a user choice`, async () => {
      // Both parsers read empty/whitespace as "unset → default ON", so the
      // producer routes. If ownership instead treated any defined value as a
      // user choice, the breaker would no-op and this install would keep
      // retrying a failing router forever — losing the first-fallback
      // protection that is the point of the breaker.
      configState.disk = {
        telemetryEnabled: true,
        deParallelRouterTrialFired: false,
        telemetryNoticeShown: true,
      };
      process.env.HF_DE_PARALLEL_ROUTER = emptyish;
      producerState.executeImpl = async (job) => {
        job.perfSummary = {
          resolution: { width: 100, height: 100 },
          drawElement: { parallelRouter: "reverted" },
        };
      };
      await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
      expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
      expect(configState.writeConfigCalls).toContainEqual(
        expect.objectContaining({ deParallelRouterTrialFired: true }),
      );
    });
  }

  it("does not override an explicit user opt-in even after a fallback", async () => {
    // "Explicit user choice wins in both directions" — the opt-in half.
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    process.env.HF_DE_PARALLEL_ROUTER = "true";
    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "reverted" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
  });

  it("keeps the router on for a telemetry opt-out — analytics choice must not cost performance", async () => {
    // The old trial refused to arm without recordable telemetry (no point
    // running an experiment you can't measure). Now that the router is a
    // shipped default, gating it on telemetry would punish a privacy choice
    // with a slower renderer.
    configState.disk = {
      telemetryEnabled: false,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
  });

  it("does NOT persist the trial as fired on a clean 'routed' success — keeps trying on future renders", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "routed" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    // A write DOES happen — the render-count backstop is tracked on every
    // engaged render — but it must not flip deParallelRouterTrialFired.
    expect(configState.writeConfigCalls).toContainEqual(
      expect.objectContaining({
        deParallelRouterTrialFired: false,
        deParallelRouterTrialRenderCount: 1,
      }),
    );
  });

  it("persists the trial as fired when the router's own safety net actually reverted", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "reverted" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(configState.writeConfigCalls).toContainEqual(
      expect.objectContaining({ deParallelRouterTrialFired: true }),
    );
  });

  it("does not persist the trial as fired or increment the render count when the router never became eligible for this render", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    producerState.executeImpl = async (job) => {
      // aggregateDrawElement (perfSummary.ts) ALWAYS defaults parallelRouter
      // to the string "none" for every render, whether or not drawElement
      // ever ran — never undefined. This fixture must match that shape, not
      // an unrealistic empty object, or the test doesn't actually exercise
      // the "none"-vs-undefined distinction (review finding).
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "none" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(configState.writeConfigCalls).toHaveLength(0);
  });

  it("does NOT persist the trial as fired when a render merely 'routed' crashes for an unrelated reason (e.g. cancellation) — not a router failure", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    producerState.executeImpl = async (job) => {
      job.errorDetails = { observability: { capture: { deParallelRouter: "routed" } } };
      throw new Error("render cancelled");
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(
      () => {},
    );
    // Still counts toward the render-count backstop (the router DID engage),
    // but must not flip deParallelRouterTrialFired — the crash wasn't the
    // router's own safety net firing.
    expect(configState.writeConfigCalls).toContainEqual(
      expect.objectContaining({
        deParallelRouterTrialFired: false,
        deParallelRouterTrialRenderCount: 1,
      }),
    );
  });

  it("persists the trial as fired from the failure path when the router's safety net reverted but the retry still failed", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    producerState.executeImpl = async (job) => {
      job.errorDetails = { observability: { capture: { deParallelRouter: "reverted" } } };
      throw new Error("worker crashed even after fallback");
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(
      () => {},
    );
    expect(configState.writeConfigCalls).toContainEqual(
      expect.objectContaining({ deParallelRouterTrialFired: true }),
    );
  });

  it("persists a later --batch row's revert even though this process already armed the trial on an earlier row", async () => {
    // The --batch scenario: multiple renderLocal calls in one process. Row 1
    // succeeds (breaker stays out of the way, env untouched); row 2 reverts
    // and must still be recorded and trip the breaker.
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };

    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "routed" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
    expect(configState.disk.deParallelRouterTrialFired).toBe(false);

    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "reverted" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);

    expect(configState.writeConfigCalls).toContainEqual(
      expect.objectContaining({ deParallelRouterTrialFired: true }),
    );
    // Explicit "false", not deleted: with a default-ON router, unsetting the
    // var would re-enable it on the host that just reverted.
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
  });

  it("does not arm the trial for programmatic callers that never opted in (opt-in polarity — also covers --batch-concurrency N>=2, which leaves it unset)", async () => {
    // The trial's process-wide env var and module-level flags are only safe
    // under sequential invocation, so manageDeParallelRouterBreaker is OPT-IN
    // (review): a programmatic renderLocal consumer that doesn't know about
    // the trial must get no trial. The CLI's concurrent-batch path relies on
    // the same default by leaving the option unset.
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    const { manageDeParallelRouterBreaker: _omitted, ...programmaticOptions } = baseOptions;
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", programmaticOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
    expect(configState.writeConfigCalls).toHaveLength(0);
  });

  it("does not override an env var the user set between two renders in the same process", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "routed" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();

    // A real interactive user can't do this mid-batch, but a wrapper script
    // invoking the CLI programmatically in the same process could — the
    // explicit override must still win on the next call.
    process.env.HF_DE_PARALLEL_ROUTER = "false";
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
  });

  it("never trips on healthy renders, however many — the old 25-render cap is gone", async () => {
    // The cap was sampling logic for an opt-in experiment. Under a shipped
    // default it would switch the feature off behind the user's back after
    // 25 good renders.
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "routed" },
      };
    };

    for (let i = 0; i < 30; i++) {
      await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    }

    expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
    expect(
      configState.writeConfigCalls.some((call) => call.deParallelRouterTrialFired === true),
    ).toBe(false);
  });

  // The config write landing is NOT enough: config.json is the copy a stale
  // writer or a re-mint can erase, so a run that mirrored nothing has left the
  // safety fact on the erasable store only. writeConfig() collapsed
  // {ok:true, mirrored:false} to success and the loop stopped there.
  it("retries when the install-state mirror fails even though config.json landed", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    configState.failMirrors = 1; // first attempt mirrors nothing
    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "reverted" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);

    expect(configState.disk.deParallelRouterTrialFired).toBe(true);
    // Two writes: the one whose mirror failed, then the retry that mirrored.
    const firedWrites = configState.writeConfigCalls.filter(
      (c) => c.deParallelRouterTrialFired === true,
    );
    expect(firedWrites.length).toBeGreaterThanOrEqual(2);
  });

  it("re-asserts the fired flag when the write is lost (concurrent clobber / transient failure), without re-counting the render", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    configState.failWrites = 1; // the consume's main write is silently dropped
    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "reverted" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    // The fired flag was verified and re-asserted (idempotent)...
    expect(configState.disk.deParallelRouterTrialFired).toBe(true);
    // ...but the render counter is deliberately NOT re-applied — a lost
    // increment under a race is benign, a re-applied one double-counts the
    // render and trips the exposure cap early (review finding).
    expect(configState.disk.deParallelRouterTrialRenderCount).toBeUndefined();
  });

  it("blocks re-arming for the rest of the process when the fired flag can never persist (unwritable config)", async () => {
    configState.disk = {
      telemetryEnabled: true,
      deParallelRouterTrialFired: false,
      telemetryNoticeShown: true,
    };
    configState.failWrites = Number.MAX_SAFE_INTEGER; // ~/.hyperframes is unwritable
    producerState.executeImpl = async (job) => {
      job.perfSummary = {
        resolution: { width: 100, height: 100 },
        drawElement: { parallelRouter: "reverted" },
      };
    };
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    // Nothing could persist...
    expect(configState.disk.deParallelRouterTrialFired).toBe(false);
    // ...but the in-process latch still blocks the next render from
    // re-running the path that just failed (review finding) — and now does
    // it by writing an explicit "false", since absent means ON.
    producerState.executeImpl = async () => undefined;
    await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
    expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
  });
});

describe("checkRenderResolutionPreflight", () => {
  const { checkRenderResolutionPreflight } = renderModule;

  // Dims must be read the same way the producer's compiler reads them:
  // `data-width` / `data-height` on the `[data-composition-id]` root.
  const comp = (w: number, h: number) =>
    `<html><body><div data-composition-id="root" data-width="${w}" data-height="${h}"></div></body></html>`;
  const portraitHtml = comp(1080, 1920);
  const landscapeHtml = comp(1920, 1080);
  const noModes = { alphaRequested: false, hdrRequested: false } as const;

  it("returns undefined when no outputResolution is requested", async () => {
    expect(await checkRenderResolutionPreflight(portraitHtml, undefined, noModes)).toBeUndefined();
  });

  it("returns undefined when the preset matches the composition orientation", async () => {
    expect(await checkRenderResolutionPreflight(portraitHtml, "portrait", noModes)).toBeUndefined();
  });

  it("returns a suggestion + aspect-mismatch kind when a landscape preset is used on a portrait composition", async () => {
    const result = await checkRenderResolutionPreflight(portraitHtml, "landscape", noModes);
    expect(result?.message).toContain("--resolution portrait");
    expect(result?.kind).toBe("aspect-mismatch");
  });

  it("suggests landscape for a landscape composition rendered with a portrait preset", async () => {
    const result = await checkRenderResolutionPreflight(landscapeHtml, "portrait", noModes);
    expect(result?.message).toContain("--resolution landscape");
  });

  it("preserves the 4K tier when suggesting a matching preset (square comp + landscape-4k → square-4k)", async () => {
    // Tier-aware suggestion is the load-bearing new behavior; square-4k is the
    // preset that only surfaces via a same-tier swap, so guard it explicitly.
    const result = await checkRenderResolutionPreflight(comp(2160, 2160), "landscape-4k", noModes);
    expect(result?.message).toContain("--resolution square-4k");
  });

  it("does not false-abort a landscape registry-block composition (data-width/height, no data-resolution)", async () => {
    // Regression guard: registry blocks carry data-width/height and no
    // data-resolution — a preset-snapping heuristic would misread this as
    // portrait and wrongly reject the correct --resolution landscape.
    expect(
      await checkRenderResolutionPreflight(landscapeHtml, "landscape", noModes),
    ).toBeUndefined();
  });

  it("allows alpha output combined with an integer outputResolution scale", async () => {
    const result = await checkRenderResolutionPreflight(landscapeHtml, "landscape-4k", {
      alphaRequested: true,
      hdrRequested: false,
    });
    expect(result).toBeUndefined();
  });

  // The remaining kinds share the same rejection sink (→ one emit each);
  // guard their classification so the telemetry dimension stays accurate.
  it("classifies an HDR + outputResolution combination as hdr-incompatible", async () => {
    const result = await checkRenderResolutionPreflight(landscapeHtml, "landscape", {
      alphaRequested: false,
      hdrRequested: true,
    });
    expect(result?.kind).toBe("hdr-incompatible");
  });

  it("passes a preset smaller than the composition", async () => {
    // 3840×2160 comp + landscape (1920×1080): same 16:9 aspect, rendered at 0.5× DPR.
    const result = await checkRenderResolutionPreflight(comp(3840, 2160), "landscape", noModes);
    expect(result).toBeUndefined();
  });

  it("classifies a non-integer upscale as non-integer-scale", async () => {
    // 1280×720 comp + landscape (1920×1080): same 16:9 aspect, 1.5× scale.
    const result = await checkRenderResolutionPreflight(comp(1280, 720), "landscape", noModes);
    expect(result?.kind).toBe("non-integer-scale");
  });

  it("returns undefined when composition dimensions can't be determined (defers to the pipeline)", async () => {
    // No [data-composition-id] root / no data-width/height → defer, never guess.
    expect(await checkRenderResolutionPreflight("", "landscape", noModes)).toBeUndefined();
    expect(
      await checkRenderResolutionPreflight("<html><body></body></html>", "landscape", noModes),
    ).toBeUndefined();
  });

  // Aspect-agnostic aliases (`--resolution 1080p` / `hd` / `4k` / `uhd`) name a
  // resolution tier without pinning an orientation. When the flag is
  // aspect-agnostic the pre-flight must NOT block on an aspect-ratio mismatch —
  // the compile stage adapts the preset to the composition's orientation
  // downstream (see `outputResolutionAspectAgnostic` on RenderConfig).
  // Field signal ts=1784176662 (darwin/arm64, CLI 0.7.59):
  //   "--resolution 1080p rejects a 1080x1920 portrait comp"
  describe("aspect-agnostic (--resolution 1080p / hd / 4k / uhd)", () => {
    const agnostic = { ...noModes, aspectAgnostic: true } as const;

    it("clears a landscape preset on a portrait composition (the field-signal scenario)", async () => {
      // The bug: --resolution 1080p normalized to `landscape` (1920×1080),
      // then errored on a 1080×1920 portrait comp with "Output resolution
      // incompatible." With aspectAgnostic=true the pre-flight steps aside
      // and the compile stage re-maps landscape → portrait.
      expect(
        await checkRenderResolutionPreflight(portraitHtml, "landscape", agnostic),
      ).toBeUndefined();
    });

    it("clears a landscape-4k preset on a portrait composition (4K tier)", async () => {
      // `--resolution 4k` → normalized `landscape-4k`. Portrait comp is fine
      // when aspect-agnostic.
      expect(
        await checkRenderResolutionPreflight(portraitHtml, "landscape-4k", agnostic),
      ).toBeUndefined();
    });

    it("clears a landscape preset on a square composition", async () => {
      // aspect > 1 → landscape, aspect = 1 → square. Both self-heal.
      expect(
        await checkRenderResolutionPreflight(comp(1080, 1080), "landscape", agnostic),
      ).toBeUndefined();
    });

    it("allows alpha + aspect-agnostic after adapting the orientation", async () => {
      const result = await checkRenderResolutionPreflight(portraitHtml, "landscape", {
        aspectAgnostic: true,
        alphaRequested: true,
        hdrRequested: false,
      });
      expect(result).toBeUndefined();
    });

    it("still flags HDR + aspect-agnostic", async () => {
      const result = await checkRenderResolutionPreflight(landscapeHtml, "landscape", {
        aspectAgnostic: true,
        alphaRequested: false,
        hdrRequested: true,
      });
      expect(result?.kind).toBe("hdr-incompatible");
    });

    it("passes `--resolution 1080p` on a 4K composition (a smaller, same-orientation preset)", async () => {
      const result = await checkRenderResolutionPreflight(comp(3840, 2160), "landscape", agnostic);
      expect(result).toBeUndefined();
    });

    it("never adapts `--resolution 4k` to another tier: a 1922×1080 composition is refused, not rendered at 480p", async () => {
      const result = await checkRenderResolutionPreflight(
        comp(1922, 1080),
        "landscape-4k",
        agnostic,
      );
      expect(result?.kind).toBeDefined();
    });

    it("does NOT auto-clear when the flag was explicit (orientation-locked preset stays strict)", async () => {
      // The negative case: `--resolution landscape` on a portrait comp — the
      // user explicitly asked for landscape orientation, and the mismatch is
      // a genuine mistake. Pre-flight must still block with the actionable
      // "did you mean --resolution portrait?" suggestion.
      const result = await checkRenderResolutionPreflight(portraitHtml, "landscape", noModes);
      expect(result?.kind).toBe("aspect-mismatch");
      expect(result?.message).toContain("--resolution portrait");
    });

    // Rames Δ2 on PR #2529: the earlier "downgrade aspect-mismatch to
    // undefined" preflight cleared *un-remapped* mismatches, so two input
    // classes below regressed from an early actionable error to a late throw
    // deep in `resolveDeviceScaleFactor` (browser + ffmpeg already up).
    // The fix computes the *effective* preset via `suggestMatchingPreset`
    // (mirroring the compile stage) and re-checks against that, so only
    // genuinely-fixable mismatches clear early.

    it("blocks IG 4:5 (non-preset aspect) early with an aspect-aware message", async () => {
      // 1080×1350 is a 4:5 portrait — no canonical preset shares that aspect,
      // so `suggestMatchingPreset` returns undefined and `adaptAspectAgnosticResolution`
      // keeps the original preset. Before the fix, aspect-agnostic downgraded
      // the mismatch here to undefined; now the preflight surfaces it early.
      const result = await checkRenderResolutionPreflight(comp(1080, 1350), "landscape", agnostic);
      expect(result?.kind).toBe("aspect-mismatch");
      // No sibling preset to suggest → message falls back to the "pick a preset
      // whose orientation matches" hint (see `buildAspectMismatch` in
      // `@hyperframes/parsers/outputResolutionCompatibility`).
      expect(result?.message).toMatch(/preset whose orientation matches|omit --resolution/i);
    });

    it("passes a portrait-4K comp + `1080p` once remapped to portrait (a smaller preset)", async () => {
      // 2160×3840 + `--resolution 1080p` remaps `landscape` → `portrait` (1080×1920), rendered at 0.5× DPR.
      const result = await checkRenderResolutionPreflight(comp(2160, 3840), "landscape", agnostic);
      expect(result).toBeUndefined();
    });

    it("blocks a portrait 720p comp + `1080p` non-integer upscale early (orientation-flip masks the fractional DPR)", async () => {
      // 720×1280 (portrait 720p) + `--resolution 1080p` — remap `landscape`
      // → `portrait` (1080×1920). widthRatio = 1080 / 720 = 1.5, which
      // `resolveDeviceScaleFactor` rejects. Surfacing it in preflight beats
      // failing after Chrome + ffmpeg spin up. Same class as Miga's
      // important note on PR #2529.
      const result = await checkRenderResolutionPreflight(comp(720, 1280), "landscape", agnostic);
      expect(result?.kind).toBe("non-integer-scale");
    });
  });
});

describe("render fps arg definition", () => {
  it("declares no citty default for --fps (so data-fps resolution can run)", async () => {
    // Regression guard: a `default: "30"` here makes citty set args.fps="30"
    // on omission, which short-circuits resolveDefaultFpsArg (explicitFps is
    // never null) and silently reverts the command to always-30 — the exact
    // no-op caught in review. The "30" fallback must live at the
    // parseFps(fpsArg ?? "30") call, not on the arg.
    const cmd = (await import("./render.js")).default;
    // citty types `args` as Resolvable (it could be a promise/factory); in
    // practice it's the literal object, so read it through a plain record.
    const args = cmd.args as unknown as Record<string, { default?: unknown } | undefined>;
    const fpsArg = args.fps;
    expect(fpsArg).toBeDefined();
    expect(fpsArg?.default).toBeUndefined();
  });
});

describe("render command explicit composition", () => {
  it("cancels before rendering when the wrapper exits during browser preparation", async () => {
    const projectDir = mkdtempSync(join(tmpdir(), "hf-render-prep-cancel-"));
    writeFileSync(
      join(projectDir, "index.html"),
      '<!doctype html><html><body><div data-composition-id="main" data-width="1920" data-height="1080" data-no-timeline></div></body></html>',
    );
    const wrapper = spawn(process.execPath, ["--eval", "setInterval(() => undefined, 1000)"], {
      stdio: "ignore",
    });
    const jobsBefore = producerState.createdJobs.length;
    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
    let releasePreparation!: () => void;
    const preparationBlocked = new Promise<void>((resolve) => {
      releasePreparation = resolve;
    });
    orphanCleanupState.parentPid = (pid) => (pid === process.pid ? wrapper.pid! : null);
    orphanCleanupState.identity = (pid) => (pid === wrapper.pid ? "wrapper-birth-token" : null);
    browserManagerState.onEnsure = async (signal) => {
      const exited = new Promise<void>((resolve) => wrapper.once("exit", () => resolve()));
      wrapper.kill("SIGTERM");
      await exited;
      await new Promise<void>((resolve, reject) => {
        const onAbort = () => reject(signal?.reason);
        signal?.addEventListener("abort", onAbort, { once: true });
        if (signal?.aborted) onAbort();
        void preparationBlocked.then(() => {
          signal?.removeEventListener("abort", onAbort);
          resolve();
        });
      });
    };

    try {
      const command = renderModule.default.run?.({
        args: {
          dir: projectDir,
          output: join(projectDir, "out.mp4"),
          quiet: true,
          quality: "standard",
          format: "mp4",
        },
      } as never);
      await expect(
        Promise.race([
          command,
          new Promise<never>((_resolve, reject) =>
            setTimeout(
              () => reject(new Error("Setup cancellation timed out")),
              process.platform === "linux" ? 1_000 : 3_000,
            ),
          ),
        ]),
      ).rejects.toThrow("render_cancelled_parent_exited");
      expect(producerState.createdJobs).toHaveLength(jobsBefore);
      expect(
        stderr.mock.calls.filter(([line]) =>
          String(line).includes("Render cancelled: render_cancelled_parent_exited"),
        ),
      ).toEqual([["Render cancelled: render_cancelled_parent_exited\n"]]);
    } finally {
      releasePreparation();
      const { consumeCommandResult } = await import("../utils/commandResult.js");
      consumeCommandResult();
      browserManagerState.onEnsure = undefined;
      orphanCleanupState.parentPid = () => null;
      orphanCleanupState.identity = () => null;
      stderr.mockRestore();
      wrapper.kill("SIGKILL");
      rmSync(projectDir, { recursive: true, force: true });
    }
  });

  it("renders an explicit composition from a project with no index.html", async () => {
    const projectDir = mkdtempSync(join(tmpdir(), "hf-render-explicit-"));
    const outputPath = join(projectDir, "out.mp4");
    writeFileSync(
      join(projectDir, "standalone.html"),
      `<html><body>
        <div data-composition-id="standalone" data-width="1920" data-height="1080" data-duration="1"></div>
        <script>window.__timelines = { standalone: gsap.timeline({ paused: true }) };</script>
      </body></html>`,
    );
    vi.useFakeTimers();

    try {
      const command = (await import("./render.js")).default;
      await command.run?.({
        args: {
          dir: projectDir,
          composition: "standalone.html",
          output: outputPath,
          quiet: true,
          quality: "standard",
          format: "mp4",
        },
      } as never);

      expect(producerState.createdJobs.at(-1)).toMatchObject({
        entryFile: "standalone.html",
      });
    } finally {
      vi.clearAllTimers();
      rmSync(projectDir, { recursive: true, force: true });
    }
  }, 60_000);
});

describe("render command batch options", () => {
  it("forwards gif loop and video frame format to batch row renders", async () => {
    const projectDir = mkdtempSync(join(tmpdir(), "hf-render-batch-options-"));
    const rowsPath = join(projectDir, "rows.json");
    writeFileSync(
      join(projectDir, "index.html"),
      '<!doctype html><html><body><div data-composition-id="main" data-width="1920" data-height="1080" data-no-timeline></div></body></html>',
      "utf8",
    );
    writeFileSync(rowsPath, "[{}]", "utf8");

    try {
      await renderModule.default.run?.({
        args: {
          dir: projectDir,
          batch: rowsPath,
          output: join(projectDir, "renders", "{index}.gif"),
          fps: "15",
          quality: "standard",
          format: "gif",
          "gif-loop": "3",
          "video-frame-format": "png",
          quiet: true,
        },
      } as never);

      expect(producerState.createdJobs.at(-1)).toMatchObject({
        format: "gif",
        gifLoop: 3,
        videoFrameFormat: "png",
      });
    } finally {
      rmSync(projectDir, { recursive: true, force: true });
    }
  }, 60_000);
});

describe("normalizeStageCode", () => {
  const { normalizeStageCode } = renderModule;

  it("maps every known updateJobStatus stage string to its code", () => {
    expect(normalizeStageCode("Queued")).toBe("queued");
    expect(normalizeStageCode("Compiling composition")).toBe("compiling_composition");
    expect(normalizeStageCode("Extracting video frames")).toBe("extracting_video_frames");
    expect(normalizeStageCode("Processing audio tracks")).toBe("processing_audio_tracks");
    expect(normalizeStageCode("Starting frame capture")).toBe("starting_frame_capture");
    expect(normalizeStageCode("Render complete")).toBe("render_complete");
    expect(normalizeStageCode("Render cancelled")).toBe("render_cancelled");
    expect(normalizeStageCode("pipeline")).toBe("pipeline");
  });

  it("keeps one code for the producer's browser start-up counts", () => {
    expect(normalizeStageCode("Starting browsers (0/6 ready)")).toBe("starting_browsers");
    expect(normalizeStageCode("Starting browsers (5/6 ready)")).toBe("starting_browsers");
  });

  it("keeps one code per stage whatever its live frame counts", () => {
    expect(normalizeStageCode("Encoding frame 600/600")).toBe("encoding_video");
    expect(normalizeStageCode("Encoding frame 12/90")).toBe("encoding_video");
    expect(normalizeStageCode("Capturing frame 120/600 (6 workers)")).toBe("capturing_frame");
    expect(normalizeStageCode("Streaming frame 3/40 (segment 1/2, 2 workers)")).toBe(
      "streaming_frame",
    );
    expect(normalizeStageCode("Assembling final video")).toBe("assembling_final_video");
  });

  it("slugifies an unrecognized stage string instead of bucketing it as unknown", () => {
    expect(normalizeStageCode("Some New Stage!")).toBe("some_new_stage");
  });

  it("falls back to unknown only when slugifying produces nothing usable", () => {
    expect(normalizeStageCode("")).toBe("unknown");
    expect(normalizeStageCode("!!!")).toBe("unknown");
  });
});

// Variables-helper tests live in `../utils/variables.test.ts`.