mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-03 04:38:33 +00:00

Files

T

Miguel Ángel 401dd1d27f fix: media-use bug-bash fixes (codex gate, id race, provider/reuse/adopt guards) + CLI unknown-flag rejection (#2033 )

* fix(media-use): codex gate misfires as 'not logged in' when piped

codexUnavailableReason() gated generation on parsing `codex login status`
stdout, but that command prints 'Logged in using ChatGPT' to stderr and
exits 0 — so the piped stdout media-use captures (execFileSync returns
stdout only on success) was empty, and the gate falsely reported 'not
logged in'. Every headless / CI / agent run was blocked from codex image
gen even when fully authed.

Gate on the durable credentials file ($CODEX_HOME/auth.json) instead of
the TTY/stderr-only human text. Token validity is still proven by the
exec, which fails cleanly on a stale login. The stdout `features list`
capability check is unchanged.

Verified: reproduced the false 'not logged in' block, then after the fix
generated end-to-end via `resolve -t image --provider codex` (valid
1254x1254 PNG, source=generated, provider=codex.image_gen).

* fix(media-use): bug-bash fixes — id race, provider/reuse/adopt guards

From the bug-bash against main:

- MU-23 (HIGH): concurrent resolves raced on nextId (read-max-then-append,
  non-atomic), so parallel agents got duplicate ids and clobbered each
  other's files. Add allocateId(): a coarse per-project lock (.media/.lock,
  15s stale-steal) around id allocation that scans the manifest AND the
  type dir for reserved ids, then O_EXCL-creates a placeholder file so the
  slow download between allocate and append can't collide. 5 parallel
  resolves now yield 5 distinct ids + files.
- X4: --reuse imported across a type mismatch (bgm asset under images/).
  Apply typesMatch on the --reuse path; reject mismatches (icon<->image
  still interchangeable).
- X5: --provider silently overrode --local-only and made a network call.
  --local-only is now a hard guard: network providers are skipped even
  under a forced provider; the miss message explains the conflict.
- BUG-2: --provider ignored the exact-cache floor and could hand back an
  asset from a different provider. A forced --provider now bypasses all
  reuse rungs (regenerate with THIS provider); the unforced floor is intact.
- MU-26/X6: 0-byte assets accepted. --adopt skips 0-byte files (loud); ingest
  refuses a 0-byte local file (freezeUrl already rejects empty responses).
- BUG-4: unknown/unavailable --provider now errors with the available list
  instead of a generic 'no provider could resolve' (typo != catalog miss).
- BUG-5: --reuse "" gave the wrong 'type and intent required' error; it now
  routes to a clear empty-sha message.
- BUG-3: voice duration leaked an unrounded float into index.md; round all
  durations to 0.1s centrally at record build (matches probe).
- Nits: whitespace-only --intent is rejected; nudge grammar (exists/exist).

Tests: allocateId reservation + registry local-only-wins added; full
media-use suite green. All fixes verified e2e.

* fix(cli): reject unknown flags instead of silently ignoring them

citty is permissive: an unrecognized flag was dropped, not rejected — so
`render . --out x` (the flag is --output/-o) silently ignored --out and
rendered to the default renders/<name>.mp4 path. A mistyped flag read as a
render/catalog miss.

Add assertKnownFlags(): validate every dash-prefixed token against the
command's declared args + aliases + the global set (help/version/json)
before the command runs, in the shared trackCommandFailures run-wrapper so
every leaf command is covered. Handles --flag=value, --no-<bool> negation,
camelCase<->kebab arg names, and combined shorts; stops at --; positionals
and flag values pass through.

Verified: `render . --out x` -> 'Error: Unknown flag: --out'; --output/-o/
--json/--help still accepted. Unit tests added.

* docs(skills): install with --full-depth so agents get current main

The documented `npx skills add heygen-com/hyperframes` fetched the
skills.sh registry blob, which lags GitHub main by hours — so users
following the docs got a stale skill (e.g. media-use v1: no --candidates,
voice stubbed). The CLI's own `hyperframes skills` command already forces
a full clone via --full-depth to bypass this; the docs didn't pass it.

Add --full-depth to every documented install command (README, CLAUDE.md,
docs/guides/skills.mdx) with a one-line note on the lag. Addresses the
user-facing half of the publish/registry lag (#2034).

* chore(media-use): collapse resolve.mjs import to satisfy oxfmt --check

* fix(cli): extract longFlagName to keep flag validator under complexity gate

Also regenerate skills-manifest.json (resolve.mjs formatting change re-hashed
the media-use skill). Fixes the Fallow audit + skills-manifest-in-sync CI gates.

2026-07-07 19:19:28 -04:00

9.5 KiB

Raw Permalink Blame History

Hyperframes

Open-source video rendering framework: write HTML, render video.

Skills

This repo ships 20 AI agent skills via vercel-labs/skills. Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover.

npx skills add heygen-com/hyperframes --full-depth              # interactive picker
npx skills add heygen-com/hyperframes --all --full-depth        # install all 20 (skips picker)
npx skills add heygen-com/hyperframes --skill <name> --full-depth  # just one (bare name, no leading slash)

Keep --full-depth: it installs the current main. Without it, skills add fetches the skills.sh registry blob, which lags main by hours (you'd get a stale skill). hyperframes skills update already uses full-depth.

/hyperframes is the entry skill — read it first. It's the capability map for the domain skills below AND the intent router for the creation workflows. The full README skills section mirrors this list; keep them in sync (see "Skill catalog maintenance" below).

Creation workflows

/product-launch-video — a product URL (or a pre-written script / text brief in no-capture mode) → product launch / promo video, up to ~3 min (sweet spot ~30-90s).
/website-to-video — a general website / URL → a video of the site (tour / showcase / social clip from captured screenshots + assets); for a product launch / promo, use /product-launch-video.
/faceless-explainer — arbitrary text, no URL and no website capture → faceless explainer, up to ~3 min (sweet spot ~30-90s); every visual is LLM-invented (typography / abstract graphics / diagram / data-viz).
/pr-to-video — a GitHub PR (URL / owner/repo#N / "this PR") → code-change explainer, up to ~3 min (changelog / feature reveal / fix / refactor). A PR link, not a product website.
/embedded-captions — an existing talking-head video (MP4) → the same footage with captions / subtitles added (verbatim rail + embedded climax, or pure-cinematic embed); the footage itself is untouched (no NLE-style editing).
/talking-head-recut — an existing talking-head / interview / podcast video (MP4) → the same footage packaged with designed graphic overlays (kinetic titles, lower-thirds, data callouts, pull-quotes, side panels, PiP) synced to the transcript; the clip plays unchanged underneath, footage untouched. For plain captions/subtitles → /embedded-captions.
/motion-graphics — a short (typically under 10s) design-led motion graphic, motion-is-the-message, no narration: kinetic type, a stat / number count-up, a chart, a logo sting, a lower-third / overlay, or an animated tweet / headline / captured-page highlight; rendered to MP4 or a transparent overlay. Longer / narrated / custom → /general-video.
/music-to-video — a music track (audio file, or video to pull audio from) → beat-synced video (lyric / slideshow / kinetic promo). Music drives pacing; user-supplied images / videos are cut onto the same beat grid.
/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 — fallback for any other video creation (title card, longer brand / sizzle reel, multi-scene montage, static loop, custom composition); the original hyperframes flow — design → plan → layout → build → validate, any length.
/remotion-to-hyperframes — port an existing Remotion (React) composition 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:

/hyperframes-core — the composition contract: data-* timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, determinism rules. Read before writing composition HTML.
/hyperframes-animation — all animation knowledge: atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP default, plus 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, text trails, 3D depth; plus hyperframes keyframes diagnostics for surfacing and verifying rendered motion.
/hyperframes-creative — non-animation creative direction: frame.md / design.md handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.
/media-use — the media OS: resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared scripts/audio.mjs engine + manifest tracking; keeps search noise on disk.
/hyperframes-cli — CLI dev loop: init, add, lint, validate, inspect, preview, render, publish, doctor, lambda (AWS Lambda cloud rendering).
/hyperframes-registry — install and wire registry blocks and components into compositions via hyperframes add. Covers 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.

Skill catalog maintenance

When adding a new skill, or substantially renaming / repurposing an existing one, update all agent-facing discoverability surfaces in lockstep:

The skill list above (CLAUDE.md) AND the workflow list in the root AGENTS.md (it carries workflows only, no domain-skill section) AND the ## Skills section in README.md AND docs/guides/skills.mdx (rendered at hyperframes.heygen.com/guides/skills). Out-of-date entries silently kill discovery.
The scaffolded project template packages/cli/src/templates/_shared/CLAUDE.md + AGENTS.md — written into every hyperframes init project, so a stale entry there ships to users. The two template files must stay byte-identical.
If the skill changes the routing surface for "make a video" requests, also update the capability map and intent router in skills/hyperframes/SKILL.md — that's the canonical router agents read first.
Mirror the Router / Creation workflows / Domain skills grouping across all surfaces so a skill always lives in the same column.
Skill count appears in the README and CLAUDE.md intro lines ("20 AI agent skills…") — update on add/remove. The docs/guides/skills.mdx page and the CLI templates deliberately omit a count to avoid drift; keep them count-free.

The skill's own SKILL.md frontmatter description: is the source of truth for the one-line "use when" blurb; copy from there into the catalog rather than paraphrasing.

Build & Test

bun install     # Install dependencies (NOT pnpm — do not create pnpm-lock.yaml)
bun run build   # Build all packages
bun run test    # Run all tests

Linting & Formatting

Uses oxlint and oxfmt (not eslint, not prettier, not biome).

bunx oxlint <files>        # Lint
bunx oxfmt <files>         # Format
bunx oxfmt --check <files> # Check formatting (CI / pre-commit)

Always lint and format changed files before committing. Lefthook pre-commit hooks enforce this automatically.

Composition Validation

After creating or editing any .html composition:

npx hyperframes lint       # Static HTML structure check
npx hyperframes validate   # Runtime check (headless Chrome — catches JS errors, missing assets)

Both must pass before previewing or considering work complete.

Project Structure

packages/
  cli/                  → hyperframes CLI (create, preview, lint, render)
  core/                 → Types, parsers, generators, linter, runtime, frame adapters
  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)
  player/               → Embeddable <hyperframes-player> web component
  producer/             → Full rendering pipeline (capture + encode + audio mix)
  shader-transitions/   → WebGL shader transitions for compositions
  studio/               → Browser-based composition editor UI
registry/
  blocks/               → Installable sub-composition scenes (50+)
  components/           → Installable effects and snippets
  examples/             → Starter project templates
docs/                   → Mintlify documentation site (hyperframes.heygen.com)
skills/                 → AI agent skill definitions

Key Conventions

Package manager: bun (not pnpm, not npm for workspace operations)
Commit format: Conventional commits (feat:, fix:, docs:, refactor:, test:)
TypeScript: Avoid any and as T assertions. Prefer type guards and narrowing.
Compositions: HTML files with data-* attributes. Clips need class="clip". GSAP timelines must be paused and registered on window.__timelines.
Frame Adapters: Animation runtimes plug in via the seek-by-frame adapter pattern. GSAP is the primary adapter.
Deterministic rendering: No Date.now(), no unseeded Math.random(), no render-time network fetches.

Documentation

Docs: https://hyperframes.heygen.com/introduction
Catalog (50+ blocks): https://hyperframes.heygen.com/catalog/blocks/data-chart

9.5 KiB Raw Permalink Blame History