Instalação do plugin: Antes de comandos de configuração ou atualização, siga as regras de instalação do 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 independentes (próprias dimensões, duração, linha do tempo). Incluídos via
data-composition-srcem uma composição hospedeira. - Componentes — snippets de efeitos (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 marcados com '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 informa quais arquivos foram gravados e um snippet para colar na sua composição hospedeira. O snippet é um ponto de partida — você precisará adicionar os atributos data-composition-id (deve corresponder ao ID de composição interno 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 no 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 no 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 do canvas do blocodata-track-index— ordenação de camadas (maior = na frente)
Consulte wiring-blocks.md para detalhes completos.
Conectando componentes
Componentes são snippets — 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
<div data-composition-id="...">da sua composição - 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 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 a principal superfície de descoberta. Pesquise pela intenção antes de navegar: o registro contém mais itens do que você pode escanear visualmente, então listá-los 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 segmento 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 nomes do envelope indicam 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 é 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 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, 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 este registro não pode servir, é descartado dos resultados e contado em dropped, então um dropped diferente de zero significa que os dois são gerações diferentes. Consulte /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
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 trabalho CI ou de agente, prefira --json seguido por um add explícito.
Relatar o que o catálogo não possui
Quando a pesquisa retornar e nada nela atender à necessidade, diga isso antes de criar manualmente o movimento:
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 ela já está em mãos no momento em que você decide que nada se encaixa.
Relate sempre que nada nos resultados atender à necessidade, em qualquer camada. Não espere que a camada on-device tenha respondido: ela precisa de um download de 33 MB consentido, 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 relatos. O valor --tier acompanha para que uma falha de vocabulário permaneça distinguível de uma falha de significado quando estas são lidas. 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 para algum lugar, que é exatamente por que é um comando deliberado separado, em vez de algo que a pesquisa faz por conta própria. Ele não carrega nenhuma classificação e nunca chega à métrica de classificação.
Este é o sinal de demanda completo para o catálogo. Ignorá-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 conseguiu instalar.
Se a 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 a CLI não consegue acessar 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 em relação à ú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. Então, 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 um componente reutilizável) e enviá-lo como um PR upstream — não instalar um existente — siga o fluxo de trabalho completo ideia → esqueleto → construir → validar → visualizar → enviar em contributing.md. Modelos iniciais para copiar e colar (legenda / VFX / componente / registry-item.json) estão em templates.md.