Skip to content

Write HTML. Render video. Built for agents.

14.5 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { basename, join, resolve } from "node:path";
import { CliUsageError } from "../../utils/commandResult.js";
import { createRenderPlan } from "./plan.js";

describe("createRenderPlan", () => {
  let projectDir: string;

  beforeEach(() => {
    projectDir = mkdtempSync(join(tmpdir(), "hf-render-plan-"));
    writeFileSync(
      join(projectDir, "index.html"),
      '<main data-composition-id="main" data-width="1920" data-height="1080" data-fps="24"></main>',
    );
    vi.spyOn(console, "error").mockImplementation(() => {});
  });

  afterEach(() => {
    vi.restoreAllMocks();
    rmSync(projectDir, { recursive: true, force: true });
  });

  it("resolves defaults once into a frozen execution plan", () => {
    const plan = createRenderPlan(
      { dir: projectDir, output: "result.mp4" },
      new Date("2026-07-10T12:34:56Z"),
    );

    expect(plan.fps).toEqual({ num: 24, den: 1 });
    expect(plan.outputPath).toBe(resolve("result.mp4"));
    expect(plan.hdrMode).toBe("auto");
    expect(plan.bestEffort).toBe(true);
    expect(plan.batchConcurrency).toBe(1);
    expect(Object.isFrozen(plan)).toBe(true);
    expect(Object.isFrozen(plan.environment)).toBe(true);
  });

  // GIF's Netscape frame-delay field is stored in centiseconds, so fps above
  // 30 rounds to visually-indistinguishable delay values. createRenderPlan
  // clamps and flags it so both the CLI console warning (present.ts) and
  // render telemetry (gif_fps_capped) can report the same decision.
  it("caps fps to 30 and flags it for --format gif above the ceiling", () => {
    const plan = createRenderPlan({
      dir: projectDir,
      output: "result.gif",
      format: "gif",
      fps: "60",
    });
    expect(plan.fps).toEqual({ num: 30, den: 1 });
    expect(plan.gifFpsCapped).toBe(true);
  });

  it("does not flag gifFpsCapped for gif fps at or below the ceiling", () => {
    const plan = createRenderPlan({
      dir: projectDir,
      output: "result.gif",
      format: "gif",
      fps: "24",
    });
    expect(plan.fps).toEqual({ num: 24, den: 1 });
    expect(plan.gifFpsCapped).toBe(false);
  });

  it("does not flag gifFpsCapped for non-gif formats regardless of fps", () => {
    const plan = createRenderPlan({
      dir: projectDir,
      output: "result.mp4",
      format: "mp4",
      fps: "60",
    });
    expect(plan.fps).toEqual({ num: 60, den: 1 });
    expect(plan.gifFpsCapped).toBe(false);
  });

  // The catalog join reaches the render event through the plan, so a plan that
  // silently drops it would leave every render reporting no catalog items.
  it("resolves catalog usage from the project manifest and the render entry", () => {
    writeFileSync(
      join(projectDir, "index.html"),
      '<main data-composition-id="main" data-width="1920" data-height="1080" data-fps="24">' +
        '<div data-composition-src="compositions/kept.html" data-duration="2"></div></main>',
    );
    mkdirSync(join(projectDir, "compositions"), { recursive: true });
    // `<template>`-wrapped, as sub-compositions are actually authored: template
    // content is inert, so a DOM scan of these files would find nothing.
    for (const name of ["kept", "dropped"]) {
      writeFileSync(
        join(projectDir, "compositions", `${name}.html`),
        `<template id="${name}-template"><div data-composition-id="${name}" data-width="1920" data-height="1080"></div></template>`,
      );
    }
    writeFileSync(
      join(projectDir, "hyperframes.json"),
      JSON.stringify({
        registry: "https://example.test",
        registryItems: [
          { name: "kept", type: "hyperframes:block", target: "compositions/kept.html" },
          { name: "dropped", type: "hyperframes:block", target: "compositions/dropped.html" },
        ],
      }),
    );

    const plan = createRenderPlan({ dir: projectDir, output: "result.mp4" });
    expect(plan.catalogUsage).toEqual({
      installed: ["dropped", "kept"],
      usedBlocks: ["kept"],
      manifestUnreadable: false,
    });
  });

  it("preserves an explicit strict-readiness opt-in", () => {
    const plan = createRenderPlan({ dir: projectDir, "best-effort": false });
    expect(plan.bestEffort).toBe(false);
  });

  it.each([undefined, "off"])("preserves page motion blur override %s", (value) => {
    expect(createRenderPlan({ dir: projectDir, "page-motion-blur": value }).pageMotionBlur).toBe(
      value,
    );
  });

  it.each(["", "on", "false", "OFF"])("rejects unsupported page motion blur value %s", (value) => {
    expect(() => createRenderPlan({ dir: projectDir, "page-motion-blur": value })).toThrow(
      CliUsageError,
    );
  });

  it("preserves an aspect-agnostic resolution alias through the execution plan", () => {
    const plan = createRenderPlan({ dir: projectDir, resolution: "1080p" });
    expect(plan.outputResolution).toBe("landscape");
    expect(plan.outputResolutionAspectAgnostic).toBe(true);
    expect(plan.outputResolutionRaw).toBe("1080p");
  });

  it("classifies malformed command input as a usage error", () => {
    expect(() => createRenderPlan({ dir: projectDir, quality: "maximum" })).toThrow(CliUsageError);
  });

  it("maps looks to standard encode with CRF 16, and delivery to high", () => {
    expect(createRenderPlan({ dir: projectDir, quality: "looks" })).toMatchObject({
      quality: "standard",
      crf: 16,
    });
    expect(createRenderPlan({ dir: projectDir, quality: "delivery" })).toMatchObject({
      quality: "high",
      crf: undefined,
    });
    expect(createRenderPlan({ dir: projectDir })).toMatchObject({ quality: "standard", crf: 16 });
  });

  it("does not inject looks CRF when --crf or MOV is already set", () => {
    expect(createRenderPlan({ dir: projectDir, quality: "looks", crf: "20" }).crf).toBe(20);
    expect(
      createRenderPlan({ dir: projectDir, format: "mov", quality: "looks" }).crf,
    ).toBeUndefined();
  });

  it.each([
    ["--crf", { crf: "18" }],
    ["--video-bitrate", { "video-bitrate": "78M" }],
  ])("rejects unsupported %s rate control for ProRes MOV", (flag, encoderArgs) => {
    expect(() => createRenderPlan({ dir: projectDir, format: "mov", ...encoderArgs })).toThrow(
      CliUsageError,
    );
    expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(flag);
    expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(
      "fixed alpha-preserving ProRes 4444",
    );
  });

  it("keeps MOV quality tiers on the fixed alpha-preserving profile", () => {
    const plan = createRenderPlan({ dir: projectDir, format: "mov", quality: "high" });

    expect(plan).toMatchObject({ format: "mov", quality: "high" });
    expect(plan.crf).toBeUndefined();
    expect(plan.videoBitrate).toBeUndefined();
  });

  it("plans HLS as directory output with the default segment length", () => {
    const plan = createRenderPlan({ dir: projectDir, format: "hls" });

    expect(plan.format).toBe("hls");
    expect(plan.hlsSegmentSeconds).toBe(4);
    // No extension: outputPath is the directory the playlists are written into.
    expect(plan.outputPath.startsWith(resolve("renders", plan.project.name))).toBe(true);
    expect(basename(plan.outputPath)).not.toContain(".");
  });

  it("carries an explicit --hls-segment-seconds and rejects a fractional one", () => {
    expect(
      createRenderPlan({ dir: projectDir, format: "hls", "hls-segment-seconds": "6" })
        .hlsSegmentSeconds,
    ).toBe(6);
    expect(() =>
      createRenderPlan({ dir: projectDir, format: "hls", "hls-segment-seconds": "2.5" }),
    ).toThrow(CliUsageError);
  });

  it("leaves hlsSegmentSeconds unset for other formats", () => {
    expect(
      createRenderPlan({ dir: projectDir, format: "mp4", "hls-segment-seconds": "6" })
        .hlsSegmentSeconds,
    ).toBeUndefined();
  });

  it.each([
    ["--hdr", { hdr: true }],
    ["--gpu", { gpu: true }],
  ])("rejects %s with HLS output", (flag, conflicting) => {
    expect(() => createRenderPlan({ dir: projectDir, format: "hls", ...conflicting })).toThrow(
      CliUsageError,
    );
    expect(vi.mocked(console.error).mock.calls.flat().join("\n")).toContain(flag);
  });

  it("keeps MP4 and WebM rate controls available", () => {
    expect(createRenderPlan({ dir: projectDir, format: "mp4", crf: "18" }).crf).toBe(18);
    expect(
      createRenderPlan({ dir: projectDir, format: "webm", "video-bitrate": "10M" }).videoBitrate,
    ).toBe("10M");
  });

  it("rejects batch and single-render variables before execution", () => {
    expect(() =>
      createRenderPlan({ dir: projectDir, batch: "rows.json", variables: '{"name":"Ada"}' }),
    ).toThrow(CliUsageError);
  });

  it("keeps environment changes declarative until execution", () => {
    const previous = process.env.PRODUCER_LOW_MEMORY_MODE;
    delete process.env.PRODUCER_LOW_MEMORY_MODE;
    try {
      const plan = createRenderPlan({ dir: projectDir, "low-memory-mode": true });
      expect(plan.environment).toEqual({ PRODUCER_LOW_MEMORY_MODE: "true" });
      expect(process.env.PRODUCER_LOW_MEMORY_MODE).toBeUndefined();
    } finally {
      if (previous === undefined) delete process.env.PRODUCER_LOW_MEMORY_MODE;
      else process.env.PRODUCER_LOW_MEMORY_MODE = previous;
    }
  });

  it("resolves a relative frame-cache directory into the execution environment", () => {
    const plan = createRenderPlan({ dir: projectDir, "frames-cache-dir": "./frame-cache" });
    expect(plan.environment.HYPERFRAMES_EXTRACT_CACHE_DIR).toBe(resolve("./frame-cache"));
  });

  it("preserves frame-cache disable aliases for engine normalization", () => {
    const plan = createRenderPlan({ dir: projectDir, "frames-cache-dir": "OFF" });
    expect(plan.environment.HYPERFRAMES_EXTRACT_CACHE_DIR).toBe("OFF");
  });

  it("attributes a flag-less render to the skill persisted in hyperframes.json", () => {
    writeFileSync(
      join(projectDir, "hyperframes.json"),
      JSON.stringify({ authoringSkill: "product-launch-video" }),
    );
    const plan = createRenderPlan({ dir: projectDir });
    expect(plan.authoringSkill).toBe("product-launch-video");
    expect(plan.authoringSkillSource).toBe("project-config");
    expect(plan.invalidAuthoringSkill).toBeUndefined();
  });

  it("lets an explicit --skill flag override the persisted project owner", () => {
    writeFileSync(
      join(projectDir, "hyperframes.json"),
      JSON.stringify({ authoringSkill: "product-launch-video" }),
    );
    const plan = createRenderPlan({ dir: projectDir, skill: "motion-graphics" });
    expect(plan.authoringSkill).toBe("motion-graphics");
    expect(plan.authoringSkillSource).toBe("flag");
  });

  it("reports no authoring skill source when neither a flag nor a project config resolved one", () => {
    const plan = createRenderPlan({ dir: projectDir });
    expect(plan.authoringSkill).toBeUndefined();
    expect(plan.authoringSkillSource).toBeUndefined();
  });

  it("preserves a malformed --skill value for telemetry without adopting it as authoringSkill", () => {
    writeFileSync(
      join(projectDir, "hyperframes.json"),
      JSON.stringify({ authoringSkill: "product-launch-video" }),
    );
    // Fails SKILL_SLUG (spaces, uppercase): normalizeSkillSlug rejects the shape,
    // not a registry of known skill names.
    const plan = createRenderPlan({ dir: projectDir, skill: "Not A Skill!" });
    expect(plan.invalidAuthoringSkill).toBe("Not A Skill!");
    // The invalid flag never wins attribution: the project's own config still does.
    expect(plan.authoringSkill).toBe("product-launch-video");
    expect(plan.authoringSkillSource).toBe("project-config");
  });

  describe("hfEnvOverrides", () => {
    const savedEnv: Record<string, string | undefined> = {};
    const OVERRIDE_KEYS = [
      "HF_DE_VERIFY",
      "HF_TEST_ENV_INT",
      "HYPERFRAMES_ZZZ_TEST_OVERRIDE",
      "HYPERFRAMES_AAA_TEST_OVERRIDE",
      "HF_SHADER_WORKER_ENTRY",
    ];

    beforeEach(() => {
      for (const key of OVERRIDE_KEYS) savedEnv[key] = process.env[key];
    });

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

    it("reports an array (never absent) and never includes a key this test didn't set", () => {
      for (const key of OVERRIDE_KEYS) delete process.env[key];
      const plan = createRenderPlan({ dir: projectDir });
      expect(Array.isArray(plan.hfEnvOverrides)).toBe(true);
      for (const key of OVERRIDE_KEYS) expect(plan.hfEnvOverrides).not.toContain(key);
    });

    it("reports the sorted names (never values) of set HF_/HYPERFRAMES_ env vars", () => {
      process.env.HF_TEST_ENV_INT = "some-path-that-must-not-leak";
      process.env.HYPERFRAMES_ZZZ_TEST_OVERRIDE = "another-secret-looking-value";
      const plan = createRenderPlan({ dir: projectDir });
      expect(plan.hfEnvOverrides).toContain("HF_TEST_ENV_INT");
      expect(plan.hfEnvOverrides).toContain("HYPERFRAMES_ZZZ_TEST_OVERRIDE");
      expect(plan.hfEnvOverrides.join(" ")).not.toContain("some-path-that-must-not-leak");
      expect(plan.hfEnvOverrides.join(" ")).not.toContain("another-secret-looking-value");
    });

    it("sorts names rather than reporting them in process.env's insertion order", () => {
      process.env.HYPERFRAMES_ZZZ_TEST_OVERRIDE = "1";
      process.env.HYPERFRAMES_AAA_TEST_OVERRIDE = "1";
      const plan = createRenderPlan({ dir: projectDir });
      const indexOfAaa = plan.hfEnvOverrides.indexOf("HYPERFRAMES_AAA_TEST_OVERRIDE");
      const indexOfZzz = plan.hfEnvOverrides.indexOf("HYPERFRAMES_ZZZ_TEST_OVERRIDE");
      expect(indexOfAaa).toBeGreaterThanOrEqual(0);
      expect(indexOfAaa).toBeLessThan(indexOfZzz);
    });

    it("never reports the CLI's own shader-worker bootstrap key as an operator override", () => {
      // A real CLI run reaches this point with the key already set by cli.ts's bootstrap;
      // no test in this file goes through that bootstrap, so set it here.
      process.env.HF_SHADER_WORKER_ENTRY = "/some/dist/shaderTransitionWorker.js";
      const plan = createRenderPlan({ dir: projectDir });
      expect(plan.hfEnvOverrides).not.toContain("HF_SHADER_WORKER_ENTRY");
    });
  });

  it("defaults the segmented resume flags off and reads --resume / --keep-segments", () => {
    const off = createRenderPlan({ dir: projectDir });
    expect(off.resumeSegments).toBe(false);
    expect(off.keepSegments).toBe(false);
    const on = createRenderPlan({ dir: projectDir, resume: true, "keep-segments": true });
    expect(on.resumeSegments).toBe(true);
    expect(on.keepSegments).toBe(true);
  });
});