Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { failCommand } from "../utils/commandResult.js";
import { defineCommand } from "citty";
import type { Example } from "./_examples.js";
export const examples: Example[] = [
["Add a block to the current project", "hyperframes add claude-code-window"],
["Add a component effect", "hyperframes add shader-wipe"],
["Add all HTML-in-Canvas blocks", "hyperframes add html-in-canvas"],
["Add all caption blocks", "hyperframes add captions"],
["Target a specific project directory", "hyperframes add shader-wipe --dir ./my-video"],
["Skip the clipboard copy (CI/headless)", "hyperframes add shader-wipe --no-clipboard"],
];
import { existsSync, readFileSync } from "node:fs";
import { parseHTML } from "linkedom";
import { resolve, relative } from "node:path";
import {
isProjectRootMissing,
ITEM_TYPE_DIRS,
realpath,
type RegistryItem,
} from "@hyperframes/core";
import { c } from "../ui/colors.js";
import {
DEFAULT_REGISTRY_URL,
prepareItem,
publishItem,
resolveItemsByTag,
type PreparedItem,
} from "../registry/index.js";
import { resolveItemWithDependencies } from "../registry/resolver.js";
import { InvalidVariableValuesError } from "../registry/variableDefaults.js";
import {
gateRegistryItemsCompatibility,
RegistryCompatibilityError,
} from "../registry/compatibility.js";
import {
DEFAULT_PROJECT_CONFIG,
loadProjectConfig,
projectConfigPath,
recordProjectRegistryItems,
createProjectConfig,
} from "../utils/projectConfig.js";
import { copyToClipboard } from "../utils/clipboard.js";
import { trackRegistryItemAdded } from "../telemetry/events.js";
// ── Target-path resolution ──────────────────────────────────────────────────
// `registry-item.json` files specify `target` paths relative to the project
// root. For blocks and components we override the default path with the
// user's `hyperframes.json#paths` so a project can reshape its layout
// without editing every item's manifest.
export function remapTarget(
item: RegistryItem,
originalTarget: string,
paths: { blocks: string; components: string },
): string {
if (item.type === "hyperframes:block") {
// Anchored to the default target prefix from DEFAULT_PROJECT_CONFIG.paths.blocks.
// Targets that don't start with "compositions/" pass through unchanged.
// Strip trailing slashes to prevent double-slash in output.
const blocksDir = paths.blocks.replace(/\/+$/, "");
return originalTarget.replace(/^compositions\//, `${blocksDir}/`);
}
if (item.type === "hyperframes:component") {
// Anchored to the default target prefix from DEFAULT_PROJECT_CONFIG.paths.components.
const componentsDir = paths.components.replace(/\/+$/, "");
return originalTarget.replace(/^compositions\/components\//, `${componentsDir}/`);
}
// Examples are installed by `init`, not `add` — no remapping.
return originalTarget;
}
// ── Include-snippet builders ────────────────────────────────────────────────
// Shown to the user after install so they know how to wire the item into
// their host composition. Copied to clipboard by default.
/**
* Values tuned on the catalog page, as an attribute on the mount element.
*
* They ride on the host rather than being written into the installed file,
* which keeps two things true: the composition on disk stays byte-identical to
* the registry's, so a later reinstall can still tell an edit from an update,
* and two mounts of the same block can carry different values.
*
* Single-quoted because the JSON is full of double quotes, and a value
* containing a single quote is escaped rather than allowed to close it early.
*/
function variableValuesAttribute(values: Record<string, unknown> | null): string {
if (!values || Object.keys(values).length === 0) return "";
const json = JSON.stringify(values).replace(/'/g, "'");
return ` data-variable-values='${json}'`;
}
/**
* The file a consumer points at for this item: the snippet if it has one, else
* its composition, else whatever landed first. Project-relative, empty when the
* item installed no files.
*
* One owner for this choice. The paste snippet's `data-composition-src` and the
* recorded manifest target must name the same file, or a render would look for
* a block at a path the composition never mounts and report it as dropped.
*/
export function primaryInstalledTarget(item: RegistryItem): string {
const primary =
item.files.find((f) => f.type === "hyperframes:snippet") ??
item.files.find((f) => f.type === "hyperframes:composition") ??
item.files[0];
return primary?.target ?? "";
}
/** The id a composition file's root declares (inside its `<template>` when templated); a host must carry the same one. */
export function compositionRootId(html: string): string | undefined {
const { document } = parseHTML(html);
const content = document.querySelector("template")?.content ?? document;
return (
content.querySelector("[data-composition-id]")?.getAttribute("data-composition-id") ?? undefined
);
}
function installedRootId(file: string): string | undefined {
return existsSync(file) ? compositionRootId(readFileSync(file, "utf-8")) : undefined;
}
export function buildSnippet(
item: RegistryItem,
relativeTarget: string,
values: Record<string, unknown> | null = null,
compositionId?: string,
): string {
if (item.type === "hyperframes:block") {
// data-start omitted — adjust to your timeline position after pasting.
const dims =
"dimensions" in item && item.dimensions
? ` data-width="${item.dimensions.width}" data-height="${item.dimensions.height}"`
: "";
const vars = variableValuesAttribute(values);
const id = compositionId
? ` data-composition-id="${compositionId.replace(/"/g, """)}"`
: "";
return `<div${id} data-composition-src="${relativeTarget}" data-duration="${item.duration}"${dims}${vars}></div>`;
}
if (item.type === "hyperframes:component") {
return `<!-- paste from ${relativeTarget} into your composition -->`;
}
return "";
}
/** `add <tag> --json` output: each item's warnings, prefixed with its name. */
export function tagAddJson(tag: string, results: RunAddResult[]) {
return {
ok: true,
tag,
installed: results.map((r) => r.name),
warnings: results.flatMap((r) => r.warnings.map((w) => `${r.name}: ${w}`)),
};
}
/** `--vars` is JSON an agent or the catalog page produced; a malformed one is
* worth a clear error rather than a snippet that silently drops the values. */
export function parseVariableValues(raw: string | undefined): Record<string, unknown> | null {
if (raw === undefined) return null;
let parsed: unknown;
try {
parsed = JSON.parse(raw);
} catch {
throw new AddError("--vars must be a JSON object of variable values", "invalid-vars");
}
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
throw new AddError("--vars must be a JSON object of variable values", "invalid-vars");
}
return parsed as Record<string, unknown>;
}
// ── Core runner (tested) ────────────────────────────────────────────────────
export interface RunAddArgs {
name: string;
projectDir: string;
skipClipboard?: boolean;
/** Variable values to bake into the printed mount snippet. */
vars?: string;
/** Overwrite files this project has changed since they were installed. */
force?: boolean;
/** Current CLI version used for registry metadata compatibility checks. */
cliVersion?: string;
source?: "cli" | "studio";
}
export interface RunAddResult {
ok: true;
name: string;
type: RegistryItem["type"];
typeDir: string;
written: string[];
/** Files left as they were because this project had changed them. */
preserved: string[];
/** Names of every item installed, in order — dependencies first, then `name`. */
installed: string[];
snippet: string;
clipboardCopied: boolean;
/** Variable ids whose default was baked into an installed component. */
variablesApplied: string[];
warnings: string[];
}
export class AddError extends Error {
constructor(
message: string,
public readonly code:
| "unknown-item"
| "invalid-vars"
| "wrong-type"
| "install-failed"
| "example-type"
| "incompatible-cli",
) {
super(message);
this.name = "AddError";
}
}
// Compatibility-gate a set of resolved items before any install runs, mapping
// the shared gate's error into an AddError so the command surfaces the right
// exit code. Returns the accumulated (non-fatal) warnings from every item.
function assertCompatibleOrThrow(items: RegistryItem[], cliVersion?: string): string[] {
try {
return gateRegistryItemsCompatibility(items, cliVersion);
} catch (err) {
if (err instanceof RegistryCompatibilityError) {
throw new AddError(err.message, "incompatible-cli");
}
throw err;
}
}
// Install a topologically-ordered plan (dependencies first, requested item
// last). Every item is fetched and checked before any is written, so a refusal
// or failed fetch anywhere in the plan writes nothing. Returns all written paths.
async function installAll(
installPlan: RegistryItem[],
destDir: string,
baseUrl: string | undefined,
force: boolean,
requestedName: string,
variableValues: Record<string, unknown> | null,
): Promise<{
written: string[];
preserved: string[];
variablesApplied: string[];
variablesUnknown: string[];
}> {
const written: string[] = [];
const preserved: string[] = [];
let variablesApplied: string[] = [];
let variablesUnknown: string[] = [];
try {
const prepared: PreparedItem[] = [];
for (const planItem of installPlan) {
prepared.push(
await prepareItem(planItem, {
destDir,
baseUrl,
force,
// Only the item the user named. A dependency dragged in behind it never
// declared these variables and must not be rewritten by them.
variableValues: planItem.name === requestedName ? variableValues : null,
}),
);
}
for (const [i, planItem] of installPlan.entries()) {
const result = publishItem(prepared[i]!);
written.push(...result.written);
preserved.push(...result.preserved);
if (planItem.name === requestedName) {
variablesApplied = result.variablesApplied;
variablesUnknown = result.variablesUnknown;
}
}
} catch (err) {
if (isProjectRootMissing(err)) throw err;
if (err instanceof InvalidVariableValuesError) throw new AddError(err.message, "invalid-vars");
throw new AddError(describeInstallFailure(err, baseUrl), "install-failed");
}
return { written, preserved, variablesApplied, variablesUnknown };
}
/**
* Turn a transport failure into something a reader can act on.
*
* Item FILES are not cached (only manifests are), so a network blip surfaces
* here as node's bare `fetch failed` with no URL, no cause and no suggestion.
* That is what a user sees after copying a command off the catalog page, and
* it reads like the command was wrong rather than the network.
*/
export function describeInstallFailure(err: unknown, registry?: string): string {
const message = err instanceof Error ? err.message : String(err);
const cause = err instanceof Error && err.cause instanceof Error ? err.cause.message : "";
const transport =
/fetch failed|ENOTFOUND|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|socket hang up|aborted/i;
if (!transport.test(`${message} ${cause}`)) return `Install failed: ${message}`;
// Name the registry first. A project that set `registry` in hyperframes.json
// points at a private host, and when that host is down the failure has
// nothing to do with the user's connection -- telling them to check their
// network sends them to debug the one thing that is working.
const custom =
registry && !registry.startsWith(DEFAULT_REGISTRY_URL)
? `\n This project's hyperframes.json sets registry to ${registry}, so that is the host ` +
"being contacted, not the public registry. If it is down or private, that is the failure."
: "";
return (
`Install failed: could not download the item's files.\n ${message}` +
"\n Item files are not cached, so every install fetches them. This is usually the " +
"registry host or the network rather than a bad command." +
custom +
"\n Retry, or set HTTPS_PROXY if you are behind a proxy."
);
}
export async function runAdd(opts: RunAddArgs): Promise<RunAddResult> {
return (await addToProject(opts)).result;
}
/** The one install path for a catalog item, shared by `add` and Studio; `item` is the requested item as installed. */
export async function addToProject(
opts: RunAddArgs,
): Promise<{ result: RunAddResult; item: RegistryItem }> {
const projectDir = resolve(opts.projectDir);
// 1. Load (or write default) project config.
let config = loadProjectConfig(projectDir);
const hasConfig = existsSync(projectConfigPath(projectDir));
if (!hasConfig && existsSync(resolve(projectDir, "index.html"))) {
createProjectConfig(projectDir, DEFAULT_PROJECT_CONFIG);
config = DEFAULT_PROJECT_CONFIG;
}
// 2. Resolve the requested item and its transitive registryDependencies.
// The list comes back topologically sorted: dependencies first, the
// requested item last.
let resolved: RegistryItem[];
try {
resolved = await resolveItemWithDependencies(opts.name, { baseUrl: config.registry });
} catch (err) {
throw new AddError(err instanceof Error ? err.message : String(err), "unknown-item");
}
// `resolveItemWithDependencies` always pushes the requested item last (or throws),
// so the final element is the item the user asked for.
const item = resolved[resolved.length - 1]!;
if (item.type === "hyperframes:example") {
throw new AddError(
`"${item.name}" is an example — use \`hyperframes init <dir> --example ${item.name}\` instead.`,
"example-type",
);
}
// 3. Compatibility-gate every item we're about to install (dependencies
// included) before writing anything.
const warnings = assertCompatibleOrThrow(resolved, opts.cliVersion);
// 4. Remap targets per project config — each item by its own type.
const installPlan: RegistryItem[] = resolved.map((resolvedItem) => ({
...resolvedItem,
files: resolvedItem.files.map((f) => ({
...f,
target: remapTarget(resolvedItem, f.target, config.paths),
})),
}));
// 5. Install — dependencies first, requested item last.
const variableValues = parseVariableValues(opts.vars);
const { written, preserved, variablesApplied, variablesUnknown } = await installAll(
installPlan,
projectDir,
config.registry,
opts.force ?? false,
item.name,
variableValues,
);
// Report what landed, not what was asked for: a failed install throws above,
// and the bulk `add <tag>` path re-enters here per item, so this one place
// covers every way an item reaches a project.
for (const planItem of installPlan) {
trackRegistryItemAdded({
item: planItem.name,
itemType: planItem.type,
requested: planItem.name === item.name,
source: opts.source ?? "cli",
});
}
// Persist what came from the registry. Installed files are plain composition
// HTML with no provenance marker, so without this a later render cannot tell
// a catalog block from one the user wrote — and "did the catalog item survive
// into the video?" stays unanswerable.
recordProjectRegistryItems(
projectDir,
installPlan.map((planItem) => ({
name: planItem.name,
type: planItem.type,
target: primaryInstalledTarget(planItem),
})),
);
// 6. Build include snippet + clipboard copy for the requested item.
const itemForInstall = installPlan[installPlan.length - 1]!;
const snippetTargetRel = primaryInstalledTarget(itemForInstall);
const compositionId = installedRootId(resolve(projectDir, snippetTargetRel));
if (item.type === "hyperframes:block" && !compositionId) {
warnings.push(
`${snippetTargetRel} declares no data-composition-id, so the snippet has none; give its root one and put the same id on the snippet`,
);
}
const snippet = buildSnippet(item, snippetTargetRel, variableValues, compositionId);
const clipboardCopied = !opts.skipClipboard && snippet ? copyToClipboard(snippet) : false;
if (variablesUnknown.length > 0) {
warnings.push(`--vars ignored (not declared by ${item.name}): ${variablesUnknown.join(", ")}`);
}
const result: RunAddResult = {
ok: true,
name: item.name,
type: item.type,
typeDir: ITEM_TYPE_DIRS[item.type],
written,
preserved,
installed: installPlan.map((planItem) => planItem.name),
snippet,
clipboardCopied,
variablesApplied,
warnings,
};
return { result, item: itemForInstall };
}
// ── Command ─────────────────────────────────────────────────────────────────
export default defineCommand({
meta: {
name: "add",
description: "Install a block or component from the registry into this project",
},
args: {
name: {
type: "positional",
description:
"Registry item name or tag. Single items install directly (e.g. shader-wipe). " +
"If the name matches a tag instead, all blocks with that tag are installed (e.g. html-in-canvas, captions).",
required: true,
},
dir: {
type: "string",
description: "Project directory (defaults to the current working directory)",
},
clipboard: {
// Declared as the positive `clipboard` (default on) so citty's built-in
// `--no-<name>` negation handles `--no-clipboard`. Declaring the arg
// literally as `"no-clipboard"` made citty parse `--no-clipboard` as the
// negation of a (nonexistent) `clipboard` arg, so assertKnownFlags threw
// "Unknown flag: --clipboard" even though --help advertised it.
type: "boolean",
default: true,
description: "Copy the include snippet to the clipboard (use --no-clipboard to skip)",
},
json: {
type: "boolean",
description: "Print a machine-readable summary (written files + snippet) to stdout",
},
vars: {
type: "string",
description:
"JSON of variable values to bake into the printed snippet, as copied from a catalog page",
},
force: {
type: "boolean",
description:
"Overwrite files you have edited since installing them (they are kept by default)",
},
},
// `run` is 28 cyclomatic and predates this change, which touches only
// `runAdd`. Fallow scores it as new because the file changed. Splitting the
// tag-fallback branch out would fix it honestly and is worth doing, but not
// inside a telemetry change.
// fallow-ignore-next-line complexity
async run({ args }) {
const projectDir = resolve(args.dir ?? process.cwd());
const json = args.json === true;
const skipClipboard = args.clipboard === false;
const hasConfigBefore = existsSync(projectConfigPath(projectDir));
// Try single item first. If it fails, check if the name matches a tag.
try {
const result = await runAdd({
name: args.name,
projectDir,
skipClipboard,
force: args.force,
vars: args.vars,
});
const wroteConfig = !hasConfigBefore && existsSync(projectConfigPath(projectDir));
if (json) {
console.log(JSON.stringify(result));
return;
}
if (wroteConfig) {
console.log(c.dim(`Wrote default ${projectConfigPath(projectDir)}`));
}
for (const warning of result.warnings) {
console.warn(c.warn(`Warning: ${warning}`));
}
console.log("");
console.log(`${c.success("✓")} Added ${c.accent(result.name)} (${result.type})`);
const root = realpath(projectDir);
for (const file of result.preserved) {
console.log(
` ${c.warn("kept")} ${relative(root, file) || file} — you have edited this; --force to overwrite`,
);
}
for (const file of result.written) {
console.log(` ${c.dim(relative(root, file))}`);
}
if (result.variablesApplied.length > 0) {
// Say it out loud. A component's values are baked into the file rather
// than shown in the snippet, so without this the command looks
// identical whether --vars worked or was thrown away.
console.log(` ${c.dim(`variables applied: ${result.variablesApplied.join(", ")}`)}`);
}
if (result.snippet) {
console.log("");
console.log(c.dim("Include snippet:"));
console.log(` ${result.snippet}`);
console.log("");
console.log(
result.clipboardCopied
? c.dim("Copied to clipboard — paste into your host composition.")
: c.dim("Paste the snippet above into your host composition."),
);
}
} catch (singleErr) {
// Not a single item — try as a tag for bulk install
if (!(singleErr instanceof AddError) || singleErr.code !== "unknown-item") {
const msg = singleErr instanceof Error ? singleErr.message : String(singleErr);
if (json) console.log(JSON.stringify({ ok: false, error: msg }));
else console.error(c.error(msg));
failCommand();
}
let config = loadProjectConfig(projectDir);
if (
!existsSync(projectConfigPath(projectDir)) &&
existsSync(resolve(projectDir, "index.html"))
) {
createProjectConfig(projectDir, DEFAULT_PROJECT_CONFIG);
config = DEFAULT_PROJECT_CONFIG;
}
let items: Awaited<ReturnType<typeof resolveItemsByTag>>;
try {
items = await resolveItemsByTag(args.name, { baseUrl: config.registry, skipCache: true });
} catch {
items = [];
}
if (items.length === 0) {
const msg = singleErr instanceof Error ? singleErr.message : String(singleErr);
if (json) console.log(JSON.stringify({ ok: false, error: msg }));
else console.error(c.error(msg));
failCommand();
}
if (!json) {
console.log("");
console.log(
`${c.accent("◆")} Installing ${c.accent(String(items.length))} blocks tagged ${c.accent(args.name)}`,
);
}
const results: RunAddResult[] = [];
for (const item of items) {
try {
const result = await runAdd({
name: item.name,
projectDir,
skipClipboard: true,
force: args.force,
vars: args.vars,
});
results.push(result);
for (const warning of result.warnings) {
if (!json) console.log(` ${c.warn("Warning:")} ${warning}`);
}
if (!json) console.log(` ${c.success("✓")} ${result.name}`);
} catch (err) {
const reason = err instanceof Error ? err.message : String(err);
if (!json) console.log(` ${c.error("✗")} ${item.name} (skipped: ${reason})`);
}
}
if (json) {
console.log(JSON.stringify(tagAddJson(args.name, results)));
} else {
console.log("");
console.log(`${c.success("✓")} Installed ${results.length}/${items.length} blocks`);
}
}
},
});