Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* Registry resolver — loads the top-level manifest and per-item manifests.
* No transitive dependency resolution yet (examples don't have any); added
* when blocks/components need it for the `add` command.
*/
import type { ItemType, RegistryItem, RegistryManifestEntry } from "@hyperframes/core";
import { fetchItemManifest, fetchRegistryManifest, DEFAULT_REGISTRY_URL } from "./remote.js";
import { runWithConcurrencyLimit } from "../utils/concurrency.js";
export interface ResolveOptions {
baseUrl?: string;
/** Bypass the 24h manifest cache and fetch fresh data from the registry. */
skipCache?: boolean;
/**
* Called once with a summary when items fail to load inside `loadAllItems`.
* Defaults to writing a diagnostic line to stderr. Pass a quieter
* implementation when rendering structured output (clack prompts, JSON, etc.).
*/
onWarn?: (message: string) => void;
}
function defaultWarn(message: string): void {
process.stderr.write(`hyperframes:registry ${message}\n`);
}
/**
* List all items in the registry, optionally filtered by type. Returns empty
* if the registry is unreachable — callers should fall back to bundled items.
*/
export async function listRegistryItems(
filter?: { type?: ItemType },
options: ResolveOptions = {},
): Promise<RegistryManifestEntry[]> {
const baseUrl = options.baseUrl ?? DEFAULT_REGISTRY_URL;
const manifest = await fetchRegistryManifest(baseUrl, { skipCache: options.skipCache });
if (!manifest) return [];
if (!filter?.type) return manifest.items;
return manifest.items.filter((item) => item.type === filter.type);
}
// Hundreds of item manifests sharing one slow link all started their timeouts at once.
const ITEM_FETCH_CONCURRENCY = 32;
/**
* Load every item's full manifest, a bounded number at a time. Items that fail
* to load are skipped with one summary warning so one missing manifest doesn't
* break the picker; after a timeout the rest come from cache only.
*/
export async function loadAllItems(
entries: RegistryManifestEntry[],
options: ResolveOptions = {},
): Promise<RegistryItem[]> {
const baseUrl = options.baseUrl ?? DEFAULT_REGISTRY_URL;
const warn = options.onWarn ?? defaultWarn;
const skipped: string[] = [];
let firstReason = "";
let timedOut = false;
const loaded = await runWithConcurrencyLimit(entries, ITEM_FETCH_CONCURRENCY, async (e) => {
try {
return await fetchItemManifest(e.name, e.type, baseUrl, { cacheOnly: timedOut });
} catch (err) {
if (err instanceof Error && err.name === "TimeoutError") timedOut = true;
skipped.push(`"${e.name}"`);
firstReason ||= String(err);
return undefined;
}
});
if (skipped.length === 1) warn(`skipped item ${skipped[0]}: ${firstReason}`);
else if (skipped.length > 1)
warn(
`skipped ${skipped.length} items (${skipped.slice(0, 3).join(", ")}${skipped.length > 3 ? ", ..." : ""}): ${firstReason}`,
);
return loaded.filter((item): item is RegistryItem => item !== undefined);
}
/**
* Resolve a single item by name. Throws if unknown or unreachable.
*
* This is a thin guard around `resolveItemWithDependencies`: it refuses items
* that declare `registryDependencies`, throwing a clear error that points the
* caller at the dependency-aware API. That keeps single-item install paths
* from silently dropping a transitive dependency — any caller that wants deps
* installed must opt in via `resolveItemWithDependencies`.
*/
export async function resolveItem(
name: string,
options: ResolveOptions = {},
): Promise<RegistryItem> {
const items = await resolveItemWithDependencies(name, options);
if (items.length > 1) {
const deps = items
.slice(0, -1)
.map((i) => i.name)
.join(", ");
throw new Error(
`Item "${name}" declares registryDependencies (${deps}); use resolveItemWithDependencies ` +
`to resolve and install them in order.`,
);
}
const item = items[items.length - 1];
if (!item) {
throw new Error(unreachableRegistryMessage(name, options.baseUrl));
}
return item;
}
/**
* "registry unreachable or empty" without saying WHICH registry is the same
* dead end the item-file failure used to be: a project that sets `registry` in
* hyperframes.json reads it as the public catalog having lost the item, and
* goes looking in the wrong place. Naming the host is the diagnosis.
*/
export function unreachableRegistryMessage(name: string, baseUrl?: string): string {
const where =
baseUrl && !baseUrl.startsWith(DEFAULT_REGISTRY_URL)
? ` Contacted ${baseUrl}, set by this project's hyperframes.json, not the public registry.`
: "";
return `Item "${name}" not found — registry unreachable or empty.${where}`;
}
/**
* Resolve an item and all of its transitive `registryDependencies` in
* topological order — dependencies first, the requested item last — so callers
* can install the returned list front-to-back and have every prerequisite on
* disk before the item that needs it.
*
* Detects cycles (throws with the offending path) and missing dependencies
* (throws naming the absent item). Shared dependencies in a diamond graph are
* resolved and returned exactly once.
*
* Note: dependencies are fetched serially during the DFS walk. This keeps the
* cycle-detection bookkeeping (the `visiting` set) simple and correct; the
* registry is small enough that the extra round-trips don't matter. Switch to
* parallel sibling fetches only if graph depth ever becomes a real cost.
*/
export async function resolveItemWithDependencies(
name: string,
options: ResolveOptions = {},
): Promise<RegistryItem[]> {
const entries = await listRegistryItems(undefined, options);
const entry = entries.find((e) => e.name === name);
if (!entry) {
const available = entries.map((e) => e.name).join(", ");
throw new Error(
available.length > 0
? `Item "${name}" not found in registry. Available: ${available}`
: unreachableRegistryMessage(name, options.baseUrl),
);
}
const entryByName = new Map(entries.map((e) => [e.name, e]));
const visiting = new Set<string>();
const visited = new Set<string>();
const ordered: RegistryItem[] = [];
const itemCache = new Map<string, Promise<RegistryItem>>();
// `async` so the missing-dependency path surfaces as a promise rejection
// rather than a synchronous throw, keeping the control flow consistent with
// the `Promise<RegistryItem>` return type. The body has no `await`, so the
// cache is still populated synchronously on first request (dedup intact).
const getItem = async (itemName: string): Promise<RegistryItem> => {
const existing = itemCache.get(itemName);
if (existing) return existing;
const registryEntry = entryByName.get(itemName);
if (!registryEntry) {
const available = entries.map((e) => e.name).join(", ");
throw new Error(
available.length > 0
? `Dependency "${itemName}" not found in registry. Available: ${available}`
: unreachableRegistryMessage(itemName, options.baseUrl),
);
}
const pending = fetchItemManifest(registryEntry.name, registryEntry.type, options.baseUrl);
itemCache.set(itemName, pending);
return pending;
};
const visit = async (itemName: string, path: string[]): Promise<void> => {
if (visited.has(itemName)) return;
if (visiting.has(itemName)) {
const cycleStart = path.indexOf(itemName);
const cyclePath = [...path.slice(cycleStart), itemName].join(" -> ");
throw new Error(`Circular registryDependencies detected: ${cyclePath}`);
}
visiting.add(itemName);
const item = await getItem(itemName);
for (const dep of item.registryDependencies ?? []) {
await visit(dep, [...path, itemName]);
}
visiting.delete(itemName);
visited.add(itemName);
ordered.push(item);
};
await visit(name, []);
return ordered;
}
/**
* Resolve all items matching a tag. Loads each item's full manifest to check
* tags (the top-level registry.json only has name+type, not tags). Items that
* fail to load are silently skipped.
*/
export async function resolveItemsByTag(
tag: string,
options: ResolveOptions = {},
): Promise<RegistryItem[]> {
const entries = await listRegistryItems(undefined, options);
const allItems = await loadAllItems(entries, { ...options, onWarn: () => {} });
return allItems.filter(
(item) => "tags" in item && Array.isArray(item.tags) && item.tags.includes(tag),
);
}