xuanru
a108ffa1f2
The browser-based `validate` (console/network/HTTP + contrast/clip audits, remote-asset localization, viewport-from-comp) only existed inline in the `validate` CLI command, so external consumers couldn't reuse it — they reimplement a parallel headless harness that drifts from render (missing localize → false CORS; hardcoded viewport → false out-of-frame; hand-maintained runtime parity). Lint doesn't have this problem: it's an importable `@hyperframes/lint` package. This lifts the browser core into a new `@hyperframes/validate` package, exporting `validateHtmlInBrowser(html, opts)`. The CLI `validate` command is behavior-unchanged: it lints + bundles, resolves Chrome via its own `ensureBrowser()`, and delegates. The package takes `opts.browserExecutablePath` so the caller owns browser discovery — the package stays launch-agnostic (no browser/manager), like lint owns rules but not I/O. New `opts.onPage(page)` runs extra checks on the SAME loaded page before teardown (findings merged), so a consumer can layer its own gates (e.g. caption-zone / out-of-frame) without a second browser load. - contrast-audit.browser.js moves to the package (its only consumer); the CLI build copies it into dist and the bundled runtime loads it via the same page.addScriptTag path. - The small low-level helpers validate needs (static file server, comp-viewport parse, linkedom shim, error normalizer) are vendored into the package so it doesn't import from @hyperframes/cli (which depends on it); folding both onto a shared low-level package is a follow-up. Marked in .fallowrc duplicates.ignore, matching the repo's moved-code convention. - Pure-function + contrast-script tests move to the package with the code they cover; the CLI keeps only extractCompositionErrorsFromLint (a CLI-side lint→error shaping concern). Verified: package build + typecheck clean, package tests 13/13, CLI tests 1270/1270 (103 files), fallow audit clean on 20 changed files, and an e2e `hyperframes validate` on a real composition through the package (Chrome launch + contrast audit) returns ok:true. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
hyperframes
CLI for creating, previewing, and rendering HTML video compositions.
Install
npm install -g hyperframes
Or use directly with npx:
npx hyperframes <command>
Requirements: Node.js >= 22, FFmpeg
Commands
init
Scaffold a new Hyperframes project from a template:
npx hyperframes init my-video
cd my-video
preview
Start the live preview studio in your browser:
npx hyperframes preview
# Studio running at http://localhost:3002
npx hyperframes preview --port 4567
render
Render a composition to MP4:
npx hyperframes render ./my-composition.html -o output.mp4
lint
Validate your Hyperframes HTML:
npx hyperframes lint ./my-composition
npx hyperframes lint ./my-composition --json # JSON output for CI/tooling
npx hyperframes lint ./my-composition --verbose # Include info-level findings
By default only errors and warnings are shown. Use --verbose to also display informational findings (e.g., external script dependency notices). Use --json for machine-readable output with errorCount, warningCount, infoCount, and a findings array.
compositions
List compositions found in the current project:
npx hyperframes compositions
benchmark
Run rendering benchmarks:
npx hyperframes benchmark ./my-composition.html
doctor
Check your environment for required dependencies (Chrome, FFmpeg, Node.js):
npx hyperframes doctor
browser
Manage the bundled Chrome/Chromium installation:
npx hyperframes browser
info
Print version and environment info:
npx hyperframes info
docs
Open the documentation in your browser:
npx hyperframes docs
upgrade
Check for updates and show upgrade instructions:
npx hyperframes upgrade
npx hyperframes upgrade --check --json # machine-readable for agents
Documentation
Full documentation: hyperframes.heygen.com/packages/cli
Related packages
@hyperframes/core— types, parsers, frame adapters@hyperframes/engine— rendering engine@hyperframes/producer— render pipeline@hyperframes/studio— composition editor UI