The Problem

Creating deterministic video from HTML/CSS/animation is tedious: designers must manually translate web assets into a timeline, and automation agents lack a reliable, reproducible rendering pipeline. The result is fragile scripts, duplicated tooling, and inconsistent output quality.

What This Does

hyperframes supplies an end‑to‑end stack that turns a web‑style markup file into an MP4 video. The repository is a portfolio of four self‑contained projects:

  • packages – the core runtime, CLI, AWS Lambda wrapper, and rendering engine (packages/*).
  • skills – pre‑packaged “agent skills” that let LLM‑based coders invoke HyperFrames (skills/*).
  • registry – a catalog of reusable block definitions and design tokens (registry/*).
  • docs / examples – reference material, MDX catalog entries, and sample Dockerfiles.

Key source files include packages/cli/src/commands/_examples (CLI entry), packages/engine/src/services/frameCapture.ts (frame capture), and packages/producer/src/services/renderOrchestrator.ts (orchestration). The project uses React for the preview UI, Tailwind for styling, Docker for reproducible builds, and Terraform for optional cloud deployment.

How It Is Wired

Execution begins at the CLI entry points declared in packages/cli/src/auth/index.ts, capture/index.ts, and commands/_examples. The npx hyperframes script (generated from packages/cli/package.json bin field) loads packages/cli/src/ui/colors.ts – a hub module imported by 60 other files – and parses the user‑provided frame.md or HTML source.

The CLI dispatches to the engine (packages/engine/src/services/frameCapture.ts) which drives FFmpeg (via packages/cli/src/docker/Dockerfile.render). The engine calls the producer (packages/producer/src/services/renderOrchestrator.ts), a high‑instability module (22 inbound, 22 outbound imports) that coordinates asset loading, animation sequencing, and final MP4 assembly. This orchestrator sits in a documented import cycle with packages/producer/src/services/render/shared.ts and packages/studio/src/player/index.ts, inflating the blast radius for changes.

Runtime initialization lives in packages/core/src/runtime/init.ts (34 outgoing imports, 2 inbound) and sets up the design system (frame.md → DESIGN.md). The studio UI (packages/studio/src/App) imports 50 modules and is the most outward‑facing component, but its high instability (0.96) indicates many downstream dependencies.

Hub modules (cli/src/ui/colors.ts, studio/src/player/store/playerStore.ts, studio/src/components/editor/domEditing.ts) concentrate import traffic; modifications there affect dozens of callers. No lockfile (package.json only) means builds are not reproducible, and the import‑cycle members make refactoring risky.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/hyperframes
cd hyperframes

# Install Node dependencies (npm works because package.json is present)
npm ci   # fails without a lockfile; npm install is the fallback

# Run the CLI locally
npx hyperframes init my-video
cd my-video
npx hyperframes preview   # launches a React preview UI (packages/studio)
npx hyperframes render    # produces my-video.mp4 via Docker/FFmpeg

For containerised builds, the test image is defined in Dockerfile.test; replace the base tag with a digest (see health section). AWS Lambda deployment uses the CDK entry packages/aws-lambda/src/cdk/index.ts.

Real‑World Use

A marketing automation platform can embed the CLI as a microservice: an incoming request triggers packages/aws-lambda/src/index.ts, which calls the same orchestrator used by the local CLI to render a product‑launch video on demand, then stores the MP4 in S3. The same code path is exercised by LLM agents via the skills package, enabling “write‑and‑render” loops without custom glue code.

Code Health & Issues

  • High – 33 committed node_modules files; remove, .gitignore, and reinstall.
  • High – CI steps discard exit codes (.github/workflows/ci.yml line 573); let failures surface.
  • High – continue-on-error on correctness steps (.github/workflows/ci.yml line 146); delete or isolate.
  • Medium – Base image not pinned (Dockerfile.test); use node:22-bookworm-slim@sha256:<digest>.
  • Medium – No dependency‑vulnerability scan in CI; add dependency-review-action or osv-scanner.
  • Medium – Checkout persists token; set persist-credentials: false.
  • Medium – Docker image runs as root; add a non‑root USER.

Measured static analysis (384 findings) highlights:

  • 7 import cycles (e.g., studio/src/player/index.ts ↔ producer/src/services/renderOrchestrator.ts).
  • 12 oversized files (>1 k LOC) such as renderOrchestrator.ts.
  • 16 hub modules with >40 inbound imports, most notably cli/src/ui/colors.ts.
  • 4 empty catch blocks, 17 high‑branching functions, and 4 deep‑nesting blocks – all increase cognitive load.

The Bottom Line

hyperframes delivers a functional HTML‑to‑video pipeline with a solid CLI, cloud‑ready Lambda wrapper, and agent‑focused skill set. However, the codebase suffers from import cycles, oversized core modules, and missing reproducibility safeguards (lockfile, pinned containers). It is suitable for teams that need a customizable rendering engine and are prepared to address the highlighted health concerns before scaling.