HyperFrames Registry — блоки и компоненты

Registry предоставляет переиспользуемые блоки и компоненты, устанавливаемые через hyperframes add <name>.

• Блоки — самостоятельные суб-композиции (собственные размеры, длительность, таймлайн). Подключаются через data-composition-src в родительской композиции.
• Компоненты — эффектные сниппеты (без собственных размеров). Вставляются напрямую в HTML родительской композиции.

Быстрый справочник

hyperframes add data-chart              # установить блок
hyperframes add grain-overlay           # установить компонент
hyperframes add shimmer-sweep --dir .   # указать конкретный проект
hyperframes add data-chart --json       # вывод в формате JSON
hyperframes add data-chart --no-clipboard  # пропустить буфер обмена (CI/headless)

После установки CLI выводит список записанных файлов и сниппет для вставки в родительскую композицию. Сниппет — отправная точка: при подключении блоков нужно добавить атрибуты data-composition-id (должен совпадать с внутренним ID блока), data-start и data-track-index.

Примечание: hyperframes add работает только для блоков и компонентов. Для примеров используйте hyperframes init <dir> --example <name>.

Пути установки

По умолчанию: блоки → compositions/<name>.html, компоненты → compositions/components/<name>.html.

Пути настраиваются в hyperframes.json:

{
  "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
  "paths": {
    "blocks": "compositions",
    "components": "compositions/components",
    "assets": "assets"
  }
}

Подключение блоков

Блоки — самостоятельные композиции, подключаются через data-composition-src в index.html:

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
></div>

Ключевые атрибуты:

• data-composition-src — путь к HTML-файлу блока
• data-composition-id — должен совпадать с внутренним ID блока
• data-start — когда блок появляется в родительском таймлайне (секунды)
• data-duration — длительность воспроизведения блока
• data-width / data-height — размеры холста блока
• data-track-index — порядок слоёв (выше = ближе к зрителю)

Подключение компонентов

Компоненты — сниппеты. Вставьте их HTML в разметку вашей композиции, CSS — в блок стилей, JS — в скрипт:

1. Прочитайте установленный файл (например, compositions/components/grain-overlay.html)
2. Скопируйте HTML-элементы в <div data-composition-id="...">
3. Скопируйте блок <style> в стили вашей композиции
4. Скопируйте содержимое <script> в скрипт вашей композиции (перед кодом таймлайна)
5. Если компонент предоставляет интеграцию с GSAP — добавьте эти вызовы в ваш таймлайн

Обнаружение элементов

# Прочитать манифест registry
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json

registry-item.json каждого элемента содержит: имя, тип, заголовок, описание, теги, размеры (только для блоков), длительность (только для блоков) и список файлов.

Создание нового блока или компонента

Чтобы создать новый элемент registry (стиль субтитров, VFX-блок, переход, lower third или переиспользуемый компонент) и отправить его как upstream PR — следуйте полному рабочему процессу идея → скаффолдинг → сборка → валидация → preview → отправка, описанному в references/contributing.md. Стартовые шаблоны (caption / VFX / component / registry-item.json) доступны в references/templates.md.