Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { EventEmitter } from "node:events";
import { afterEach, describe, expect, it, vi } from "vitest";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
renameSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { basename, join } from "node:path";
import {
createProjectSignature,
fileContentVersion,
HistoryBusyError,
HistoryClosedError,
} from "@hyperframes/studio-server";
import { loadHyperframeRuntimeSource } from "@hyperframes/core";
import { loadRuntimeSource } from "./runtimeSource.js";
import { findFFmpeg, findFFprobe } from "../browser/ffmpeg.js";
import { createStudioServer, type StudioServer } from "./studioServer.js";
// Forces loadStudioProducer() down its production import branch (real
// isDevMode() is true for a .ts test file, which instead throws a
// "requires bun" error before ever reaching executeRenderJob — see
// studioServer.ts's loadStudioProducer). Only startRender reads this.
vi.mock("../utils/env.js", () => ({ isDevMode: () => false }));
const producerState = vi.hoisted(() => ({
// Set per-test to control when the render "finishes" so a shutdown that
// races an in-flight render is observable instead of vacuous.
executeRenderJob: (
_job: unknown,
_dir: string,
_outputPath: string,
_onProgress: unknown,
_signal: AbortSignal,
): Promise<void> => Promise.resolve(),
}));
vi.mock("@hyperframes/producer", () => ({
createRenderJob: (opts: Record<string, unknown>) => ({ ...opts, perfSummary: undefined }),
executeRenderJob: (...args: Parameters<typeof producerState.executeRenderJob>) =>
producerState.executeRenderJob(...args),
}));
const engineState = vi.hoisted(() => ({
acquireBrowser: async (..._args: unknown[]): Promise<unknown> => {
throw new Error("acquireBrowser called without a test double");
},
closeBrowserPool: async (): Promise<void> => {},
}));
vi.mock("@hyperframes/engine", () => ({
acquireBrowser: (...args: unknown[]) => engineState.acquireBrowser(...args),
buildChromeArgs: () => [],
killTrackedProcesses: () => {},
closeBrowserPool: () => engineState.closeBrowserPool(),
getSystemTotalMb: () => 0,
}));
vi.mock("../browser/gpuPolicy.js", () => ({
resolveCaptureBrowserGpuMode: async () => "software",
resolveLocalBrowserGpuMode: () => "software",
compositionRequiresWebGpu: () => false,
assertWebGpuAdapterAvailable: async () => {},
resolveLocalWebGpu: (browserGpuMode: string) => ({
gpuConfig: { browserGpuMode, allowSoftwareWebGpu: false },
softwareWebGpu: false,
}),
}));
vi.mock("../browser/preflight.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../browser/preflight.js")>()),
resolveRenderBrowser: async () => ({ executablePath: "/fake/chrome", source: "system" }),
}));
vi.mock("../browser/manager.js", () => ({
ensureBrowser: async () => ({ executablePath: undefined, source: "system" }),
}));
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 };
},
};
},
}));
// Lets one test hold the project history in its opening; every other test opens the real one.
const historyState = vi.hoisted(() => ({
open: null as null | ((...args: unknown[]) => Promise<unknown>),
}));
vi.mock("@hyperframes/studio-server", async (importOriginal) => {
const original = await importOriginal<typeof import("@hyperframes/studio-server")>();
return {
...original,
createProjectSignature: vi.fn(original.createProjectSignature),
openProjectHistory: (...args: Parameters<typeof original.openProjectHistory>) =>
historyState.open ? historyState.open(...args) : original.openProjectHistory(...args),
};
});
// Only `fs.watch` is replaced, so the SSE describe below can fire a file-change
// on demand; every other server test keeps reading and writing real files.
const mockWatcher = new EventEmitter() as EventEmitter & { close: () => void };
mockWatcher.close = vi.fn();
vi.mock("node:fs", async (importOriginal) => {
const original = await importOriginal<typeof import("node:fs")>();
const watch = vi.fn(
(_path: string, _options: unknown, onChange: (event: string, filename: string) => void) => {
mockWatcher.on("change", onChange);
return mockWatcher;
},
);
return { ...original, default: { ...original, watch }, watch };
});
// Every server-backed describe below wants the same two things: a throwaway
// project directory, and a server whose watcher is closed afterwards. Three
// copies of that got out of step, so it lives here once.
const dirs: string[] = [];
let server: StudioServer | undefined;
function tmpProject(): string {
const dir = mkdtempSync(join(tmpdir(), "hf-studio-server-test-"));
dirs.push(dir);
return dir;
}
const openReaders: ReadableStreamDefaultReader<Uint8Array>[] = [];
afterEach(async () => {
await Promise.all(openReaders.splice(0).map((reader) => reader.cancel().catch(() => {})));
mockWatcher.removeAllListeners();
server?.watcher.close();
server = undefined;
delete process.env.HYPERFRAMES_FFMPEG_PATH;
delete process.env.HYPERFRAMES_FFPROBE_PATH;
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
describe("loadRuntimeSource", () => {
it("loads runtime source from the published core entrypoint", async () => {
await expect(loadRuntimeSource()).resolves.toBe(loadHyperframeRuntimeSource());
});
});
describe("Studio thumbnail GPU capture plumbing", () => {
it("uses the shared auto probe, resolved launch mode, requirement guard, and completion-aware seek", () => {
const source = readFileSync(new URL("./studioServer.ts", import.meta.url), "utf8");
expect(source).toContain("resolveCaptureBrowserGpuMode");
expect(source).toContain("resolveLocalWebGpu(resolvedGpuMode, true)");
expect(source).toContain("requiresWebGpu && session.softwareWebGpu");
expect(source).toContain("await seekCompositionTimeline(page, opts.seekTime");
});
});
describe("createStudioServer project history (D-491)", () => {
it("serves the project's history, and a change the watcher sees becomes an entry", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
server = createStudioServer({ projectDir, historyRoot: tmpProject() });
const historyUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
const list = async () =>
(await (await server!.app.request(historyUrl)).json()) as {
entries: Array<{ who: { kind: string } }>;
back: { label: string } | null;
};
expect(await list()).toMatchObject({ entries: [], back: null });
writeFileSync(join(projectDir, "index.html"), "<html>agent</html>");
mockWatcher.emit("change", "change", "index.html");
// Writes with no window open group until 2 s of quiet.
await vi.waitFor(async () => expect((await list()).entries).toHaveLength(1), {
timeout: 5_000,
interval: 200,
});
expect((await list()).entries[0]!.who.kind).toBe("outside");
await server.shutdown();
});
it.each([
["another process was holding", new HistoryBusyError(1)],
["whose folder changed while it opened", new HistoryClosedError("now another project")],
])(
"tries a history %s again on the next request, instead of turning it off",
async (_, refusal) => {
historyState.open = async () => {
historyState.open = null;
throw refusal;
};
const projectDir = tmpProject();
server = createStudioServer({ projectDir, historyRoot: tmpProject() });
const historyUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
expect((await server.app.request(historyUrl)).status).toBe(404);
expect((await server.app.request(historyUrl)).status).toBe(200);
await server.shutdown();
},
);
it("never makes a request wait on another process's history lock again once it was busy", async () => {
const waits: unknown[] = [];
historyState.open = async (options) => {
waits.push((options as { ownerWaitMs?: number }).ownerWaitMs);
throw new HistoryBusyError(1);
};
const projectDir = tmpProject();
server = createStudioServer({ projectDir, historyRoot: tmpProject() });
const historyUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
await server.app.request(historyUrl);
await server.app.request(historyUrl);
historyState.open = null;
expect(waits).toEqual([undefined, 0]);
await server.shutdown();
});
it("waits for the history lock again once a history opened after a busy one", async () => {
const waits: unknown[] = [];
const reopenable = { replacedAtPath: () => true, close: async () => {} };
let opens = 0;
historyState.open = async (options) => {
waits.push((options as { ownerWaitMs?: number }).ownerWaitMs);
opens += 1;
if (opens === 1) throw new HistoryBusyError(1);
if (opens === 2) return reopenable;
historyState.open = null;
throw new HistoryBusyError(1);
};
const projectDir = tmpProject();
server = createStudioServer({ projectDir, historyRoot: tmpProject() });
const historyUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
await server.app.request(historyUrl);
await server.app.request(historyUrl);
historyState.open = null;
expect(waits).toEqual([undefined, 0, undefined]);
await server.shutdown();
});
it("opens a new project's own history once it takes the folder's path", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
server = createStudioServer({ projectDir, historyRoot: tmpProject() });
const historyUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
expect((await server.app.request(historyUrl)).status).toBe(200);
renameSync(projectDir, `${projectDir}-moved`);
dirs.push(`${projectDir}-moved`);
mkdirSync(projectDir);
writeFileSync(join(projectDir, "index.html"), "<html>new</html>");
expect((await server.app.request(historyUrl)).status).toBe(200);
expect(existsSync(join(projectDir, ".hyperframes", "history-id"))).toBe(true);
await server.shutdown();
});
it("shutdown returns within preview's exit watchdog while the history is still opening", async () => {
historyState.open = () => new Promise(() => {});
try {
const projectDir = tmpProject();
server = createStudioServer({ projectDir, historyRoot: tmpProject() });
void server.app.request(`/api/projects/${encodeURIComponent(basename(projectDir))}/history`);
await new Promise((resolve) => setTimeout(resolve, 50));
const started = Date.now();
await server.shutdown();
expect(Date.now() - started).toBeLessThan(2_900);
} finally {
historyState.open = null;
}
});
});
describe("createStudioServer autoProxy plumbing", () => {
it("hyperframes.json media.autoProxy=false flows through to the adapter", () => {
const projectDir = tmpProject();
writeFileSync(
join(projectDir, "hyperframes.json"),
JSON.stringify({ media: { autoProxy: false } }),
);
server = createStudioServer({ projectDir });
expect(server.adapter.autoProxy).toBe(false);
});
it("defaults the adapter to autoProxy=true when neither option nor config disables it", () => {
server = createStudioServer({ projectDir: tmpProject() });
expect(server.adapter.autoProxy).toBe(true);
});
it("an explicit option (the preview command's resolved --proxy flag) wins over config", () => {
const projectDir = tmpProject();
writeFileSync(
join(projectDir, "hyperframes.json"),
JSON.stringify({ media: { autoProxy: false } }),
);
server = createStudioServer({ projectDir, autoProxy: true });
expect(server.adapter.autoProxy).toBe(true);
});
it("advertises the GPU policy used for thumbnail capture", async () => {
const projectDir = tmpProject();
server = createStudioServer({ projectDir, browserGpuMode: "software" });
const response = await server.app.request("/__hyperframes_config");
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({ browserGpuMode: "software" });
});
});
// A render that never reaches the executor (browser check refused, import failed) must fail with
// its reason, not hang until the suite timeout.
async function untilStarted(started: Promise<void>, state: { status: string; error?: string }) {
let timer: ReturnType<typeof setTimeout> | undefined;
const never = new Promise<never>((_, reject) => {
timer = setTimeout(
() =>
reject(
new Error(
`render never reached executeRenderJob: status=${state.status} error=${state.error}`,
),
),
5_000,
);
});
try {
await Promise.race([started, never]);
} finally {
clearTimeout(timer);
}
}
describe("createStudioServer shutdown", () => {
function startRenderOpts(jobId: string, outputPath: string) {
return {
project: { id: "demo", dir: tmpProject(), title: "demo" },
outputPath,
format: "mp4" as const,
fps: { num: 30, den: 1 },
quality: "draft",
jobId,
};
}
it("hands the limiter's audioLoweredDb to the job state and the render sidecar", async () => {
producerState.executeRenderJob = async (job) => {
if (typeof job === "object" && job !== null) Reflect.set(job, "audioLoweredDb", 1.44);
};
const outputPath = join(mkdtempSync(join(tmpdir(), "hf-lowered-")), "out.mp4");
server = createStudioServer({ projectDir: tmpProject() });
const state = server.adapter.startRender(startRenderOpts("job-lowered", outputPath));
await vi.waitFor(() => expect(state.status, state.error).toBe("complete"), { timeout: 5_000 });
expect(state.audioLoweredDb).toBe(1.44);
const meta = JSON.parse(readFileSync(outputPath.replace(/\.mp4$/, ".meta.json"), "utf8"));
expect(meta.audioLoweredDb).toBe(1.44);
});
it("stops measuring CPU however a render ends, and never for an opted-out requester", async () => {
cpuSamplerState.samplers = [];
const outDir = mkdtempSync(join(tmpdir(), "hf-render-cpu-"));
server = createStudioServer({ projectDir: tmpProject() });
producerState.executeRenderJob = async () => {};
const done = server.adapter.startRender(startRenderOpts("job-done", join(outDir, "a.mp4")));
await vi.waitFor(() => expect(done.status, done.error).toBe("complete"), { timeout: 5_000 });
producerState.executeRenderJob = async () => {
throw new Error("boom");
};
const failed = server.adapter.startRender({
...startRenderOpts("job-failed", join(outDir, "b.mp4")),
telemetryOptOut: true,
});
await vi.waitFor(() => expect(failed.status).toBe("failed"), { timeout: 5_000 });
let started!: () => void;
const startedPromise = new Promise<void>((resolve) => {
started = resolve;
});
producerState.executeRenderJob = (_job, _dir, _outputPath, _onProgress, signal) => {
started();
return new Promise((_resolve, reject) => {
const onAbort = () => reject(Object.assign(new Error("cancelled"), { name: "AbortError" }));
if (signal.aborted) onAbort();
else signal.addEventListener("abort", onAbort);
});
};
const cancelled = server.adapter.startRender(
startRenderOpts("job-cancelled", join(outDir, "c.mp4")),
);
await untilStarted(startedPromise, cancelled);
cancelled.cancel?.();
await vi.waitFor(() => expect(cancelled.status).toBe("cancelled"), { timeout: 5_000 });
expect(cpuSamplerState.samplers).toEqual([
{ requesterOptedIn: true, stopped: true },
{ requesterOptedIn: false, stopped: true },
{ requesterOptedIn: true, stopped: true },
]);
rmSync(outDir, { recursive: true, force: true });
});
it("cancels an in-flight render's signal and waits for it before draining the browser pool", async () => {
const events: string[] = [];
let started!: () => void;
const startedPromise = new Promise<void>((resolve) => {
started = resolve;
});
producerState.executeRenderJob = (_job, _dir, _outputPath, _onProgress, signal) => {
started();
return new Promise((_resolve, reject) => {
const onAbort = () =>
setTimeout(() => {
events.push("render-settled");
reject(Object.assign(new Error("cancelled"), { name: "AbortError" }));
}, 20);
// A signal aborted before this executor ran would never fire a later
// "abort" listener (edge-triggered, not level-triggered) — check the
// already-aborted case too, same as real capture code must.
if (signal.aborted) onAbort();
else signal.addEventListener("abort", onAbort);
});
};
server = createStudioServer({ projectDir: tmpProject() });
const outputPath = join(tmpdir(), "shutdown-render.mp4");
const state = server.adapter.startRender(startRenderOpts("job-1", outputPath));
expect(state.status).toBe("rendering");
// Wait until the render has actually reached executeRenderJob (several
// microtask hops through loadStudioProducer/ensureBrowser) before racing
// it against shutdown, or shutdown could abort a signal nothing is
// listening on yet — a race in this test, not in the fix under test.
await untilStarted(startedPromise, state);
await server.shutdown();
events.push("drain-and-shutdown-returned");
expect(events).toEqual(["render-settled", "drain-and-shutdown-returned"]);
});
it("refuses a render started after shutdown has begun instead of launching a fresh browser", async () => {
let releaseFirstRender: () => void = () => {};
let started!: () => void;
const startedPromise = new Promise<void>((resolve) => {
started = resolve;
});
producerState.executeRenderJob = () => {
started();
return new Promise<void>((resolve) => {
releaseFirstRender = resolve;
});
};
server = createStudioServer({ projectDir: tmpProject() });
const first = server.adapter.startRender(startRenderOpts("job-1", join(tmpdir(), "a.mp4")));
await untilStarted(startedPromise, first);
const shutdownPromise = server.shutdown();
// shuttingDown is set synchronously as shutdown()'s first statement, so a
// render request arriving anywhere after that call has been made (even
// before it resolves) must already see it.
const late = server.adapter.startRender(startRenderOpts("job-2", join(tmpdir(), "b.mp4")));
expect(late.status).toBe("failed");
expect(late.error).toMatch(/shutting down/i);
releaseFirstRender();
await shutdownPromise;
});
const thumbnailOpts = () => ({
project: { id: "demo", dir: tmpProject(), title: "demo" },
compPath: "index.html",
seekTime: 0.5,
width: 640,
height: 360,
outputWidth: 640,
outputHeight: 360,
previewUrl: "http://localhost/preview",
signal: new AbortController().signal,
});
it("does not launch a browser for a thumbnail request after shutdown has begun", async () => {
const acquire = vi.fn();
engineState.acquireBrowser = acquire;
server = createStudioServer({ projectDir: tmpProject() });
await server.shutdown();
await expect(server.adapter.generateThumbnail?.(thumbnailOpts())).resolves.toBeNull();
expect(acquire).not.toHaveBeenCalled();
});
it("releases a thumbnail browser that finished launching after shutdown began", async () => {
const release = vi.fn(async () => {});
let launched!: () => void;
const launchedPromise = new Promise<void>((resolve) => (launched = resolve));
let finishLaunch: () => void = () => {};
engineState.acquireBrowser = async () => {
launched();
await new Promise<void>((resolve) => (finishLaunch = resolve));
return { browser: new EventEmitter(), release };
};
let reachedBrowserClose!: () => void;
const reachedBrowserClosePromise = new Promise<void>(
(resolve) => (reachedBrowserClose = resolve),
);
engineState.closeBrowserPool = async () => reachedBrowserClose();
server = createStudioServer({ projectDir: tmpProject() });
const thumbnail = server.adapter.generateThumbnail?.(thumbnailOpts());
await launchedPromise;
const shutdown = server.shutdown();
// shutdown() starts the pool close alongside the thumbnail-browser close,
// before it waits on renders: closing is the signal the close has begun
// while the launch is still pending, without racing a fixed sleep.
await reachedBrowserClosePromise;
finishLaunch();
await shutdown;
await expect(thumbnail).resolves.toBeNull();
expect(release).toHaveBeenCalledTimes(1);
});
it("closes browsers within a bounded timeout even when a render's done promise never settles", async () => {
const closeBrowserPool = vi.fn(async () => {});
engineState.closeBrowserPool = closeBrowserPool;
const release = vi.fn(async () => {});
let launched!: () => void;
const launchedPromise = new Promise<void>((resolve) => (launched = resolve));
let finishLaunch: () => void = () => {};
engineState.acquireBrowser = async () => {
launched();
await new Promise<void>((resolve) => (finishLaunch = resolve));
return { browser: new EventEmitter(), release };
};
let started!: () => void;
const startedPromise = new Promise<void>((resolve) => {
started = resolve;
});
producerState.executeRenderJob = () => {
started();
// Never settles, even once aborted -- the pathological case the CLI's
// 3s exit watchdog exists to survive.
return new Promise<void>(() => {});
};
server = createStudioServer({ projectDir: tmpProject() });
const state = server.adapter.startRender(startRenderOpts("job-1", join(tmpdir(), "hang.mp4")));
await untilStarted(startedPromise, state);
const thumbnail = server.adapter.generateThumbnail?.(thumbnailOpts());
await launchedPromise;
finishLaunch();
let timer: ReturnType<typeof setTimeout> | undefined;
const never = new Promise<never>((_, reject) => {
timer = setTimeout(
() => reject(new Error("shutdown() did not resolve within its bound")),
3_000,
);
});
try {
await Promise.race([server.shutdown(), never]);
} finally {
clearTimeout(timer);
}
expect(release).toHaveBeenCalledTimes(1);
expect(closeBrowserPool).toHaveBeenCalledTimes(1);
await expect(thumbnail).resolves.toBeNull();
});
it("does not hand an already-leased browser to a new caller once shutdown has begun", async () => {
const release = vi.fn(async () => {});
const newPage = vi.fn(async () => {
throw new Error("no real page in this test double");
});
engineState.acquireBrowser = async () => ({
browser: { connected: true, newPage, on: () => {} },
release,
});
server = createStudioServer({ projectDir: tmpProject() });
await server.adapter.generateThumbnail?.(thumbnailOpts());
expect(newPage).toHaveBeenCalledTimes(1);
const shutdownPromise = server.shutdown();
// shuttingDown flips true synchronously as shutdown()'s first statement,
// before its closeThumbnailBrowser() call runs -- this request lands in
// that window and must not reuse the still-connected lease.
const late = server.adapter.generateThumbnail?.(thumbnailOpts());
await expect(late).resolves.toBeNull();
expect(newPage).toHaveBeenCalledTimes(1);
await shutdownPromise;
});
});
describe("Studio thumbnail capture", () => {
// The thumbnail browser lease is module-wide; without a shutdown the next test inherits this one's fake.
afterEach(async () => {
await server?.shutdown();
});
function fakePageBrowser(onEvaluate = () => {}) {
const screenshot = vi.fn(async () => Buffer.from("jpeg"));
const evaluate = vi.fn(async () => onEvaluate());
const page = new Proxy(
{ screenshot, evaluate },
{
get: (target, key) =>
key === "then"
? undefined
: key in target
? target[key as keyof typeof target]
: async () => {},
},
);
engineState.acquireBrowser = async () => ({
browser: { connected: true, newPage: async () => page, on: () => {} },
release: async () => {},
});
return { screenshot, evaluate };
}
const opts = (dir: string, signal = new AbortController().signal) => ({
project: { id: "demo", dir, title: "demo" },
compPath: "index.html",
seekTime: 0.5,
width: 640,
height: 360,
outputWidth: 640,
outputHeight: 360,
previewUrl: "http://localhost/preview",
signal,
});
it("stops a thumbnail whose request is aborted before its screenshot", async () => {
let abortOnEvaluate: AbortController | undefined;
const { screenshot } = fakePageBrowser(() => abortOnEvaluate?.abort());
const dir = tmpProject();
server = createStudioServer({ projectDir: dir });
await expect(server.adapter.generateThumbnail?.(opts(dir))).resolves.toBeInstanceOf(Buffer);
expect(screenshot).toHaveBeenCalledTimes(1);
const aborting = new AbortController();
abortOnEvaluate = aborting;
await expect(
server.adapter.generateThumbnail?.(opts(dir, aborting.signal)),
).resolves.toBeNull();
expect(screenshot).toHaveBeenCalledTimes(1);
});
it("undoes a row's isolation after its screenshot, since the page is reused", async () => {
const { screenshot, evaluate } = fakePageBrowser();
const dir = tmpProject();
server = createStudioServer({ projectDir: dir });
await server.adapter.generateThumbnail?.({ ...opts(dir), selector: "#title" });
const clears = evaluate.mock.calls.flatMap((call, i) =>
((call as unknown[])[0] as { name?: string }).name === "clearElementScreenshotIsolation"
? [evaluate.mock.invocationCallOrder[i]!]
: [],
);
expect(clears).toHaveLength(1);
expect(clears[0]).toBeGreaterThan(screenshot.mock.invocationCallOrder[0]!);
});
it("reuses the cached project signature instead of walking the project per thumbnail", async () => {
fakePageBrowser();
const dir = tmpProject();
server = createStudioServer({ projectDir: dir });
await server.adapter.generateThumbnail?.(opts(dir));
const walks = vi.mocked(createProjectSignature).mock.calls.length;
for (let i = 0; i < 3; i++) await server.adapter.generateThumbnail?.(opts(dir));
expect(vi.mocked(createProjectSignature).mock.calls.length).toBe(walks);
});
});
describe("Studio project lint endpoint", () => {
it("surfaces findings that require the complete project graph", async () => {
const projectDir = tmpProject();
mkdirSync(join(projectDir, "compositions"));
mkdirSync(join(projectDir, "scenes"));
writeFileSync(
join(projectDir, "index.html"),
`<html><body><div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10"></div></body></html>`,
);
writeFileSync(
join(projectDir, "compositions", "index.html"),
`<html><body><div data-composition-id="authored" data-width="1920" data-height="1080" data-start="0" data-duration="5"><div class="clip" data-start="0" data-duration="5">Visible</div></div></body></html>`,
);
writeFileSync(join(projectDir, "scenes", "intro.html"), "<html><body>Intro</body></html>");
server = createStudioServer({ projectDir, projectName: "demo" });
const response = await server.app.request("http://localhost/api/projects/demo/lint");
const payload = (await response.json()) as {
findings?: Array<{ code?: string; file?: string }>;
};
expect(response.status).toBe(200);
expect(payload.findings).toContainEqual(
expect.objectContaining({ code: "blank_root_with_standalone_composition" }),
);
expect(payload.findings).toContainEqual(expect.objectContaining({ file: "scenes/intro.html" }));
expect(payload.findings?.every((finding) => !finding.file?.startsWith(projectDir))).toBe(true);
});
});
describe("host guarding on identity-bearing responses", () => {
// NOTE: the SPA-injection branch itself is covered in telemetryIdentity.test.ts
// via buildStudioHeadScriptsForHost. It cannot be asserted here: this route
// only reaches the injection branch when packages/studio/dist is built,
// which is true locally and false in the CI test lane, so a route-level
// assertion on the returned HTML passes on a dev box and fails in CI.
it("refuses the identity endpoint for a hostile Host", async () => {
server = createStudioServer({ projectDir: tmpProject() });
const res = await server.app.request("/api/telemetry-identity", {
headers: { host: "evil.example.com" },
});
expect(res.status).toBe(403);
expect(await res.text()).not.toContain('distinctId":"');
});
it("serves the identity endpoint on a loopback Host", async () => {
server = createStudioServer({ projectDir: tmpProject() });
const res = await server.app.request("/api/telemetry-identity", {
headers: { host: "127.0.0.1:5173" },
});
expect(res.status).toBe(200);
// The seed is no longer served here at all — Studio gets decisions
// injected instead, so nothing needs it over HTTP.
expect(Object.keys((await res.json()) as object)).toEqual(["distinctId"]);
});
});
// Studio asks this before it offers Export, so a machine without an encoder
// gets an install command up front instead of a 503 after the work is done.
describe("FFmpeg environment endpoint", () => {
it("reports the cause and a pasteable command when FFmpeg is unusable", async () => {
// A configured-but-missing override is the one "no FFmpeg" state a test can
// force on a machine that does have FFmpeg installed.
process.env.HYPERFRAMES_FFMPEG_PATH = join(tmpdir(), "hf-missing-ffmpeg");
server = createStudioServer({ projectDir: tmpProject() });
const res = await server.app.request("/api/environment/ffmpeg");
expect(res.status).toBe(200);
const body = (await res.json()) as {
ok: boolean;
title?: string;
detail?: string;
command?: string;
};
expect(body.ok).toBe(false);
expect(body.title).toContain("not found");
expect(body.detail).toBeTruthy();
// Undefined only on platforms with no one-line install; CI runs none.
expect(body.command).toBeTruthy();
});
// Needs a real FFmpeg: the check runs `-version` on whatever it resolves, so
// a stand-in binary would only prove the stand-in works. Skipped rather than
// faked on machines without one.
it.skipIf(!findFFmpeg() || !findFFprobe())(
"answers a plain ok when both binaries resolve",
async () => {
server = createStudioServer({ projectDir: tmpProject() });
const res = await server.app.request("/api/environment/ffmpeg");
expect(await res.json()).toEqual({ ok: true });
},
);
});
describe("Studio file-change SSE", () => {
/** Opens `count` `/api/events` connections and waits for each to register its listener. */
async function subscribe(count: number): Promise<ReadableStreamDefaultReader<Uint8Array>[]> {
const responses = await Promise.all(
Array.from({ length: count }, () => server!.app.request("/api/events")),
);
const streams = responses.map((response) => {
const reader = response.body!.getReader();
openReaders.push(reader);
return reader;
});
// streamSSE runs its callback after the Response resolves, so the listener
// each connection adds has to exist before the watcher fires.
await new Promise((resolve) => setTimeout(resolve, 20));
return streams;
}
const nextEvent = async (reader: ReadableStreamDefaultReader<Uint8Array>): Promise<string> =>
new TextDecoder().decode((await reader.read()).value);
/** The version as it appears inside the JSON-encoded SSE data line. */
const encodedVersion = (content: string): string =>
fileContentVersion(content).replaceAll('"', '\\"');
/** A project whose preview has been loaded once, as an open Studio tab does on its first render. */
async function previewedProject(): Promise<{ projectDir: string; projectUrl: string }> {
const projectDir = tmpProject();
mkdirSync(join(projectDir, "assets"));
writeFileSync(join(projectDir, "assets", "logo.png"), "logo-v1");
writeFileSync(
join(projectDir, "index.html"),
'<html><body><div data-composition-id="root"><img src="assets/logo.png"></div></body></html>',
);
server = createStudioServer({ projectDir });
const projectUrl = `/api/projects/${encodeURIComponent(basename(projectDir))}`;
expect((await server.app.request(`${projectUrl}/preview`)).status).toBe(200);
expect((await server.app.request(`${projectUrl}/preview/assets/logo.png`)).status).toBe(200);
return { projectDir, projectUrl };
}
it("marks a notes write as not affecting the preview, so the tab does not reload", async () => {
const { projectDir } = await previewedProject();
const [stream] = await subscribe(1);
writeFileSync(join(projectDir, "notes.md"), "review notes");
mockWatcher.emit("change", "rename", "notes.md");
const payload = await nextEvent(stream!);
expect(payload).toContain('"path":"notes.md"');
expect(payload).toContain('"affectsPreview":false');
expect(payload).toContain('"affectedCompositions":[]');
});
it("marks a write to an asset the preview loaded as affecting it", async () => {
const { projectDir } = await previewedProject();
const [stream] = await subscribe(1);
writeFileSync(join(projectDir, "assets", "logo.png"), "logo-v2");
mockWatcher.emit("change", "change", "assets/logo.png");
expect(await nextEvent(stream!)).toContain('"affectsPreview":true');
});
it("reloads when a folder holding an asset the preview missed is moved in", async () => {
const { projectDir, projectUrl } = await previewedProject();
expect((await server!.app.request(`${projectUrl}/preview/media/clip.png`)).status).toBe(404);
const [stream] = await subscribe(1);
mkdirSync(join(projectDir, "media"));
writeFileSync(join(projectDir, "media", "clip.png"), "clip");
mockWatcher.emit("change", "rename", "media");
const payload = await nextEvent(stream!);
expect(payload).toContain('"path":"media"');
expect(payload).toContain('"affectsPreview":true');
});
it("reloads when a folder holding an asset the preview loaded is moved out", async () => {
const { projectDir } = await previewedProject();
const [stream] = await subscribe(1);
renameSync(join(projectDir, "assets"), join(tmpProject(), "assets"));
mockWatcher.emit("change", "rename", "assets");
expect(await nextEvent(stream!)).toContain('"affectsPreview":true');
});
it("still delivers a new file in a folder an old watchIgnore listed, for the file tree", async () => {
const { projectDir } = await previewedProject();
writeFileSync(
join(projectDir, "hyperframes.json"),
JSON.stringify({ preview: { watchIgnore: ["docs"] } }),
);
const [stream] = await subscribe(1);
mkdirSync(join(projectDir, "docs"));
writeFileSync(join(projectDir, "docs", "report.json"), "{}");
mockWatcher.emit("change", "rename", "docs/report.json");
const payload = await nextEvent(stream!);
expect(payload).toContain('"path":"docs/report.json"');
expect(payload).toContain('"affectsPreview":false');
});
it("counts every write as affecting the preview until the preview has loaded anything", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html></html>");
server = createStudioServer({ projectDir });
const [stream] = await subscribe(1);
writeFileSync(join(projectDir, "notes.md"), "notes");
mockWatcher.emit("change", "rename", "notes.md");
expect(await nextEvent(stream!)).toContain('"affectsPreview":true');
});
it("labels a Studio write for every open subscriber, not just the first", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
server = createStudioServer({ projectDir });
const streams = await subscribe(2);
const written = "<html>after</html>";
const write = await server.app.request(
`/api/projects/${encodeURIComponent(basename(projectDir))}/files/index.html`,
{
method: "PUT",
headers: {
"If-Match": fileContentVersion("<html>before</html>"),
"X-Hyperframes-Write-Token": "studio-write-1",
},
body: written,
},
);
expect(write.status).toBe(200);
mockWatcher.emit("change", "change", "index.html");
for (const payload of await Promise.all(streams.map(nextEvent))) {
expect(payload).toContain("studio-write-1");
expect(payload).toContain(encodedVersion(written));
}
});
it("still reports an external write with a version so subscribers can dedupe it", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
server = createStudioServer({ projectDir });
const streams = await subscribe(2);
writeFileSync(join(projectDir, "index.html"), "<html>agent</html>");
mockWatcher.emit("change", "change", "index.html");
for (const payload of await Promise.all(streams.map(nextEvent))) {
expect(payload).not.toContain("writeToken");
expect(payload).toContain(encodedVersion("<html>agent</html>"));
}
});
it("labels the deletion an undo from Studio makes with Studio's write token", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
server = createStudioServer({ projectDir, historyRoot: tmpProject() });
const history = `/api/projects/${encodeURIComponent(basename(projectDir))}/history`;
const post = (path: string, body: object, headers: Record<string, string> = {}) =>
server!.app.request(`${history}${path}`, {
method: "POST",
headers: { "Content-Type": "application/json", ...headers },
body: JSON.stringify(body),
});
await server.app.request(history); // opens the history, as Studio's first load does
writeFileSync(join(projectDir, "extra.html"), "<html>added</html>");
await post("/claim", { label: "Added a section", paths: ["extra.html"] });
const streams = await subscribe(1);
await post("/step", { direction: "back" }, { "X-Hyperframes-Write-Token": "studio-undo-1" });
expect(existsSync(join(projectDir, "extra.html"))).toBe(false);
mockWatcher.emit("change", "rename", "extra.html");
const [payload] = await Promise.all(streams.map(nextEvent));
expect(payload).toContain("studio-undo-1");
});
// `/api/events` is one connection per SERVER, not per project: a tab left
// open from a `preview` run whose port was later reused by a DIFFERENT
// project shares this exact stream. Without `projectId` on the wire, that
// stale tab cannot tell "my project changed" from "the other project this
// server now serves changed" — see useExternalFileChangeCoordinator's
// cross-project filter, which reads this field.
it("labels every file-change with this server's project id", async () => {
const projectDir = tmpProject();
writeFileSync(join(projectDir, "index.html"), "<html>before</html>");
server = createStudioServer({ projectDir, projectName: "demo-project" });
const streams = await subscribe(1);
writeFileSync(join(projectDir, "index.html"), "<html>agent</html>");
mockWatcher.emit("change", "change", "index.html");
const [payload] = await Promise.all(streams.map(nextEvent));
expect(payload).toContain('"projectId":"demo-project"');
});
});