Miguel ÁngelandMiguel Angel Simon Sierra 1ae2067b8d feat(catalog): put the variables panel back, on payloads (#3199)
* feat(catalog): put the variables panel back, on payloads

The panel drove its preview by loading an .html from docs/public, a type the
host does not publish, so it showed an empty frame in production and was
parked when the catalog was re-landed.

It now mounts the same JSON payload the plain player uses and re-mounts it as
values change, injecting them as window.__hfVariables into the composition head
before any of its scripts run, which is where the runtime reads overrides from.
Doing it in the markup rather than after load is what stops the composition
initialising with the wrong values first.

172 items with variables get the panel back; the playhead carries across a
change so a tweak mid-shot does not jump back to frame zero.

* fix(docs): drop the unused url form and the needless escapes

* fix(docs): the panel cannot reference a binding beside the export

* feat(catalog): make importing an SVG the obvious move

A reader arrives at this control with a shape, not with path data, and the
panel asked for the coordinates first. Import is now the primary action in a
drop target you can see is a drop target, and the raw path sits behind a
disclosure for anyone who wants it.

* feat(cli): let a fruitless catalog search report the gap

An agent that searches by meaning and finds nothing worth installing knows
something we do not: the name of a move the catalog is missing. There was no
way to tell us, so that knowledge was lost at the end of every run.

hyperframes feedback --search-miss "<query>" --wanted "<the move>" records it.
It carries no rating, so it never lands in the rating metric, and it is a
separate deliberate command rather than something catalog --query does on its
own: plain search still sends nothing, which is what the CLI promises.

--rating stops being required at the arg level, since a miss has no rating to
give. The check moved into the run body, where an absent one is now handled
rather than crashing on undefined.

* feat(cli): carry tuned variable values into the install snippet

Someone who tunes a block on its catalog page had no way to keep those values:
the install command was the same one everybody gets, and the tuning stayed on
the page.

hyperframes add <item> --vars '<json>' now prints a mount element carrying
data-variable-values, so the values land where the block is used.

They ride on the host rather than being written into the installed file. That
keeps the composition on disk byte-identical to the registry's, so a later
reinstall can still tell an edit from an update, and it lets two mounts of the
same block carry different values.

* fix(catalog): serve the item's own directory so runtime paths resolve

Some compositions assemble their asset URLs at run time —
"compositions/components/" + texture + ".png" for the texture masks, a font the
compiler pulled into _remote_media — and no scan of the markup can see a string
that does not exist until a script concatenates it. Those items either rendered
black or were dropped to a video that had never been uploaded.

Each item that needs it now has its prepared directory published, and its
payload carries a <base> pointing at it, so any relative path the composition
invents resolves. caption-texture renders its masks again, and
variable-font-flex has a preview at all for the first time: its MP4 and poster
are both 403.

Both layouts are published, because which one a composition asks for differs
per item, and a directory only earns that if it is under 2 MB. The 12 MB
texture sheet keeps the recorded video it already had.

* fix(catalog): let the variables panel actually drive the composition

Every control on the panel was inert. The values reached the composition and
nothing repainted, because the payload had already been compiled: compiling
inlines a mounted component and resolves its variables into the markup and CSS,
so by the time a reader turns a knob there is nothing left to change.

An item that declares variables now ships uncompiled, keeping the mount the
runtime loads at run time, which is the only state where data-variable-values
still means anything. The component travels inline as a data URI rather than a
sibling file, because .html is the one type the docs host will not publish. The
demo's own pinned values come off, so the reader's choices reach the mount
instead of losing to the values the demo picked to show itself off.

Measured on the rendered frame rather than the DOM: green rgb(98,207,144),
blue rgb(6,6,199), violet rgb(177,147,230), and back to green.

docs/public/catalog drops from 48 MB to 35 MB along the way, since an
uncompiled payload carries far less than an inlined one.

* feat(catalog): keep variable changes in the url

A reader who tuned a piece lost it on reload, and had nothing to send anyone.
The values now live in the query string, scoped by composition id so two links
never read each other,and only the ones that differ from the defaults are
written, so changing one knob gives a short URL rather than every variable
spelled out.

replaceState rather than pushState: dragging a slider should not leave a trail
of history entries. An unreadable value is ignored rather than thrown, so a
truncated or hand-edited link opens the piece at its defaults.

* fix(catalog): only rewrite the url when a value actually changed

* refactor(catalog): memoise the declared defaults on their content

* feat(catalog): offer an install command carrying the tuned values

The Install block is generated before anyone touches a knob, so it can only
ever print the plain command. Someone who spent a minute tuning a piece copied
it and got the defaults back.

The panel now carries its own command in the Snippet tab, with --vars holding
exactly the values that differ. An untouched piece still offers the same short
command, so nothing gets noisier for the common case.

* fix(catalog): a piece with nothing to render is a skip, not a failure

caption-blend-difference is a stylesheet and a paragraph of prose — a class you
add to your own captions, with no standalone scene to show. The generator
treated that as a build failure, so every run ended by reporting something
broken when nothing was.

It now reports the shape it is and keeps its recorded video, which is the only
honest preview such an item has. A genuine render failure still throws.

* fix(catalog): restore variables from the url on a cold load

A shared link opened at the defaults. The first render happens on the server,
where there is no window to read the query string from, and React then hydrates
against that markup and never revisits it — so the values only appeared once you
touched a control.

The URL is read again after mount, which is the first moment it exists. The
value is also escaped once now rather than twice: URLSearchParams already
decodes on the way out, and decoding a second time turned an SVG path full of
percent-escapes into something that no longer parsed, besides doubling the
length of every link.

* fix(catalog): mount the preview with the values a link carried

The frame was built from the declared defaults and the shared values were
posted to it afterwards, which is too late for anything the composition reads
once at init: a path arrived after the mark had already been drawn from the
default one, so a link looked right in the panel and wrong on screen.

* feat(catalog): the install command follows the values you tuned

Copying the Install line gave the plain command back, because that block is
generated before anyone touches a knob and had no way to know what changed. The
tuned command only existed in the panel Snippet tab, which is not where anyone
looks for it.

The line now reads the same query string the panel writes, so the two agree
without either component knowing the other exists, and a shared link carries the
right command too. replaceState fires no event, so the panel announces its own
writes.

* fix(catalog): send a text variable to the preview once it is finished

Every other control in the explorer reports a whole value on every event: a
slider at any position is a position, a swatch is a colour. A text field is
not. Typing v3 into a badge posted v first, so the preview remounted and
rendered a composition built from half a word.

The post now waits while a text field has focus and goes out when the edit is
committed, with Enter or by clicking away. The field itself is unchanged and
still tracks every keystroke.

---------

Co-authored-by: Miguel Angel Simon Sierra <miguelangelsi07@gmail.com>
2026-08-10 22:40:01 -04:00
2026-08-10 08:08:16 -07:00
2026-03-21 22:43:56 -07:00

HyperFrames

npm version npm downloads License Node.js Discord

Write HTML. Render video. Built for agents.

Quickstart | Showcase | Playground | Catalog | Docs | Discord

HyperFrames demo: HTML code on the left transforms into a rendered video on the right

HyperFrames is an open-source framework for turning HTML, CSS, media, and seekable animations into deterministic MP4 videos. Use it locally with the CLI, from AI coding agents with skills, or as the rendering core behind hosted authoring workflows.

Quick Start

With an AI coding agent

Install the HyperFrames skills, then describe the video you want:

npx skills add heygen-com/hyperframes --full-depth

The picker opens with nothing pre-selected — the Core Skills group is all you need: the /hyperframes router installs each creation workflow on demand. Agents and non-interactive runs should use npx hyperframes skills update instead — it installs exactly the core set, whereas a non-interactive skills add without --skill installs all 19.

--full-depth does a full clone of the repo's current main. Without it, skills add fetches the skills.sh registry blob, which lags main by hours — you'd get an older copy of a skill. (hyperframes skills update already installs full-depth.)

Try a prompt like:

Using /hyperframes, create a 10-second product intro with a fade-in title, a background video, and subtle background music.

The skills teach agents the HyperFrames production loop: plan the video, write valid HTML, wire seekable animations, add media, lint, preview, and render. They work with Claude Code, Cursor, Gemini CLI, Codex, and other coding agents that support skills.

Skills

HyperFrames ships 19 skills agents load on demand. Read /hyperframes first — it's the router and capability map; it picks a workflow for any "make me a…" request — video, deck, or composition port — and points to the domain skills below.

Default to the core set — the router installs each creation workflow on demand. npx hyperframes skills update installs exactly that from anywhere; the interactive picker (npx skills add heygen-com/hyperframes --full-depth) lists it as the "Core Skills" group, nothing pre-selected. The picker is interactive-only — a non-interactive or agent run without --skill installs all 19. Use npx skills add heygen-com/hyperframes --all --full-depth to install all 19 deliberately (skips the picker), or npx skills add heygen-com/hyperframes --skill <name> --full-depth for just one (bare name, no leading /). Keep --full-depth — it installs the current main; without it skills add fetches the skills.sh blob, which lags by hours.

Installs stay lean after that: npx hyperframes init keeps the core set fresh (the router, the hyperframes-* domain skills, and media-use — plus whatever is already installed; /figma stays on demand) and never expands a partial install; the creation workflows install on demand — the router runs npx hyperframes skills update <workflow> before entering one. Nothing re-pulls the full set behind your back.

Upload to Codex

Build the upload-ready Codex plugin archive from the committed HEAD version of the manifest, brand assets, and skills:

bun run package:codex-plugin

This writes dist/hyperframes-plugin.zip with a hyperframes/ root folder and fails if the archive exceeds Codex's 100 MB upload limit.

Router

Skill Use when
/hyperframes Read first for any request to make / create / edit / animate / render a video, animation, or motion graphic. Capability map for the domain skills, the intent layer that confirms every creation brief up front, and intent router for the creation workflows below.

Creation workflows

Skill Use when
/product-launch-video Any website — marketing / launching / promoting a product (from its URL, a brief, or a script), or a site tour / showcase / social clip featuring the site's own visuals. Up to ~3 min (sweet spot 30-90s).
/faceless-explainer Explaining a topic / concept from arbitrary text — no product, no URL, no website capture; every visual is LLM-invented (typography / abstract / diagram / data-viz).
/pr-to-video A GitHub pull request (PR URL, owner/repo#N ref, or "this PR") → changelog / feature-reveal / fix / refactor explainer, read via the gh CLI.
/embedded-captions Adding captions / subtitles to an existing talking-head video (footage untouched) — verbatim rail, embedded climax behind the subject, or pure-cinematic embed.
/talking-head-recut Packaging an existing talking-head / interview / podcast video with designed graphic overlays — lower-thirds, data callouts, kinetic titles, pull-quotes, side panels, PiP.
/motion-graphics A short, unnarrated, design-led motion graphic (~under 10s) — kinetic type, stat / chart hit, logo sting, lower-third, animated tweet / headline. MP4 or transparent overlay.
/music-to-video A music track (audio file, video to pull audio from, or one generated from a mood brief) → a beat-synced video — lyric, slideshow, or kinetic promo; music drives pacing.
/slideshow A presentation / pitch deck / interactive deck — discrete slides, fragment reveals, branching, hotspot navigation, presenter mode. Output is a navigable deck, not a rendered video.
/general-video Anything else — longer or multi-scene pieces, brand / sizzle reel, title card, static loop, freeform composition. Input- and length-agnostic fallback, and the home of companion mode (co-create with the full toolbox).
/remotion-to-hyperframes Porting an existing Remotion (React) composition's source to HyperFrames HTML. One-way migration, not creation.

Domain skills (loaded on demand)

Atomic capabilities the creation workflows compose against — pull one when you need that specific layer.

Skill Covers
/hyperframes-core The composition contract — data-* timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, determinism rules.
/hyperframes-animation All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).
/hyperframes-keyframes Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus hyperframes keyframes diagnostics for rendered motion.
/hyperframes-creative Non-animation creative direction — frame.md / design.md, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.
/media-use The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice, color grade, LUT) into a frozen local file or paste-ready block + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking.
/hyperframes-cli CLI dev loop — init, lint, check, snapshot, preview, render, publish, doctor, plus HeyGen-hosted cloud rendering (cloud render) and AWS Lambda rendering (lambda deploy / render / progress).
/hyperframes-registry Install and wire registry blocks and components into compositions via hyperframes add. Authoring a new block or component to contribute upstream.
/figma Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition.

For visual design handoff workflows, see the Claude Design guide and Open Design guide.

Manually with the CLI

npx hyperframes init my-video
cd my-video
npx hyperframes preview      # preview in browser with live reload
npx hyperframes render       # render to MP4

Requirements: Node.js 22+, FFmpeg

What You Can Build

Need ideas? Browse the Showcase for finished videos you can watch, read, run, and remix.

  • Product launch videos and feature announcements
  • PR walkthroughs with animated code diffs, narration, and captions
  • Data visualizations, chart races, and map animations
  • Social videos with kinetic captions, overlays, and music
  • Docs-to-video, PDF-to-video, and site-tour explainers
  • Reusable motion graphics for automated content pipelines

Frame.md

frame.md — your design system, ready for video.

Every brand has a design.md. None of them were written for a camera. frame.md is the missing translation layer: it takes your web-context design spec and inverts it for the frame — the same tokens, the same rules, but rewritten so an AI agent can compose a promo video without guessing at scale or reaching for web chrome.

The output is a DESIGN.md superset your whole toolchain can read. Atoms stay sacred. Composition stays free. Numbers come from the script.

Biennale Yellow
Biennale Yellow
BlockFrame
BlockFrame
Blue Professional
Blue Professional
Bold Poster
Bold Poster
Broadside
Broadside
Capsule
Capsule
Cartesian
Cartesian
Cobalt Grid
Cobalt Grid
Coral
Coral
Creative Mode
Creative Mode

Browse and remix them all at hyperframes.dev/design.

How It Works

Define a video as HTML. Add data attributes for timing and tracks. Use GSAP, CSS, Lottie, Three.js, Anime.js, WAAPI, or your own frame adapter for seekable animation.

<div id="stage" data-composition-id="launch" data-start="0" data-width="1920" data-height="1080">
  <video
    class="clip"
    data-start="0"
    data-duration="6"
    data-track-index="0"
    src="intro.mp4"
    muted
    playsinline
  ></video>

  <h1 id="title" class="clip" data-start="1" data-duration="4" data-track-index="1">Launch day</h1>

  <audio
    data-start="0"
    data-duration="6"
    data-track-index="2"
    data-volume="0.5"
    src="music.wav"
  ></audio>

  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1);
    window.__timelines = window.__timelines || {};
    window.__timelines.launch = tl;
  </script>
</div>

Preview instantly in the browser. Render locally or in Docker. The renderer seeks each frame in headless Chrome and encodes the result with FFmpeg, so the same input produces the same video.

HyperFrames Stack

HyperFrames is the open-source rendering engine, plus a growing set of tools around HTML-native video creation.

Piece Status What it does
CLI Available Scaffold, preview, lint, inspect, and render local video projects
Core / Engine / Producer Available Parse compositions, drive headless Chrome, encode video, and mix audio
Catalog Available Reusable blocks and components for transitions, overlays, captions, charts, maps, and effects
Agent skills Available Teach coding agents the video-production patterns that generic web docs miss
Studio Available, evolving Browser surface for previewing and editing compositions
AWS Lambda rendering Available Deploy a distributed render stack and drive renders from your laptop or CI
hyperframes.dev Available Community playground for previewing, iterating, sharing, and rendering HTML-native video projects
frame.md Available Invert your design system for the camera — a DESIGN.md superset an agent can compose video from

Catalog

Install ready-to-use blocks and components:

npx hyperframes add flash-through-white   # shader transition
npx hyperframes add instagram-follow      # social overlay
npx hyperframes add data-chart            # animated chart

Browse the catalog at hyperframes.heygen.com/catalog.

Why HyperFrames?

  • HTML-native: compositions are HTML files with data attributes. No React requirement, no proprietary timeline format.
  • Agent-friendly: agents already write HTML, and the CLI is non-interactive by default.
  • Deterministic: same input, same frames, same output. Built for CI, regression tests, and automated rendering.
  • No build step: an index.html composition plays as-is and can be previewed directly in the browser.
  • Adapter-based animation: bring GSAP, CSS animations, Lottie, Three.js, Anime.js, WAAPI, or a custom runtime.
  • Open source: Apache 2.0 license, with no per-render fees or commercial-use thresholds.

HyperFrames vs Remotion

HyperFrames is inspired by Remotion. Both tools render video with headless Chrome and FFmpeg. The main difference is the authoring model: Remotion's bet is React components; HyperFrames' bet is plain HTML that humans and agents can both write easily.

HyperFrames Remotion
Authoring HTML + CSS + seekable animation React components
Build step None; index.html plays as-is Bundler required
Agent handoff Plain HTML files JSX / React project
Library-clock animations Seekable, frame-accurate via adapters Wall-clock animation patterns need care
Distributed rendering Local and AWS Lambda render paths Remotion Lambda, mature cloud renderer
License Apache 2.0 Source-available Remotion License

Read the full comparison in the HyperFrames vs Remotion guide.

Documentation

Full documentation: hyperframes.heygen.com/introduction

Packages

Package Description
hyperframes CLI for creating, previewing, linting, and rendering compositions
@hyperframes/core Types, parsers, generators, linter, runtime, and frame adapters
@hyperframes/engine Seekable page-to-video capture engine using Puppeteer and FFmpeg
@hyperframes/producer Full rendering pipeline for capture, encode, and audio mix
@hyperframes/studio Browser-based composition editor UI
@hyperframes/player Embeddable <hyperframes-player> web component
@hyperframes/shader-transitions WebGL shader transitions for compositions
@hyperframes/aws-lambda AWS Lambda SDK and deployment surface for distributed renders

Community

HyperFrames is used in production at HeyGen, with community examples from teams like tldraw, TanStack, and others in ADOPTERS.md. Open a PR if your team is using HyperFrames.

Development Note

The repo uses Git LFS for golden regression-test baselines under packages/producer/tests/**/output.mp4 (about 240 MB of .mp4 files). If you're cloning the full repo for development, install Git LFS first:

# macOS
brew install git-lfs

# Ubuntu / Debian
sudo apt install git-lfs

# Windows
winget install GitHub.GitLFS

# Then, once per machine
git lfs install

If you only need source files, you can skip LFS content:

GIT_LFS_SKIP_SMUDGE=1 git clone https://github.com/heygen-com/hyperframes.git

License

Apache 2.0

S
Description
Write HTML. Render video. Built for agents.
Readme
750 MiB
Languages
JavaScript 56%
TypeScript 43.8%