grafo-de-lore-visualizacao-e-filtros
Renderiza, navega e filtra o grafo de entidades do universo ficcional (personagens, locais, eventos, objetos) com agrupamento semântico, zoom temporal e filtros por tipo/personagem/período. Ativar ao
SKILL.md.agents/skills/grafo-de-lore-visualizacao-e-filtros/SKILL.md
GitHubgrafo-de-lore-visualizacao-e-filtros
Descrição
A skill grafo-de-lore-visualizacao-e-filtros especifica a implementação do painel de visualização interativa do Grafo de Universo Ficcional (GUF) no navegador. Ela define a biblioteca de renderização, a estratégia de layout, os filtros interativos por tipo de entidade, personagem e período temporal, e as otimizações para evitar saturação visual quando o grafo tem centenas de nós.
Quando usar
Gatilhos concretos e observáveis:
- A equipe implementa ou atualiza o componente de grafo na aba "Wiki" ou "Universo" do editor.
- O usuário abre o painel de grafo com mais de 50 entidades cadastradas.
- Novos tipos de entidade (facções, itens mágicos, locais) são adicionados ao GUF.
Quando NÃO usar:
- Para a lógica de extração e persistência de entidades (ver skill
extracao-autonoma-relacoes-literarias). - Para análise temporal de consistência (ver skill
analise-consistencia-narrativa-tempo-e-eventos).
Pré-requisitos
- Biblioteca de visualização de grafos: Cytoscape.js (recomendada) ou D3-force.
- API de backend que retorna nós e arestas do GUF em formato JSON (campos:
id,label,type,chapter_first_appearance,connections). - Componente de sidebar de filtros implementado no framework frontend.
Processo (passo a passo executável)
Inicialização do Grafo (Cytoscape.js):
- Instanciar o Cytoscape com o container
div#guf-canvas. - Carregar os dados do GUF via endpoint
/api/guf/nodescom paginação porchapter_range. - Definir estilos visuais por
typede entidade (ex:personagem= círculo azul,local= hexágono verde,evento= diamante laranja).
- Instanciar o Cytoscape com o container
Layout Inicial (Cola Force-Directed):
- Aplicar o layout
cose-bilkent(Cola) para separação automática de clusters de entidades relacionadas. - Agrupar nós com 3 ou mais conexões em clusters colapsáveis para reduzir saturação visual.
- Limitar o número de nós visíveis simultaneamente a
MAX_VISIBLE_NODES = 120.
- Aplicar o layout
Filtros Interativos (Sidebar):
- Implementar filtros cumulativos na sidebar:
- Por Tipo: Checkboxes para cada tipo de entidade (personagem, local, evento, objeto, facção).
- Por Personagem: Dropdown que ao selecionar um personagem destaca o subgrafo ego-centrado (o personagem + todos os nós conectados a ele em até 2 saltos).
- Por Período Temporal: Slider de capítulos (ex: capítulos 1–5) que oculta entidades introduzidas fora do intervalo selecionado.
- Aplicar filtros via
cy.elements().filter()sem recarregar os dados do servidor.
- Implementar filtros cumulativos na sidebar:
Interação com Nós:
- Ao clicar num nó, exibir um painel lateral com a ficha completa da entidade (nome, aliases, descrição, capítulo de introdução).
- Ao passar o mouse sobre uma aresta, exibir tooltip com o tipo da relação (ex: "é aliado de", "é filho de", "habita").
Time-Slicing Animado:
- Implementar botão "Animar linha do tempo" que itera progressivamente pelos capítulos, mostrando como o grafo evolui (entidades aparecendo e desaparecendo conforme o capítulo avança).
Parâmetros e configuração
| Parâmetro | Descrição | Padrão |
|---|---|---|
MAX_VISIBLE_NODES |
Número máximo de nós visíveis simultaneamente antes de colapsar clusters | 120 |
EGO_GRAPH_HOPS |
Número de saltos para o subgrafo ego-centrado ao selecionar personagem | 2 |
LAYOUT_ALGORITHM |
Algoritmo de layout do grafo | "cose-bilkent" |
ANIMATION_INTERVAL_MS |
Intervalo entre frames na animação de linha do tempo | 800 |
Armadilhas e como evitá-las
- Armadilha: Renderizar o grafo completo com todos os nós de uma vez sem paginação ou cluster colapso. Com 300+ nós em um layout force-directed, o navegador congela por 5–10 segundos e o resultado visual é ilegível.
Mitigação: Implementar colapso automático de clusters com
MAX_VISIBLE_NODESe carregar entidades de capítulos adicionais sob demanda (lazy loading por range de capítulos).
Critérios de validação (Definition of Done)
- O painel de grafo com 200 entidades carrega e renderiza em menos de 2 segundos no Chrome.
- Os filtros por tipo, personagem e período funcionam sem recarregar dados do servidor.
- O usuário consegue navegar pelo grafo (zoom, pan, clique em nó) sem travamentos.
Exemplos
Filtro por personagem: Usuário seleciona "Helena" → sistema destaca Helena (nó central) + todos os personagens com quem ela interage + todos os locais onde ela aparece. Nós sem conexão com Helena ficam com opacidade 0.15.
Time-slicing: Slider em Capítulo 3 → somente entidades introduzidas até o capítulo 3 são visíveis. Slider movido para Capítulo 7 → novas entidades aparecem com animação fade-in.