reversa-arquitetura-3d

name	reversa-arquitetura-3d
description	Cria visualizações 3D interativas de arquitetura de software com Three.js, gerando HTML standalone navegável por câmera livre a partir de JSON de módulos e dependências.
disable-model-invocation	true
license	MIT
compatibility	Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
metadata	{"author":"sandeco","version":"1.0.0","framework":"reversa","team":"shared-skills","role":"3d-renderer"}

Arquitetura 3D

Cria visualizações 3D de arquitetura de software usando Three.js. Gera sempre HTML standalone (arquivo único, self-contained) com cena 3D interativa, controles de câmera (mouse, touch, teclado), sidebar de parâmetros e botão de exportar a viewport como PNG.

A skill cobre cinco modos visuais consagrados em visualização de software, cada um com referência dedicada em references/:

Modo	Quando usar	Referência
Code City	Visão geral de tamanho/complexidade de cada arquivo, padrão "cidade de código"	references/CODE_CITY.md
Dependency Graph 3D	Grafo de dependências com força repulsiva, nós em 3D	references/DEPENDENCY_GRAPH_3D.md
Layer Stack	Camadas arquiteturais (UI / Domain / Infra) empilhadas com setas de fluxo	references/LAYER_STACK.md
Call Graph 3D	Árvore de chamadas explorável em profundidade	references/CALL_GRAPH_3D.md
Architecture Tour	Câmera animada percorrendo a cena com overlay narrativo	references/ARCH_TOUR.md

Padrões compartilhados de Three.js, lighting, controles e performance vivem em references/THREE_PATTERNS.md. Cenários de erro e tratamento em references/ERRORS.md.

Fluxo de Trabalho

1. Receber os dados

Os dados podem vir de:

• JSON inline: usuário fornece modules.json (lista de módulos) e/ou deps.json (grafo de dependências).
• Caminho de arquivo: usuário aponta para JSONs em _reversa_docs/assets/data/ (gerados pelo agente /reversa-documentation).
• Solicitado ao usuário: se a skill é invocada sem dados, perguntar caminho ou pedir colagem inline.

Schema esperado de modules.json:

[
  {
    "name": "src/auth/login.ts",
    "folder": "src/auth",
    "loc": 142,
    "complexity": 8,
    "type": "code"
  }
]

Schema esperado de deps.json (orientado):

{
  "nodes": [{ "id": "src/auth/login.ts" }, { "id": "src/auth/jwt.ts" }],
  "edges": [{ "from": "src/auth/login.ts", "to": "src/auth/jwt.ts", "weight": 1 }]
}

2. Escolher o modo

Se o usuário especificou o modo, usar aquele. Se não, sugerir 2 ou 3 opções com base nos dados:

Tipo de dado	Modos recomendados
modules.json com LOC + complexidade	Code City (padrão), Layer Stack se houver pastas/camadas claras
deps.json com muitas arestas	Dependency Graph 3D, Code City colorindo hot path
Trace de execução ou call graph	Call Graph 3D
Pedido explícito de apresentação	Architecture Tour combinando duas das anteriores

Quando o número de nós ultrapassa 500, aplicar agrupamento por pasta automaticamente e avisar o usuário (registrar a decisão no rodapé do HTML gerado).

3. Gerar o código

Consultar references/THREE_PATTERNS.md para setup base (renderer, cena, câmera, iluminação, OrbitControls). Consultar a referência específica do modo escolhido para o algoritmo de layout e materiais.

Regras fundamentais:

1. HTML standalone: arquivo único .html com tudo embutido (CSS, JS, dados inline em <script id="data">). Quando rodada pelo Time Reversa Docs, os dados vêm de window.RV_DATA.modules e window.RV_DATA.deps (carregados pelo assets/js/data.js que o Publisher gera) e o <script id="data"> fica vazio ou ausente. Páginas finais nunca fazem fetch() para arquivos locais (quebra via file://).
2. Three.js local: usar <script src="assets/vendor/three.min.js"></script> apontando para o arquivo baixado pelo Publisher (versão pinada em agents/reversa-docs-publisher/references/vendor-pins.yaml, hoje three@0.147.0 IIFE). Em modo invocação isolada fora do time Docs, aceite CDN como fallback (https://unpkg.com/three@0.147.0/build/three.min.js), mas nunca misture versões.
3. OrbitControls local: usar <script src="assets/vendor/OrbitControls.js"></script> (também IIFE, compatível com three@0.147). Não use examples/jsm/... enquanto a skill não migrar para importmap + ESM.
4. Renderer: WebGLRenderer com antialiasing, pixelRatio do device.
5. Iluminação: HemisphereLight + DirectionalLight com sombras suaves. Para Code City, AmbientLight extra para preencher.
6. Câmera: PerspectiveCamera, posição inicial olhando o centro da cena de cima e levemente angulada. Distância derivada do tamanho da cena.
7. Performance: usar InstancedMesh quando há mais de 200 elementos do mesmo tipo. Limite máximo de 5.000 prédios no Code City sem agrupamento.
8. Responsividade: handler de resize redimensiona renderer e ajusta aspect ratio da câmera.
9. Sidebar: lado direito, controles sliders/checkboxes/botões em layout vertical. Cada controle tem ID estável para localStorage.
10. Exportar PNG: botão captura o canvas via renderer.domElement.toBlob().

4. Estrutura do HTML gerado

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Arquitetura 3D | <!-- PROJECT_NAME --></title>
    <script src="assets/vendor/three.min.js"></script>
    <script src="assets/vendor/OrbitControls.js"></script>
    <script src="assets/js/data.js"></script>
    <style>
        body { margin: 0; overflow: hidden; font-family: system-ui, sans-serif; }
        #scene { position: fixed; inset: 0; }
        #sidebar { position: fixed; top: 0; right: 0; width: 280px; height: 100vh; padding: 16px; background: rgba(15,15,20,0.85); color: #eaeaea; overflow-y: auto; }
        #loader { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center; font-size: 18px; background: #0a0a10; color: #eaeaea; }
        /* Estilo Reversa: variantes derivam de data-style do <body> via CSS externo do agente */
    </style>
</head>
<body data-style="exploratory">
    <div id="loader">Carregando cena 3D...</div>
    <canvas id="scene"></canvas>
    <aside id="sidebar">
        <h3>Controles</h3>
        <!-- SIDEBAR_CONTROLS -->
        <button id="reset">Reset</button>
        <button id="export-png">Exportar PNG</button>
    </aside>
    <script id="data" type="application/json"><!-- DATA_JSON --></script>
    <script>
        // OrbitControls IIFE expõe THREE.OrbitControls globalmente.
        // 1. Carregar dados de window.RV_DATA quando rodando no time Docs,
        //    ou do <script id="data"> em modo standalone.
        // 2. Configurar cena, câmera, renderer, iluminação
        // 3. Construir geometria conforme o modo (Code City, Dep Graph, etc)
        // 4. Conectar sidebar aos parâmetros da cena
        // 5. Loop de renderização e tratamento de eventos
    </script>
</body>
</html>

5. Salvar e entregar

O output é sempre HTML standalone. Salvar no caminho indicado pelo agente orquestrador (geralmente _reversa_docs/arquitetura.html).

Quando invocada fora do contexto do /reversa-documentation, perguntar caminho de destino ou usar <modo>-<timestamp>.html no diretório atual.

Diretrizes de qualidade

• Câmera intuitiva: posição inicial mostra a cena inteira; OrbitControls com damping para movimento suave.
• Materiais coesos: paleta limitada (5 a 8 cores no máximo); cores carregadas indicam atributo (ex: vermelho para hot path, azul para módulos leves).
• Labels legíveis: usar CSS2DRenderer ou sprites; labels só aparecem em hover ou zoom acima de um threshold para não poluir.
• Loader visível: cena começa com overlay "Carregando cena 3D..." que some quando o requestAnimationFrame da primeira frame termina.
• Fallback gracioso: se Three.js não carregar (sem internet), mostrar mensagem "Esta visualização requer carregar a biblioteca Three.js. Conecte-se à internet e recarregue."
• Acessibilidade básica: navegação por teclado nos botões da sidebar; foco visível.
• Idioma: comentários e textos visíveis em pt-br. Sem travessão.

Diretrizes de código

• Modularidade: separar criação da cena, construção da geometria e gerenciamento de interação em funções com nomes claros.
• Sem dependências além de Three.js e OrbitControls (locais em assets/vendor/): não importar GSAP, dat.GUI, ou qualquer outra lib sem necessidade clara.
• Constantes nomeadas no topo: cores, sizes, thresholds em um bloco de configuração visível.
• Dispose: ao trocar de modo ou regenerar, chamar geometry.dispose() e material.dispose() para evitar vazamento.
• Performance check: antes de renderizar, contar nós; se > 5.000 sem instanced mesh, abortar e mostrar aviso.

Tratamento de erros

Consultar references/ERRORS.md para cenários comuns (CDN inacessível, JSON malformado, projeto vazio, WebGL não suportado, etc).