For AI agents

HyperFrames was designed for the case where a model — not a human — is at the keyboard. Every command is non-interactive, flag-driven, and emits structured JSON. Every render is deterministic, so the model can verify its own output by hash.

What you'll learn

• The three-leg loop: prompt, generate, render
• How to use lint --json and stable exit codes for self-correction
• Why determinism matters for agent safety

A full agent turn

The three tabs below are one agent turn: the prompt sent to the LLM, the HTML it returned, and the shell command that turned it into video.

System: You write HyperFrames compositions. Output one HTML document, no commentary.
Use data-width, data-height, data-duration on the root.
Use data-start and data-duration on tracks.
You may listen to "hf-seek" on window.

User: Make a 4-second 1920x1080 product card for "Lumen Mug".
Background should fade from #0a0a0a to #1f1f23.
Title fades in at 0.4s and stays.
Subtitle "Brews 6oz in 90s" slides up at 1.2s.
End card "lumen.shop" appears at 3s.

Minimal loop

import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { writeFile } from "node:fs/promises";
const sh = promisify(execFile);

async function authorAndRender(prompt: string) {
  let html = await llm.writeComposition(prompt);
  await writeFile("comp.html", html);

  const lint = JSON.parse(
    (await sh("hyperframes", ["lint", "comp.html", "--json"])).stdout,
  );
  if (lint.errors.length > 0) {
    html = await llm.fix(html, lint.errors);
    await writeFile("comp.html", html);
  }

  const out = JSON.parse(
    (await sh("hyperframes", ["render", "comp.html", "--out", "out.mp4", "--json"])).stdout,
  );
  return out; // { status, sha, size, frames, durationMs }
}

Determinism is a safety feature

Catalog-first authoring

The agent will produce more reliable compositions if you point it at the registry instead of asking it to invent visuals from scratch. A prompt like "Use the glitch-text block from the catalog. Headline 'Now shipping.' Gradient red to blue." is dramatically more reliable than "make a cool glitch effect". Registry blocks are pre-tested and pre-rendered.

hyperframes add glitch-text

Use and avoid

Use lint --json and inspect --json before render. They are cheap; render is expensive. Always pass --json. Stable error codes are documented in the CLI reference.

Avoid parsing pretty text. Avoid --human-friendly in the loop — it makes the output unparseable. Avoid re-authoring from scratch on lint warnings; small fixes are cheaper. Avoid rendering twice when one lint-then-render pass would do.

Next

• CI & batch — scale the loop horizontally
• Programmatic video from data — N rows in, N MP4s out