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 { runCommand as runCittyCommand, type CommandDef } from "citty";
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import type { RegistryItem, RegistryManifest } from "@hyperframes/core";
import { lintHyperframeHtml } from "@hyperframes/lint";
import type { RunAddResult } from "./add.js";
import addCommand, {
AddError,
buildSnippet,
compositionRootId,
describeInstallFailure,
parseVariableValues,
remapTarget,
runAdd,
tagAddJson,
} from "./add.js";
import { trackRegistryItemAdded } from "../telemetry/events.js";
import { CliUsageError } from "../utils/commandResult.js";
import { trackCommandFailures } from "../utils/command-failure-tracking.js";
// Assert the emitted payload rather than the transport: `shouldTrack()` is
// already false under test (dev mode / no PostHog key), so a real call would
// be indistinguishable from no call at all.
vi.mock("../telemetry/events.js", () => ({ trackRegistryItemAdded: vi.fn() }));
// ── Fixtures ────────────────────────────────────────────────────────────────
const MANIFEST: RegistryManifest = {
$schema: "https://hyperframes.heygen.com/schema/registry.json",
name: "test",
homepage: "https://example.com",
items: [
{ name: "my-block", type: "hyperframes:block" },
{ name: "deprecated-block", type: "hyperframes:block" },
{ name: "future-block", type: "hyperframes:block" },
{ name: "dep-block", type: "hyperframes:block" },
{ name: "base-component", type: "hyperframes:component" },
{ name: "my-component", type: "hyperframes:component" },
{ name: "my-example", type: "hyperframes:example" },
],
};
const BLOCK_ITEM: RegistryItem = {
$schema: "https://hyperframes.heygen.com/schema/registry-item.json",
name: "my-block",
type: "hyperframes:block",
title: "My Block",
description: "Block for tests",
dimensions: { width: 1080, height: 1350 },
duration: 6,
files: [
{
path: "my-block.html",
target: "compositions/my-block.html",
type: "hyperframes:composition",
},
],
};
const COMPONENT_ITEM: RegistryItem = {
$schema: "https://hyperframes.heygen.com/schema/registry-item.json",
name: "my-component",
type: "hyperframes:component",
title: "My Component",
description: "Component for tests",
files: [
{
path: "my-component.html",
target: "compositions/components/my-component/my-component.html",
type: "hyperframes:snippet",
},
{
path: "my-component.css",
target: "compositions/components/my-component/my-component.css",
type: "hyperframes:style",
},
{
path: "assets/mask.png",
target: "assets/my-component/mask.png",
type: "hyperframes:asset",
},
],
};
const DEPRECATED_BLOCK_ITEM: RegistryItem = {
...BLOCK_ITEM,
name: "deprecated-block",
title: "Deprecated Block",
deprecated: "Use `my-block` instead.",
files: [
{
path: "deprecated-block.html",
target: "compositions/deprecated-block.html",
type: "hyperframes:composition",
},
],
};
const FUTURE_BLOCK_ITEM: RegistryItem = {
...BLOCK_ITEM,
name: "future-block",
title: "Future Block",
minCliVersion: "999.0.0",
files: [
{
path: "future-block.html",
target: "compositions/future-block.html",
type: "hyperframes:composition",
},
],
};
const BASE_COMPONENT_ITEM: RegistryItem = {
$schema: "https://hyperframes.heygen.com/schema/registry-item.json",
name: "base-component",
type: "hyperframes:component",
title: "Base Component",
description: "Base component dependency for tests",
files: [
{
path: "base-component.css",
target: "compositions/components/base-component/base-component.css",
type: "hyperframes:style",
},
],
};
// A block that declares a transitive registryDependency on base-component.
const DEP_BLOCK_ITEM: RegistryItem = {
...BLOCK_ITEM,
name: "dep-block",
title: "Dependent Block",
registryDependencies: ["base-component"],
files: [
{
path: "dep-block.html",
target: "compositions/dep-block.html",
type: "hyperframes:composition",
},
],
};
const EXAMPLE_ITEM: RegistryItem = {
$schema: "https://hyperframes.heygen.com/schema/registry-item.json",
name: "my-example",
type: "hyperframes:example",
title: "My Example",
description: "Example for tests",
dimensions: { width: 1920, height: 1080 },
duration: 10,
files: [{ path: "index.html", target: "index.html", type: "hyperframes:composition" }],
};
const ITEM_BY_NAME: Record<string, RegistryItem> = {
"my-block": BLOCK_ITEM,
"deprecated-block": DEPRECATED_BLOCK_ITEM,
"future-block": FUTURE_BLOCK_ITEM,
"dep-block": DEP_BLOCK_ITEM,
"base-component": BASE_COMPONENT_ITEM,
"my-component": COMPONENT_ITEM,
"my-example": EXAMPLE_ITEM,
};
const DEP_BLOCK_HTML = `<div data-composition-variables='[{ "id": "maths", "type": "boolean", "label": "Maths", "default": false }]'></div>`;
const FILE_BODIES: Record<string, string> = {
"dep-block.html": DEP_BLOCK_HTML,
"deprecated-block.html": `<div data-composition-id="deprecated-block"></div>`,
"my-block.html": `<div data-composition-id="my-block-root" data-width="1080" data-height="1350"></div>`,
};
function mockFetch(): void {
vi.stubGlobal(
"fetch",
vi.fn(async (input: string | URL) => {
const url = typeof input === "string" ? input : input.toString();
if (url.endsWith("/registry.json")) {
return new Response(JSON.stringify(MANIFEST), { status: 200 });
}
const m = /\/(examples|blocks|components)\/([^/]+)\/registry-item\.json$/.exec(url);
if (m) {
const item = ITEM_BY_NAME[m[2]!];
if (item) return new Response(JSON.stringify(item), { status: 200 });
}
// File fetch — match `/<type-dir>/<name>/<rest>` and serve synthetic content.
const f = /\/(examples|blocks|components)\/([^/]+)\/(.+)$/.exec(url);
if (f) {
return new Response(FILE_BODIES[f[3]!] ?? `/* ${f[3]} */\n`, { status: 200 });
}
return new Response("not found", { status: 404 });
}),
);
}
function tmp(): string {
return mkdtempSync(join(tmpdir(), "hf-add-test-"));
}
function uniqueBase(): string {
return `https://test.invalid/${crypto.randomUUID()}`;
}
const DEFAULT_TEST_PATHS = {
blocks: "compositions",
components: "compositions/components",
assets: "assets",
};
function writeRegistryConfig(
dir: string,
paths: typeof DEFAULT_TEST_PATHS = DEFAULT_TEST_PATHS,
): void {
writeFileSync(
join(dir, "hyperframes.json"),
JSON.stringify({
$schema: "https://hyperframes.heygen.com/schema/hyperframes.json",
registry: uniqueBase(),
paths,
}),
"utf-8",
);
}
// ── Tests ───────────────────────────────────────────────────────────────────
describe("add command pure helpers", () => {
describe("remapTarget", () => {
const PATHS = { blocks: "src/scenes", components: "src/fx" };
it("rewrites block default path to paths.blocks", () => {
expect(remapTarget(BLOCK_ITEM, "compositions/my-block.html", PATHS)).toBe(
"src/scenes/my-block.html",
);
});
it("rewrites component default path to paths.components", () => {
expect(
remapTarget(
COMPONENT_ITEM,
"compositions/components/my-component/my-component.html",
PATHS,
),
).toBe("src/fx/my-component/my-component.html");
});
it("leaves example targets alone", () => {
expect(remapTarget(EXAMPLE_ITEM, "index.html", PATHS)).toBe("index.html");
});
it("leaves non-default block paths alone (no blind string replace)", () => {
// A block's manifest could in future use a non-default target — make
// sure the prefix match is anchored.
expect(remapTarget(BLOCK_ITEM, "elsewhere/my-block.html", PATHS)).toBe(
"elsewhere/my-block.html",
);
});
});
describe("buildSnippet", () => {
it("wraps blocks in a div with data-composition-src and duration", () => {
const snip = buildSnippet(BLOCK_ITEM, "src/scenes/my-block.html");
expect(snip).toContain('data-composition-src="src/scenes/my-block.html"');
expect(snip).toContain('data-duration="6"');
});
it("reads a composition's root id, inside its <template> when it has one", () => {
expect(compositionRootId(`<div data-composition-id="plain" data-width="1"></div>`)).toBe(
"plain",
);
expect(
compositionRootId(
`<html><head><template id="t"><div data-composition-id="templated"></div></template></head><body></body></html>`,
),
).toBe("templated");
expect(compositionRootId(`<div>no root</div>`)).toBeUndefined();
});
it("gives the block host the composition id that check requires", async () => {
const snip = buildSnippet(BLOCK_ITEM, "compositions/my-block.html", null, "my-block-root");
const html = `<!doctype html><html><body><div data-composition-id="root" data-width="1080" data-height="1350">${snip}</div></body></html>`;
const { findings } = await lintHyperframeHtml(html);
expect(findings.map((f) => f.code)).not.toContain("host_missing_composition_id");
expect(snip).toContain('data-composition-id="my-block-root"');
});
it("emits a paste hint for components", () => {
const snip = buildSnippet(COMPONENT_ITEM, "src/fx/my-component/my-component.html");
expect(snip).toContain("paste from");
expect(snip).toContain("my-component.html");
});
it("returns empty string for examples", () => {
expect(buildSnippet(EXAMPLE_ITEM, "index.html")).toBe("");
});
});
});
describe("runAdd (integration, mocked registry)", () => {
beforeEach(() => {
vi.mocked(trackRegistryItemAdded).mockClear();
mockFetch();
});
afterEach(() => {
vi.unstubAllGlobals();
});
it("installs a block into the default compositions/ path and returns the snippet", async () => {
const dir = tmp();
try {
// Write hyperframes.json so runAdd uses our unique baseUrl.
writeRegistryConfig(dir);
const result = await runAdd({ name: "my-block", projectDir: dir, skipClipboard: true });
expect(result.ok).toBe(true);
expect(result.name).toBe("my-block");
expect(result.type).toBe("hyperframes:block");
expect(result.written).toHaveLength(1);
expect(result.installed).toEqual(["my-block"]);
expect(result.warnings).toEqual([]);
expect(existsSync(join(dir, "compositions/my-block.html"))).toBe(true);
const installed = readFileSync(join(dir, "compositions/my-block.html"), "utf-8");
expect(installed).toContain("<!-- hyperframes-registry-item: my-block -->");
expect(installed).toContain('data-composition-id="my-block-root"');
expect(result.snippet).toContain("compositions/my-block.html");
expect(result.snippet).toContain('data-composition-id="my-block-root"');
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("returns a warning for deprecated registry items while still installing", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir);
const result = await runAdd({
name: "deprecated-block",
projectDir: dir,
skipClipboard: true,
});
expect(result.warnings).toEqual([
'Registry item "deprecated-block" is deprecated: Use `my-block` instead.',
]);
expect(existsSync(join(dir, "compositions/deprecated-block.html"))).toBe(true);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("blocks registry items that require a newer CLI before writing files", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir);
await expect(
runAdd({
name: "future-block",
projectDir: dir,
skipClipboard: true,
cliVersion: "0.6.79",
}),
).rejects.toMatchObject({
code: "incompatible-cli",
});
expect(existsSync(join(dir, "compositions/future-block.html"))).toBe(false);
// Nothing was written, so nothing may be counted: an install count that
// also counts refused installs is not a download count.
expect(trackRegistryItemAdded).not.toHaveBeenCalled();
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("remaps component snippet/style targets while leaving asset targets stable", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir, { blocks: "compositions", components: "src/fx", assets: "assets" });
const result = await runAdd({
name: "my-component",
projectDir: dir,
skipClipboard: true,
});
expect(result.written.length).toBe(3);
expect(existsSync(join(dir, "src/fx/my-component/my-component.html"))).toBe(true);
expect(existsSync(join(dir, "src/fx/my-component/my-component.css"))).toBe(true);
expect(existsSync(join(dir, "assets/my-component/mask.png"))).toBe(true);
expect(result.snippet).toContain("src/fx/my-component/my-component.html");
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("refuses a wrong-typed --vars before writing any item in the plan", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir);
await expect(
runAdd({ name: "dep-block", projectDir: dir, skipClipboard: true, vars: '{"maths":1}' }),
).rejects.toThrow(/maths: expected boolean, got number/);
expect(existsSync(join(dir, "compositions/components/base-component"))).toBe(false);
expect(existsSync(join(dir, "hyperframes.lock.json"))).toBe(false);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("installs transitive registryDependencies before the requested item", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir);
const result = await runAdd({ name: "dep-block", projectDir: dir, skipClipboard: true });
expect(result.name).toBe("dep-block");
// Dependency first, requested item last.
expect(result.installed).toEqual(["base-component", "dep-block"]);
expect(result.written).toHaveLength(2);
expect(
existsSync(join(dir, "compositions/components/base-component/base-component.css")),
).toBe(true);
expect(existsSync(join(dir, "compositions/dep-block.html"))).toBe(true);
// Snippet points at the requested block, not the dependency.
expect(result.snippet).toContain("compositions/dep-block.html");
expect(result.warnings).toEqual([
expect.stringContaining("compositions/dep-block.html declares no data-composition-id"),
]);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("reports every installed item, marking only the requested one", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir);
await runAdd({ name: "dep-block", projectDir: dir, skipClipboard: true });
// A dependency dragged in behind the request must not read as a vote for
// itself, or a popular dependency outranks everything that depends on it.
expect(trackRegistryItemAdded).toHaveBeenCalledTimes(2);
expect(trackRegistryItemAdded).toHaveBeenCalledWith({
item: "base-component",
itemType: "hyperframes:component",
requested: false,
source: "cli",
});
expect(trackRegistryItemAdded).toHaveBeenCalledWith({
item: "dep-block",
itemType: "hyperframes:block",
requested: true,
source: "cli",
});
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("throws AddError with code 'example-type' when asked to add an example", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir);
await expect(
runAdd({ name: "my-example", projectDir: dir, skipClipboard: true }),
).rejects.toMatchObject({
code: "example-type",
});
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it("throws AddError with code 'unknown-item' for a missing name", async () => {
const dir = tmp();
try {
writeRegistryConfig(dir);
await expect(
runAdd({ name: "nope", projectDir: dir, skipClipboard: true }),
).rejects.toBeInstanceOf(AddError);
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});
describe("variable values in the snippet", () => {
const block = {
name: "split-flap-board",
type: "hyperframes:block",
duration: 3.5,
dimensions: { width: 1920, height: 1080 },
} as unknown as RegistryItem;
it("leaves the snippet alone when no values are passed", () => {
const snippet = buildSnippet(block, "compositions/split-flap-board.html");
expect(snippet).not.toContain("data-variable-values");
});
it("carries values tuned on the catalog page", () => {
const snippet = buildSnippet(block, "compositions/split-flap-board.html", {
boardText: "GATE 42",
cellCount: 16,
});
expect(snippet).toContain(`data-variable-values='{"boardText":"GATE 42","cellCount":16}'`);
});
it("escapes a single quote rather than letting it close the attribute", () => {
const snippet = buildSnippet(block, "x.html", { boardText: "IT'S BOARDING" });
expect(snippet).toContain("'");
expect(snippet.match(/data-variable-values='/g)?.length).toBe(1);
});
it("treats an empty object as nothing to say", () => {
expect(buildSnippet(block, "x.html", {})).not.toContain("data-variable-values");
});
it("rejects --vars that is not a JSON object", () => {
expect(() => parseVariableValues("not json")).toThrow(/JSON object/);
expect(() => parseVariableValues("[1,2]")).toThrow(/JSON object/);
expect(parseVariableValues(undefined)).toBeNull();
});
});
describe("add command run() — extra positional arguments", () => {
let dir: string;
let errorSpy: ReturnType<typeof vi.spyOn>;
beforeEach(() => {
dir = tmp();
errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
});
afterEach(() => {
errorSpy.mockRestore();
vi.unstubAllGlobals();
rmSync(dir, { recursive: true, force: true });
});
async function runWrapped(rawArgs: string[]): Promise<void> {
const cmd = await trackCommandFailures(() => Promise.resolve(addCommand as CommandDef))();
await runCittyCommand(cmd, { rawArgs });
}
it("rejects `add a --dir <dir> b c` through the CLI wrapper, before any registry call", async () => {
const fetchSpy = vi.fn();
vi.stubGlobal("fetch", fetchSpy);
await expect(runWrapped(["a", "--dir", dir, "b", "c"])).rejects.toThrow(CliUsageError);
expect(fetchSpy).not.toHaveBeenCalled();
expect(errorSpy.mock.calls.flat().join(" ")).toContain(
"Unexpected extra arguments for hyperframes add: b, c",
);
expect(errorSpy.mock.calls.flat().join(" ")).toContain("Run add once per item");
});
it("does not fire on a normal single-item invocation", async () => {
mockFetch();
writeRegistryConfig(dir);
await expect(
runWrapped(["my-block", "--dir", dir, "--no-clipboard", "--json"]),
).resolves.toBeUndefined();
});
});
describe("describeInstallFailure", () => {
it("explains a bare transport failure instead of echoing it", () => {
// What the user actually sees after copying a command off the catalog page.
// Item FILES are not cached, so a blip surfaces as node's `fetch failed`
// with no URL and no cause, and reads like the command was wrong.
const message = describeInstallFailure(new Error("fetch failed"));
expect(message).toContain("could not download the item's files");
expect(message).toContain("rather than a bad command");
expect(message).toContain("HTTPS_PROXY");
});
it("names the project's own registry when it is not the public one", () => {
// The reported failure: hyperframes.json pointed at a private host with a
// self-signed certificate. Telling that reader to check their connection
// sends them to debug the one thing that was working.
const message = describeInstallFailure(
new Error("fetch failed"),
"https://private.example/registry",
);
expect(message).toContain("https://private.example/registry");
expect(message).toContain("not the public registry");
});
it("stays quiet about the registry when it is the default one", () => {
const message = describeInstallFailure(
new Error("fetch failed"),
"https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
);
expect(message).not.toContain("not the public registry");
});
it("leaves a non-transport failure exactly as it was", () => {
// An unsafe target or a malformed item is the caller's problem to read; a
// connectivity lecture there would send them to fix the wrong thing.
const message = describeInstallFailure(new Error('Unsafe target "../x"'));
expect(message).toBe('Install failed: Unsafe target "../x"');
});
});
describe("tagAddJson", () => {
it("carries every installed item's warnings", () => {
const result = (name: string, warnings: string[]) => ({ name, warnings }) as RunAddResult;
expect(tagAddJson("lower-thirds", [result("a", []), result("b", ["no id"])])).toEqual({
ok: true,
tag: "lower-thirds",
installed: ["a", "b"],
warnings: ["b: no id"],
});
});
});