Especificação de Desenvolvimento de Componentes de Vídeo iPolloWork
O que é entregue é um componente que pode ser inserido em um vídeo, ajustado por meio de formulários compartilhados, que segue o tema do projeto e pode ser processado por IA. Não crie um editor, painel de parâmetros, renderizador ou plugin de host separado para um componente.
1. Antes de Começar: Siga o Contrato de Código Atual
No diretório raiz do repositório iPolloWork, leia AGENTS.md e as especificações de manutenção. Primeiro, encontre componentes semelhantes e depois decida se deve estender ou adicionar. Os caminhos a seguir são relativos ao diretório raiz do repositório:
vendor/hyperframes/registry/blocks/world-map/: Referência para mapas, herança de temas e dados estruturados.vendor/hyperframes/registry/blocks/metric-signal/: Referência para exibição de dados e receitas de animação opcionais.vendor/hyperframes/packages/core/src/registry/types.ts: Contrato de categorias e manifestos de componentes.vendor/hyperframes/packages/core/src/registry/componentData.ts: Estruturas de dados compartilhadas e regras de análise.vendor/hyperframes/packages/core/schemas/registry-item.json,packages/types/src/hyperframes.ts: Contratos de validação de itens de registro e host.vendor/hyperframes/packages/studio/src/utils/blockInstaller.ts: Método real de instalação, acesso a temas e variáveis.
Não copie esses schemas nem crie outro conjunto de protocolos de dados. Quando a especificação e o código estiverem inconsistentes, verifique primeiro os consumidores atuais, não use exemplos antigos para adivinhar a interface.
2. Estrutura Mínima de Entrega
Normalmente, basta colocar em vendor/hyperframes/registry/blocks/<slug>/:
registry-item.json # Metadados, variáveis, categorias, arquivos e declarações de capacidade
<slug>.html # Visual e animações
Se realmente necessário, adicione imagens locais, fontes, dados ou arquivos de visualização; os arquivos necessários para instalação devem ser declarados em files, com caminhos relativos ao pacote. Registre no vendor/hyperframes/registry/registry.json existente, não crie um serviço de diretório de componentes separado.
No produto, são chamados de "componentes", mas o tipo subjacente deve ser preciso: mapas, rankings etc., com tela e duração independentes, geralmente são hyperframes:block; fragmentos injetados em telas existentes são hyperframes:component. Modelos de projeto completos pertencem a outro tipo de entrega, não misture.
3. Variáveis: Poucas e Úteis, Formulários Compartilhados
- Declare
idestável,labelcompreensível, tipo e valor padrão emvariablesno manifesto, consistente comdata-composition-variablesno HTML. - Use os tipos existentes
string / number / color / boolean / enum; para números, dê um intervalo razoável; para enumerações, forneça opções; para textos longos, defina restrições de comprimento. Não adicione tipos de objeto por conta própria. - Exponha apenas conteúdo, dados, destaques e layout necessários para decisões do usuário; não transforme cada valor CSS em um parâmetro. As cores padrão vêm do tema, não podem exigir que o usuário configure cada item para usar.
update: liveé apenas para parâmetros que podem ser atualizados instantaneamente; ao alterar estrutura ou animação, userebuild / reloadconforme o mecanismo existente, a declaração deve ser consistente com o comportamento real.- Conecte-se ao mecanismo de atualização de variáveis existente; após a atualização, o DOM e as animações devem refletir os novos valores e manter a posição de reprodução atual do host. Não altere apenas o texto enquanto a linha do tempo ainda aponta para o elemento antigo.
- Use formulários de variáveis e tabelas de dados compartilhados, não crie um novo painel para cada componente. Campos de controle do sistema como
motionCueTimes,motionStylenão são tratados como parâmetros comuns do usuário.
4. Dados: Estrutura para IA, Tabela para o Usuário
Componentes de dados como mapas, rotas, gráficos e rankings usam visualComponent.data, declarando colunas, semântica, identificadores de linha, limites de linha e vinculações. Use os tipos existentes category-value / region-value / point-value / route-value / series-value, escolhendo o que realmente corresponde aos dados.
Os dados padrão orientados para IA são:
{
"version": 1,
"kind": "region-value",
"rows": [
{ "region": "China", "value": 96 },
{ "region": "Japan", "value": 77 }
]
}
Os nomes das colunas são determinados pelas columns do componente, nem todos os componentes usam fixamente region. rowId deve ser estável e único; números mantêm o tipo numérico; unidade, precisão, destaque e semântica de substituição/sobreposição devem ser declarados conforme o contrato existente.
binding.variable deve corresponder a uma variável real. Internamente, podem ser usadas as codificações existentes json / key-value-list / route-value-list / label-detail-list, mas convertidas pela camada de adaptação compartilhada; não exija que o usuário escreva vírgulas, dois-pontos etc. manualmente. Não crie outro estado JSON que não esteja sincronizado. Dados inválidos devem fornecer dicas claras, não descartar linhas silenciosamente ou gerar valores fictícios.
5. Tema e Classificação
- Declare
visualComponent.version: 1,themeMode: inherit, e preenchasurfacesconforme a capacidade; prefiravideo, não afirme suporte a PPT ou web antes de validar. - Use as categorias atuais
VISUAL_COMPONENT_CATEGORIES, por exemplo, mapasmaps, dadosdata, diagramas/arquiteturadiagrams. Para aberturas e encerramentos, use olibrarySectionexistente para posicionamento; não crie outra árvore de classificação. - Use as variáveis de tema existentes, como
--ipw-color-bg,--ipw-color-surface,--ipw-color-text,--ipw-color-primary,--ipw-color-border,--ipw-font-display,--ipw-font-body,--ipw-card-radius. - Permita valores de fallback padrão para visualização independente, mas não substitua o tema do host. Após a troca de tema, fundo, texto, gráficos, bordas e fontes devem mudar de forma coordenada; exceções para cores semânticas de dados precisam de justificativa clara.
- Mantenha hierarquia clara, espaçamento razoável e legibilidade em chinês. Use gradientes ou efeitos de vidro com moderação quando necessário, não substitua a expressão de informações por efeitos especiais.
6. Animações e Linha do Tempo
- Padrão: HTML + CSS + GSAP; priorize a reutilização de gráficos existentes e SVG local. Considere Three.js apenas quando for necessária 3D real, não adicione dependências pesadas para mapas simples.
- Use o nó raiz, dimensões, duração e mecanismo de instalação existentes da composição; registre na linha do tempo GSAP pausada
window.__timelines[compositionId], controlada pelo HyperFrames para reprodução, pausa e busca. - O seletor, estado e linha do tempo de cada instância afetam apenas a si mesma. Limpe animações antigas ao reconstruir, não substitua outras instâncias.
- O mesmo momento deve produzir a mesma tela: não use temporizadores independentes, loops de reprodução automática, números aleatórios não fixados ou animações CSS autoexecutadas para conduzir conteúdo crítico. Imagens reais, áudio e vídeo seguem o método de sincronização de tempo de mídia existente.
- As animações servem à ordem de explicação: aparecimento claro, destaque, pausa e saída; texto e dados devem ter tempo de leitura suficiente. Evite a mesma entrada para todos os componentes, bem como movimento contínuo apenas para mostrar habilidade.
- Componentes comuns não exigem a adição de
motionRecipe. Só quando a IA precisar chamar receitas de animação com base na narração, use o contrato de receita suportado existente; eventos, vinculações de cue e elementos reais devem ser consistentes, com capacidade e limites de texto baseados em evidências reais, não invente tempos de dublagem.
7. Espaço de Processamento de IA
Use visualComponent.ai.slots para declarar áreas editáveis estáveis e adicione data-ipw-ai-slot nas posições HTML correspondentes. instructions deve descrever brevemente o propósito, regras de entrada e estrutura a ser preservada.
Suporte IA para substituir conteúdo, ajustar layout, reduzir mapa e adicionar explicações ao lado, etc., como processamento local; mantenha IDs de variáveis, vinculação de dados, herança de tema e acesso à linha do tempo inalterados. Não force todo processamento a se tornar parâmetros de formulário, nem mantenha outra versão da tela para IA.
Texto externo deve ser tratado como texto, não incorporado em HTML executável; não execute scripts em dados de entrada, não incorpore chaves. Ao referenciar recursos como mapas, fontes e imagens, mantenha a fonte e a licença; quando faltarem materiais, explique claramente, não substitua silenciosamente por recursos online.
8. Aceitação e Entrega
- Manifesto, variáveis HTML, slots de IA, vinculação de dados e caminhos de instalação devem ser consistentes, passando pela validação do repositório atual e testes afetados.
- Instale o componente no Studio existente; o formulário compartilhado deve modificar a tela real; a tabela de dados deve permitir adicionar, excluir e editar linhas válidas.
- Verifique os estados padrão, limites, valores nulos, texto longo em chinês, dados de erro e dois temas; múltiplas instâncias não devem interferir entre si.
- Verifique a reprodução do início, busca no meio, arrastar de volta ao início e busca após atualização de parâmetros; a tela e a linha do tempo devem ser consistentes.
- Exporte um pequeno vídeo com materiais reais, confirmando que a visualização do navegador corresponde à saída; não afirme aprovação apenas com capturas de tela.
- Entregue arquivos do componente, recursos necessários com fontes, exemplos de parâmetros/dados, resultados reais de teste e itens não validados. Não copie o Studio, não altere o comportamento de modelos existentes, não deixe implementações alternativas residuais.
Esta especificação orienta apenas o desenvolvimento de componentes. Publicar no npm, modificar plugins do host, enviar PRs ou fazer upload para o mercado de componentes requer autorização do usuário e segue o processo de publicação existente separadamente.