// 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"; import { VERSION } from "../version.js"; const producerState = vi.hoisted(() => ({ createdJobs: [] as Array>, resolveConfigCalls: [] as Array>, 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, _abortSignal?: AbortSignal, _assertRenderActive?: () => void, ): Promise => 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; cache: Record | null; writeConfigCalls: Array>; 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>, })); 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) | undefined, })); vi.mock("../utils/producer.js", () => ({ loadProducer: vi.fn(async () => ({ ...(await import("../../../engine/src/services/referenceBackground.js")), 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) => { 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 }, runtime: { logger?: unknown }) => { const { engineConfig, ...options } = request.options; return { ...options, producerConfig: engineConfig, logger: runtime.logger }; }, ), createRenderJob: vi.fn((config: Record) => { producerState.createdJobs.push(config); return { config, progress: 100, outcome: "completed", warnings: [] }; }), executeRenderJob: vi.fn( async ( job: Record, _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; 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) => { 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; }), releaseDeParallelRouterLatch: vi.fn(() => { configState.disk = { ...configState.disk, deParallelRouterTrialFired: undefined }; configState.cache = { ...configState.disk }; }), // 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) => { 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) => { trackingState.renderObservations.push(props); }), })); vi.mock("../browser/ffmpeg.js", async (importOriginal) => { const actual = await importOriginal(); 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(); 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.each([ { kind: "solid", rgb: [10, 46, 138] }, { kind: "none" }, { kind: "unsupported_non_solid" }, { kind: "unknown" }, ])("returns the same $kind background object as the remote receipt", async (background) => { producerState.executeImpl = async (job) => { job.reference_background = background; }; const result = await 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, }); expect(result?.reference_background).toEqual(background); }); it("warns that the whole mix was lowered, and the render still completes", async () => { const warn = vi.spyOn(console, "warn").mockImplementation(() => {}); producerState.executeImpl = async (job: { audioLoweredDb?: number }) => { job.audioLoweredDb = 7.3; }; const result = await 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, }); expect(warn).toHaveBeenCalledWith(expect.stringContaining("[audio_lowered] Audio lowered 7.3")); expect(result?.outcome).toBe("completed"); expect(result?.warnings?.map((warning) => warning.code)).toEqual(["audio_lowered"]); warn.mockRestore(); }); 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((resolve) => { markExecutionStarted = resolve; }); let producerSignal: AbortSignal | undefined; producerState.executeImpl = async (_job, abortSignal) => { producerSignal = abortSignal; markExecutionStarted(); await new Promise((_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, beginFrameFirstFrameDeadlineMs: 20_000, }); 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"); expect(producerState.resolveConfigCalls[0]).not.toHaveProperty( "beginFrameFirstFrameDeadlineMs", ); }); 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(); 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 strike = (over: Record = {}) => ({ reason: "psnr", at: "2026-10-01T00:00:00.000Z", version: VERSION, atRender: 0, ...over, }); /** One earlier revert on record: the next one trips the breaker. */ const afterOneStrike = () => ({ telemetryEnabled: true, deParallelRouterTrialFired: false, telemetryNoticeShown: true, deParallelRouterBreaker: { strike: strike() }, deParallelRouterTrialRenderCount: 1, }); const tripped = (over: Record = {}) => ({ telemetryEnabled: true, deParallelRouterTrialFired: true, telemetryNoticeShown: true, deParallelRouterBreaker: { trip: { ...strike(), cleanRenders: 0, ...over } }, }); const revertedRender = async (job: { perfSummary?: unknown }) => { job.perfSummary = { resolution: { width: 100, height: 100 }, drawElement: { parallelRouter: "reverted" }, }; }; 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 = tripped(); 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 = afterOneStrike(); 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 = afterOneStrike(); producerState.executeImpl = async (job) => { job.perfSummary = { resolution: { width: 100, height: 100 }, drawElement: { parallelRouter: "reverted", fallbackReason: "psnr", fallbackFrameIndex: 812, fallbackFailedDb: 24.5, fallbackThresholdDb: 32, }, }; }; await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(configState.writeConfigCalls).toContainEqual( expect.objectContaining({ deParallelRouterTrialFired: true, deParallelRouterBreaker: { trip: expect.objectContaining({ reason: "psnr", frameIndex: 812, failedDb: 24.5, thresholdDb: 32, version: VERSION, cleanRenders: 0, }), }, }), ); }); 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 = afterOneStrike(); 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("trips on the second revert of a --batch, not the first", async () => { configState.disk = { telemetryEnabled: true, deParallelRouterTrialFired: false, telemetryNoticeShown: true, }; producerState.executeImpl = revertedRender; await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined(); expect(configState.disk.deParallelRouterTrialFired).toBe(false); await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(configState.disk.deParallelRouterTrialFired).toBe(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("keeps the router on after a single revert and remembers the strike", async () => { configState.disk = { telemetryEnabled: true, telemetryNoticeShown: true }; producerState.executeImpl = revertedRender; await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined(); expect(configState.disk.deParallelRouterTrialFired).toBeFalsy(); expect(configState.disk.deParallelRouterBreaker).toEqual({ strike: expect.objectContaining({ reason: "reverted", atRender: 1, version: VERSION }), }); }); it("forgets a strike that is 20 or more router renders old", async () => { configState.disk = { ...afterOneStrike(), deParallelRouterTrialRenderCount: 20 }; producerState.executeImpl = revertedRender; await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(configState.disk.deParallelRouterTrialFired).toBeFalsy(); expect(configState.disk.deParallelRouterBreaker).toEqual({ strike: expect.objectContaining({ atRender: 21 }), }); }); it("brings the router back for a new CLI version", async () => { configState.disk = tripped({ version: "0.0.1-older" }); await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined(); expect(configState.disk.deParallelRouterTrialFired).toBeFalsy(); expect(configState.disk.deParallelRouterBreaker).toBeUndefined(); }); it("brings the router back when the latch has no record (set by an older CLI)", async () => { configState.disk = { telemetryEnabled: true, deParallelRouterTrialFired: true, telemetryNoticeShown: true, }; await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined(); expect(configState.disk.deParallelRouterTrialFired).toBeFalsy(); }); it("brings the router back after 20 clean renders, not before", async () => { configState.disk = tripped({ cleanRenders: 17 }); for (const expected of [18, 19]) { await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false"); expect(configState.disk.deParallelRouterBreaker).toEqual({ trip: expect.objectContaining({ cleanRenders: expected }), }); } await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions); expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined(); expect(configState.disk.deParallelRouterTrialFired).toBeFalsy(); expect(configState.disk.deParallelRouterBreaker).toBeUndefined(); }); it("does not count a failed render toward bringing the router back", async () => { configState.disk = tripped({ cleanRenders: 5 }); producerState.executeImpl = async () => { throw new Error("render failed"); }; await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch( () => {}, ); expect(configState.disk.deParallelRouterBreaker).toEqual({ trip: expect.objectContaining({ cleanRenders: 5 }), }); }); 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 = afterOneStrike(); 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 = afterOneStrike(); 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).toBe(1); }); it("blocks re-arming for the rest of the process when the fired flag can never persist (unwritable config)", async () => { configState.disk = afterOneStrike(); 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) => `
`; 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("", "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; 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"), '
', ); 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((resolve) => { releasePreparation = resolve; }); let markWrapperExited!: () => void; const wrapperExited = new Promise((resolve) => { markWrapperExited = 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((resolve) => wrapper.once("exit", () => resolve())); wrapper.kill("SIGTERM"); await exited; markWrapperExited(); await new Promise((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, wrapperExited.then( () => new Promise((_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"), `
`, ); 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"), '
', "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`.