Instalação do plugin: Antes de executar 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 independentes (com suas próprias dimensões, duração e linha do tempo). Incluídos via
data-composition-srcem uma composição anfitriã. - Componentes — trechos de efeito (sem dimensões próprias). Colados diretamente no HTML da composição anfitriã.
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 . # mirar em 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 gravados e um snippet para colar em sua composição anfitriã. 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 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 anfitrião:
<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 da composição anfitriã (segundos)data-duration— por quanto tempo o bloco é reproduzidodata-width/data-height— dimensões do canvas do blocodata-track-index— linha da linha do tempo do Studio; apenas exibição. Use oz-indexdo CSS para camadas
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 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 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 a superfície principal de descoberta. Pesquise pela intenção antes de navegar: o registro contém mais itens do que você pode examinar visualmente, portanto 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 em relação ao que a cena 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, ela 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, portanto 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 on-device 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 naturalmente os segue: descreva o movimento em inglês, depois escreva o texto na tela no idioma que o vídeo precisar. Se uma consulta retornar No searchable words in query, isso é devido a esta regra, não a um componente faltante, 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 registro não pode servir, é descartado dos resultados e contado em dropped, portanto um dropped diferente de zero significa que os dois são de gerações diferentes. Consulte /hyperframes-cli para a camada offline, as portas de consentimento e como atualizar um índice obsoleto.
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 de um add explícito.
Relatar o que o catálogo não possui
Quando a pesquisa retorna e nada nela atende ao que você precisa, 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 <a camada que respondeu>
catalog --query imprime esta linha para você, pré-preenchida, e --json a carrega como report_gap — portanto ela já está em mãos no momento em que você decide que nada se encaixa.
Relate sempre que nada nos resultados atender ao que você precisa, em qualquer camada. Não espere que a camada on-device tenha respondido: ela precisa de um download consentido de 33 MB, portanto 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 falha de vocabulário permaneça distinguível de uma falha 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 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 avaliação.
Este é o sinal de demanda completo para o catálogo. Ignorá-lo significa que a lacuna que você encontrou será adivinhada a partir das contagens de instalação, o que não pode ver um movimento que ninguém conseguiu 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 buscado anteriormente continua servindo além de sua janela de atualização de 24h sempre que a revalidação falha, portanto catalog e catalog --query ainda listam e classificam com base na última cópia em disco.
add ainda precisa de 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.
O registry-item.json de cada item 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 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 → scaffold → 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.