Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
import type { RegistryItem, RegistryManifest } from "@hyperframes/core";
import {
listRegistryItems,
loadAllItems,
resolveItem,
resolveItemWithDependencies,
unreachableRegistryMessage,
} from "./resolver.js";
const MANIFEST: RegistryManifest = {
$schema: "https://hyperframes.heygen.com/schema/registry.json",
name: "test",
homepage: "https://example.com",
items: [
{ name: "alpha", type: "hyperframes:example" },
{ name: "beta", type: "hyperframes:example" },
{ name: "gamma", type: "hyperframes:block" },
],
};
function buildItem(name: string, type: "hyperframes:example" | "hyperframes:block"): RegistryItem {
if (type === "hyperframes:example") {
return {
name,
type,
title: name.toUpperCase(),
description: `${name} desc`,
dimensions: { width: 1920, height: 1080 },
duration: 10,
files: [{ path: "index.html", target: "index.html", type: "hyperframes:composition" }],
};
}
return {
name,
type,
title: name.toUpperCase(),
description: `${name} desc`,
dimensions: { width: 1080, height: 1350 },
duration: 6,
files: [
{
path: `${name}.html`,
target: `compositions/${name}.html`,
type: "hyperframes:composition",
},
],
};
}
function mockFetch(
overrides: {
registryFails?: boolean;
missing?: string[];
/** Inject `registryDependencies` into served items, keyed by item name. */
dependencies?: Record<string, string[] | undefined>;
} = {},
): void {
vi.stubGlobal(
"fetch",
vi.fn(async (urlInput: string | URL) => {
const url = typeof urlInput === "string" ? urlInput : urlInput.toString();
if (url.endsWith("/registry.json") && !overrides.registryFails) {
return new Response(JSON.stringify(MANIFEST), { status: 200 });
}
const m = /\/(examples|blocks|components)\/([^/]+)\/registry-item\.json$/.exec(url);
if (m && !overrides.missing?.includes(m[2]!)) {
const type = m[1] === "examples" ? "hyperframes:example" : "hyperframes:block";
const item = buildItem(m[2]!, type);
if (overrides.dependencies && item.name in overrides.dependencies) {
item.registryDependencies = overrides.dependencies[item.name];
}
return new Response(JSON.stringify(item), { status: 200 });
}
return new Response("not found", { status: 404 });
}),
);
}
function uniqueBaseUrl(): string {
// Unique per-test so the 24h on-disk cache doesn't pollute sibling tests.
return `https://test.invalid/${crypto.randomUUID()}`;
}
describe("registry resolver", () => {
beforeEach(() => mockFetch());
afterEach(() => vi.unstubAllGlobals());
describe("listRegistryItems", () => {
it("returns all items when no filter is given", async () => {
const items = await listRegistryItems(undefined, { baseUrl: uniqueBaseUrl() });
expect(items.map((i) => i.name)).toEqual(["alpha", "beta", "gamma"]);
});
it("filters by type", async () => {
const baseUrl = uniqueBaseUrl();
const examples = await listRegistryItems({ type: "hyperframes:example" }, { baseUrl });
expect(examples.map((i) => i.name)).toEqual(["alpha", "beta"]);
const blocks = await listRegistryItems({ type: "hyperframes:block" }, { baseUrl });
expect(blocks.map((i) => i.name)).toEqual(["gamma"]);
});
it("returns empty on unreachable registry", async () => {
vi.stubGlobal(
"fetch",
vi.fn(async () => new Response("oops", { status: 500 })),
);
const items = await listRegistryItems(undefined, { baseUrl: uniqueBaseUrl() });
expect(items).toEqual([]);
});
});
describe("loadAllItems", () => {
it("loads manifests in parallel", async () => {
const baseUrl = uniqueBaseUrl();
const entries = await listRegistryItems(undefined, { baseUrl });
const items = await loadAllItems(entries, { baseUrl });
expect(items.map((i) => i.name).sort()).toEqual(["alpha", "beta", "gamma"]);
expect(items.find((i) => i.name === "alpha")?.title).toBe("ALPHA");
});
it("skips items whose manifest fails to load (warning, not failure)", async () => {
mockFetch({ missing: ["beta"] });
const baseUrl = uniqueBaseUrl();
const warnings: string[] = [];
const entries = await listRegistryItems(undefined, { baseUrl });
const items = await loadAllItems(entries, { baseUrl, onWarn: (m) => warnings.push(m) });
expect(items.map((i) => i.name).sort()).toEqual(["alpha", "gamma"]);
expect(warnings.length).toBeGreaterThan(0);
expect(warnings.some((w) => w.includes("beta"))).toBe(true);
});
});
describe("loadAllItems on a slow registry", () => {
const entries = Array.from({ length: 100 }, (_, i) => ({
name: `item-${i}`,
type: "hyperframes:block" as const,
}));
const itemName = (url: string) => /\/blocks\/([^/]+)\/registry-item\.json$/.exec(url)?.[1];
it("keeps at most 32 item fetches in flight", async () => {
let inFlight = 0;
let peak = 0;
vi.stubGlobal(
"fetch",
vi.fn(async (url: string) => {
inFlight += 1;
peak = Math.max(peak, inFlight);
await new Promise((resolve) => setImmediate(resolve));
inFlight -= 1;
return new Response(JSON.stringify(buildItem(itemName(url)!, "hyperframes:block")));
}),
);
const items = await loadAllItems(entries, { baseUrl: uniqueBaseUrl() });
expect(items).toHaveLength(100);
expect(peak).toBe(32);
});
it("stops fetching after a timeout and warns once for every skipped item", async () => {
const fetchMock = vi.fn(async () => {
throw new DOMException("The operation was aborted due to timeout", "TimeoutError");
});
vi.stubGlobal("fetch", fetchMock);
const warnings: string[] = [];
const items = await loadAllItems(entries, {
baseUrl: uniqueBaseUrl(),
onWarn: (m) => warnings.push(m),
});
expect(items).toEqual([]);
expect(fetchMock).toHaveBeenCalledTimes(32);
expect(warnings).toEqual([
'skipped 100 items ("item-0", "item-1", "item-2", ...): TimeoutError: The operation was aborted due to timeout',
]);
});
});
describe("resolveItem", () => {
it("returns the full manifest for a known item", async () => {
const baseUrl = uniqueBaseUrl();
const item = await resolveItem("alpha", { baseUrl });
expect(item.name).toBe("alpha");
expect(item.type).toBe("hyperframes:example");
expect(item.files).toHaveLength(1);
});
it("throws with an `Available:` list when the name is unknown", async () => {
const baseUrl = uniqueBaseUrl();
await expect(resolveItem("nonexistent", { baseUrl })).rejects.toThrow(
/Available: alpha, beta, gamma/,
);
});
it("throws a clear message when the registry itself is unreachable", async () => {
vi.stubGlobal(
"fetch",
vi.fn(async () => new Response("down", { status: 500 })),
);
const baseUrl = uniqueBaseUrl();
await expect(resolveItem("alpha", { baseUrl })).rejects.toThrow(/unreachable/);
});
it("refuses an item that declares registryDependencies", async () => {
mockFetch({ dependencies: { beta: ["alpha"] } });
const baseUrl = uniqueBaseUrl();
await expect(resolveItem("beta", { baseUrl })).rejects.toThrow(
/declares registryDependencies \(alpha\); use resolveItemWithDependencies/,
);
});
});
describe("resolveItemWithDependencies", () => {
it("returns dependencies first, then the requested item (linear chain)", async () => {
mockFetch({ dependencies: { beta: ["alpha"], gamma: ["beta"] } });
const baseUrl = uniqueBaseUrl();
const items = await resolveItemWithDependencies("gamma", { baseUrl });
expect(items.map((item) => item.name)).toEqual(["alpha", "beta", "gamma"]);
});
it("returns a single item when there are no dependencies", async () => {
const baseUrl = uniqueBaseUrl();
const items = await resolveItemWithDependencies("alpha", { baseUrl });
expect(items.map((item) => item.name)).toEqual(["alpha"]);
});
it("installs a shared transitive dependency exactly once (diamond)", async () => {
// gamma depends on both alpha and beta; beta also depends on alpha.
mockFetch({ dependencies: { gamma: ["alpha", "beta"], beta: ["alpha"] } });
const baseUrl = uniqueBaseUrl();
const items = await resolveItemWithDependencies("gamma", { baseUrl });
expect(items.map((item) => item.name)).toEqual(["alpha", "beta", "gamma"]);
expect(items.filter((item) => item.name === "alpha")).toHaveLength(1);
});
it("throws when a transitive dependency is missing from the registry", async () => {
mockFetch({ dependencies: { beta: ["does-not-exist"], gamma: ["beta"] } });
const baseUrl = uniqueBaseUrl();
await expect(resolveItemWithDependencies("gamma", { baseUrl })).rejects.toThrow(
/Dependency "does-not-exist" not found in registry/,
);
});
it("throws a clear cycle error for circular dependencies", async () => {
mockFetch({ dependencies: { alpha: ["gamma"], beta: ["alpha"], gamma: ["beta"] } });
const baseUrl = uniqueBaseUrl();
await expect(resolveItemWithDependencies("gamma", { baseUrl })).rejects.toThrow(
/Circular registryDependencies detected: gamma -> beta -> alpha -> gamma/,
);
});
});
});
describe("unreachableRegistryMessage", () => {
it("names a private registry, so the reader looks at the right host", () => {
// Same dead end the item-file failure used to be: without the host, a
// project that set `registry` in hyperframes.json reads this as the public
// catalog having lost the item.
const message = unreachableRegistryMessage("blur-in", "https://private.example/registry");
expect(message).toContain("https://private.example/registry");
expect(message).toContain("hyperframes.json");
});
it("stays quiet when the registry is the public one", () => {
const message = unreachableRegistryMessage(
"blur-in",
"https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
);
expect(message).toBe('Item "blur-in" not found \u2014 registry unreachable or empty.');
});
it("stays quiet when no registry was supplied at all", () => {
expect(unreachableRegistryMessage("blur-in")).toBe(
'Item "blur-in" not found \u2014 registry unreachable or empty.',
);
});
});