Instalação do plugin: Antes de comandos de configuração ou atualização, siga as regras de instalação de plugin quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
Registro HyperFrames
O registro fornece blocos e componentes reutilizáveis instaláveis via hyperframes add <nome>.
- Blocos — subcomposições autônomas (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 da 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 # ignorar área de transferência (CI/headless)
Após a instalação, o CLI exibe quais arquivos foram gravados e um trecho para colar em sua composição hospedeira. O trecho é 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 exato de item. Se nenhum item corresponder e o valor for uma tag, o comando instala todos os blocos com essa tag. As 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"
}
}
Veja install-locations.md para detalhes completos.
Conectando blocos
Blocos são composições autônomas — 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— linha da linha do tempo do Studio; apenas exibição. Use CSSz-indexpara camadas
Veja 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 estilo 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 expuser integração com a timeline GSAP (veja o bloco de comentários no trecho), adicione essas chamadas à sua linha do tempo
Veja wiring-components.md para detalhes completos.
Descoberta
Use o CLI como superfície principal de descoberta. Pesquise por intenção antes de navegar: o registro contém mais itens do que você pode escanear visualmente, então listar e combinar por nomes ou tags é o caminho lento e falha sempre que a redação do autor difere da sua.
# Classificar todo o catálogo contra o que o beat deve fazer
npx hyperframes catalog --query "revelar um título uma linha de cada 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, então só encontra itens que reutilizam suas palavras; --on-device classifica por significado, após um download único do modelo. Com --json os envelopes nomeiam qual camada respondeu, então verifique isso em vez de assumir que uma classificação ocorreu.
Sempre consulte em inglês, independentemente do idioma do vídeo. O catálogo está escrito em inglês e ambas as camadas o indexam dessa forma (o modelo no dispositivo também é apenas em inglês). Uma consulta em outro script não produz termos pesquisáveis e não 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 todos 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, isso é esta regra, não um componente ausente, e não vale um relatório de lacuna.
A instalabilidade é aplicada após a classificação, não antes: um nome que os vetores carregam mas este registro não pode servir é removido dos resultados e contado em dropped, então um dropped diferente de zero significa que as duas são gerações diferentes. Veja /hyperframes-cli para a camada offline, as portas 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
O modo normal de tabela 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 trabalho CI ou de agente, prefira --json seguido de um add explícito.
Relatar o que o catálogo não tem
Quando a pesquisa retornar e nada nela fizer o trabalho, diga antes de criar o movimento manualmente:
npx hyperframes feedback --search-miss "<a consulta que você executou>" --wanted "<o movimento que você precisava>" --tier <a camada que respondeu>
catalog --query imprime esta linha para você, pré-preenchida, e --json a carrega como report_gap — então ela já está em mãos no momento em que você decide que nada se encaixa.
Relate sempre que nada nos resultados fizer o trabalho, em qualquer camada. Não espere que a camada no dispositivo 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 estes são 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 qualquer lugar, que é exatamente por que é um comando deliberado separado, não algo que a pesquisa faz sozinha. Ele não carrega nenhuma classificação e nunca cai na métrica de avaliação.
Este é o sinal de demanda completo para o catálogo. Pulá-lo significa que a lacuna que você encontrou é adivinhada a partir de contagens de instalação, que não podem ver um movimento que ninguém pôde instalar.
Se o CLI não conseguir acessar 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 o CLI não consegue alcançar não esvazia o catálogo para descoberta: um manifesto buscado 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 contra a ú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 em 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 do item contém: nome, tipo, título, descrição, tags, dimensões (apenas blocos), duração (apenas blocos) e lista de arquivos.
Veja discovery.md para detalhes sobre filtragem por tipo e tags.
Contribuindo com um novo bloco ou componente
Para criar um NOVO item de registro (estilo de legenda, bloco VFX, transição, terço inferior ou um componente reutilizável) e enviá-lo como um PR upstream — não instalar um existente — siga o fluxo de trabalho completo de ideia → scaffolding → construir → validar → pré-visualizar → enviar em contributing.md. Modelos iniciais para copiar e colar (legenda / VFX / componente / registry-item.json) estão em templates.md.