Files
hyperframes/skills
ukimsanov 570dedbde2 feat(cli): add capture-video for on-demand video fetch from manifest
The capture pipeline writes capture/extracted/video-manifest.json
listing every <video> element on the source page (URL, dimensions,
heading, caption, preview PNG) but deliberately doesn't download the
mp4s — sites with 15+ feature videos would balloon capture size by
hundreds of MB.

User direction on this tradeoff: keep the capture lean, let the AI
agent decide per-beat whether the actual mp4 is worth fetching, and
provide a single CLI command to fetch one when the answer is yes.
That preserves the determinism (the manifest is the contract) and
the choice (agent picks what's relevant).

The motivating case is heygen.com's "Orb" — a 3D-rendered hero
animation that's at index 0 of the heygen manifest (768×768, heading
"Turn your ideas into videos in minutes"). On the last real-AI-test
run, the agent KNEW about it ("the genuine article was in the capture")
but composed a CSS-3D cube approximation instead because there was no
one-step way to fetch the actual mp4. This command closes that gap.

New command surface:

  hyperframes capture-video <project-dir> --list
      List manifest entries with index, dimensions, heading, URL.

  hyperframes capture-video <project-dir> --index 0
      Download the manifest entry at the given index.

  hyperframes capture-video <project-dir> --url <URL>
      Download a specific entry by exact URL match.

Behavior:
- Reads <project-dir>/capture/extracted/video-manifest.json.
- Resolves the target entry by --index or --url (clear error message
  on out-of-range / missing).
- Downloads to <project-dir>/capture/assets/videos/<filename> — same
  layout as the rest of the captured-assets tree, so compositions
  reference videos with the same `capture/assets/...` path pattern
  they already use for SVGs and rasters.
- Decodes URL-encoded characters and sanitizes the filename so
  manifest entries like `Frame-2147227325%20(1).mp4` land as
  `Frame-2147227325_1_.mp4` on disk.
- Idempotent: if the file already exists, warns and skips (delete +
  re-run to refetch).
- On success, prints a ready-to-paste <video> embed snippet with
  data-start / data-duration / data-track-index. Aspect-aware: square
  videos (e.g. the Orb) get a 5s default duration suggestion vs 4s
  for landscape feature videos.

Files changed:
- packages/cli/src/commands/capture-video.ts — new command (~170 LOC).
- packages/cli/src/cli.ts — registered `capture-video` subcommand.
- packages/cli/src/help.ts — added to the "Getting Started" group so
  it appears in `hyperframes --help`.
- skills/website-to-hyperframes/references/beat-builder-guide.md —
  updated the "Captured videos" landmine (from commit e6aa7fed) to
  point at the CLI command instead of the raw curl pattern. The CLI
  command becomes the documented path; curl is no longer mentioned
  (one path is better than two).

Smoke-tested against the existing /videos/heygen-com capture:
`capture-video --list` correctly lists all 9 manifest entries with
the Orb at index 0 (768×768, "Turn your ideas into videos in
minutes"). Did NOT actually download in this commit — that's the
user's runtime choice. Command + help output verified.

Closes the asset-discoverability bundle for this turn:
  e6aa7fed - doc landmine for asset-descriptions.md search
  02f95f95 - broadened isLogo via structural DOM signals
  953004b9 - LOGO tags in asset-descriptions.md (Gemini & no-Gemini)
  this    - on-demand video fetch for the Orb-class assets
2026-06-12 01:12:43 -07:00
..