HyperFrames Registry
O registro fornece blocos e componentes reutilizáveis instaláveis via hyperframes add <nome>.
- Blocos — subcomposições independentes (próprias dimensões, duração, linha do tempo). Incluídos via
data-composition-srcem uma composição hospedeira. - Componentes — trechos de efeito (sem dimensões próprias). Colados diretamente no HTML de uma composição hospedeira.
Referência rápida
hyperframes add data-chart # instalar um bloco
hyperframes add grain-overlay # instalar um componente
hyperframes add captions # instalar todos os blocos com a tag captions
hyperframes add shimmer-sweep --dir . # direcionar um projeto específico
hyperframes add data-chart --json # saída legível por máquina
hyperframes add data-chart --no-clipboard # pular área de transferência (CI/headless)
Após a instalação, a CLI exibe quais arquivos foram gravados e um snippet para colar em sua composição hospedeira. O snippet é um ponto de partida — você precisará adicionar os atributos data-composition-id (deve corresponder ao ID interno da composição do bloco), data-start e data-track-index ao conectar blocos.
O valor posicional é resolvido primeiro como um nome de item exato. Se nenhum item corresponder e o valor for uma tag, o comando instala todos os blocos com essa tag. Dependências do registro são instaladas antes do item solicitado. hyperframes add funciona apenas para blocos e componentes; para exemplos, use hyperframes init <dir> --example <nome>.
Locais de instalação
Blocos são instalados em compositions/<nome>.html por padrão. Componentes são instalados em compositions/components/<nome>.html por padrão.
Esses caminhos são configuráveis em hyperframes.json:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
Consulte install-locations.md para detalhes completos.
Conectando blocos
Blocos são composições independentes — inclua-os via data-composition-src em seu index.html hospedeiro:
<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>
Atributos principais:
data-composition-src— caminho para o arquivo HTML do blocodata-composition-id— deve corresponder ao ID interno do blocodata-start— quando o bloco aparece na linha do tempo hospedeira (segundos)data-duration— por quanto tempo o bloco é reproduzidodata-width/data-height— dimensões da tela do blocodata-track-index— ordenação de camadas (maior = na frente)
Consulte wiring-blocks.md para detalhes completos.
Conectando componentes
Componentes são trechos — cole seu HTML na marcação da sua composição, seu CSS no bloco de estilos e seu JS no script (se houver):
- Leia o arquivo instalado (ex.:
compositions/components/grain-overlay.html) - Copie os elementos HTML para dentro da sua composição
<div data-composition-id="..."> - Copie o bloco
<style>para os estilos da sua composição - Copie qualquer conteúdo
<script>para o script da sua composição (antes do código da linha do tempo) - Se o componente expõe integração com a linha do tempo GSAP (veja o bloco de comentários no snippet), adicione essas chamadas à sua linha do tempo
Consulte wiring-components.md para detalhes completos.
Descoberta
Use a CLI como superfície de descoberta principal. Pesquise por intenção antes de navegar: o registro contém mais itens do que você pode verificar manualmente, então listá-los e corresponder por nomes ou tags é o caminho lento, e falha sempre que a redação do autor difere da sua.
# Classifique todo o catálogo contra o que o beat deve fazer
npx hyperframes catalog --query "revelar um título uma linha por vez"
npx hyperframes add caption-clip-wipe
A pesquisa é local e não envia nada. Por padrão, classifica com base no vocabulário compartilhado com o nome, título e descrição do item, portanto só encontra itens que reutilizam suas palavras; --on-device classifica por significado, após um download único do modelo. Com --json, o envelope indica qual camada respondeu, então verifique isso em vez de presumir que uma classificação ocorreu.
Sempre consulte em inglês, independentemente do idioma do vídeo. O catálogo é escrito em inglês e ambas as camadas o indexam dessa forma (o modelo on-device também é apenas inglês). Uma consulta em outro script não produz termos pesquisáveis e retorna nada. Isso é fácil de errar em um projeto japonês ou chinês, onde o briefing, as legendas e a narração estão nesse idioma e a consulta segue naturalmente: descreva o movimento em inglês, depois escreva o texto na tela no idioma que o vídeo precisar. Se uma consulta retornar Nenhuma palavra pesquisável na consulta, esta é a regra, não um componente faltando, e não vale um relatório de lacuna.
A capacidade de instalação é aplicada após a classificação, não antes: um nome que os vetores carregam mas que este registro não pode servir é removido dos resultados e contado em dropped, então um dropped diferente de zero significa que são gerações diferentes. Consulte /hyperframes-cli para a camada offline, os portões de consentimento e como atualizar um índice desatualizado.
Para navegar ou filtrar em vez de pesquisar:
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
Os modos de tabela normal e --json listam apenas correspondências; instale um nome selecionado com hyperframes add <nome>. --human-friendly abre um seletor interativo e instala o item selecionado imediatamente. Em fluxos de CI ou agente, prefira --json seguido por um add explícito.
Relatar o que o catálogo não tem
Quando a pesquisa retornar e nada nela atender, diga isso antes de criar o movimento manualmente:
npx hyperframes feedback --search-miss "<a consulta que você executou>" --wanted "<o movimento que você precisava>" --tier on-device
catalog --query imprime esta linha para você, pré-preenchida, e --json a carrega como report_gap — então já está em mãos no momento em que você decide que nada se encaixa.
Relate sempre que nada nos resultados atender, em qualquer camada. Não espere que a camada on-device tenha respondido: ela precisa de um download consentido de 33 MB, então uma execução de agente está em words a menos que tenha optado explicitamente, e depender de on-device silenciaria quase todos os relatórios. O valor --tier acompanha para que uma falta de vocabulário permaneça distinguível de uma falta de significado quando lidos. Descreva o efeito que você queria, não o nome do item que imaginou: o que retorna é uma lista de movimentos que valem a pena construir, e um relatório nomeando um item inexistente não ensina nada. Este é o único caminho que envia uma consulta a algum lugar, que é exatamente por isso é um comando deliberado separado, em vez de algo que a pesquisa faz sozinha. Ele não carrega nenhuma classificação e nunca chega à métrica de avaliação.
Este é todo o sinal de demanda para o catálogo. Pulá-lo significa que a lacuna que você encontrou é adivinhada a partir das contagens de instalação, que não podem ver um movimento que ninguém pôde instalar.
Se a CLI não conseguir alcançar o registro configurado, inspecione o manifesto bruto como fallback:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
Um registro que a CLI não consegue alcançar não esvazia o catálogo para descoberta: um manifesto obtido anteriormente continua servindo além de sua janela de atualização de 24h sempre que a revalidação falha, então catalog e catalog --query ainda listam e classificam com base na última cópia em disco.
add ainda precisa da rede, mesmo para um item que você instalou ontem. Apenas manifestos são armazenados em cache; os arquivos reais do item são buscados a cada instalação. Portanto, offline você pode pesquisar e ver o que um item é, mas instalá-lo falha na busca do arquivo. Não prometa a um usuário uma instalação offline.
Cada registry-item.json contém: nome, tipo, título, descrição, tags, dimensões (apenas blocos), duração (apenas blocos) e lista de arquivos.
Consulte discovery.md para detalhes sobre filtragem por tipo e tags.
Contribuindo com um novo bloco ou componente
Para criar um NOVO item do registro (estilo de legenda, bloco VFX, transição, terço inferior ou componente reutilizável) e enviá-lo como um PR upstream — não instalar um existente — siga o fluxo completo de ideia → esqueleto → construção → validação → pré-visualização → envio em contributing.md. Modelos iniciais de copiar-e-colar (legenda / VFX / componente / registry-item.json) estão em templates.md.