Files
hyperframes/packages/cli
ukimsanov 02f95f9556 fix(capture): broaden isLogo detection — structural signals catch real header logos
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).
2026-06-12 01:07:30 -07:00
..
2026-06-11 02:40:36 +00:00

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