Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { DEFAULT_MAX_SCREENSHOTS } from "../capture/types.js";
import { failCommand, scheduleCliExit } from "../utils/commandResult.js";
import { defineCommand } from "citty";
import { resolve } from "node:path";
import type { Example } from "./_examples.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { diag } from "../ui/diagnostics.js";
import type { CapturePhaseProgress } from "../capture/types.js";
import { parseCaptureDeadline } from "../capture/captureWatchdog.js";
const CAPTURE_PHASE_PREFIX = "HYPERFRAMES_CAPTURE_PHASE ";
function emitCapturePhase(event: CapturePhaseProgress): void {
diag.notice(`${CAPTURE_PHASE_PREFIX}${JSON.stringify(event)}`);
}
function parsePositiveInteger(
raw: string | undefined,
flag: string,
unit = "",
): number | undefined {
if (raw === undefined) return undefined;
const parsed = Number(raw);
if (!Number.isInteger(parsed) || parsed <= 0) {
console.error(`${flag} must be a positive integer${unit}.`);
failCommand();
}
return parsed;
}
export const examples: Example[] = [
["Capture a website into ./capture/", "hyperframes capture https://stripe.com"],
["Capture to a different directory", "hyperframes capture https://linear.app -o linear-video"],
["JSON output for AI agents", "hyperframes capture https://example.com --json"],
[
"Pull a video from the captured manifest by index",
"hyperframes capture --video ./linear-video --index 0",
],
[
"List videos referenced in the captured manifest",
"hyperframes capture --video ./linear-video --list",
],
];
export default defineCommand({
meta: {
name: "capture",
description: "Capture a website as editable HyperFrames components",
},
args: {
url: {
type: "positional",
description: "Website URL to capture (omit when using --video)",
required: false,
},
output: {
type: "string",
description: "Output directory name (default: ./capture, then ./capture-2/, ./capture-3/, …)",
alias: "o",
},
"skip-assets": {
type: "boolean",
description: "Skip downloading assets (images, SVGs)",
default: false,
},
"skip-vision": {
type: "boolean",
description: "Skip optional AI image captioning",
default: false,
},
"max-screenshots": {
type: "string",
description: `Maximum page-capture files including the full-page plate, excluding derived contact sheets (default: ${DEFAULT_MAX_SCREENSHOTS})`,
},
timeout: {
type: "string",
description: "Page load timeout in ms (default: 120000)",
},
"capture-budget": {
type: "string",
description:
"Cooperative post-navigation budget in ms (default: 120000), separate from page-load --timeout; not a hard wall-clock timeout and cannot interrupt already-started native/core work",
},
json: {
type: "boolean",
description: "Output JSON (for AI agents / programmatic use)",
default: false,
},
video: {
type: "string",
description:
"Switch to video-download mode: path to a captured project directory whose video-manifest.json should be read. Pair with --index, --video-url, or --list.",
},
index: {
type: "string",
description: "(--video mode) Manifest entry index to download (0-based)",
},
"video-url": {
type: "string",
description: "(--video mode) Exact video URL to download (must match a manifest entry)",
},
list: {
type: "boolean",
description: "(--video mode) List manifest entries and exit",
default: false,
},
},
// fallow-ignore-next-line complexity
async run({ args }) {
if (args.video) {
const { runVideoMode } = await import("./capture/video.js");
await runVideoMode({
project: args.video as string,
index: (args.index as string | undefined) ?? null,
url: (args["video-url"] as string | undefined) ?? null,
list: args.list as boolean,
});
return;
}
const url = args.url as string | undefined;
if (!url) {
console.error(
"Missing URL. Pass a website URL, or use --video <project> for video download.",
);
failCommand();
}
try {
new URL(url);
} catch {
console.error(`Invalid URL: ${url}`);
failCommand();
}
const captureBudgetMs = parsePositiveInteger(
args["capture-budget"] as string | undefined,
"--capture-budget",
" in milliseconds",
);
const maxScreenshots = parsePositiveInteger(
args["max-screenshots"] as string | undefined,
"--max-screenshots",
);
const isDefaultOutput = !args.output;
let outputName = (args.output as string | undefined) ?? "capture";
let outputDir = resolve(outputName);
if (isDefaultOutput) {
const { existsSync } = await import("node:fs");
// Auto-suffix when ./capture/ is taken: capture-2, capture-3, … so re-runs
// never silently merge into a previous capture's artifacts.
let n = 2;
while (existsSync(outputDir) && n < 100) {
outputName = `capture-${n}`;
outputDir = resolve(outputName);
n++;
}
if (existsSync(outputDir)) {
console.error(`./capture-{2..99} are all taken. Pass -o <name> to pick a directory.`);
failCommand();
}
}
const isJson = args.json as boolean;
if (!isJson) {
const { c } = await import("../ui/colors.js");
console.log();
console.log(c.dim("◆") + " Capturing " + c.bold(url));
if (isDefaultOutput && outputName !== "capture") {
console.log(` ${c.dim(`(./capture/ exists; writing to ./${outputName}/)`)}`);
}
console.log();
}
const { captureWebsite } = await import("../capture/index.js");
let captureFailed = false;
try {
const result = await captureWebsite(
{
url,
outputDir,
skipAssets: args["skip-assets"] as boolean,
skipVision: args["skip-vision"] as boolean,
maxScreenshots,
timeout: args.timeout ? parseInt(args.timeout as string) : undefined,
postNavigationBudgetMs: captureBudgetMs,
captureDeadlineMs: parseCaptureDeadline(process.env.HYPERFRAMES_CAPTURE_DEADLINE_MS),
json: isJson,
onPhase: emitCapturePhase,
},
isJson
? undefined
: (stage: string, detail?: string) => {
const stages: Record<string, string> = {
browser: " Launching browser...",
navigate: " Loading page...",
extract: " Extracting HTML & CSS...",
tokens: " Extracting design tokens...",
screenshots: " Capturing screenshots...",
assets: " Downloading assets...",
style: " Generating visual style...",
done: " Done",
};
const label = stages[stage] || ` ${stage}`;
console.log(detail ? `${label} ${detail}` : label);
},
);
captureFailed = !result.ok;
if (isJson) {
// Output structured JSON for Claude Code / programmatic use
console.log(
JSON.stringify(
{
ok: result.ok,
projectDir: result.projectDir,
url: result.url,
// Reported beside `ok`, because they answer different questions: a capture of an
// error page is `ok: true` with a status the caller has to see to know it.
httpStatus: result.httpStatus,
title: result.title,
screenshots: result.screenshots.length,
assets: result.assets.length,
dropped: result.dropped,
detectedSections: result.tokens.sections.length,
fonts: result.tokens.fonts.map((f) => f.family),
fontsDetailed: result.tokens.fonts,
animations: result.animationCatalog?.summary,
warnings: result.warnings,
lastPhase: result.lastPhase,
},
null,
2,
),
);
} else {
const { c } = await import("../ui/colors.js");
console.log();
const icon = result.ok ? c.success("◇") : c.error("✗");
const status = result.ok ? "Captured" : "Capture failed";
console.log(icon + ` ${status} ${c.bold(result.title)} → ${c.dim(outputDir)}`);
console.log();
console.log(` ${c.dim("Screenshots:")} ${result.screenshots.length}`);
console.log(` ${c.dim("Assets:")} ${result.assets.length}`);
const droppedTotal = Object.values(result.dropped).reduce((sum, n) => sum + n, 0);
if (droppedTotal > 0) {
const breakdown = Object.entries(result.dropped)
.filter(function (entry) {
return entry[1] > 0;
})
.map(function (entry) {
return entry[1] + " " + entry[0];
})
.join(", ");
console.log(` ${c.dim("Dropped:")} ${droppedTotal} (${breakdown})`);
}
console.log(` ${c.dim("Sections:")} ${result.tokens.sections.length}`);
console.log(
` ${c.dim("Fonts:")} ${result.tokens.fonts
.map(function (f) {
return (
f.family +
" (" +
(f.variable && f.weightRange
? f.weightRange[0] + "-" + f.weightRange[1] + " variable"
: f.weights.join(",")) +
")"
);
})
.join(", ")}`,
);
if (result.warnings.length > 0) {
console.log();
for (const w of result.warnings) {
console.log(` ${c.warn("⚠")} ${w}`);
}
}
console.log();
}
} catch (err) {
const errMsg = normalizeErrorMessage(err);
try {
const { mkdirSync } = await import("node:fs");
const { formatCaptureFailureReason } = await import("../capture/captureTimeout.js");
const { writeCaptureFileSync } = await import("../capture/captureFile.js");
mkdirSync(outputDir, { recursive: true });
const reason = formatCaptureFailureReason(errMsg);
writeCaptureFileSync(
`${outputDir}/BLOCKED.md`,
`# Capture Failed\n\n${reason}\n\nURL: ${url}\n\n## What to try\n\n- Re-run with a longer timeout: \`--timeout 60000\`\n- The site may block headless browsers (anti-bot protection)\n- Try capturing a different page on the same domain\n`,
"utf-8",
);
} catch {
/* best-effort */
}
if (isJson) {
console.log(JSON.stringify({ ok: false, error: errMsg }));
} else {
console.error(`\n ✗ Capture failed: ${errMsg}\n`);
}
scheduleCliExit(1);
failCommand();
}
scheduleCliExit(captureFailed ? 1 : 0);
if (captureFailed) failCommand();
},
});