Instalação do plugin: Antes de comandos de configuração ou atualização, siga as regras de execução do plugin quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
Registry HyperFrames
O registry fornece blocos e componentes reutilizáveis instaláveis via hyperframes add <nome>.
- Blocos — sub-composições independentes (com suas próprias dimensões, duração, timeline). Incluídos via
data-composition-srcem uma composição hospedeira. - Componentes — snippets 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 imprime quais arquivos foram escritos 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 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 registry 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 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 timeline hospedeira (segundos)data-duration— quanto tempo o bloco é reproduzidodata-width/data-height— dimensões do canvas do blocodata-track-index— linha da timeline do Studio; apenas exibição. Use CSSz-indexpara camadas
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 sua timeline) - Se o componente expuser integração com timeline GSAP (veja o bloco de comentários no snippet), adicione essas chamadas à sua timeline
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 registry contém mais itens do que você pode escanear visualmente, então listá-los e combiná-los por nomes ou tags é o caminho lento, e falha sempre que a escolha de palavras 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 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, então só encontra itens que reutilizam suas palavras; --on-device classifica por significado, após um download único do modelo. Com --json, o envelope informa 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 assim (o modelo on-device também é apenas em inglês). Uma consulta em outro script não produz termos pesquisáveis e não retorna nada. É fácil errar isso 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 instalabilidade é aplicada após a classificação, não antes: um nome que os vetores carregam mas que este registry não pode servir é removido dos resultados e contado em dropped, então um dropped diferente de zero significa que os dois são de 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
O modo de tabela normal e --json apenas listam correspondências; instale um nome selecionado com hyperframes add <nome>. --human-friendly abre um seletor interativo e instala o item selecionado imediatamente. Em workflows 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 atender à necessidade, informe 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 atender à necessidade, 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 condicionar a 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 forem 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 para qualquer lugar, que é exatamente por que é um comando deliberado separado, em vez de algo que a pesquisa faz sozinha. Ele não carrega classificação e nunca entra na métrica de classificação.
Este é o único sinal de demanda para o catálogo. Pulá-lo significa que a lacuna que você encontrou será adivinhada a partir de contagens de instalação, que não podem ver um movimento que ninguém conseguiu instalar.
Se a CLI não conseguir alcançar o registry configurado, inspecione o manifesto bruto como fallback:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
Um registry que a CLI não consegue alcançar não esvazia o catálogo para descoberta: um manifesto buscado anteriormente continua servindo por mais 24h além da janela de atualização 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. 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 registry (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 completo ideia → scaffold → construir → validar → pré-visualizar → enviar em contributing.md. Modelos iniciais copiáveis (legenda / VFX / componente / registry-item.json) estão em templates.md.