Skip to content

Write HTML. Render video. Built for agents.

23.3 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from "vitest";
import { Hono } from "hono";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  truncateSync,
  utimesSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { pruneThumbnailCache, registerThumbnailRoutes } from "./thumbnail";
import { PREVIEW_CAPTURE_PARAM } from "./preview";
import type { StudioApiAdapter } from "../types";
import { createProjectSignature } from "../helpers/projectSignature.js";
import { proxyActivityMark } from "../helpers/proxyTranscoder.js";

vi.mock("../helpers/proxyTranscoder.js", async (importOriginal) => ({
  ...(await importOriginal<typeof import("../helpers/proxyTranscoder.js")>()),
  proxyActivityMark: vi.fn(() => "0"),
}));

const tempProjectDirs: string[] = [];

afterEach(() => {
  for (const dir of tempProjectDirs.splice(0)) {
    rmSync(dir, { recursive: true, force: true });
  }
});

function createAdapter(): StudioApiAdapter {
  const projectDir = mkdtempSync(join(tmpdir(), "hf-thumbnail-test-"));
  tempProjectDirs.push(projectDir);

  return {
    listProjects: () => [],
    resolveProject: async (id: string) => ({ id, dir: projectDir }),
    bundle: async () => null,
    lint: async () => ({ findings: [] }),
    runtimeUrl: "/api/runtime.js",
    rendersDir: () => "/tmp/renders",
    startRender: () => ({
      id: "job-1",
      status: "rendering",
      progress: 0,
      outputPath: "/tmp/out.mp4",
    }),
    generateThumbnail: vi.fn(async () => Buffer.from("thumb")),
  };
}

async function writeComposition(
  adapter: StudioApiAdapter,
  width: number,
  height: number,
): Promise<void> {
  const project = await adapter.resolveProject("demo");
  if (!project) throw new Error("missing project");
  writeFileSync(
    join(project.dir, "index.html"),
    `<div data-width="${width}" data-height="${height}"></div>`,
  );
}

describe("registerThumbnailRoutes", () => {
  it("screenshots the capture variant of the preview document", async () => {
    const adapter = createAdapter();
    await writeComposition(adapter, 1920, 1080);
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    const loaded: string[] = [];
    vi.mocked(adapter.generateThumbnail!).mockImplementation(async ({ previewUrl }) => {
      loaded.push(new URL(previewUrl).search);
      return Buffer.from("thumb");
    });

    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=6");
    await app.request("http://localhost/projects/demo/thumbnail/scenes%2Fb.html?t=6");

    expect(loaded).toEqual([`?${PREVIEW_CAPTURE_PARAM}=1`, `?${PREVIEW_CAPTURE_PARAM}=1`]);
  });

  it("forwards selector queries to thumbnail generation", async () => {
    const adapter = createAdapter();
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const response = await app.request(
      "http://localhost/projects/demo/thumbnail/index.html?t=1.2&selector=%23title-card",
    );

    expect(response.status).toBe(200);
    expect(adapter.generateThumbnail).toHaveBeenCalledWith(
      expect.objectContaining({
        compPath: "index.html",
        seekTime: 1.2,
        selector: "#title-card",
        format: "jpeg",
        outputWidth: 240,
        outputHeight: 135,
        signal: expect.any(AbortSignal),
      }),
    );
  });

  it("keeps selectors that differ only in punctuation apart in the cache", async () => {
    const adapter = createAdapter();
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    for (const selector of ["%23a%5C.b", "%23a_b", "%23a%5C.b"]) {
      await app.request(
        `http://localhost/projects/demo/thumbnail/index.html?t=1.2&selector=${selector}`,
      );
    }

    expect(vi.mocked(adapter.generateThumbnail!).mock.calls.map(([opts]) => opts.selector)).toEqual(
      ["#a\\.b", "#a_b"],
    );
  });

  it("maps square authored dimensions across jpeg output modes", async () => {
    const adapter = createAdapter();
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    await writeComposition(adapter, 1080, 1080);

    const sourceResponse = await app.request(
      "http://localhost/projects/demo/thumbnail/index.html?t=1.2&output=source",
    );
    const previewResponse = await app.request(
      "http://localhost/projects/demo/thumbnail/index.html?t=1.2&output=preview",
    );

    expect(sourceResponse.status).toBe(200);
    expect(previewResponse.status).toBe(200);
    expect(adapter.generateThumbnail).toHaveBeenNthCalledWith(
      1,
      expect.objectContaining({
        format: "jpeg",
        outputWidth: 1080,
        outputHeight: 1080,
      }),
    );
    expect(adapter.generateThumbnail).toHaveBeenNthCalledWith(
      2,
      expect.objectContaining({ outputWidth: 135, outputHeight: 135 }),
    );
  });

  it("answers a cache-only request from the cache, with no content and no render on a miss", async () => {
    const adapter = createAdapter();
    await writeComposition(adapter, 1920, 1080);
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    const url = "http://localhost/projects/demo/thumbnail/index.html?t=0&output=source";

    const miss = await app.request(`${url}&cached=1`);
    expect(miss.status).toBe(204);
    expect(miss.headers.get("Cache-Control")).toBe("no-cache");
    expect(await miss.text()).toBe("");
    expect(adapter.generateThumbnail).not.toHaveBeenCalled();

    expect((await app.request(url)).status).toBe(200);
    const hit = await app.request(`${url}&cached=1`);
    expect(hit.status).toBe(200);
    expect(await hit.text()).toBe("thumb");
    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
  });

  it("deduplicates concurrent generation and writes one complete cache entry", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    let resolve!: (buffer: Buffer) => void;
    const generated = new Promise<Buffer>((done) => (resolve = done));
    adapter.generateThumbnail = vi.fn(async () => generated);
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
    const first = app.request(url);
    const second = app.request(url);
    await vi.waitFor(() => expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1));
    resolve(Buffer.from("shared"));

    expect(await (await first).text()).toBe("shared");
    expect(await (await second).text()).toBe("shared");
    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
    const cached = readdirSync(join(project.dir, ".thumbnails"));
    expect(cached).toHaveLength(1);
    expect(cached[0]).not.toContain(".tmp");
  });

  it("forwards png capture requests and returns a png content type", async () => {
    const adapter = createAdapter();
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const response = await app.request(
      "http://localhost/projects/demo/thumbnail/compositions%2Fintro.html?t=2&format=png",
    );

    expect(response.status).toBe(200);
    expect(response.headers.get("Content-Type")).toBe("image/png");
    expect(adapter.generateThumbnail).toHaveBeenCalledWith(
      expect.objectContaining({
        compPath: "compositions/intro.html",
        seekTime: 2,
        format: "png",
        outputWidth: 1920,
        outputHeight: 1080,
      }),
    );
  });

  it("allows png callers to opt into bounded preview output", async () => {
    const adapter = createAdapter();
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const response = await app.request(
      "http://localhost/projects/demo/thumbnail/index.html?format=png&output=preview",
    );

    expect(response.status).toBe(200);
    expect(adapter.generateThumbnail).toHaveBeenCalledWith(
      expect.objectContaining({ outputWidth: 240, outputHeight: 135 }),
    );
  });

  it("preserves an explicit zero seek time", async () => {
    const adapter = createAdapter();
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const response = await app.request(
      "http://localhost/projects/demo/thumbnail/index.html?t=0&format=png",
    );

    expect(response.status).toBe(200);
    expect(adapter.generateThumbnail).toHaveBeenCalledWith(
      expect.objectContaining({
        compPath: "index.html",
        seekTime: 0,
        format: "png",
      }),
    );
  });

  it("forwards selector occurrence indexes to thumbnail generation", async () => {
    const adapter = createAdapter();
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const response = await app.request(
      "http://localhost/projects/demo/thumbnail/index.html?t=1.2&selector=.card&selectorIndex=2",
    );

    expect(response.status).toBe(200);
    expect(adapter.generateThumbnail).toHaveBeenCalledWith(
      expect.objectContaining({
        selector: ".card",
        selectorIndex: 2,
      }),
    );
  });

  it("keeps url thumbnail versions separated in the disk cache", async () => {
    const adapter = createAdapter();
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=old");
    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=old");
    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=new");

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  it("keeps changed composition dimensions separated in the disk cache", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const indexPath = join(project.dir, "index.html");
    writeFileSync(indexPath, `<div data-composition-id="main" data-width="640" data-height="360">`);
    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");

    writeFileSync(
      indexPath,
      `<div data-composition-id="main" data-width="1280" data-height="720">`,
    );
    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
    expect(adapter.generateThumbnail).toHaveBeenLastCalledWith(
      expect.objectContaining({
        width: 1280,
        height: 720,
      }),
    );
  });

  it("keeps changed studio manual edits separated in the disk cache", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const indexPath = join(project.dir, "index.html");
    writeFileSync(indexPath, `<div data-composition-id="main" data-width="640" data-height="360">`);
    const manualEditsDir = join(project.dir, ".hyperframes");
    mkdirSync(manualEditsDir, { recursive: true });
    const manualEditsPath = join(manualEditsDir, "studio-manual-edits.json");
    writeFileSync(manualEditsPath, `{"version":1,"edits":[]}`);

    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
    writeFileSync(
      manualEditsPath,
      `{"version":1,"edits":[{"kind":"rotation","target":{"sourceFile":"index.html","id":"card"},"angle":30}]}`,
    );
    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  it("regenerates when the composition HTML changes even with explicit w/h", async () => {
    // Repro: the Studio requests thumbnails WITH explicit dimensions. The old
    // code only read (and keyed on) the composition file when no w/h was given,
    // so editing the HTML left the disk-cache key unchanged and served a stale
    // thumbnail — even after a hard reload. The content hash must always be keyed.
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const indexPath = join(project.dir, "index.html");
    const url = "http://localhost/projects/demo/thumbnail/index.html?t=2&w=640&h=360&v=test";

    writeFileSync(indexPath, `<div id="box">before</div>`);
    await app.request(url);
    writeFileSync(indexPath, `<div id="box">after</div>`);
    await app.request(url);

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  it("regenerates a parent thumbnail when nested composition HTML changes", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    writeFileSync(
      join(project.dir, "index.html"),
      `<div data-width="640" data-height="360" data-composition-src="compositions/nested.html"></div>`,
    );
    const compositionsDir = join(project.dir, "compositions");
    mkdirSync(compositionsDir, { recursive: true });
    const nestedPath = join(compositionsDir, "nested.html");
    writeFileSync(nestedPath, `<div>before</div>`);
    const url = "http://localhost/projects/demo/thumbnail/index.html?t=2&v=test";

    await app.request(url);
    writeFileSync(nestedPath, `<div>after with a different size</div>`);
    await app.request(url);

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  function writeTwoScenes(dir: string): { sceneA: string; sceneB: string } {
    writeFileSync(
      join(dir, "index.html"),
      `<head><style>body { margin: 0 }</style></head><div data-width="640" data-height="360">` +
        `<div data-composition-src="compositions/a.html"></div>` +
        `<div data-composition-src="compositions/b.html"></div></div>`,
    );
    mkdirSync(join(dir, "compositions"), { recursive: true });
    const sceneA = join(dir, "compositions", "a.html");
    const sceneB = join(dir, "compositions", "b.html");
    writeFileSync(sceneA, `<template><div data-composition-id="a">A</div></template>`);
    writeFileSync(sceneB, `<template><div data-composition-id="b">B</div></template>`);
    return { sceneA, sceneB };
  }

  it("keeps a scene's cached thumbnail when a sibling scene changes", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    const { sceneA } = writeTwoScenes(project.dir);
    const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=2&v=test";

    await app.request(url);
    writeFileSync(sceneA, `<template><div data-composition-id="a">A, edited</div></template>`);
    await app.request(url);

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
  });

  it("regenerates a scene thumbnail when the root it is built on changes", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    writeTwoScenes(project.dir);
    const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=2&v=test";

    await app.request(url);
    const root = join(project.dir, "index.html");
    writeFileSync(root, readFileSync(root, "utf-8").replace("margin: 0", "margin: 4px"));
    await app.request(url);

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  it("regenerates a thumbnail when imported CSS changes", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    writeFileSync(
      join(project.dir, "index.html"),
      `<link rel="stylesheet" href="./styles.css"><div data-width="640" data-height="360"></div>`,
    );
    const stylesPath = join(project.dir, "styles.css");
    writeFileSync(stylesPath, `.card { color: red; }`);
    const url = "http://localhost/projects/demo/thumbnail/index.html?t=2&v=test";

    await app.request(url);
    writeFileSync(stylesPath, `.card { color: rebeccapurple; }`);
    await app.request(url);

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  it("uses the adapter-cached project signature for disk reuse and in-flight dedupe", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const getProjectSignature = vi.fn(() => createProjectSignature(project.dir));
    adapter.getProjectSignature = getProjectSignature;
    let resolve!: (buffer: Buffer) => void;
    const generated = new Promise<Buffer>((done) => (resolve = done));
    adapter.generateThumbnail = vi.fn(async () => generated);
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";

    const first = app.request(url);
    const duplicate = app.request(url);
    await vi.waitFor(() => expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1));
    resolve(Buffer.from("shared"));
    expect(await (await first).text()).toBe("shared");
    expect(await (await duplicate).text()).toBe("shared");
    expect(await (await app.request(url)).text()).toBe("shared");

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
    expect(getProjectSignature).toHaveBeenCalledTimes(4);
    expect(getProjectSignature).toHaveBeenNthCalledWith(1, project.dir);
  });

  it("does not cache generated pixels when the composition's inputs changed in flight", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const { sceneB } = writeTwoScenes(project.dir);
    adapter.generateThumbnail = vi
      .fn()
      .mockImplementationOnce(async () => {
        writeFileSync(sceneB, `<template><div data-composition-id="b">B, edited</div></template>`);
        return Buffer.from("rendered-after-change");
      })
      .mockResolvedValueOnce(Buffer.from("rendered-current"));
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=3";

    expect(await (await app.request(url)).text()).toBe("rendered-after-change");
    expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
    expect(await (await app.request(url)).text()).toBe("rendered-current");
    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  it("does not cache a thumbnail rendered while a clip's preview copy is still being made", async () => {
    const adapter = createAdapter();
    await writeComposition(adapter, 1920, 1080);
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    vi.mocked(proxyActivityMark).mockReturnValueOnce(null).mockReturnValueOnce(null);
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";

    expect((await app.request(url)).status).toBe(200);
    expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
    expect((await app.request(url)).status).toBe(200);
    expect(existsSync(join(project.dir, ".thumbnails"))).toBe(true);
    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  it("does not cache a thumbnail when a preview copy starts or lands during the render", async () => {
    const adapter = createAdapter();
    await writeComposition(adapter, 1920, 1080);
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    vi.mocked(proxyActivityMark).mockReturnValueOnce("0").mockReturnValueOnce("1");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    expect(
      (await app.request("http://localhost/projects/demo/thumbnail/index.html?t=3")).status,
    ).toBe(200);
    expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
  });

  it("does not cache pixels changed in flight behind a stale adapter signature", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const { sceneB } = writeTwoScenes(project.dir);
    const stale = createProjectSignature(project.dir);
    adapter.getProjectSignature = () => stale;
    adapter.generateThumbnail = vi
      .fn()
      .mockImplementationOnce(async () => {
        writeFileSync(sceneB, `<template><div data-composition-id="b">B, edited</div></template>`);
        return Buffer.from("rendered-after-change");
      })
      .mockResolvedValueOnce(Buffer.from("rendered-again"));
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);
    const url = "http://localhost/projects/demo/thumbnail/compositions/b.html?t=3";

    expect(await (await app.request(url)).text()).toBe("rendered-after-change");
    expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
    expect(await (await app.request(url)).text()).toBe("rendered-again");
  });

  it("keeps changed studio motion separated in the disk cache", async () => {
    const adapter = createAdapter();
    const project = await adapter.resolveProject("demo");
    if (!project) throw new Error("missing project");
    const app = new Hono();
    registerThumbnailRoutes(app, adapter);

    const indexPath = join(project.dir, "index.html");
    writeFileSync(indexPath, `<div data-composition-id="main" data-width="640" data-height="360">`);
    const motionDir = join(project.dir, ".hyperframes");
    mkdirSync(motionDir, { recursive: true });
    const motionPath = join(motionDir, "studio-motion.json");
    writeFileSync(motionPath, `{"version":1,"motions":[]}`);

    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");
    writeFileSync(
      motionPath,
      `{"version":1,"motions":[{"kind":"gsap-motion","target":{"sourceFile":"index.html","id":"card"},"start":0,"duration":1,"ease":"power2.out","from":{"y":32},"to":{"y":0}}]}`,
    );
    await app.request("http://localhost/projects/demo/thumbnail/index.html?t=2&v=test");

    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
  });

  it("prunes expired and over-budget files without touching protected work", () => {
    const cacheDir = mkdtempSync(join(tmpdir(), "hf-thumbnail-cache-test-"));
    tempProjectDirs.push(cacheDir);
    const expiredPath = join(cacheDir, "expired.jpg");
    const protectedPath = join(cacheDir, "protected.jpg");
    const overflowPath = join(cacheDir, "overflow.jpg");
    writeFileSync(expiredPath, "expired");
    writeFileSync(protectedPath, "protected");
    writeFileSync(overflowPath, "overflow");
    const now = Date.now();
    const expiredSeconds = (now - 15 * 24 * 60 * 60 * 1000) / 1000;
    utimesSync(expiredPath, expiredSeconds, expiredSeconds);
    truncateSync(protectedPath, 400 * 1024 * 1024);
    truncateSync(overflowPath, 200 * 1024 * 1024);

    pruneThumbnailCache(cacheDir, new Set([protectedPath]), now);

    expect(existsSync(expiredPath)).toBe(false);
    expect(existsSync(protectedPath)).toBe(true);
    expect(existsSync(overflowPath)).toBe(false);
  });
});