Verified on the heygen.com + huly.io captures from the last real-AI-test
run: the prior class-substring detectors caught 0 / 32 (heygen) and
0 / 19 (huly) SVGs as logos. Both sites' actual header logos were
captured but never got the `logo-<hash>.svg` prefix, so AI agents had
no filename signal to find them and ended up composing fakes.
Root cause: modern React / Tailwind builds rarely put "logo" / "brand"
anywhere in an ancestor className. Tailwind's class names are utility
classes ("flex items-center"), and component frameworks emit hashed
classes ("Header__inner_a1b2c3"). The detector's substring check
("[class*=\"logo\"]") matched neither.
Fix: add structural DOM signals alongside the existing class check.
Three signals catch the universal "site header logo" pattern even
without semantic class names:
1. inBanner — element sits inside <header>, <nav>, or [role="banner"].
The canonical "logo at the top of the page" container.
2. inHomeLink — element sits inside an <a> whose href is the site root
("/", "#", "./", or origin-only URL). The brand-home link wrap that
nearly every header logo lives in.
3. matchesTitleBrand — element's alt / aria-label / title contains
the brand segment of document.title (everything before " - " /
" | " / " — "). Catches the explicit "alt=HeyGen" pattern.
These three are independent — ANY positive signal sets isLogo. False
positives (an icon that happens to be the first <svg> in a <nav>) are
acceptable because the downstream effect is only that the file gets
named `logo-<hash>.svg` instead of `svg-<hash>.svg` — content is
identical, agents will read asset-descriptions.md to disambiguate
either way.
Files changed:
1. packages/cli/src/capture/tokenExtractor.ts — inline-DOM SVG scan
(the path that catches <svg>...</svg> markup directly in the page).
Existing isLogo line replaced with the broadened block that runs
the three structural checks after the original class/label checks.
2. packages/cli/src/capture/assetCataloger.ts —
- CatalogedAsset interface: added optional inBanner, inHomeLink,
matchesTitleBrand booleans.
- getElementContext: emits the three signals on every cataloged
asset so the downloader can read them.
- The add() function merges booleans with "any positive wins"
semantics — if any DOM occurrence of a URL is in a banner, the
URL is a header-context asset.
- deduplicateSrcsetVariants merges the same way across w= variants.
3. packages/cli/src/capture/assetDownloader.ts — URL-downloaded SVG
path (which catches the HeyGen header lockup, served via <img src=
"...cdn.svg" alt="HeyGen">). The lone `contexts` substring check —
which never fired because contexts hold HTML positions like
'img[src]', not semantic labels — is now one prong among many. The
structural signals (inBanner / inHomeLink / matchesTitleBrand)
carry most of the recall; the substring check stays as a backstop
against future contexts vocabulary additions.
No behavior change for projects where isLogo was already firing
correctly. The change only PROMOTES previously-undetected logos to
the logo-<hash>.svg naming. The byte content and downstream rendering
are unchanged either way.
Tied to commit e6aa7fed (the doc landmine for searching
asset-descriptions.md before composing a logo) — together these
close the heygen / huly logo discoverability gap from two angles:
better signal in the filename when detection fires, doc-rule
fallback when it doesn't.
Followup: strengthen the no-Gemini fallback in contentExtractor.ts
so asset-descriptions.md remains useful for teams without a Gemini
API key (currently falls back to just the filename hash).
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