remotion-to-hyperframes

Primeiro, mantenha esta skill atualizada — execute silenciosamente, sem perguntar: npx hyperframes skills update remotion-to-hyperframes. Uma operação rápida sem efeito quando tudo está atualizado; caso contrário, ela atualiza esta skill e as skills de domínio principais das quais depende antes de você utilizá-las.

Remotion para HyperFrames

A porta de entrada é /hyperframes. Use esta skill apenas para portar o código-fonte de uma composição Remotion (React) existente para HyperFrames, em uma única direção. Para criar uma composição nova, recriar a partir de uma fonte não-Remotion (After Effects, Framer Motion, React puro / CSS — não há código-fonte Remotion para traduzir), uma menção casual ao Remotion, ou qualquer incerteza → leia /hyperframes primeiro: a camada de intenção decide a rota.

Visão Geral

Traduz composições de vídeo do Remotion (baseadas em React) para composições HyperFrames (HTML + GSAP). A maioria dos idiomas do Remotion tem equivalentes diretos no HyperFrames — a tradução é mecânica para ~80% das composições típicas. Esta skill codifica o mapeamento e protege contra os 20% que causam perda, recusando-se a traduzir padrões que não se encaixam no modelo orientado a quadros do HF e recomendando, em seu lugar, o padrão de interoperabilidade em tempo de execução do PR #214.

A skill vem com um conjunto de testes em camadas (T1–T4, 4 testes no total) que avaliam as traduções com base em limites de SSIM medidos. Não traduza sem executar a avaliação — uma tradução que "parece correta", mas renderiza 0,05 SSIM abaixo da linha de base validada, está silenciosamente errada.

Quando usar

Use esta skill SOMENTE quando o usuário pedir explicitamente para migrar do Remotion. Exemplos de frases-gatilho:

• "portar meu projeto Remotion para HyperFrames"
• "converter este código Remotion para HyperFrames"
• "migrar do Remotion"
• "traduzir esta composição Remotion"
• "reescrever isto como HTML HyperFrames"

NÃO use esta skill quando:

• (a) O usuário está criando uma composição nova do HyperFrames, mesmo que tenha ou esteja testando A/B com um vídeo Remotion semelhante.
• (b) O usuário menciona o Remotion de passagem, sem pedir migração.
• (c) O usuário compartilha código Remotion como material de referência, e não como pedido de tradução.
• (d) O usuário pede "o mesmo vídeo do meu Remotion" sem pedir explicitamente para migrar o código-fonte — trate como uma criação nova do HyperFrames.

NÃO SUPORTADO (recuse — não é o que esta skill faz):

• A direção inversa. Exportar uma composição HyperFrames de volta para Remotion (ou para qualquer outro framework) não é um fluxo de trabalho — a tradução é apenas Remotion → HyperFrames. Diga isso claramente.
• Fontes não-Remotion. Um projeto do After Effects (.aep), uma animação Framer Motion / React puro / CSS, ou qualquer outra ferramenta não é uma composição Remotion — não há código-fonte Remotion para traduzir. Recrie-a nativamente via /general-video, ou recuse se o HyperFrames não puder representá-la.

Em caso de dúvida, opte por criar uma composição HyperFrames nativa com /general-video (o fluxo geral de criação HyperFrames).

Fluxo de Trabalho

Passo 1: Analise o código-fonte

Execute scripts/lint_source.py sobre o diretório de origem do Remotion. A análise detecta padrões que não podem ser traduzidos limposamente:

• Bloqueadores (recuse + recomende interoperabilidade): useState, useReducer, useEffect/useLayoutEffect com dependências não vazias, calculateMetadata assíncrono, bibliotecas de UI React de terceiros (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).
• Avisos (traduza após remover a construção): configuração @remotion/lambda, delayRender, useCallback, useMemo, hooks personalizados.
• Informações (traduza com nota): staticFile, interpolateColors.

Se algum bloqueador for acionado, pare. Leia references/escape-hatch.md e apresente a mensagem de recomendação. Os avisos não interrompem a tradução — remova a construção ofensiva no passo 3 e anote a lacuna em TRANSLATION_NOTES.md. A configuração @remotion/lambda é o caso canônico de aviso: a skill remove o import + as chamadas renderMediaOnLambda(...) mas traduz o resto da composição.

Passo 2: Planeje a tradução

Leia references/api-map.md — o índice de cada API do Remotion e seu equivalente no HF ou referência por tópico. Identifique quais referências de tópico você precisará com base no que o código-fonte usa:

Fonte contém	Carregar referência
Composition, defaultProps, schema, calculateMetadata	parameters.md
Sequence, Series, Loop, AbsoluteFill, Freeze	sequencing.md
useCurrentFrame, interpolate, spring, Easing, interpolateColors	timing.md
Audio, Video, Img, IFrame, staticFile, delayRender	media.md
TransitionSeries, @remotion/transitions	transitions.md
@remotion/lottie	lottie.md
@remotion/google-fonts/<Family>, Font.loadFont, @font-face	fonts.md

Não carregue todas — carregue apenas as que o código-fonte específico precisar.

Passo 3: Gere a composição HF

Emita index.html com:

• Raiz <div id="stage"> contendo o data-composition-id, data-start="0", data-duration (em segundos), data-fps, data-width, data-height, mais um data-* por propriedade escalar.
• Uma lista plana de divs de cena com data-start / data-duration / data-track-index.
• <style> inline para layout; CSS define o estado from de cada propriedade animada.
• Uma única tag <script> no final contendo uma gsap.timeline({paused: true}). Cada derivação useCurrentFrame() do Remotion se torna um tween nesta timeline no deslocamento correto.
• window.__timelines["<composition-id>"] = tl; registra a timeline no runtime do HF.

Subcomponentes React personalizados são incorporados como HTML repetido usando a interface de props como modelo (veja parameters.md para o padrão data-* por instância).

Passo 4: Valide

Execute o harness de avaliação — references/eval.md para o guia completo. Caminho rápido:

# Renderizar linha de base Remotion (após npm install no fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4

# Renderizar tradução HF
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4

# Diferença SSIM
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

Limiar: ~0,02 abaixo do p05 do nível de complexidade da fonte (veja a tabela de limites validados em eval.md). Se a diferença falhar, execute scripts/frame_strip.sh para ver quais quadros divergiram, depois releia a referência relevante de tempo/sequenciamento/mídia.

Crítico: ambas as renderizações devem usar formato de pixel correspondente. Defina Config.setVideoImageFormat("png") + Config.setColorSpace("bt709") no remotion.config.ts da fonte Remotion — caso contrário, a diferença mede diferenças de codificador (~0,05 SSIM de impacto), não a fidelidade da tradução.

Passo 5: Documente as lacunas

Qualquer coisa que não tenha sido traduzida limposamente (ramos de volume removidos, apresentações personalizadas aproximadas, fontes substituídas) recebe um TRANSLATION_NOTES.md escrito ao lado da saída HF. Veja references/limitations.md para o formato.

O que esta skill explicitamente NÃO faz

• Traduzir máquinas de estado React. Composições que dirigem animação via useState + useEffect não são alvos determinísticos de captura de quadros no modelo orientado a quadros do HyperFrames. Recomende o padrão de interoperabilidade em tempo de execução.
• Executar o pipeline de renderização do Remotion junto com o HyperFrames. Esse é o padrão de interoperabilidade em tempo de execução do PR #214 — uma solução separada para composições que falham na análise desta skill.

(@remotion/lambda não é um bloqueador — a configuração Lambda é implantação, não animação. A skill a remove como aviso e traduz o resto. Veja references/escape-hatch.md.)

Como avaliar sua própria tradução

Execute o orquestrador do conjunto de testes:

./assets/test-corpus/run.sh

Ele executa T1, T2, T3 (renderização + diferença) e T4 (validação de lint), imprime uma tabela de aprovação/reprovação por nível e emite um relatório JSON agregado. Use isto para verificar se a skill está funcionando de ponta a ponta em uma cópia limpa — e como verificação de regressão após editar qualquer referência.

Linha de base validada (a partir de 2026-04-27):

Nível	Forma da composição	SSIM médio	Limiar
T1	fade-in de elemento único	0,974	0,95
T2	multi-cena + spring + áudio + imagem	0,985	0,95
T3	orientada a dados, subcomponentes personalizados, contagem	0,953	0,90
T4	escape-hatch (8 casos de lint)	8/8 aprovados	n/a