Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { afterEach, describe, expect, it, vi } from "vitest";
import { Hono } from "hono";
import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { VALID_CANVAS_RESOLUTIONS } from "@hyperframes/parsers";
import { registerRenderRoutes } from "./render";
import type { StudioApiAdapter } from "../types";
function createAdapter(
startRenderSpy: ReturnType<typeof vi.fn>,
rendersDir = mkdtempSync(join(tmpdir(), "hf-render-test-")),
): { adapter: StudioApiAdapter; rendersDir: string } {
const adapter: StudioApiAdapter = {
listProjects: () => [],
// Use a real, existing dir: isSafePath() canonicalizes the project dir with
// realpath and fails closed if it doesn't exist (real projects always do).
resolveProject: async (id: string) => ({ id, dir: tmpdir() }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => rendersDir,
startRender: (opts) => {
startRenderSpy(opts);
return {
id: opts.jobId,
status: "rendering",
progress: 0,
outputPath: opts.outputPath,
};
},
};
return { adapter, rendersDir };
}
function buildApp(spy: ReturnType<typeof vi.fn>): {
app: Hono;
rendersDir: string;
cleanup: () => void;
} {
const { adapter, rendersDir } = createAdapter(spy);
const app = new Hono();
registerRenderRoutes(app, adapter);
return { app, rendersDir, cleanup: () => rmSync(rendersDir, { recursive: true, force: true }) };
}
describe("GET /projects/:id/renders — stale sidecar status", () => {
it("does not mark an existing output failed from stale metadata", async () => {
const spy = vi.fn();
const { app, rendersDir, cleanup } = buildApp(spy);
try {
writeFileSync(join(rendersDir, "retry.mp4"), "valid-output");
writeFileSync(
join(rendersDir, "retry.meta.json"),
JSON.stringify({ status: "failed", error: "first attempt" }),
);
const res = await app.request("http://localhost/projects/demo/renders");
expect(res.status).toBe(200);
const body = await res.json();
expect(body.renders).toEqual([expect.objectContaining({ id: "retry", status: "complete" })]);
} finally {
cleanup();
}
});
});
describe("POST /projects/:id/render — outputResolution forwarding", () => {
it("forwards a valid resolution preset to the adapter", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "high",
format: "mp4",
resolution: "landscape-4k",
}),
});
expect(res.status).toBe(200);
expect(spy).toHaveBeenCalledOnce();
const opts = spy.mock.calls[0][0];
expect(opts.outputResolution).toBe("landscape-4k");
} finally {
cleanup();
}
});
it("omits outputResolution when the request does not specify one", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4" }),
});
expect(res.status).toBe(200);
const opts = spy.mock.calls[0][0];
expect(opts.outputResolution).toBeUndefined();
} finally {
cleanup();
}
});
it("drops an invalid resolution string (defense-in-depth, not a 400)", async () => {
// The route is intentionally lenient on unknown enum values — the producer
// is the source of truth for validation and emits a clear error message.
// We just want to make sure garbage doesn't propagate as if it were valid.
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4", resolution: "8k" }),
});
expect(res.status).toBe(200);
const opts = spy.mock.calls[0][0];
expect(opts.outputResolution).toBeUndefined();
} finally {
cleanup();
}
});
// Contract pin per PR #2529 R2 review: the HTTP route accepts canonical
// presets only, not the CLI-side tier aliases (`1080p` / `hd` / `4k` /
// `uhd`, `landscape-4k` is already canonical). Miga asked that Studio
// Server's contract stay explicit here rather than silently extending it.
// Aliases fall through to the same `undefined` sink as any unknown value,
// which means the render falls back to composition dimensions — a safe,
// deliberate no-op rather than a portrait-1080p failure mode.
it.each(["1080p", "4k", "hd", "uhd"])(
"does NOT accept the CLI-side tier alias %s (canonical-only contract)",
async (alias) => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "standard",
format: "mp4",
resolution: alias,
}),
});
expect(res.status).toBe(200);
// Alias falls through to undefined → render uses composition dims.
// If Studio Server ever extends its contract to accept aliases,
// it must also plumb `outputResolutionAspectAgnostic` alongside so
// the compile stage can remap orientation; today the surface is
// deliberately narrow.
expect(spy.mock.calls[0][0].outputResolution).toBeUndefined();
} finally {
cleanup();
}
},
);
it("accepts each canonical preset value", async () => {
for (const preset of VALID_CANVAS_RESOLUTIONS) {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4", resolution: preset }),
});
expect(spy.mock.calls[0][0].outputResolution).toBe(preset);
} finally {
cleanup();
}
}
});
});
describe("POST /projects/:id/render — composition forwarding", () => {
it("forwards a valid composition path to the adapter", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "standard",
format: "mp4",
composition: "compositions/intro.html",
}),
});
expect(res.status).toBe(200);
expect(spy).toHaveBeenCalledOnce();
expect(spy.mock.calls[0][0].composition).toBe("compositions/intro.html");
} finally {
cleanup();
}
});
it("omits composition when not specified", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4" }),
});
expect(res.status).toBe(200);
expect(spy.mock.calls[0][0].composition).toBeUndefined();
} finally {
cleanup();
}
});
it("omits composition when empty string", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4", composition: "" }),
});
expect(res.status).toBe(200);
expect(spy.mock.calls[0][0].composition).toBeUndefined();
} finally {
cleanup();
}
});
it("rejects path-traversal attempts with 400", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "standard",
format: "mp4",
composition: "../../../etc/passwd",
}),
});
expect(res.status).toBe(400);
expect(spy).not.toHaveBeenCalled();
} finally {
cleanup();
}
});
});
describe("POST /projects/:id/render — fps wire format", () => {
// The fps fraction-syntax feature accepts JSON `number` (integer fps) and
// JSON `string` (ffmpeg-style rational) on the wire, normalizing both to
// the structured Fps form before invoking the adapter.
it("forwards integer fps as { num, den: 1 }", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 60, quality: "standard", format: "mp4" }),
});
expect(spy.mock.calls[0][0].fps).toEqual({ num: 60, den: 1 });
} finally {
cleanup();
}
});
it("parses '30000/1001' string body as exact NTSC", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: "30000/1001", quality: "standard", format: "mp4" }),
});
expect(spy.mock.calls[0][0].fps).toEqual({ num: 30000, den: 1001 });
} finally {
cleanup();
}
});
it("falls back to 30/1 for malformed fps values", async () => {
// Matches the lenient handling of `quality` and `resolution` in the same
// route — the producer surfaces a clearer downstream error if the value
// is genuinely unusable.
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: "abc", quality: "standard", format: "mp4" }),
});
expect(spy.mock.calls[0][0].fps).toEqual({ num: 30, den: 1 });
} finally {
cleanup();
}
});
it("falls back to 30/1 when fps is omitted", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ quality: "standard", format: "mp4" }),
});
expect(spy.mock.calls[0][0].fps).toEqual({ num: 30, den: 1 });
} finally {
cleanup();
}
});
});
describe("POST /projects/:id/render — crf", () => {
async function post(body: Record<string, unknown>) {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", ...body }),
});
return { res, opts: spy.mock.calls[0]?.[0] };
} finally {
cleanup();
}
}
it("forwards a valid crf for mp4 and webm", async () => {
expect((await post({ format: "mp4", crf: 12 })).opts.crf).toBe(12);
expect((await post({ format: "webm", crf: 63 })).opts.crf).toBe(63);
});
it("omits crf when the request does not specify one", async () => {
const { res, opts } = await post({ format: "mp4" });
expect(res.status).toBe(200);
expect(opts).not.toHaveProperty("crf");
});
it("ignores crf for mov, which has no CRF", async () => {
const { res, opts } = await post({ format: "mov", crf: 12 });
expect(res.status).toBe(200);
expect(opts).not.toHaveProperty("crf");
});
it("forwards the other encoder options and refuses crf with a bitrate", async () => {
const { opts } = await post({
format: "mp4",
videoBitrate: "10M",
videoFrameFormat: "png",
hdrMode: "force-sdr",
});
expect(opts).toMatchObject({
videoBitrate: "10M",
videoFrameFormat: "png",
hdrMode: "force-sdr",
});
const both = await post({ format: "mp4", crf: 12, videoBitrate: "10M" });
expect(both.res.status).toBe(400);
expect(both.opts).toBeUndefined();
});
it.each([
["mp4", 52],
["mp4", -1],
["mp4", 12.5],
["mp4", "12"],
["webm", 64],
])("rejects %s crf %j with 400 and does not start a render", async (format, crf) => {
const { res, opts } = await post({ format, crf });
expect(res.status).toBe(400);
expect(opts).toBeUndefined();
});
});
describe("POST /projects/:id/render — composition path safety", () => {
const tmpDirs: string[] = [];
function buildAppWithProjectDir(spy: ReturnType<typeof vi.fn>): {
app: Hono;
projectDir: string;
} {
const projectDir = mkdtempSync(join(tmpdir(), "hf-render-proj-"));
const rendersDir = mkdtempSync(join(tmpdir(), "hf-render-out-"));
tmpDirs.push(projectDir, rendersDir);
const adapter: StudioApiAdapter = {
listProjects: () => [],
resolveProject: async (id: string) => ({ id, dir: projectDir }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => rendersDir,
startRender: (opts) => {
spy(opts);
return { id: opts.jobId, status: "rendering", progress: 0, outputPath: opts.outputPath };
},
};
const app = new Hono();
registerRenderRoutes(app, adapter);
return { app, projectDir };
}
afterEach(() => {
for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
tmpDirs.length = 0;
});
async function postComposition(app: Hono, composition: string): Promise<Response> {
return app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4", composition }),
});
}
// Mirror the repo convention (preview.test.ts): skip symlink cases on
// non-symlink-privileged Windows runners rather than crash the suite.
function tryCreateSymlink(target: string, path: string, type: "dir" | "file"): boolean {
try {
symlinkSync(target, path, type);
return true;
} catch {
return false;
}
}
it("accepts a composition path inside the project directory", async () => {
const spy = vi.fn();
const { app } = buildAppWithProjectDir(spy);
const res = await postComposition(app, "scenes/intro.html");
expect(res.status).toBe(200);
expect(spy).toHaveBeenCalledOnce();
});
it("rejects a `..` traversal in the composition path", async () => {
const spy = vi.fn();
const { app } = buildAppWithProjectDir(spy);
const res = await postComposition(app, "../../etc/passwd");
expect(res.status).toBe(400);
expect(spy).not.toHaveBeenCalled();
});
it("rejects a composition reached through an in-project symlink pointing outside the project", async () => {
const spy = vi.fn();
const { app, projectDir } = buildAppWithProjectDir(spy);
const external = mkdtempSync(join(tmpdir(), "hf-render-external-"));
tmpDirs.push(external);
writeFileSync(join(external, "secret.html"), "<html></html>");
if (!tryCreateSymlink(external, join(projectDir, "link"), "dir")) return;
const res = await postComposition(app, "link/secret.html");
expect(res.status).toBe(400);
expect(spy).not.toHaveBeenCalled();
});
it("allows a composition reached through an in-project symlink that stays inside the project", async () => {
const spy = vi.fn();
const { app, projectDir } = buildAppWithProjectDir(spy);
mkdirSync(join(projectDir, "real"));
writeFileSync(join(projectDir, "real", "scene.html"), "<html></html>");
if (!tryCreateSymlink(join(projectDir, "real"), join(projectDir, "alias"), "dir")) return;
const res = await postComposition(app, "alias/scene.html");
expect(res.status).toBe(200);
expect(spy).toHaveBeenCalledOnce();
});
});
describe("GET /projects/:id/renders/file/* — path safety", () => {
const tmpDirs: string[] = [];
function buildApp(): { app: Hono; rendersDir: string } {
const rendersDir = mkdtempSync(join(tmpdir(), "hf-renders-out-"));
tmpDirs.push(rendersDir);
const adapter: StudioApiAdapter = {
listProjects: () => [],
resolveProject: async (id: string) => ({ id, dir: tmpdir() }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => rendersDir,
startRender: (opts) => ({
id: opts.jobId,
status: "rendering",
progress: 0,
outputPath: opts.outputPath,
}),
};
const app = new Hono();
registerRenderRoutes(app, adapter);
return { app, rendersDir };
}
// Mirror the repo convention (preview.test.ts / composition tests above):
// skip symlink cases on non-symlink-privileged Windows runners.
function tryCreateSymlink(target: string, path: string, type: "dir" | "file"): boolean {
try {
symlinkSync(target, path, type);
return true;
} catch {
return false;
}
}
afterEach(() => {
for (const d of tmpDirs) rmSync(d, { recursive: true, force: true });
tmpDirs.length = 0;
});
it("serves non-Latin-1 filenames with RFC 6266 content dispositions", async () => {
const filename = "測試.mp4";
const { app, rendersDir } = buildApp();
const outputPath = join(rendersDir, filename);
writeFileSync(outputPath, "render-bytes");
const listResponse = await app.request("http://localhost/projects/demo/renders");
expect(listResponse.status).toBe(200);
const jobId = encodeURIComponent(filename.replace(/\.mp4$/, ""));
const expectedFilename = `filename="__.mp4"; filename*=UTF-8''${encodeURIComponent(filename)}`;
const responses = [
{
response: await app.request(`http://localhost/render/${jobId}/view`),
disposition: "inline",
},
{
response: await app.request(`http://localhost/render/${jobId}/download`),
disposition: "attachment",
},
{
response: await app.request(
`http://localhost/projects/demo/renders/file/${encodeURIComponent(filename)}`,
),
disposition: "inline",
},
];
for (const { response, disposition } of responses) {
expect(response.status).toBe(200);
const header = response.headers.get("Content-Disposition");
expect(header).toBe(`${disposition}; ${expectedFilename}`);
expect(header).toMatch(/^[\x20-\x7e]+$/);
}
});
it("refuses the desktop app's records when renders/ is linked into .hyperframes/", async () => {
const project = mkdtempSync(join(tmpdir(), "hf-renders-project-"));
tmpDirs.push(project);
mkdirSync(join(project, ".hyperframes"));
writeFileSync(join(project, ".hyperframes", "app-history.jsonl"), '{"asked":"secret"}');
if (!tryCreateSymlink(join(project, ".hyperframes"), join(project, "renders"), "dir")) return;
const app = new Hono();
registerRenderRoutes(app, {
listProjects: () => [],
resolveProject: async (id: string) => ({ id, dir: project }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => join(project, "renders"),
startRender: (opts) => ({
id: opts.jobId,
status: "rendering",
progress: 0,
outputPath: opts.outputPath,
}),
});
const res = await app.request("http://localhost/projects/demo/renders/file/app-history.jsonl");
expect(res.status).toBe(403);
expect(await res.text()).not.toContain("secret");
});
it("never lists, views or downloads a render that links to the app's records", async () => {
const project = mkdtempSync(join(tmpdir(), "hf-renders-project-"));
tmpDirs.push(project);
mkdirSync(join(project, ".hyperframes"));
mkdirSync(join(project, "renders"));
writeFileSync(join(project, ".hyperframes", "app-history.jsonl"), '{"asked":"secret"}');
writeFileSync(join(project, "renders", "real.mp4"), "render-bytes");
const leak = join(project, "renders", "leak.mp4");
if (!tryCreateSymlink(join(project, ".hyperframes", "app-history.jsonl"), leak, "file")) return;
const app = new Hono();
registerRenderRoutes(app, {
listProjects: () => [],
resolveProject: async (id: string) => ({ id, dir: project }),
bundle: async () => null,
lint: async () => ({ findings: [] }),
runtimeUrl: "/api/runtime.js",
rendersDir: () => join(project, "renders"),
startRender: (opts) => ({
id: opts.jobId,
status: "rendering",
progress: 0,
outputPath: opts.outputPath,
}),
});
const list = (await (await app.request("http://localhost/projects/demo/renders")).json()) as {
renders: { id: string }[];
};
expect(list.renders.map((r) => r.id)).toEqual(["real"]);
for (const kind of ["view", "download"]) {
const res = await app.request(`http://localhost/render/leak/${kind}`);
expect(res.status).toBe(404);
expect(await res.text()).not.toContain("secret");
expect((await app.request(`http://localhost/render/real/${kind}`)).status).toBe(200);
}
});
it("serves a render file that lives inside rendersDir", async () => {
const { app, rendersDir } = buildApp();
writeFileSync(join(rendersDir, "demo.mp4"), "render-bytes");
const res = await app.request("http://localhost/projects/demo/renders/file/demo.mp4");
expect(res.status).toBe(200);
expect(await res.text()).toBe("render-bytes");
});
it("rejects a file reached through a symlink inside rendersDir pointing outside it", async () => {
const { app, rendersDir } = buildApp();
// A bare join()+readFileSync followed the symlink and leaked the target;
// the resolveWithinProject chokepoint canonicalizes with realpath first.
const external = mkdtempSync(join(tmpdir(), "hf-renders-external-"));
tmpDirs.push(external);
writeFileSync(join(external, "secret.txt"), "TOP-SECRET");
if (!tryCreateSymlink(join(external, "secret.txt"), join(rendersDir, "leak.txt"), "file"))
return;
const res = await app.request("http://localhost/projects/demo/renders/file/leak.txt");
expect(res.status).toBe(403);
expect(await res.text()).not.toContain("TOP-SECRET");
});
it("serves a render file reached through a symlink that stays inside rendersDir", async () => {
const { app, rendersDir } = buildApp();
mkdirSync(join(rendersDir, "nested"));
writeFileSync(join(rendersDir, "nested", "clip.mp4"), "nested-bytes");
if (!tryCreateSymlink(join(rendersDir, "nested"), join(rendersDir, "alias"), "dir")) return;
const res = await app.request("http://localhost/projects/demo/renders/file/alias/clip.mp4");
expect(res.status).toBe(200);
expect(await res.text()).toBe("nested-bytes");
});
});
describe("POST /render/:jobId/cancel", () => {
async function startJob(app: Hono): Promise<string> {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4" }),
});
expect(res.status).toBe(200);
return ((await res.json()) as { jobId: string }).jobId;
}
it("marks a rendering job cancelled and invokes the adapter abort hook", async () => {
const spy = vi.fn();
let aborted = false;
const { adapter, rendersDir } = createAdapter(spy);
const baseStartRender = adapter.startRender.bind(adapter);
adapter.startRender = (opts) => {
const state = baseStartRender(opts);
state.cancel = () => {
aborted = true;
};
return state;
};
const app = new Hono();
registerRenderRoutes(app, adapter);
try {
const jobId = await startJob(app);
const res = await app.request(`http://localhost/render/${jobId}/cancel`, { method: "POST" });
expect(res.status).toBe(200);
expect(((await res.json()) as { status: string }).status).toBe("cancelled");
expect(aborted).toBe(true);
// SSE progress for a cancelled job must terminate (status is terminal).
const progress = await app.request(`http://localhost/render/${jobId}/progress`);
expect(progress.status).toBe(200);
} finally {
rmSync(rendersDir, { recursive: true, force: true });
}
});
it("does not cancel a job that already completed", async () => {
const spy = vi.fn();
const states: Array<{ status: string }> = [];
const { adapter, rendersDir } = createAdapter(spy);
const baseStartRender = adapter.startRender.bind(adapter);
adapter.startRender = (opts) => {
const state = baseStartRender(opts);
states.push(state);
return state;
};
const app = new Hono();
registerRenderRoutes(app, adapter);
try {
const jobId = await startJob(app);
const [state] = states;
if (state) state.status = "complete";
const res = await app.request(`http://localhost/render/${jobId}/cancel`, { method: "POST" });
expect(res.status).toBe(200);
expect(((await res.json()) as { status: string }).status).toBe("complete");
} finally {
rmSync(rendersDir, { recursive: true, force: true });
}
});
it("404s for unknown jobs", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/render/nope/cancel", { method: "POST" });
expect(res.status).toBe(404);
} finally {
cleanup();
}
});
});
describe("POST /projects/:id/render — telemetryDistinctId forwarding", () => {
it("forwards the browser telemetryDistinctId to the adapter as distinctId", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "standard",
format: "mp4",
telemetryDistinctId: "browser-user-123",
}),
});
expect(res.status).toBe(200);
expect(spy.mock.calls[0][0].distinctId).toBe("browser-user-123");
} finally {
cleanup();
}
});
it("passes undefined when no telemetryDistinctId is sent (older clients)", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4" }),
});
expect(res.status).toBe(200);
expect(spy.mock.calls[0][0].distinctId).toBeUndefined();
} finally {
cleanup();
}
});
// Explicit suppression, forwarded so the CLI can honour a browser opt-out
// it has no other way to observe.
it("forwards an explicit telemetryOptOut", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "standard",
format: "mp4",
telemetryOptOut: true,
}),
});
expect(res.status).toBe(200);
expect(spy.mock.calls[0][0].telemetryOptOut).toBe(true);
} finally {
cleanup();
}
});
// WYSIWYG: the browser says whether its preview could blur; only `false` is a signal, and the
// route hands every adapter the final render value.
it.each([
[false, "off"],
[true, undefined],
["false", undefined],
[undefined, undefined],
])("maps previewMotionBlur %s to pageMotionBlur %s", async (flag, expected) => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "standard",
format: "mp4",
previewMotionBlur: flag,
}),
});
expect(spy.mock.calls[0][0].pageMotionBlur).toBe(expected);
expect(spy.mock.calls[0][0]).not.toHaveProperty("previewMotionBlur");
} finally {
cleanup();
}
});
it("preserves explicit page motion blur off over preview capability", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ pageMotionBlur: "off", previewMotionBlur: true }),
});
expect(res.status).toBe(200);
expect(spy.mock.calls[0][0].pageMotionBlur).toBe("off");
} finally {
cleanup();
}
});
it.each(["on", "", false, true, null, 0])(
"rejects invalid page motion blur %s before starting a render",
async (pageMotionBlur) => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ pageMotionBlur }),
});
expect(res.status).toBe(400);
expect(spy).not.toHaveBeenCalled();
} finally {
cleanup();
}
},
);
// An old client omits the flag, and a non-boolean is not a signal either.
// Defaulting those to "opted out" would silently drop every pre-upgrade
// render outcome.
it.each([undefined, false, "true"])(
"treats telemetryOptOut %s as not opted out",
async (flag) => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "standard",
format: "mp4",
telemetryOptOut: flag,
}),
});
expect(spy.mock.calls[0][0].telemetryOptOut).toBe(false);
} finally {
cleanup();
}
},
);
it("ignores a non-string telemetryDistinctId", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
fps: 30,
quality: "standard",
format: "mp4",
telemetryDistinctId: 42,
}),
});
expect(res.status).toBe(200);
expect(spy.mock.calls[0][0].distinctId).toBeUndefined();
} finally {
cleanup();
}
});
});
describe("POST /projects/:id/render — variables forwarding", () => {
it("forwards a variables object to the adapter", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
format: "mp4",
variables: { title: "Custom", count: 5, dark: true },
}),
});
expect(res.status).toBe(200);
expect(spy).toHaveBeenCalledOnce();
expect(spy.mock.calls[0][0].variables).toEqual({ title: "Custom", count: 5, dark: true });
} finally {
cleanup();
}
});
it("omits variables from adapter opts when not provided", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ format: "mp4" }),
});
expect(res.status).toBe(200);
expect(spy.mock.calls[0][0].variables).toBeUndefined();
} finally {
cleanup();
}
});
it("rejects non-object variables payloads with 400 (no silent drop)", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
for (const variables of [["a"], "str", 42, null]) {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ format: "mp4", variables }),
});
expect(res.status).toBe(400);
}
expect(spy).not.toHaveBeenCalled();
} finally {
cleanup();
}
});
});
describe("POST /projects/:id/render — GPU encoding", () => {
it("passes gpu: true on an MP4 export to the adapter as useGpu, and anything else as off", async () => {
const spy = vi.fn();
const { app, cleanup } = buildApp(spy);
try {
const requests = [
{ format: "mp4", gpu: true },
{ format: "mp4" },
{ format: "mp4", gpu: "true" },
{ format: "mp4", gpu: 1 },
{ format: "webm", gpu: true },
{ format: "mov", gpu: true },
];
for (const body of requests) {
const res = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(body),
});
expect(res.status).toBe(200);
}
expect(spy.mock.calls.map(([opts]) => opts.useGpu)).toEqual([
true,
false,
false,
false,
false,
false,
]);
} finally {
cleanup();
}
});
});
describe("audioLoweredDb — the limiter's attenuation reaches the host", () => {
async function completedJobProgress(audioLoweredDb: number | undefined): Promise<string> {
const spy = vi.fn();
const { adapter, rendersDir } = createAdapter(spy);
const baseStartRender = adapter.startRender.bind(adapter);
adapter.startRender = (opts) => {
const state = baseStartRender(opts);
state.status = "complete";
state.progress = 100;
if (audioLoweredDb !== undefined) state.audioLoweredDb = audioLoweredDb;
return state;
};
const app = new Hono();
registerRenderRoutes(app, adapter);
try {
const started = await app.request("http://localhost/projects/demo/render", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4" }),
});
const { jobId } = (await started.json()) as { jobId: string };
return await (await app.request(`http://localhost/render/${jobId}/progress`)).text();
} finally {
rmSync(rendersDir, { recursive: true, force: true });
}
}
it("carries audioLoweredDb in the complete progress event", async () => {
const body = await completedJobProgress(1.44);
expect(body).toContain('"status":"complete"');
expect(body).toContain('"audioLoweredDb":1.44');
});
it("omits it when the limiter did not engage", async () => {
expect(await completedJobProgress(undefined)).not.toContain("audioLoweredDb");
});
it("lists it on the render record from the sidecar, and omits it otherwise", async () => {
const { app, rendersDir, cleanup } = buildApp(vi.fn());
try {
writeFileSync(join(rendersDir, "loud.mp4"), "x");
writeFileSync(
join(rendersDir, "loud.meta.json"),
JSON.stringify({ status: "complete", audioLoweredDb: 1.44 }),
);
writeFileSync(join(rendersDir, "quiet.mp4"), "x");
writeFileSync(join(rendersDir, "quiet.meta.json"), JSON.stringify({ status: "complete" }));
const { renders } = (await (
await app.request("http://localhost/projects/demo/renders")
).json()) as { renders: Array<{ id: string; audioLoweredDb?: number }> };
expect(renders.find((r) => r.id === "loud")?.audioLoweredDb).toBe(1.44);
expect(renders.find((r) => r.id === "quiet")).not.toHaveProperty("audioLoweredDb");
} finally {
cleanup();
}
});
});