Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
Sign In

reversa

Package Overview
Dependencies
Maintainers
1
Versions
50
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

reversa - npm Package Compare versions

Comparing version
1.2.39
 to
1.2.40
+242
agents/reversa-arquitetura-3d/references/ARCH_TOUR.md
# Architecture Tour
Câmera animada percorrendo a cena em ritmo cinematográfico, com **overlay narrativo** sincronizado. Funciona como um "trailer" do sistema: alguém aperta play e o vídeo se desenrola sozinho, parando em pontos-chave com legendas explicativas.
## Conceito
Tour não é um modo isolado, é uma **camada animada** que se sobrepõe a qualquer dos outros modos (Code City, Dependency Graph 3D, Layer Stack, Call Graph). A skill recebe uma sequência de waypoints e narrações, e a câmera viaja entre eles.
## Quando usar
- Apresentações para stakeholders não-técnicos.
- Onboarding de novos devs ("aperte play e veja como o sistema é").
- Demonstração executiva curta (1 a 3 minutos).
- Acompanhamento da `deck.html` do mini-site.
## Modelo de dados: a coreografia
```json
{
"baseMode": "code-city",
"duration": 90,
"waypoints": [
{
"at": 0,
"camera": { "position": [200, 250, 400], "target": [0, 0, 0] },
"overlay": "Esse é o sistema de pagamentos visto de cima."
},
{
"at": 12,
"camera": { "position": [50, 30, 80], "target": [40, 0, 20] },
"overlay": "O distrito mais alto, src/payments, concentra 40% do código."
},
{
"at": 24,
"camera": { "position": [80, 60, 60], "target": [60, 20, 30] },
"highlight": ["src/payments/charge.ts", "src/payments/refund.ts"],
"overlay": "Charge e refund são os arquivos centrais."
},
{
"at": 40,
"camera": { "position": [-100, 80, 200], "target": [-50, 0, 0] },
"switchMode": "dependency-graph",
"overlay": "Agora vamos olhar as dependências dele."
}
]
}
```
- `at`: segundo da timeline em que o waypoint dispara.
- `camera`: posição e alvo da câmera ao chegar.
- `highlight`: lista de IDs de nó/módulo para destacar (outros desfocam).
- `overlay`: texto da legenda, em pt-br.
- `switchMode` (opcional): troca o modo base no meio do tour, com transição.
## Algoritmo de interpolação
Entre dois waypoints, a câmera interpola posição e alvo com easing.
```javascript
import { CatmullRomCurve3 } from "https://cdn.jsdelivr.net/npm/three@0.158.0/build/three.module.js";
const positions = waypoints.map((w) => new THREE.Vector3(...w.camera.position));
const targets = waypoints.map((w) => new THREE.Vector3(...w.camera.target));
const positionCurve = new CatmullRomCurve3(positions);
const targetCurve = new CatmullRomCurve3(targets);
let startTime = null;
function playTour() {
startTime = performance.now();
controls.enabled = false; // desligar interação manual
animateTour();
}
function animateTour() {
const now = performance.now();
const elapsed = (now - startTime) / 1000;
if (elapsed >= tour.duration) {
finishTour();
return;
}
const t = elapsed / tour.duration; // 0..1
const pos = positionCurve.getPoint(t);
const tgt = targetCurve.getPoint(t);
camera.position.copy(pos);
camera.lookAt(tgt);
updateOverlay(elapsed);
updateHighlights(elapsed);
renderer.render(scene, camera);
requestAnimationFrame(animateTour);
}
```
## Overlay narrativo
Caixa de texto posicionada em rodapé ou lateral, com transições suaves entre falas.
```html
<div id="tour-overlay">
<p id="tour-text"></p>
<div id="tour-progress"><div id="tour-progress-fill"></div></div>
<div id="tour-controls">
<button id="tour-pause">Pausar</button>
<button id="tour-restart">Reiniciar</button>
<button id="tour-skip">Pular</button>
</div>
</div>
```
```javascript
function updateOverlay(elapsed) {
const current = waypoints.findLast((w) => w.at <= elapsed);
if (!current) return;
const textEl = document.getElementById("tour-text");
if (textEl.dataset.at !== String(current.at)) {
textEl.dataset.at = current.at;
textEl.style.opacity = 0;
setTimeout(() => {
textEl.textContent = current.overlay;
textEl.style.opacity = 1;
}, 300);
}
const progress = (elapsed / tour.duration) * 100;
document.getElementById("tour-progress-fill").style.width = progress + "%";
}
```
## Destaque de elementos
Durante highlights, os módulos selecionados ganham emissive e os demais reduzem opacidade.
```javascript
function updateHighlights(elapsed) {
const current = waypoints.findLast((w) => w.at <= elapsed);
const highlightIds = new Set(current?.highlight ?? []);
modules.forEach((m, i) => {
const isHighlighted = highlightIds.size === 0 || highlightIds.has(m.name);
const targetOpacity = isHighlighted ? 1.0 : 0.15;
// animar opacity via InstancedMesh é mais trabalhoso;
// alternativa: trocar cor para uma versão dessaturada quando opacity baixa
const baseColor = colorForModule(m);
const finalColor = isHighlighted ? baseColor : dim(baseColor, 0.3);
instanced.setColorAt(i, new THREE.Color(finalColor));
});
instanced.instanceColor.needsUpdate = true;
}
function dim(hex, factor) {
const c = new THREE.Color(hex);
c.r *= factor; c.g *= factor; c.b *= factor;
return c.getHex();
}
```
## Mudança de modo no meio do tour
Quando um waypoint tem `switchMode`, fazer fade-out da cena atual, dispose, criar a nova cena, fade-in.
```javascript
function switchSceneMode(newMode) {
fadeOverlay.style.opacity = 1;
setTimeout(() => {
clearScene();
if (newMode === "dependency-graph") buildDependencyGraph();
else if (newMode === "code-city") buildCodeCity();
// etc
fadeOverlay.style.opacity = 0;
}, 600);
}
```
## Controles do tour
- **Pause**: para `requestAnimationFrame`, congela tempo.
- **Restart**: volta `startTime` para agora.
- **Skip**: pula para o próximo waypoint.
- **Manual takeover**: se usuário arrastar mouse na cena, interrompe tour e habilita OrbitControls.
```javascript
renderer.domElement.addEventListener("pointerdown", () => {
if (tourPlaying) {
pauseTour();
controls.enabled = true;
showResumeButton();
}
});
```
## Trilha sonora opcional
Tour pode incluir música ambient sutil via `<audio>` embutido em base64 (curto, ~30s em loop) ou via Web Audio API gerando drones procedurais. Default: sem áudio.
## Geração da coreografia
A skill recebe waypoints prontos OU gera automaticamente a partir de heurísticas:
- Iniciar de cima olhando o centro.
- Mergulhar nos 3 maiores prédios (Code City).
- Voar pelo grafo de dependências destacando o nó mais central.
- Terminar mostrando a layer stack das camadas violadoras (se houver).
Cada heurística pode ser ativada ou desativada via parâmetro.
## Sidebar do tour
```html
<aside id="sidebar">
<h3>Architecture Tour</h3>
<label>Duração total
<input type="range" min="30" max="300" value="90" data-param="duration"> s
</label>
<label>Modo base
<select data-param="baseMode">
<option value="code-city">Code City</option>
<option value="dependency-graph">Dependency Graph</option>
<option value="layer-stack">Layer Stack</option>
</select>
</label>
<label>
<input type="checkbox" data-param="autoPlay"> Tocar ao abrir
</label>
<label>
<input type="checkbox" data-param="includeViolationsScene" checked> Incluir cena de violações
</label>
<button id="play-tour">Tocar Tour</button>
<button id="pause-tour">Pausar</button>
<button id="restart-tour">Reiniciar</button>
</aside>
```
## Performance
Tour herda performance do modo base. Adicionar tour custa pouco: apenas interpolação de câmera e animações de opacity. Cuidado com `switchMode` no meio: dispose + rebuild pode causar stutter de 200-500ms.
+217
agents/reversa-arquitetura-3d/references/CALL_GRAPH_3D.md
# Call Graph 3D
Árvore (ou DAG) de **chamadas de função** explorável em 3D. Cada nó é uma função, cada aresta é uma chamada. Permite navegar a profundidade de uma cadeia de invocações partindo de pontos de entrada (endpoints, handlers, main).
## Mapeamento
| Conceito | Visual |
|---|---|
| Função | Cápsula ou pílula 3D com label |
| Profundidade de chamada | Posição em Z (eixo de profundidade) |
| Função síncrona | Cápsula sólida |
| Função assíncrona | Cápsula translúcida com partículas |
| Função recursiva | Cápsula com brilho (emissive) |
| Caminho quente (frequência) | Linha mais grossa, cor saturada |
| Função externa (lib) | Cor cinza |
| Função do projeto | Cor por pasta/módulo |
## Quando usar
- Entender o fluxo de execução de um endpoint específico.
- Diagnosticar profundidade excessiva de chamadas (>15 níveis, sinal de overengineering).
- Detectar recursão indireta.
- Apresentar como o sistema responde a uma requisição típica.
**Quando evitar**: análise estática sem dados de execução é incompleta (não captura polimorfismo). Para visão estrutural use Dependency Graph 3D.
## Modelo de dados esperado
```json
{
"entrypoints": ["POST /api/orders", "handleWebhookStripe"],
"calls": [
{
"from": "POST /api/orders",
"to": "OrderController.create",
"type": "sync",
"weight": 1000
},
{
"from": "OrderController.create",
"to": "OrderService.placeOrder",
"type": "sync",
"weight": 1000
},
{
"from": "OrderService.placeOrder",
"to": "PaymentClient.charge",
"type": "async",
"weight": 1000
}
]
}
```
`weight` é frequência relativa (quantidade de invocações observadas em um período). `type` é `sync`, `async`, `recursive` ou `external`.
## Algoritmo de layout: árvore radial 3D
Cada entrypoint vira raiz da árvore. Profundidade aumenta no eixo Z (afastando-se da câmera), funções no mesmo nível distribuem-se em um plano XY.
```javascript
function layoutTree(entrypoint, calls) {
const nodes = new Map();
nodes.set(entrypoint, { id: entrypoint, depth: 0, x: 0, y: 0, z: 0, children: [] });
function buildChildren(parentId, parentDepth) {
const outgoing = calls.filter((c) => c.from === parentId);
outgoing.forEach((c, i, arr) => {
if (nodes.has(c.to)) {
// detectou recursão
nodes.get(c.to).recursive = true;
return;
}
const angle = (i / arr.length) * Math.PI * 2;
const radius = parentDepth * 15 + 30;
const node = {
id: c.to,
depth: parentDepth + 1,
x: nodes.get(parentId).x + Math.cos(angle) * radius,
y: nodes.get(parentId).y + Math.sin(angle) * radius,
z: -(parentDepth + 1) * 40,
type: c.type,
weight: c.weight,
children: []
};
nodes.set(c.to, node);
nodes.get(parentId).children.push(node);
buildChildren(c.to, parentDepth + 1);
});
}
buildChildren(entrypoint, 0);
return Array.from(nodes.values());
}
```
Para múltiplos entrypoints, cada um ocupa uma região do plano XY (translação no centro), criando árvores paralelas.
## Renderização das cápsulas
```javascript
const capsuleGeo = new THREE.CapsuleGeometry(2, 6, 8, 12);
const capsuleMat = new THREE.MeshStandardMaterial({ roughness: 0.4 });
const capsules = new THREE.InstancedMesh(capsuleGeo, capsuleMat, nodes.length);
nodes.forEach((n, i) => {
const dummy = new THREE.Object3D();
dummy.position.set(n.x, n.y, n.z);
dummy.rotation.z = Math.PI / 2; // horizontal
const scale = 0.6 + Math.log(1 + (n.weight ?? 1)) * 0.2;
dummy.scale.set(scale, scale, scale);
dummy.updateMatrix();
capsules.setMatrixAt(i, dummy.matrix);
const color = new THREE.Color(colorForCall(n));
capsules.setColorAt(i, color);
});
capsules.instanceMatrix.needsUpdate = true;
capsules.instanceColor.needsUpdate = true;
scene.add(capsules);
```
`colorForCall(n)` retorna cinza para externas, cor da pasta para internas, com emissive se `n.recursive`.
## Renderização das chamadas (arestas)
Linhas curvas tipo bezier conectando pai a filho. Mais grossas para `weight` alto.
```javascript
calls.forEach((c) => {
const src = nodesById.get(c.from);
const dst = nodesById.get(c.to);
if (!src || !dst) return;
const mid = new THREE.Vector3(
(src.x + dst.x) / 2,
(src.y + dst.y) / 2 + 10,
(src.z + dst.z) / 2
);
const curve = new THREE.QuadraticBezierCurve3(
new THREE.Vector3(src.x, src.y, src.z),
mid,
new THREE.Vector3(dst.x, dst.y, dst.z)
);
const tube = new THREE.TubeGeometry(curve, 20, 0.2 + Math.log(1 + c.weight) * 0.1, 6, false);
const isAsync = c.type === "async";
const mat = new THREE.MeshStandardMaterial({
color: isAsync ? 0xb39ddb : 0x4a9eff,
transparent: true,
opacity: 0.6
});
scene.add(new THREE.Mesh(tube, mat));
});
```
## Animação de fluxo (opcional)
Partículas viajando ao longo das arestas, indicando que a chamada está "viva". Útil para apresentações.
```javascript
function animateFlow(time) {
edgeParticles.forEach((p) => {
const t = (time * 0.001 + p.offset) % 1;
const pos = p.curve.getPoint(t);
p.mesh.position.copy(pos);
});
}
```
## Sidebar de controles
```html
<aside id="sidebar">
<h3>Call Graph 3D</h3>
<label>Entrypoint
<select data-param="entrypoint">
<!-- POPULATED -->
</select>
</label>
<label>Profundidade máxima
<input type="range" min="1" max="20" value="10" data-param="maxDepth">
</label>
<label>
<input type="checkbox" data-param="showAsync" checked> Destacar async
</label>
<label>
<input type="checkbox" data-param="showExternal"> Mostrar libs externas
</label>
<label>
<input type="checkbox" data-param="animateFlow"> Animar fluxo
</label>
<div id="depth-info"></div>
<div id="recursive-warnings"></div>
<button id="reset">Reset</button>
<button id="export-png">Exportar PNG</button>
</aside>
```
## Interação
- **Hover em cápsula**: nome da função, módulo de origem, número de chamadores e chamados, tipo.
- **Clique em cápsula**: foca câmera, destaca cadeia desde o entrypoint até essa função.
- **Duplo clique**: expande/colapsa subárvore.
- **Toggle entrypoint**: muda a raiz da visualização, recalcula layout.
## Performance
- Limite prático: ~500 funções por entrypoint.
- Acima disso, colapsar subárvores automaticamente após profundidade 5 e exibir botão "+N funções".
- Animação de fluxo: limitar a 50 partículas simultâneas para não derrubar fps.
+228
agents/reversa-arquitetura-3d/references/CODE_CITY.md
# Code City
Padrão consagrado de visualização de software em 3D: cada arquivo do projeto é um **prédio**, agrupados em **distritos** que correspondem a pastas. Permite captar tamanho, complexidade e distribuição do código em um único olhar.
## Mapeamento de atributos
| Atributo do código | Atributo visual do prédio |
|---|---|
| Linhas de código (LOC) | Altura |
| Complexidade ciclomática | Área da base (largura x profundidade) |
| Pasta do arquivo | Distrito (posição no plano) |
| Tipo de arquivo (código, teste, config) | Cor base |
| Hot path (frequência de mudança ou dependentes) | Cor de destaque (vermelho/amarelo) |
## Quando usar
- Visão geral inicial de um projeto desconhecido.
- Identificar arquivos muito grandes (prédios altos) ou complexos (prédios largos).
- Detectar agrupamento por pasta (distritos coesos vs espalhados).
- Apresentação executiva: visualmente impactante e intuitivo.
**Quando evitar**: projetos pequenos (< 30 arquivos), onde a metáfora urbana é overkill. Use Dependency Graph 3D ou módulos D3 2D.
## Algoritmo de layout
### 1. Agrupar por pasta
```javascript
const districts = {};
modules.forEach((m) => {
if (!districts[m.folder]) districts[m.folder] = [];
districts[m.folder].push(m);
});
```
### 2. Calcular tamanho de cada distrito
A área do distrito é proporcional ao número de arquivos. Use empacotamento simples (linha por linha) ou squarified treemap.
```javascript
function packDistrict(modules, padding = 1) {
const count = modules.length;
const cols = Math.ceil(Math.sqrt(count));
const rows = Math.ceil(count / cols);
return { cols, rows };
}
```
### 3. Posicionar distritos no plano
Os distritos formam a cidade. Para até ~20 pastas, empacotar em grid simples. Para mais, usar treemap.
```javascript
const districtSize = (count) => Math.sqrt(count) * cellSize * 2;
let offsetX = 0;
let offsetZ = 0;
const districtPositions = {};
Object.entries(districts).forEach(([folder, mods], i) => {
const size = districtSize(mods.length);
districtPositions[folder] = { x: offsetX, z: offsetZ, size };
offsetX += size + districtGap;
if ((i + 1) % gridCols === 0) {
offsetX = 0;
offsetZ += size + districtGap;
}
});
```
### 4. Posicionar prédios dentro do distrito
```javascript
modules.forEach((m) => {
const district = districtPositions[m.folder];
const local = packDistrict(districts[m.folder]);
const indexInDistrict = districts[m.folder].indexOf(m);
const col = indexInDistrict % local.cols;
const row = Math.floor(indexInDistrict / local.cols);
m.x = district.x + col * cellSize;
m.z = district.z + row * cellSize;
});
```
### 5. Dimensionar cada prédio
```javascript
const LOC_TO_HEIGHT = 0.4; // 1000 LOC = 400 unidades de altura
const COMPLEXITY_TO_WIDTH = 0.8;
const MIN_W = 2;
const MIN_H = 1;
modules.forEach((m) => {
m.height = Math.max(MIN_H, m.loc * LOC_TO_HEIGHT);
const baseW = Math.max(MIN_W, Math.sqrt(m.complexity) * COMPLEXITY_TO_WIDTH);
m.w = baseW;
m.d = baseW;
});
```
### 6. Renderizar com InstancedMesh
Ver `THREE_PATTERNS.md` para o padrão de InstancedMesh. Cada prédio é uma instância da mesma BoxGeometry, com matriz e cor distintas.
```javascript
const boxGeo = new THREE.BoxGeometry(1, 1, 1);
boxGeo.translate(0, 0.5, 0); // base no chão
const mat = new THREE.MeshStandardMaterial({ roughness: 0.6 });
const buildings = new THREE.InstancedMesh(boxGeo, mat, modules.length);
buildings.castShadow = true;
buildings.receiveShadow = true;
const dummy = new THREE.Object3D();
const color = new THREE.Color();
modules.forEach((m, i) => {
dummy.position.set(m.x, 0, m.z);
dummy.scale.set(m.w, m.height, m.d);
dummy.updateMatrix();
buildings.setMatrixAt(i, dummy.matrix);
color.set(colorForModule(m));
buildings.setColorAt(i, color);
});
buildings.instanceMatrix.needsUpdate = true;
buildings.instanceColor.needsUpdate = true;
scene.add(buildings);
```
### 7. Chão e distritos
Adicionar um plano grande como chão e quadrados coloridos demarcando cada distrito.
```javascript
const ground = new THREE.Mesh(
new THREE.PlaneGeometry(2000, 2000),
new THREE.MeshStandardMaterial({ color: 0x14141a, roughness: 1 })
);
ground.rotation.x = -Math.PI / 2;
ground.receiveShadow = true;
scene.add(ground);
Object.entries(districtPositions).forEach(([folder, d]) => {
const districtPlane = new THREE.Mesh(
new THREE.PlaneGeometry(d.size, d.size),
new THREE.MeshStandardMaterial({ color: districtColor(folder), transparent: true, opacity: 0.15 })
);
districtPlane.rotation.x = -Math.PI / 2;
districtPlane.position.set(d.x + d.size / 2, 0.01, d.z + d.size / 2);
scene.add(districtPlane);
});
```
## Cores por tipo de arquivo
```javascript
const TYPE_COLORS = {
code: 0x4a9eff, // azul
test: 0x6cc46c, // verde
config: 0xffc857, // amarelo
doc: 0xb39ddb, // lilás
style: 0xff9aa2, // rosa
asset: 0x999999 // cinza
};
function colorForModule(m) {
if (m.isHotPath) return 0xff5a4f;
return TYPE_COLORS[m.type] || 0xcccccc;
}
```
## Sidebar de controles (Code City)
```html
<aside id="sidebar">
<h3>Code City</h3>
<label>Altura (LOC)
<input type="range" min="0.1" max="2.0" step="0.1" value="0.4" data-param="locScale">
</label>
<label>Base (complexidade)
<input type="range" min="0.2" max="2.0" step="0.1" value="0.8" data-param="complexityScale">
</label>
<label>Threshold de hot path
<input type="range" min="0" max="100" step="5" value="50" data-param="hotPathThreshold">
</label>
<label>
<input type="checkbox" data-param="showLabels" checked> Labels visíveis
</label>
<label>
<input type="checkbox" data-param="showDistricts" checked> Mostrar distritos
</label>
<label>Filtrar pasta
<select data-param="folderFilter">
<option value="all">Todas</option>
<!-- POPULATED_FROM_DATA -->
</select>
</label>
<button id="reset">Reset</button>
<button id="export-png">Exportar PNG</button>
</aside>
```
Quando um slider muda, recalcular `m.height`, `m.w`, `m.d` e atualizar a `InstancedMesh` com novas matrizes.
## Interação
- **Hover em prédio**: tooltip mostra nome do arquivo, LOC, complexidade, pasta.
- **Clique em prédio**: foca câmera no prédio (anima `controls.target` para a posição do prédio).
- **Drag em distrito**: rotaciona câmera com OrbitControls.
- **Scroll**: zoom in/out.
## Performance
- Até **5.000 prédios** é seguro com InstancedMesh.
- Acima disso, agrupar arquivos por pasta (um prédio = uma pasta com altura agregada de LOC, área pelo número de arquivos).
- Desativar sombras se o framerate cair abaixo de 30fps (detectar via `requestAnimationFrame` timer).
## Variantes opcionais
- **Code City temporal**: animar crescimento ao longo do histórico do projeto (cada commit faz prédios crescerem).
- **Code City colorida por autor**: cores indicam quem é o maintainer principal de cada arquivo.
- **Code City com chuva**: hot paths recebem efeito de partículas vermelhas caindo, indicando "instabilidade".
Estas variantes ficam para versões futuras da skill.
+240
agents/reversa-arq...ra-3d/references/DEPENDENCY_GRAPH_3D.md
# Dependency Graph 3D
Grafo orientado de dependências entre módulos visualizado em 3D, com simulação de forças (atração entre nós conectados, repulsão entre não conectados) que distribui o grafo no espaço de forma orgânica.
## Mapeamento
| Atributo do código | Atributo visual do nó |
|---|---|
| Módulo | Esfera ou ícone |
| Tamanho (LOC ou número de dependentes) | Raio da esfera |
| Tipo do módulo | Cor |
| Pasta | Cor secundária ou cluster próximo |
| Aresta = `imports/requires` | Linha curva orientada (com seta) |
| Peso da aresta (frequência de uso) | Espessura da linha |
## Quando usar
- Detectar **acoplamento alto** (nós muito conectados ficam no centro do cluster).
- Identificar **módulos centrais** (alto fan-in) e **módulos isolados**.
- Visualizar **ciclos de dependência** (loops visíveis na simulação).
- Comparar coesão entre pastas (módulos da mesma pasta deveriam estar próximos).
**Quando evitar**: projetos com mais de ~300 módulos, onde o grafo vira hairball ilegível. Use Code City ou agrupe por pasta.
## Algoritmo de layout: força em 3D
Simulação tipo D3-force adaptada para 3 dimensões. Roda em loop até estabilizar, depois congela.
```javascript
const nodes = deps.nodes.map((n) => ({
id: n.id,
x: (Math.random() - 0.5) * 200,
y: (Math.random() - 0.5) * 200,
z: (Math.random() - 0.5) * 200,
vx: 0, vy: 0, vz: 0,
fx: 0, fy: 0, fz: 0,
mass: 1 + (n.loc ?? 0) / 100
}));
const edges = deps.edges.map((e) => ({
source: nodes.find((n) => n.id === e.from),
target: nodes.find((n) => n.id === e.to),
weight: e.weight ?? 1
}));
const REPULSION = 800;
const ATTRACTION = 0.04;
const CENTER_GRAVITY = 0.002;
const DAMPING = 0.85;
function simulationStep() {
nodes.forEach((n) => { n.fx = 0; n.fy = 0; n.fz = 0; });
// Repulsão entre todos os pares
for (let i = 0; i < nodes.length; i++) {
for (let j = i + 1; j < nodes.length; j++) {
const a = nodes[i], b = nodes[j];
const dx = b.x - a.x, dy = b.y - a.y, dz = b.z - a.z;
const distSq = dx * dx + dy * dy + dz * dz + 0.1;
const dist = Math.sqrt(distSq);
const force = REPULSION / distSq;
const fx = (dx / dist) * force;
const fy = (dy / dist) * force;
const fz = (dz / dist) * force;
a.fx -= fx; a.fy -= fy; a.fz -= fz;
b.fx += fx; b.fy += fy; b.fz += fz;
}
}
// Atração ao longo das arestas
edges.forEach((e) => {
const dx = e.target.x - e.source.x;
const dy = e.target.y - e.source.y;
const dz = e.target.z - e.source.z;
const f = ATTRACTION * e.weight;
e.source.fx += dx * f; e.source.fy += dy * f; e.source.fz += dz * f;
e.target.fx -= dx * f; e.target.fy -= dy * f; e.target.fz -= dz * f;
});
// Gravidade para o centro
nodes.forEach((n) => {
n.fx -= n.x * CENTER_GRAVITY;
n.fy -= n.y * CENTER_GRAVITY;
n.fz -= n.z * CENTER_GRAVITY;
});
// Integrar
nodes.forEach((n) => {
n.vx = (n.vx + n.fx / n.mass) * DAMPING;
n.vy = (n.vy + n.fy / n.mass) * DAMPING;
n.vz = (n.vz + n.fz / n.mass) * DAMPING;
n.x += n.vx;
n.y += n.vy;
n.z += n.vz;
});
}
```
Para grafos grandes (>200 nós), substituir repulsão O(n²) por **octree (Barnes-Hut)** para reduzir a O(n log n).
## Renderização dos nós
Usar `InstancedMesh` de esferas para até 1.000 nós; acima disso, billboard com sprites.
```javascript
const sphereGeo = new THREE.SphereGeometry(1, 16, 16);
const sphereMat = new THREE.MeshStandardMaterial({ roughness: 0.4 });
const nodeMesh = new THREE.InstancedMesh(sphereGeo, sphereMat, nodes.length);
nodeMesh.castShadow = true;
const dummy = new THREE.Object3D();
const color = new THREE.Color();
function updateNodes() {
nodes.forEach((n, i) => {
dummy.position.set(n.x, n.y, n.z);
const radius = 1 + Math.sqrt(n.mass) * 0.5;
dummy.scale.set(radius, radius, radius);
dummy.updateMatrix();
nodeMesh.setMatrixAt(i, dummy.matrix);
color.set(colorForNode(n));
nodeMesh.setColorAt(i, color);
});
nodeMesh.instanceMatrix.needsUpdate = true;
nodeMesh.instanceColor.needsUpdate = true;
}
```
## Renderização das arestas
Linhas curvas em 3D usando `BufferGeometry` com `LineSegments` ou `TubeGeometry` para arestas com volume.
```javascript
const edgePositions = new Float32Array(edges.length * 6);
const edgeGeo = new THREE.BufferGeometry();
edgeGeo.setAttribute("position", new THREE.BufferAttribute(edgePositions, 3));
const edgeMat = new THREE.LineBasicMaterial({ color: 0x4a9eff, transparent: true, opacity: 0.4 });
const edgeLines = new THREE.LineSegments(edgeGeo, edgeMat);
scene.add(edgeLines);
function updateEdges() {
edges.forEach((e, i) => {
edgePositions[i * 6 + 0] = e.source.x;
edgePositions[i * 6 + 1] = e.source.y;
edgePositions[i * 6 + 2] = e.source.z;
edgePositions[i * 6 + 3] = e.target.x;
edgePositions[i * 6 + 4] = e.target.y;
edgePositions[i * 6 + 5] = e.target.z;
});
edgeGeo.attributes.position.needsUpdate = true;
}
```
Para arestas orientadas com seta visível, usar `ArrowHelper` ou pequenos cones próximos ao target.
## Loop de simulação + renderização
```javascript
let frame = 0;
const MAX_SIM_FRAMES = 400; // estabiliza após ~7s em 60fps
function tick() {
if (frame < MAX_SIM_FRAMES) {
simulationStep();
updateNodes();
updateEdges();
frame++;
}
controls.update();
renderer.render(scene, camera);
requestAnimationFrame(tick);
}
```
Depois de estabilizar, manter renderização mas pausar simulação para economizar CPU.
## Detecção de ciclos
Rodar Tarjan ou Kosaraju antes de renderizar; nós que pertencem a ciclos recebem cor especial (laranja) e suas arestas viram vermelhas.
```javascript
const cycles = findStronglyConnectedComponents(nodes, edges).filter((c) => c.length > 1);
cycles.flat().forEach((n) => n.inCycle = true);
edges.forEach((e) => {
e.inCycle = e.source.inCycle && e.target.inCycle;
});
```
## Sidebar de controles
```html
<aside id="sidebar">
<h3>Dependency Graph 3D</h3>
<label>Repulsão
<input type="range" min="100" max="2000" value="800" data-param="repulsion">
</label>
<label>Atração
<input type="range" min="0.01" max="0.2" step="0.01" value="0.04" data-param="attraction">
</label>
<label>Filtrar por pasta
<select data-param="folderFilter">
<option value="all">Todas</option>
</select>
</label>
<label>
<input type="checkbox" data-param="highlightCycles" checked> Destacar ciclos
</label>
<label>
<input type="checkbox" data-param="showLabels"> Labels visíveis
</label>
<button id="reset">Reset</button>
<button id="freeze">Congelar simulação</button>
<button id="export-png">Exportar PNG</button>
</aside>
```
Mudanças nos sliders reativam a simulação por mais 100 frames antes de congelar novamente.
## Interação
- **Hover em nó**: tooltip com nome, número de dependentes (fan-in), dependências (fan-out).
- **Clique em nó**: destaca o nó e suas arestas conectadas, desfoca os demais (opacity reduzida).
- **Duplo clique em nó**: foca câmera no nó.
- **Scroll**: zoom.
## Performance
| Nós | Estratégia |
|---|---|
| < 50 | Esferas individuais com `add()` |
| 50 a 500 | InstancedMesh + repulsão O(n²) |
| 500 a 2.000 | InstancedMesh + Barnes-Hut octree |
| > 2.000 | Agrupar por pasta antes (cada cluster = um meta-nó) |
Arestas: até **10.000** com LineSegments. Acima disso, simplificar (mostrar só as top N por peso) ou usar gradient de cor em vez de duplicar geometria.
+286
agents/reversa-arquitetura-3d/references/ERRORS.md
# Cenários de Erro e Tratamento
Catálogo de erros comuns na skill `arquitetura-3d` e como tratá-los para preservar a experiência do usuário.
---
## ERR-01: Three.js indisponível (CDN inacessível)
**Causa**: usuário está offline na primeira execução, ou CDN bloqueado por firewall corporativo.
**Detecção**: o script `<script type="module">` falha ao importar, ou `THREE` fica `undefined` após o carregamento.
**Tratamento**:
```javascript
try {
const mod = await import("https://cdn.jsdelivr.net/npm/three@0.158.0/build/three.module.js");
window.THREE = mod;
} catch (e) {
document.getElementById("loader").innerHTML = `
<div class="error-panel">
<h2>Não foi possível carregar a biblioteca 3D</h2>
<p>Esta visualização requer acesso à internet para baixar o Three.js uma vez.
Conecte-se à internet e recarregue a página.</p>
<p>Detalhe técnico: ${e.message}</p>
</div>`;
return;
}
```
Texto sempre em pt-br, sem travessão.
---
## ERR-02: WebGL não suportado
**Causa**: browser sem WebGL (raríssimo hoje, mas possível em VMs antigas ou ambientes corporativos restritos).
**Detecção**: `new THREE.WebGLRenderer()` lança exceção ou retorna `null`.
**Tratamento**:
```javascript
let renderer;
try {
renderer = new THREE.WebGLRenderer({ antialias: true });
} catch (e) {
showFallback("WebGL não está disponível no seu browser. Use Chrome, Firefox ou Edge atualizados.");
return;
}
```
Fallback exibe uma versão estática da cena (screenshot pré-renderizado se houver, ou ASCII art simbólico) com mensagem clara.
---
## ERR-03: JSON malformado
**Causa**: `modules.json` ou `deps.json` com sintaxe inválida, ou campos esperados ausentes.
**Detecção**: `JSON.parse` falha, ou validação de schema indica campos ausentes.
**Tratamento**:
```javascript
function loadData() {
const raw = document.getElementById("data").textContent;
let data;
try {
data = JSON.parse(raw);
} catch (e) {
showError("Dados de entrada inválidos: arquivo JSON malformado. " + e.message);
return null;
}
if (!Array.isArray(data.modules)) {
showError("Dados de entrada inválidos: 'modules' deve ser uma lista.");
return null;
}
data.modules = data.modules.filter((m) => {
if (!m.name) {
console.warn("Módulo sem 'name' descartado:", m);
return false;
}
return true;
});
return data;
}
```
Erros não-fatais (módulo individual ruim) descartam o item com aviso. Erros fatais (estrutura raiz inválida) mostram mensagem clara.
---
## ERR-04: Projeto vazio ou sem dados visualizáveis
**Causa**: `modules.json` tem 0 itens, ou `deps.json` tem 0 arestas, ou ambos.
**Detecção**: após `loadData()`, contagem dos itens.
**Tratamento**:
```javascript
if (data.modules.length === 0) {
showEmptyState({
title: "Nada para visualizar ainda",
message: "O projeto não tem módulos detectados. Rode `/reversa` para extrair a estrutura primeiro.",
actions: [
{ label: "Voltar à documentação", href: "index.html" }
]
});
return;
}
```
Empty state amigável, nunca cena vazia silenciosa.
---
## ERR-05: Projeto muito grande (>5.000 módulos sem agrupamento)
**Causa**: o usuário força modo Code City sem agrupamento em um projeto enorme.
**Detecção**: `data.modules.length > 5000` e nenhuma estratégia de agrupamento ativada.
**Tratamento**: aplicar agrupamento automaticamente e avisar.
```javascript
if (data.modules.length > 5000) {
showToast("Projeto grande detectado (" + data.modules.length + " arquivos). Agrupando por pasta para manter performance.");
data.modules = groupByFolder(data.modules);
config.grouped = true;
}
```
O agrupamento e seu impacto aparecem no rodapé permanente da página: "Visualização agrupada por pasta. Cada bloco representa N arquivos."
---
## ERR-06: Performance degradada (fps < 30)
**Causa**: hardware fraco, projeto no limite superior, sombras pesadas.
**Detecção**: medir `requestAnimationFrame` delta.
```javascript
let frameTimes = [];
function measureFps(time) {
frameTimes.push(time);
if (frameTimes.length > 60) frameTimes.shift();
if (frameTimes.length === 60) {
const fps = 1000 / ((frameTimes[59] - frameTimes[0]) / 59);
if (fps < 30 && !config.degraded) {
degradeQuality();
}
}
}
```
**Tratamento progressivo** (`degradeQuality`):
1. Desativar sombras.
2. Reduzir pixelRatio para 1.
3. Reduzir contagem de partículas em tours.
4. Mostrar toast "Modo de performance ativado".
---
## ERR-07: InstancedMesh limit excedido
**Causa**: tentativa de criar InstancedMesh com mais instâncias do que o hardware suporta (limite de ~65k em hardwares antigos via Uint16, mas raro).
**Detecção**: console error do Three.js após `setMatrixAt` para índices altos.
**Tratamento**:
```javascript
const MAX_INSTANCES = 32768;
if (modules.length > MAX_INSTANCES) {
showWarning("Limite de instâncias excedido. Mostrando apenas os " + MAX_INSTANCES + " maiores.");
modules = modules.sort((a, b) => b.loc - a.loc).slice(0, MAX_INSTANCES);
}
```
---
## ERR-08: Ciclo de dependências infinito durante layout
**Causa**: grafo com ciclo fechado e layout iterativo sem critério de parada.
**Detecção**: medir iterações de simulação; se passar `MAX_SIM_FRAMES` sem convergir, abortar.
**Tratamento**: parar simulação no frame limite, mostrar aviso "Layout não convergiu, posições podem não refletir estabilidade ideal", desenhar mesmo assim.
---
## ERR-09: WebGL context lost
**Causa**: aba inativa por muito tempo, troca de driver gráfico, GPU sobrecarregada.
**Detecção**: evento `webglcontextlost` no canvas.
**Tratamento**:
```javascript
renderer.domElement.addEventListener("webglcontextlost", (e) => {
e.preventDefault();
showToast("Contexto 3D foi perdido. Tentando recuperar...");
});
renderer.domElement.addEventListener("webglcontextrestored", () => {
rebuildScene();
showToast("Contexto recuperado.");
});
```
Em vez de recarregar a página, reconstruir a cena no mesmo canvas. Importante chamar `rebuildScene()` que recria texturas e buffers.
---
## ERR-10: Sidebar localStorage corrompido
**Causa**: dados antigos de localStorage com formato incompatível após atualização da skill.
**Detecção**: `JSON.parse` falha ao restaurar estado, ou valor está fora do range esperado de um slider.
**Tratamento**: silencioso, descarta e usa default.
```javascript
function loadSliderState(slider) {
try {
const saved = localStorage.getItem(`arq3d.${slider.dataset.param}`);
if (saved !== null) {
const value = parseFloat(saved);
if (value >= slider.min && value <= slider.max) {
slider.value = value;
}
}
} catch (e) {
// ignora e mantém valor padrão
}
}
```
---
## Função utilitária: showError + showWarning + showToast
```javascript
function showError(message) {
const panel = document.createElement("div");
panel.className = "reversa-error-panel";
panel.innerHTML = `<h2>Erro</h2><p>${escapeHtml(message)}</p>`;
document.body.appendChild(panel);
}
function showWarning(message) {
const panel = document.createElement("div");
panel.className = "reversa-warning-banner";
panel.textContent = message;
document.body.appendChild(panel);
setTimeout(() => panel.remove(), 8000);
}
function showToast(message) {
const t = document.createElement("div");
t.className = "reversa-toast";
t.textContent = message;
document.body.appendChild(t);
setTimeout(() => t.remove(), 4000);
}
function escapeHtml(s) {
return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
}
```
Estilos `reversa-error-panel`, `reversa-warning-banner`, `reversa-toast` ficam no CSS compartilhado do mini-site.
---
## Princípio geral
Nenhum erro deve resultar em **tela branca silenciosa**. Sempre mostrar mensagem clara em pt-br com instrução acionável ou indicação clara de limitação. Mensagens curtas, sem jargão de framework, sem travessão.
+230
agents/reversa-arquitetura-3d/references/LAYER_STACK.md
# Layer Stack 3D
Visualização de **camadas arquiteturais** empilhadas verticalmente, cada camada como um plano com seus módulos, conectadas por setas verticais que mostram o fluxo de dependências entre camadas.
## Mapeamento
| Conceito arquitetural | Visual |
|---|---|
| Camada (UI, Domain, Infra, etc) | Plano horizontal em altura distinta |
| Módulo dentro da camada | Caixa/disco posicionado no plano da camada |
| Dependência inter-camada | Linha vertical orientada conectando módulos |
| Direção do fluxo | Seta na ponta da linha |
| Violação de camada (camada de baixo importando de cima) | Linha vermelha pulsante |
## Quando usar
- Validar que a arquitetura segue Clean Architecture, Hexagonal, ou Onion.
- Detectar **violações de camada** (UI importando direto de Infra, por exemplo).
- Apresentar o sistema para stakeholders que pensam em camadas.
- Comparar com o diagrama arquitetural esperado lado a lado.
**Quando evitar**: sistemas sem separação clara de camadas (monolitos planos). Use Code City.
## Detecção de camadas
A skill aceita o mapeamento de camadas vindo do usuário (via JSON) ou tenta inferir de padrões de pasta.
**Mapeamento explícito**:
```json
{
"layers": [
{ "name": "UI", "order": 0, "folders": ["src/components", "src/pages"] },
{ "name": "Application", "order": 1, "folders": ["src/services", "src/use-cases"] },
{ "name": "Domain", "order": 2, "folders": ["src/domain", "src/entities"] },
{ "name": "Infrastructure", "order": 3, "folders": ["src/db", "src/external"] }
]
}
```
**Inferência heurística** (quando não fornecido): regex sobre nomes de pasta.
```javascript
const LAYER_PATTERNS = [
{ name: "UI", regex: /(components|pages|views|screens|ui)/i, order: 0 },
{ name: "Application", regex: /(services|use-cases|application|handlers)/i, order: 1 },
{ name: "Domain", regex: /(domain|entities|models|business)/i, order: 2 },
{ name: "Infrastructure", regex: /(db|database|repositories|external|infra|adapters)/i, order: 3 }
];
function inferLayer(folder) {
for (const p of LAYER_PATTERNS) {
if (p.regex.test(folder)) return p;
}
return { name: "Outros", order: 999 };
}
```
## Algoritmo de layout
### 1. Empilhar camadas verticalmente
```javascript
const LAYER_GAP = 80;
const LAYER_SIZE = 400; // plano 400x400
const layerPlanes = layers.map((layer, i) => ({
name: layer.name,
y: i * LAYER_GAP,
modules: modules.filter((m) => belongsToLayer(m, layer))
}));
```
### 2. Posicionar módulos dentro da camada
Empacotamento simples em grid 2D no plano da camada.
```javascript
layerPlanes.forEach((layer) => {
const cols = Math.ceil(Math.sqrt(layer.modules.length));
const cellSize = LAYER_SIZE / cols;
layer.modules.forEach((m, idx) => {
const col = idx % cols;
const row = Math.floor(idx / cols);
m.x = (col - cols / 2) * cellSize;
m.y = layer.y;
m.z = (row - cols / 2) * cellSize;
});
});
```
### 3. Renderizar planos de camada
```javascript
layerPlanes.forEach((layer, i) => {
const planeGeo = new THREE.PlaneGeometry(LAYER_SIZE, LAYER_SIZE);
const planeMat = new THREE.MeshStandardMaterial({
color: LAYER_COLORS[i % LAYER_COLORS.length],
transparent: true,
opacity: 0.15,
side: THREE.DoubleSide
});
const plane = new THREE.Mesh(planeGeo, planeMat);
plane.rotation.x = Math.PI / 2;
plane.position.y = layer.y;
scene.add(plane);
// Label da camada lateral
const label = addLabel(layer.name, new THREE.Vector3(LAYER_SIZE / 2 + 20, layer.y, 0));
scene.add(label);
});
const LAYER_COLORS = [0x4a9eff, 0x6cc46c, 0xffc857, 0xb39ddb, 0xff9aa2];
```
### 4. Renderizar módulos como discos
```javascript
const moduleGeo = new THREE.CylinderGeometry(1, 1, 0.5, 16);
const moduleMat = new THREE.MeshStandardMaterial({ roughness: 0.5 });
const modulesMesh = new THREE.InstancedMesh(moduleGeo, moduleMat, modules.length);
modules.forEach((m, i) => {
const dummy = new THREE.Object3D();
const size = 1 + Math.sqrt(m.loc / 100);
dummy.position.set(m.x, m.y, m.z);
dummy.scale.set(size, 1, size);
dummy.updateMatrix();
modulesMesh.setMatrixAt(i, dummy.matrix);
});
modulesMesh.instanceMatrix.needsUpdate = true;
scene.add(modulesMesh);
```
### 5. Renderizar dependências como linhas verticais
```javascript
edges.forEach((e) => {
const src = modules.find((m) => m.name === e.from);
const dst = modules.find((m) => m.name === e.to);
if (!src || !dst) return;
const isViolation = isLayerViolation(src, dst);
const color = isViolation ? 0xff5a4f : 0x6c8eb0;
const points = [
new THREE.Vector3(src.x, src.y, src.z),
new THREE.Vector3(dst.x, dst.y, dst.z)
];
const geo = new THREE.BufferGeometry().setFromPoints(points);
const mat = new THREE.LineBasicMaterial({
color,
transparent: true,
opacity: isViolation ? 1.0 : 0.4
});
const line = new THREE.Line(geo, mat);
if (isViolation) line.userData.pulse = true; // anima opacidade
scene.add(line);
});
```
### 6. Detecção de violação de camada
A regra padrão (Clean Architecture): camadas só dependem de camadas com `order` maior (mais para "dentro").
```javascript
function isLayerViolation(src, dst) {
return src.layerOrder > dst.layerOrder;
}
```
Pode haver exceções configuráveis (ex: ports/adapters em hexagonal).
## Animação de violações
Linhas vermelhas pulsam (opacity oscilando) para chamar atenção.
```javascript
function pulseViolations(time) {
scene.traverse((obj) => {
if (obj.userData?.pulse) {
obj.material.opacity = 0.5 + 0.5 * Math.sin(time * 0.003);
}
});
}
```
## Sidebar de controles
```html
<aside id="sidebar">
<h3>Layer Stack</h3>
<label>Espaçamento entre camadas
<input type="range" min="40" max="200" value="80" data-param="layerGap">
</label>
<label>
<input type="checkbox" data-param="showViolations" checked> Destacar violações
</label>
<label>
<input type="checkbox" data-param="showLabels" checked> Labels de módulo
</label>
<label>Mostrar apenas
<select data-param="layerFilter">
<option value="all">Todas as camadas</option>
<!-- POPULATED -->
</select>
</label>
<div id="violations-count"></div>
<button id="reset">Reset</button>
<button id="export-png">Exportar PNG</button>
</aside>
```
O contador `#violations-count` mostra em tempo real "X violações detectadas".
## Interação
- **Hover em módulo**: tooltip com nome, camada, dependências.
- **Clique em violação**: foca câmera nos dois módulos envolvidos e mostra detalhes da relação no painel.
- **Filtro de camada**: oculta camadas não selecionadas.
## Performance
Camadas tipicamente têm dezenas a poucas centenas de módulos cada. Limite total de ~2.000 módulos. Acima disso, agrupar por pasta dentro de cada camada.
+221
agents/reversa-arquitetura-3d/references/THREE_PATTERNS.md
# Padrões Three.js para Visualização de Arquitetura
Referência rápida de setup, materiais e técnicas comuns a todos os modos da skill. Three.js v0.158+, ESM via CDN.
---
## Setup base da cena
```javascript
import * as THREE from "https://cdn.jsdelivr.net/npm/three@0.158.0/build/three.module.js";
import { OrbitControls } from "https://cdn.jsdelivr.net/npm/three@0.158.0/examples/jsm/controls/OrbitControls.js";
const container = document.getElementById("scene-container");
const width = container.clientWidth;
const height = container.clientHeight;
// Cena
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x0a0a14);
scene.fog = new THREE.Fog(0x0a0a14, 100, 800);
// Câmera
const camera = new THREE.PerspectiveCamera(50, width / height, 0.1, 2000);
camera.position.set(150, 200, 300);
camera.lookAt(0, 0, 0);
// Renderer
const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.setSize(width, height);
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
container.appendChild(renderer.domElement);
// Controles
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.dampingFactor = 0.08;
controls.minDistance = 20;
controls.maxDistance = 1500;
```
## Iluminação padrão
```javascript
// Luz ambiente leve para não ter sombras totalmente pretas
const ambient = new THREE.AmbientLight(0xffffff, 0.35);
scene.add(ambient);
// Hemisfério: céu vs chão, dá profundidade natural
const hemi = new THREE.HemisphereLight(0xddeeff, 0x202028, 0.5);
hemi.position.set(0, 200, 0);
scene.add(hemi);
// Direcional: simula sol, projeta sombras
const dir = new THREE.DirectionalLight(0xffffff, 0.85);
dir.position.set(80, 200, 100);
dir.castShadow = true;
dir.shadow.mapSize.set(2048, 2048);
dir.shadow.camera.left = -400;
dir.shadow.camera.right = 400;
dir.shadow.camera.top = 400;
dir.shadow.camera.bottom = -400;
scene.add(dir);
```
## Loop de renderização
```javascript
function tick() {
controls.update();
renderer.render(scene, camera);
requestAnimationFrame(tick);
}
tick();
```
## Handler de resize
```javascript
window.addEventListener("resize", () => {
const w = container.clientWidth;
const h = container.clientHeight;
camera.aspect = w / h;
camera.updateProjectionMatrix();
renderer.setSize(w, h);
});
```
## InstancedMesh para grandes volumes
Quando há mais de 200 elementos do mesmo tipo (prédios do Code City, nós do dep graph), usar `InstancedMesh` em vez de loop com `add()`.
```javascript
const boxGeo = new THREE.BoxGeometry(1, 1, 1);
const mat = new THREE.MeshStandardMaterial({ color: 0xffffff });
const instanced = new THREE.InstancedMesh(boxGeo, mat, modules.length);
const dummy = new THREE.Object3D();
const colorObj = new THREE.Color();
modules.forEach((m, i) => {
dummy.position.set(m.x, m.height / 2, m.z);
dummy.scale.set(m.w, m.height, m.d);
dummy.updateMatrix();
instanced.setMatrixAt(i, dummy.matrix);
colorObj.set(m.color);
instanced.setColorAt(i, colorObj);
});
instanced.instanceMatrix.needsUpdate = true;
if (instanced.instanceColor) instanced.instanceColor.needsUpdate = true;
scene.add(instanced);
```
## Labels em CSS2D (legíveis sempre)
```javascript
import { CSS2DRenderer, CSS2DObject } from "https://cdn.jsdelivr.net/npm/three@0.158.0/examples/jsm/renderers/CSS2DRenderer.js";
const labelRenderer = new CSS2DRenderer();
labelRenderer.setSize(width, height);
labelRenderer.domElement.style.position = "absolute";
labelRenderer.domElement.style.top = "0";
labelRenderer.domElement.style.pointerEvents = "none";
container.appendChild(labelRenderer.domElement);
function addLabel(text, position) {
const div = document.createElement("div");
div.className = "label-3d";
div.textContent = text;
const label = new CSS2DObject(div);
label.position.copy(position);
return label;
}
```
No `tick()`, chamar `labelRenderer.render(scene, camera)` junto com o renderer principal.
**Regra**: mostrar labels apenas quando o nó está próximo da câmera (distância < threshold) ou em hover, para evitar poluição.
## Raycaster para hover e clique
```javascript
const raycaster = new THREE.Raycaster();
const pointer = new THREE.Vector2();
renderer.domElement.addEventListener("pointermove", (e) => {
const rect = renderer.domElement.getBoundingClientRect();
pointer.x = ((e.clientX - rect.left) / rect.width) * 2 - 1;
pointer.y = -((e.clientY - rect.top) / rect.height) * 2 + 1;
raycaster.setFromCamera(pointer, camera);
const hits = raycaster.intersectObject(instanced);
if (hits.length > 0) {
const i = hits[0].instanceId;
showTooltip(modules[i]);
} else {
hideTooltip();
}
});
```
## Sidebar reativa
```javascript
const sliders = document.querySelectorAll("aside input[type=range]");
sliders.forEach((slider) => {
slider.addEventListener("input", (e) => {
const param = e.target.dataset.param;
const value = parseFloat(e.target.value);
applyParam(param, value); // função específica do modo
localStorage.setItem(`arq3d.${param}`, value);
});
// restore
const saved = localStorage.getItem(`arq3d.${slider.dataset.param}`);
if (saved !== null) {
slider.value = saved;
slider.dispatchEvent(new Event("input"));
}
});
```
## Exportar PNG
```javascript
document.getElementById("export-png").addEventListener("click", () => {
renderer.render(scene, camera); // garantir frame atual
renderer.domElement.toBlob((blob) => {
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "arquitetura-3d.png";
a.click();
URL.revokeObjectURL(url);
});
});
```
## Dispose ao trocar de modo
```javascript
function clearScene() {
scene.traverse((obj) => {
if (obj.geometry) obj.geometry.dispose();
if (obj.material) {
if (Array.isArray(obj.material)) obj.material.forEach((m) => m.dispose());
else obj.material.dispose();
}
});
while (scene.children.length > 0) scene.remove(scene.children[0]);
}
```
## Performance: limites práticos
| Cenário | Limite seguro | Acima disso |
|---|---|---|
| BoxGeometry independentes | 200 | Migrar para InstancedMesh |
| InstancedMesh de cubos | 5.000 | Aplicar agrupamento por pasta |
| Linhas (LineSegments) | 10.000 segmentos | Usar Line2 (fat lines) ou agrupar |
| Sprites/labels CSS2D | 100 visíveis | Mostrar só sob hover ou proximidade |
| Polígonos texturizados | 50.000 tris | Reduzir LOD ou desativar sombras |
+168
agents/reversa-arquitetura-3d/SKILL.md
---
name: reversa-arquitetura-3d
description: >
Cria visualizações 3D interativas de arquitetura de software usando Three.js, gerando
HTML standalone com cenas navegáveis por câmera livre. Use esta skill sempre que o
usuário pedir para visualizar arquitetura, módulos, dependências, camadas ou hierarquia
de chamadas em 3D. Deve ser ativada quando o usuário mencionar termos como "code city",
"cidade de código", "arquitetura 3D", "dependency graph 3D", "module map 3D", "layer
stack 3D", "call graph 3D", "architecture tour", "tour pela arquitetura", "visualizar
software em 3D", "Three.js" no contexto de software, ou pedir para explorar a estrutura
de um sistema com câmera 3D. Funciona com JSON de módulos (nome, pasta, LOC, complexidade)
e dependências (grafo orientado). Sempre gera HTML standalone completo com Three.js via CDN.
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/documentation/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`**:
```json
[
{
"name": "src/auth/login.ts",
"folder": "src/auth",
"loc": 142,
"complexity": 8,
"type": "code"
}
]
```
**Schema esperado de `deps.json`** (orientado):
```json
{
"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">`).
2. **Three.js via CDN**: usar `https://cdnjs.cloudflare.com/ajax/libs/three.js/r158/three.min.js` (versão estável recente).
3. **OrbitControls via CDN**: `https://cdn.jsdelivr.net/npm/three@0.158.0/examples/jsm/controls/OrbitControls.js`.
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
```html
<!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="https://cdnjs.cloudflare.com/ajax/libs/three.js/r158/three.min.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 type="module">
import { OrbitControls } from "https://cdn.jsdelivr.net/npm/three@0.158.0/examples/jsm/controls/OrbitControls.js";
// 1. Carregar dados
// 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/documentation/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 via CDN**: 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).
+159
agents/reversa-docs-analyst/SKILL.md
---
name: reversa-docs-analyst
description: "Analista do Time Reversa Docs. Produz as páginas de dados quantitativos do mini-site: dashboard de métricas com Highcharts (treemap LOC, barras complexidade, sankey dependências, histograma) e timeline interativa de eventos do projeto. Ative com /reversa-docs-analyst, reversa-docs-analyst, regenerar métricas, refazer timeline, dashboard do projeto."
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: documentation
phase: quantitative-data
role: analyst
---
Você é o Analyst do Time Reversa Docs. Traduz dados quantitativos do código (LOC, complexidade, dependências) e do histórico (eventos do chronicle) em visualizações estatísticas claras. Números bem-apresentados contam mais história que parágrafos.
## Posicionamento
Segundo agente do pipeline `/reversa-docs`. Reusa os JSONs intermediários do Mapper (`modules.json`, `deps.json`). Em invocação isolada, detecta ausência e roda extração mínima usando os mesmos scripts do Mapper.
## Inputs
- `.reversa/documentation/assets/data/modules.json` (do Mapper, ou extrai sob demanda)
- `.reversa/documentation/assets/data/deps.json`
- `.reversa/chronicle.md` (histórico, se existir)
- `.reversa/documentation/.config.json`
- Skill: `reversa-highcharts-visualizer`
## Outputs
- `.reversa/documentation/metricas.html` (dashboard 4+ gráficos)
- `.reversa/documentation/timeline.html` (omitida se chronicle ausente)
- `.reversa/documentation/assets/data/metrics.json`
- `.reversa/documentation/assets/data/timeline.json` (apenas se chronicle existir)
## Antes de começar
1. Leia `.reversa/state.json` para `user_name`, `chat_language`.
2. Leia `.reversa/documentation/.config.json`. Se ausente, conduza entrevista mínima.
3. Verifique presença de `modules.json` e `deps.json`. Se ausentes, invoque os scripts do Mapper para gerá-los (`extract_modules.py`, `extract_deps.py`). Política de cache em `agents/reversa-docs-mapper/references/extraction-policy.md`.
## Entrevista mínima
Pergunta única (estilo visual, mesma do orquestrador). Persiste em `.config.json`.
## Processo
### 1. Derivar `metrics.json`
Carregue `modules.json` e `deps.json`. Agregue:
```json
{
"schemaVersion": 1,
"generatedAt": "ISO-8601",
"treemap_loc_by_folder": [
{"folder": "src/auth", "loc": 4231, "modules": 12}
],
"top_complexity": [
{"id": "src/auth/login.py", "complexity": 24, "loc": 142}
],
"loc_histogram": {
"bins": [0, 50, 100, 200, 500, 1000, 5000],
"counts": [142, 87, 56, 23, 9, 3]
},
"dependency_sankey": {
"nodes": [{"id": "src/auth"}, {"id": "src/orders"}],
"links": [{"source": "src/auth", "target": "src/orders", "value": 7}]
},
"language_distribution": [
{"language": "python", "modules": 234, "loc": 18234}
]
}
```
Salve em `.reversa/documentation/assets/data/metrics.json`.
### 2. Gerar `metricas.html` (dashboard)
1. Carregue `metrics.json`.
2. Invoque a skill `reversa-highcharts-visualizer` para gerar 4 gráficos:
- **Treemap**: `treemap_loc_by_folder`
- **Column**: `top_complexity` (top 20)
- **Histogram**: `loc_histogram`
- **Sankey**: `dependency_sankey`
3. Adapte ao chassis `viewer.html`:
- Preencha marcadores padrão (TITLE = "Métricas", PAGE_ID = "metricas", REVERSA_CATEGORY = "diagram", REVERSA_PRODUCER_AGENT = "reversa-docs-analyst", REVERSA_TEMPLATE = "metricas", VISUAL_STYLE, GENERATED_AT).
- `<!-- HEAD_EXTRAS -->`: `<script src="https://code.highcharts.com/highcharts.js"></script>` + módulos treemap e sankey.
- Use `templates/documentation/pages/metricas.html.tpl` como guia de estrutura do PAYLOAD.
4. Layout responsivo em grid 2x2. Adicione 5º/6º gráficos se houver dados ricos (ex: `language_distribution`).
5. Salve em `.reversa/documentation/metricas.html`.
### 3. Derivar `timeline.json` (se chronicle existir)
1. Verifique se `.reversa/chronicle.md` existe.
2. Se ausente, **omita** timeline.html e registre em `pagesOmitted` com motivo "chronicle.md not found".
3. Se presente, invoque:
```
python templates/documentation/scripts/convert_chronicle.py \
--src .reversa/chronicle.md \
--out .reversa/documentation/assets/data/timeline.json
```
4. Se Python indisponível, faça parsing inline: cada item de bullet ou heading com data ISO-8601 vira um evento.
### 4. Gerar `timeline.html`
1. Carregue `timeline.json`.
2. Invoque `reversa-highcharts-visualizer` modo `timeline` (Highcharts Timeline).
3. Aplique o chassis usando `templates/documentation/pages/timeline.html.tpl`.
4. Adicione `<script src="https://code.highcharts.com/modules/timeline.js"></script>` em HEAD_EXTRAS.
5. Cada evento clicável abre painel lateral com detalhes (use `EVENT_DETAILS` marker).
6. Salve em `.reversa/documentation/timeline.html`.
### 5. Atualizar `.state.json`
- Adicione `analyst` ao array `completedAgents`.
- Registre páginas geradas em `pages` com hash sha256.
## Backup automático
`.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever.
## Diretiva non-destructive
Apenas escreve em `.reversa/documentation/`. `chronicle.md`, `modules.json`, `deps.json` são lidos sem modificação.
## Tratamento gracioso
| Fonte ausente | Comportamento |
|---|---|
| `modules.json`/`deps.json` (Mapper não rodou) | Invoca scripts de extração antes de seguir. |
| `chronicle.md` | Omite timeline.html, registra motivo em `pagesOmitted`. |
| Python indisponível | Faz parsing inline via Read + regex. |
| Skill `reversa-highcharts-visualizer` ausente | Aborta com mensagem clara indicando `npx reversa install`. |
## Encerramento
> "[Nome], **Analyst** terminou.
>
> Páginas geradas:
> - metricas.html ([X] gráficos, [Y] módulos analisados)
> [- timeline.html ([Z] eventos do chronicle) se gerada]
>
> Omissões: [lista]
> Tempo: [N]s
>
> [Se invocado isolado:] Próximo natural: `/reversa-docs-storyteller`, ou `/reversa-docs-publisher` para reintegrar o index.
>
> [Se invocado pelo orquestrador:] Próximo: **Storyteller** gera glossário, deck e páginas por feature.
>
> Digite **CONTINUAR** para prosseguir."
## Regras absolutas
- Nunca escreva fora de `.reversa/documentation/`.
- Nunca modifique chronicle.md ou os JSONs do Mapper.
- Nunca rode varredura de credenciais.
- Sempre backup antes de sobrescrever.
- Texto em pt-br, sem travessão.
+44
agents/reversa-docs-mapper/references/extraction-policy.md
# Política de extração de dados (Mapper)
Define quando invocar scripts de extração vs reusar cache em `.reversa/documentation/assets/data/`.
## Cache hit (reutilizar)
Use o JSON existente quando **todas** as condições forem verdadeiras:
1. O arquivo existe em `.reversa/documentation/assets/data/<nome>.json`.
2. `mtime` do JSON é maior que o `mtime` máximo entre todos os arquivos fonte relevantes:
- Para `modules.json`: maior `mtime` dentro do código fonte (excluindo `.reversa/`, `_reversa_sdd/`, `node_modules/`, `.git/`).
- Para `deps.json`: maior `mtime` do código fonte E do `modules.json`.
3. O `schemaVersion` do JSON é compatível com a versão atual (1).
## Cache miss (regenerar)
Em qualquer outro caso, invoque o script Python correspondente:
```bash
python templates/documentation/scripts/extract_modules.py \
--root . \
--out .reversa/documentation/assets/data/modules.json
python templates/documentation/scripts/extract_deps.py \
--modules .reversa/documentation/assets/data/modules.json \
--out .reversa/documentation/assets/data/deps.json
```
## Python indisponível
Faça extração inline na engine de IA:
1. Use Glob para listar arquivos por extensão (`*.py`, `*.js`, `*.ts`, `*.go`, `*.java`).
2. Use Read para contar linhas não-vazias de cada arquivo.
3. Monte estrutura idêntica ao schema `modules.json` (ver `specs/reversa-docs/design.md`).
4. Para `deps.json`, na falta de parser AST, comece com `nodes` populado e `edges: []`. Marque em `.config.json.pagesPlanned` que dependencies não foram extraídas.
## Forçar regeneração
Se o usuário passar `--force-extract` ao `/reversa-docs-mapper`, ignore o cache e regenere. Backup do JSON anterior em `.backup-<timestamp>/assets/data/`.
## Quando o Analyst invoca isolado
Se o `Analyst` rodar antes do Mapper ou em modo isolado e não encontrar `modules.json`/`deps.json`, ele deve invocar os **mesmos scripts** seguindo esta mesma política. O resultado é compartilhado: Mapper subsequente vai usar o cache.
+163
agents/reversa-docs-mapper/SKILL.md
---
name: reversa-docs-mapper
description: "Mapeador do Time Reversa Docs. Produz as páginas de estrutura espacial do mini-site: arquitetura 3D (Code City via Three.js), module map 2D (force-directed via D3), e topologia side-by-side (legado vs moderno vs híbrido). Ative com /reversa-docs-mapper, reversa-docs-mapper, regenerar arquitetura, refazer mapa de módulos, code city do projeto."
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: documentation
phase: spatial-structure
role: mapper
---
Você é o Mapper do Time Reversa Docs. Transforma o conhecimento extraído sobre módulos, dependências e topologia em visualizações 3D e 2D navegáveis. Sua missão é fazer o leitor entender em poucos segundos como o sistema está organizado fisicamente.
## Posicionamento
Primeiro agente do pipeline `/reversa-docs`. Pode ser invocado isolado para regenerar apenas suas páginas. Os JSONs intermediários que deixa em `assets/data/` são reusados pelo Analyst.
## Inputs
- `.reversa/documentation/.config.json` (entrevista, seed, estilo visual)
- Código fonte do projeto legado (LOC, complexidade, dependências)
- `_reversa_sdd/architecture.md` se houver (topologia detectada)
- Skills: `reversa-arquitetura-3d` (3D), `especialista-d3` (2D)
## Outputs
- `.reversa/documentation/arquitetura.html`
- `.reversa/documentation/modulos.html`
- `.reversa/documentation/topologia.html` (omitido se sem topologia detectada)
- `.reversa/documentation/assets/data/modules.json`
- `.reversa/documentation/assets/data/deps.json`
Schemas formais em `specs/reversa-docs/design.md`, seção "JSONs intermediários em assets/data/".
## Antes de começar
1. Leia `.reversa/state.json` para `user_name`, `chat_language`.
2. Leia `.reversa/documentation/.config.json`. Se não existir, conduza a entrevista mínima.
3. Verifique `templates/documentation/scripts/extract_modules.py` e `extract_deps.py` acessíveis.
## Entrevista mínima (apenas isolado e sem .config.json)
Pergunta única (estilo visual):
> "[Nome], qual estilo visual para o mapa?
>
> 1. **Sóbrio técnico** — Cinza, alto contraste. Padrão.
> 2. **Premium cinematográfico** — Tons escuros, hero animado.
> 3. **Denso com dados** — Layout compacto.
> 4. **Exploratório com 3D destacado** — Code City em destaque.
> 5. **Outro** — Descreva.
>
> Digite 1, 2, 3, 4 ou 5."
Cria `.config.json` mínimo com apenas `interview.visualStyle` preenchido.
## Processo
### 1. Extração de dados (com cache)
Leia `references/extraction-policy.md` para a política de cache. Resumo:
- Se `assets/data/modules.json` existe e é mais recente que `mtime` máximo do código fonte, **reuse**.
- Senão, invoque:
```
python templates/documentation/scripts/extract_modules.py \
--root . \
--out .reversa/documentation/assets/data/modules.json
```
- Mesmo para `deps.json`:
```
python templates/documentation/scripts/extract_deps.py \
--modules .reversa/documentation/assets/data/modules.json \
--out .reversa/documentation/assets/data/deps.json
```
Se Python não estiver disponível, gere os JSONs lendo o código fonte direto via Glob + Read e aplique a mesma estrutura definida nos schemas.
### 2. Gerar `arquitetura.html` (Code City 3D)
1. Carregue `modules.json` e `deps.json`.
2. Invoque a skill `reversa-arquitetura-3d` em modo `code-city` passando:
- `modules` (do JSON)
- `seed` (do `.config.json.seed.hash`)
- `palette` (derivada de `.config.json.interview.visualStyle`)
- `groupByFolder` (true se `modules.length > 500`)
3. A skill retorna HTML self-contained. Você precisa **adaptar para usar o chassis** `templates/documentation/viewer.html`:
- Preencha marcadores: `<!-- TITLE -->` = "Arquitetura 3D", `<!-- PAGE_ID -->` = "arquitetura", `<!-- REVERSA_CATEGORY -->` = "diagram", `<!-- REVERSA_PRODUCER_AGENT -->` = "reversa-docs-mapper", `<!-- REVERSA_TEMPLATE -->` = "arquitetura", `<!-- VISUAL_STYLE -->` = (valor do config), `<!-- GENERATED_AT -->` = ISO-8601 atual.
- Coloque o `<canvas>` e o `<script>` Three.js dentro de `<!-- PAYLOAD -->`.
- Coloque `<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r158/three.min.js"></script>` em `<!-- HEAD_EXTRAS -->`.
- Use o template `templates/documentation/pages/arquitetura.html.tpl` como referência de estrutura do PAYLOAD.
4. Adicione sidebar com `data-param` controlando: escala vertical, intensidade da luz, paleta. Use o helper `templates/documentation/assets/js/sidebar.js` (já incluso pelo viewer).
5. Salve em `.reversa/documentation/arquitetura.html`.
### 3. Gerar `modulos.html` (force-directed 2D)
1. Carregue `modules.json` e `deps.json`.
2. Invoque a skill `especialista-d3` em modo `force-directed` passando os mesmos dados.
3. Aplique o chassis `viewer.html` igual ao anterior, usando `templates/documentation/pages/modulos.html.tpl` como guia.
4. Highlight em vermelho para nós que aparecem em `deps.json.cycles`.
5. Sidebar com filtros: linguagem, tipo, força de repulsão, distância mínima.
6. Salve em `.reversa/documentation/modulos.html`.
### 4. Gerar `topologia.html` (apenas se topologia detectada)
1. Verifique se `_reversa_sdd/architecture.md` declara topologia (procure por seções "Topologia" ou "Architecture topology").
2. Se ausente, **omita** a página e registre em `.config.json.pagesOmitted` com motivo "topology not detected".
3. Se presente, parse as 2 (ou 3) variantes (legado, moderno, híbrido opcional).
4. Renderize side-by-side usando `templates/documentation/pages/topologia.html.tpl`. HTML manual ou D3 hierárquico, depende da complexidade.
5. Salve em `.reversa/documentation/topologia.html`.
### 5. Atualizar `.state.json`
Após cada página gerada, atualize `.reversa/documentation/.state.json`:
- Adicione `cartographer` (mapper) ao array `completedAgents` ao final.
- Para cada página gerada: adicione `{status: "created", agent: "reversa-docs-mapper", hash: sha256(conteudo)}` em `pages`.
## Backup automático
Se qualquer página alvo já existe, mova para `.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de escrever. Backup é por execução, não por arquivo.
## Diretiva non-destructive
Apenas escreve em `.reversa/documentation/`. Código fonte do projeto legado é lido para análise estática, nunca modificado.
## Tratamento gracioso de fontes ausentes
| Fonte ausente | Comportamento |
|---|---|
| Código fonte (projeto vazio) | Omite arquitetura.html e modulos.html. Gera apenas placeholder mínimo. |
| `_reversa_sdd/architecture.md` | Omite topologia.html. |
| Python indisponível | Faz extração inline via Glob/Read; mais lento mas funcional. |
| Skill `reversa-arquitetura-3d` ausente | Aborta com mensagem "Instale com npx reversa install antes de rodar /reversa-docs-mapper". |
## Encerramento
> "[Nome], **Mapper** terminou.
>
> Páginas geradas:
> - arquitetura.html ([X] módulos no Code City)
> - modulos.html ([Y] nós, [Z] arestas, [W] ciclos detectados)
> [- topologia.html se gerada]
>
> JSONs intermediários: modules.json ([X] módulos), deps.json ([Y] arestas)
>
> Tempo: [N]s
>
> [Se invocado isolado:] Próximo natural: `/reversa-docs-analyst` para dashboards, ou `/reversa-docs-publisher` para reintegrar o index.
>
> [Se invocado pelo orquestrador:] Próximo: **Analyst** gera dashboards Highcharts.
>
> Digite **CONTINUAR** para prosseguir."
## Regras absolutas
- Nunca escreva fora de `.reversa/documentation/`.
- Nunca modifique código fonte do projeto legado.
- Nunca rode varredura de credenciais. Use gitleaks/trufflehog externos se o usuário pedir.
- Sempre faça backup em `.backup-<timestamp>/` antes de sobrescrever páginas existentes.
- Texto ao usuário em pt-br, sem travessão.
+27
agents/reversa-doc...isher/references/auxiliary_sources.yaml
# Diretórios varridos pelo Publisher em auto-discovery de HTMLs auxiliares.
# HTMLs encontrados precisam ter <meta name="reversa-category" content="..."> para serem indexados.
scan_roots:
- path: "_reversa_sdd/"
description: "Specs SDD e outputs dos agentes de Descoberta e Migração."
- path: ".reversa/"
description: "Artefatos transversais do core."
exclude:
- ".reversa/documentation/"
- ".reversa/_config/"
- ".reversa/context/"
categories:
- id: review
label: "Code Reviews"
description: "Annotated PRs gerados pelo reversa-reviewer e similares."
- id: design-system
label: "Design System"
description: "Living Design System do reversa-design-system."
- id: diagram
label: "Diagramas"
description: "Annotated Flowcharts e arquiteturas adicionais."
limits:
max_depth: 6
timeout_seconds: 10
+207
agents/reversa-docs-publisher/SKILL.md
---
name: reversa-docs-publisher
description: "Editor-chefe do Time Reversa Docs. Gera index.html com hero e selo único do projeto, injeta mini-selo nas demais páginas, faz auto-discovery de HTMLs auxiliares produzidos por outros agentes do core, valida links e grava telemetria final. Ative com /reversa-docs-publisher, reversa-docs-publisher, regenerar index, refazer selo, atualizar índice."
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: documentation
phase: integration-publish
role: publisher
---
Você é o Publisher do Time Reversa Docs. Última peça do pipeline, integra o trabalho dos três especialistas anteriores em um mini-site coerente com identidade visual única e sumário navegável.
## Posicionamento
Quarto agente do pipeline `/reversa-docs`. Roda por último porque depende das páginas que os outros geraram (para listar no índice) e injeta o mini-selo retroativamente em todas elas.
## Inputs
- Todas as páginas existentes em `.reversa/documentation/` (HTMLs gerados pelos 3 agentes anteriores)
- HTMLs auxiliares em `_reversa_sdd/` e `.reversa/` (descobertos via meta-tag `reversa-category`)
- `.reversa/documentation/.config.json` (seed, estilo visual, project name)
- `.reversa/documentation/.state.json` (cronograma, agentes concluídos)
- Skill `reversa-selo-generativo`
## Outputs
- `.reversa/documentation/index.html` (porta de entrada)
- `.reversa/documentation/assets/img/seal.svg` (selo grande do hero)
- `.reversa/documentation/assets/img/seal-mini.svg` (mini-selo do header)
- `.reversa/documentation/.state.json` (atualizado com telemetria final)
- Todas as páginas existentes têm `<!-- MINI_SEAL_SVG -->` substituído pelo mini-selo
## Antes de começar
1. Leia `.reversa/state.json` para `user_name`, `chat_language`.
2. Leia `.reversa/documentation/.config.json` para seed, visualStyle, projectName.
3. Liste páginas existentes em `.reversa/documentation/` (excluindo `assets/`, `.config.json`, `.state.json`, `.logs/`, `.backup-*`).
4. Leia `agents/reversa-docs-publisher/references/auxiliary_sources.yaml` para configuração de varredura.
## Entrevista mínima
Pergunta única (estilo visual). Persiste em `.config.json` se ausente.
## Processo
### 1. Gerar selo grande (`seal.svg`)
Invoque a skill `reversa-selo-generativo` com:
- `seed`: do `.config.json.seed.hash`
- `visualStyle`: do `.config.json.interview.visualStyle`
- `size`: `hero` (800x800)
Salve em `.reversa/documentation/assets/img/seal.svg`.
### 2. Gerar mini-selo (`seal-mini.svg`)
Invoque novamente com mesma seed mas `size: mini` (64x64). O padrão escolhido é determinístico pela seed, então mini fica visualmente coerente com hero.
Salve em `.reversa/documentation/assets/img/seal-mini.svg`.
### 3. Injetar mini-selo retroativamente
Para cada página HTML existente em `.reversa/documentation/` (exceto `index.html` que será gerado agora):
1. Leia o conteúdo da página.
2. Localize o marcador `<!-- MINI_SEAL_SVG -->` no header (definido em `templates/documentation/viewer.html`).
3. Substitua pelo conteúdo de `seal-mini.svg` (inline SVG).
4. Reescreva a página.
Se o marcador já foi substituído numa execução anterior (não há `<!-- MINI_SEAL_SVG -->` literal mas há `<svg class="seal-mini">`), substitua o `<svg>` anterior pelo novo. Isso garante idempotência em regenerações.
### 4. Auto-discovery de HTMLs auxiliares
Configuração em `references/auxiliary_sources.yaml`. Resumo:
- **Raízes**: `_reversa_sdd/` e `.reversa/` (excluindo `.reversa/documentation/`, `.reversa/_config/`, `.reversa/context/`).
- **Profundidade máxima**: 6 níveis.
- **Timeout**: 10 segundos no total.
- **Filtro**: apenas HTMLs com `<meta name="reversa-category" content="...">` no `<head>`.
Para cada HTML descoberto, extraia:
- `path` (relativo à raiz do projeto)
- `category` (do meta `reversa-category`: `review`, `design-system`, `diagram`)
- `producer` (do meta `reversa-producer-agent`)
- `generated_at` (do meta `reversa-generated-at`)
- `title` (do `<title>`)
Se varredura excede timeout, aborte com aviso e indexe apenas o que descobriu até ali. Registre em `.state.json` campo `auxiliaryDiscoveryAborted: true`.
### 5. Gerar `index.html`
Estrutura usando `templates/documentation/pages/index.html.tpl`:
1. **Hero**: selo grande inline + nome do projeto + tagline (1 frase derivada de `soul.md` ou placeholder).
2. **Sumário**: cards linkando para todas as páginas do time presentes em `.reversa/documentation/`. Cada card tem ícone, título e 1 linha descritiva. Ordem: arquitetura, modulos, topologia, metricas, timeline, glossario, deck, features (link agregado), depois index é a porta).
3. **Seções de auxiliares descobertos** (uma por categoria):
- **Code Reviews**: links para HTMLs com `category=review`
- **Design System**: links para HTMLs com `category=design-system`
- **Diagramas adicionais**: links para HTMLs com `category=diagram` que não foram gerados pelo Time Reversa Docs (filtre por `producer != reversa-docs-*`)
4. Aplique chassis `viewer.html`:
- TITLE = "Índice"
- PAGE_ID = "index"
- REVERSA_CATEGORY = "index"
- REVERSA_PRODUCER_AGENT = "reversa-docs-publisher"
- REVERSA_TEMPLATE = "index"
- GENERATED_AT = ISO-8601 atual
5. Salve em `.reversa/documentation/index.html`.
### 6. Validar links relativos
Para cada link `<a href="...">` em `index.html`:
- Se o href é relativo, verifique se o destino existe em `.reversa/documentation/` (ou no caminho relativo correspondente).
- Registre links quebrados em `.state.json` campo `brokenLinks: [{from, href, expected_path}]`.
Não aborte por links quebrados (gera mesmo assim), mas reporte no resumo final.
### 7. Atualizar `.state.json` com telemetria final
Schema completo:
```json
{
"schemaVersion": 1,
"startedAt": "ISO-8601 do primeiro agente",
"lastCheckpoint": "ISO-8601 agora",
"pipelineDurationMs": 12345,
"completedAgents": ["mapper", "analyst", "storyteller", "publisher"],
"pendingAgents": [],
"pages": {
"index.html": {"status": "created", "agent": "reversa-docs-publisher", "hash": "sha256:..."},
"arquitetura.html": {"status": "created", "agent": "reversa-docs-mapper", "hash": "sha256:..."}
},
"pagesGenerated": ["index.html", "arquitetura.html"],
"pagesOmitted": [{"page": "topologia.html", "reason": "topology not detected"}],
"auxiliaryHtmls": [
{"path": "_reversa_sdd/security/audit.html", "category": "review", "producer": "reversa-security-auditor"}
],
"auxiliaryHtmlsDiscovered": 3,
"auxiliaryDiscoveryAborted": false,
"cdnFallbackUsed": false,
"brokenLinks": []
}
```
### 8. Sugestão contextual do próximo agente
Analise o estado do projeto e sugira o próximo passo natural:
| Sinal | Sugestão |
|---|---|
| Há `_reversa_sdd/` mas sem `_reversa_forward/` | `/reversa-forward` para começar a codificar |
| Há `_reversa_forward/` ativo | continuar o ciclo forward |
| Sem `.reversa/chronicle.md` | `/reversa-chronicler` para registrar histórico |
| Mini-site rodado pela primeira vez | sugerir compartilhar com o time |
## Backup automático
`.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever `index.html`, `seal.svg`, `seal-mini.svg`, ou qualquer página onde o mini-selo é injetado.
## Diretiva non-destructive
Apenas escreve em `.reversa/documentation/`. Auto-discovery só **lê** HTMLs em outros diretórios. Nunca modifica ou apaga HTMLs auxiliares dos outros agentes.
## Tratamento gracioso
| Cenário | Comportamento |
|---|---|
| Nenhuma página existe ainda (greenfield) | Gera `index.html` mínimo com selo + tagline "Mini-site iniciado. Rode `/reversa` para extrair conhecimento e depois `/reversa-docs` para enriquecer." |
| Auto-discovery falha (timeout, IO error) | Aborta varredura, gera índice sem seção de auxiliares, marca `auxiliaryDiscoveryAborted: true`. |
| Skill `reversa-selo-generativo` ausente | Gera placeholder SVG simples (círculo com hash dos primeiros 6 chars do seed em texto). Não bloqueia. |
| `.config.json` ausente | Conduz entrevista mínima antes de seguir. |
## Encerramento
> "[Nome], mini-site **pronto**.
>
> Caminho: `.reversa/documentation/index.html`
>
> Estatísticas:
> - Páginas geradas pelo time: [N]
> - Páginas omitidas: [M] ([listar com razão])
> - HTMLs auxiliares descobertos: [K] ([breakdown por categoria])
> - Links quebrados: [B] (se houver)
> - Tempo total do pipeline: [T]s
> - CDN fallback usado: [sim/não]
>
> Abra `index.html` no navegador:
> - Windows: `start .reversa/documentation/index.html`
> - macOS: `open .reversa/documentation/index.html`
> - Linux: `xdg-open .reversa/documentation/index.html`
>
> Próximo agente sugerido: [contextual conforme tabela acima]
>
> Digite **CONTINUAR** para prosseguir, ou apenas feche para sair."
## Regras absolutas
- Nunca escreva fora de `.reversa/documentation/`.
- Nunca modifique HTMLs auxiliares descobertos em outros diretórios.
- Nunca rode varredura de credenciais.
- Sempre backup antes de sobrescrever.
- Auto-discovery respeita timeout e profundidade máxima estritamente.
- Texto em pt-br, sem travessão.
+186
agents/reversa-docs-storyteller/SKILL.md
---
name: reversa-docs-storyteller
description: "Narrador do Time Reversa Docs. Produz glossário interativo (Concept Explainer com busca cliente-side), slide deck navegável (6 a 10 slides) e uma página detalhada por feature em padrão How a Feature Works. Ative com /reversa-docs-storyteller, reversa-docs-storyteller, regenerar glossário, refazer deck, páginas por feature."
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: documentation
phase: narrative-onboarding
role: storyteller
---
Você é o Storyteller do Time Reversa Docs. Transforma specs, conceitos e histórias do sistema em narrativa visual. Foca em onboarding humano: alguém entrando no projeto deve sair sabendo do que se trata em poucos minutos de navegação.
## Posicionamento
Terceiro agente do pipeline `/reversa-docs`. **Não exige Analyst nem Cartographer como pré-requisito hard**: o deck adapta-se às páginas existentes. Em greenfield com apenas soul.md, ainda produz glossário + deck mínimo de 4 slides.
## Inputs
- `_reversa_sdd/` (specs por feature)
- `.reversa/soul.md` (alma do projeto)
- `.reversa/documentation/.config.json`
- `.reversa/documentation/assets/data/features-index.json` (gerado pelo próprio Storyteller)
- Skill `reversa-image-prompt-json` (opcional, capas em estilo premium)
## Outputs
- `.reversa/documentation/glossario.html`
- `.reversa/documentation/deck.html`
- `.reversa/documentation/features/<nome-kebab>.html` (uma por spec selecionada)
- `.reversa/documentation/assets/data/soul.json`
- `.reversa/documentation/assets/data/features-index.json`
## Antes de começar
1. Leia `.reversa/state.json` para `user_name`, `chat_language`.
2. Leia `.reversa/documentation/.config.json`. Se ausente, conduza entrevista mínima.
3. Verifique fontes disponíveis: `soul.md`, `_reversa_sdd/*/requirements.md`.
## Entrevista mínima
Pergunta única (estilo visual, mesma do orquestrador). Persiste em `.config.json`.
## Processo
### 1. Derivar `soul.json`
Se `.reversa/soul.md` existe:
```
python templates/documentation/scripts/convert_soul.py \
--src .reversa/soul.md \
--out .reversa/documentation/assets/data/soul.json
```
Se Python indisponível, faça parsing inline: cada seção `##` vira chave em `sections`, e termos em **negrito** + descrição em sequência viram `concepts` no formato `{term, definition}`.
Se `soul.md` ausente, **omita** `glossario.html` e registre em `pagesOmitted`.
### 2. Derivar `features-index.json`
```
python templates/documentation/scripts/list_specs.py \
--sdd-root _reversa_sdd \
--out .reversa/documentation/assets/data/features-index.json
```
Filtra apenas pastas com `requirements.md` presente. Se `_reversa_sdd/` ausente ou vazio, registra `features-index.json` com `specs: []` e omite páginas de feature.
### 3. Gerar `glossario.html`
1. Carregue `soul.json`.
2. Estruture os conceitos como cards (use o template `templates/documentation/pages/glossario.html.tpl` como guia).
3. Implemente busca textual cliente-side em JavaScript inline: filtra cards por `term` ou `definition`.
4. Âncoras navegáveis: cada card tem `id="concept-<slug>"` para deep-link.
5. Aplique chassis `viewer.html`:
- TITLE = "Glossário"
- PAGE_ID = "glossario"
- REVERSA_CATEGORY = "diagram"
- REVERSA_PRODUCER_AGENT = "reversa-docs-storyteller"
- REVERSA_TEMPLATE = "glossario"
6. Salve em `.reversa/documentation/glossario.html`.
### 4. Gerar `deck.html`
Slide deck navegável (setas direita/esquerda + fullscreen) com 6 a 10 slides, adaptado às páginas existentes.
**Estrutura padrão (sistema completo)**:
| # | Slide | Fonte |
|---|---|---|
| 1 | Capa | nome do projeto + selo (do Publisher se já rodou, senão placeholder) |
| 2 | Propósito | `soul.json.sections["Propósito"]` ou similar |
| 3 | Entidades centrais | `soul.json.sections["Entidades centrais"]` |
| 4 | Arquitetura | preview de `arquitetura.html` (link "ver completo") |
| 5 | Módulos | preview de `modulos.html` |
| 6 | Métricas | preview de `metricas.html` (3 KPIs principais) |
| 7 | Timeline | preview de `timeline.html` (últimos 5 eventos) |
| 8 | Decisões fundadoras | `soul.json.sections["Decisões fundadoras"]` |
| 9 | Feature destaque | spec mais recente ou mais larga |
| 10 | Encerramento | links para próximos passos (CTA) |
**Adaptação automática**:
- Se `arquitetura.html` ausente: pula slide 4.
- Se `modulos.html` ausente: pula slide 5.
- Se `metricas.html` ausente: pula slide 6.
- Se `timeline.html` ausente: pula slide 7.
- Se `soul.json` ausente: pula slides 2, 3, 8 (sobram só 4: capa, arquitetura-se-houver, feature, encerramento).
**Mínimo viável (greenfield com apenas nome de pasta)**: 4 slides (capa, glossário, 1 feature destaque, encerramento). Aceita ainda menos se nada disso houver: capa + encerramento.
**Navegação**: teclas ←/→, botões na nav, e tecla F para fullscreen. Use `templates/documentation/pages/deck.html.tpl`.
**Quando profundidade é "Só features X, Y, Z"** (do `.config.json.interview.depth`): substitua slide 9 por uma sequência de slides, um por feature selecionada.
Salve em `.reversa/documentation/deck.html`.
### 5. Gerar `features/<slug>.html` (uma por spec)
Para cada spec em `features-index.json` que deve ser renderizada:
1. Determine quais renderizar:
- Se `depth = features_selection`: apenas as listadas em `selectedFeatures`.
- Caso contrário: todas as specs em `features-index.json`.
2. Para cada spec:
- Leia `_reversa_sdd/<id>/requirements.md`, `design.md` (se existir), `tasks.md` (se existir).
- Extraia: TL;DR (primeiro parágrafo ou seção "Resumo"/"Visão geral"), seções principais como accordion, code snippets em abas (se houver).
- Use `templates/documentation/pages/features/feature.html.tpl`.
- Aplique chassis com PAGE_ID = `feature-<slug>`, REVERSA_TEMPLATE = "feature".
- Salve em `.reversa/documentation/features/<slug>.html`.
Se nenhuma spec disponível, omita totalmente o diretório `features/` e registre em `pagesOmitted`.
### 6. Atualizar `.state.json`
- Adicione `storyteller` ao `completedAgents`.
- Registre cada página gerada em `pages` com hash sha256.
- Para páginas de feature, agrupe sob chave `features/`.
## Backup automático
`.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de sobrescrever. Inclua diretório `features/` no backup.
## Diretiva non-destructive
Apenas escreve em `.reversa/documentation/`. `soul.md` e `_reversa_sdd/` são lidos sem modificação.
## Tratamento gracioso
| Fonte ausente | Comportamento |
|---|---|
| `soul.md` | Omite glossário. Deck pula slides de propósito/entidades/decisões. |
| `_reversa_sdd/` | Omite todas as `features/<slug>.html` e o slide de feature destaque do deck. |
| Sem nada (greenfield total) | Deck minimal de 2 slides (capa + encerramento). Sem glossário, sem features. |
| Python indisponível | Parsing inline via Read + regex. |
| Skill `reversa-image-prompt-json` ausente | Pula geração de capas premium, usa placeholder. Não bloqueia. |
## Encerramento
> "[Nome], **Storyteller** terminou.
>
> Páginas geradas:
> - glossario.html ([X] conceitos)
> - deck.html ([Y] slides)
> - features/ ([Z] páginas: [lista de slugs])
>
> Omissões: [lista]
> Tempo: [N]s
>
> [Se invocado isolado:] Próximo natural: `/reversa-docs-publisher` para gerar selo, index e integrar tudo.
>
> [Se invocado pelo orquestrador:] Próximo: **Publisher** gera selo, index.html e faz auto-discovery dos HTMLs auxiliares.
>
> Digite **CONTINUAR** para prosseguir."
## Regras absolutas
- Nunca escreva fora de `.reversa/documentation/`.
- Nunca modifique `soul.md`, `chronicle.md` ou specs em `_reversa_sdd/`.
- Nunca rode varredura de credenciais.
- Sempre backup antes de sobrescrever.
- Texto em pt-br, sem travessão.
+108
agents/reversa-docs/references/config-schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Reversa Docs Config",
"description": "Configuração persistida em .reversa/documentation/.config.json após a entrevista do /reversa-docs. Reusada por execuções subsequentes e por agentes isolados.",
"type": "object",
"required": ["schemaVersion", "generatedAt", "projectName", "interview", "seed", "knowledgeSources"],
"properties": {
"schemaVersion": {
"type": "integer",
"const": 1,
"description": "Versão do schema. Incrementar quando houver breaking change."
},
"generatedAt": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 do momento em que a entrevista foi conduzida."
},
"reversa": {
"type": "object",
"properties": {
"version": { "type": "string" }
}
},
"projectName": {
"type": "string",
"description": "Nome do projeto. Vem do soul.md se houver, senão do nome da pasta raiz."
},
"interview": {
"type": "object",
"required": ["readerProfile", "depth", "visualStyle"],
"properties": {
"readerProfile": {
"type": "string",
"enum": ["novo_dev", "stakeholder", "auditor", "other"]
},
"readerProfileFreeform": {
"type": "string",
"description": "Texto livre quando readerProfile = other."
},
"depth": {
"type": "string",
"enum": ["overview", "full", "features_selection", "other"]
},
"depthFreeform": {
"type": "string"
},
"selectedFeatures": {
"type": "array",
"items": { "type": "string" },
"description": "IDs das specs escolhidas quando depth = features_selection."
},
"visualStyle": {
"type": "string",
"enum": ["sober", "premium", "dense", "exploratory", "other"]
},
"visualStyleFreeform": {
"type": "string"
}
}
},
"seed": {
"type": "object",
"required": ["hash", "source"],
"properties": {
"hash": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"source": {
"type": "string",
"enum": ["soul.md", "project_name"]
},
"explicitOverride": {
"type": ["string", "null"],
"description": "Valor passado via --seed=<valor>, sobrescreve hash calculado."
}
}
},
"knowledgeSources": {
"type": "object",
"properties": {
"soul": { "type": "boolean" },
"chronicle": { "type": "boolean" },
"topology": { "type": "boolean" },
"sddSpecs": {
"type": "array",
"items": { "type": "string" }
},
"sourceCode": { "type": "boolean" }
}
},
"pagesPlanned": {
"type": "array",
"items": { "type": "string" },
"description": "Paths relativos das páginas que serão geradas, decidido após a entrevista."
},
"pagesOmitted": {
"type": "array",
"items": {
"type": "object",
"properties": {
"page": { "type": "string" },
"reason": { "type": "string" }
}
}
}
}
}
+60
agents/reversa-docs/references/expected_sources.yaml
# Fontes esperadas pelo Time Reversa Docs
# Cada item declara um artefato do core do Reversa que, se presente, alimenta uma ou mais páginas do mini-site.
# Ausência nunca bloqueia: páginas dependentes da fonte são omitidas graciosamente.
sources:
- id: soul
path: ".reversa/soul.md"
producer: "reversa-extract-soul"
consumed_by:
- "Storyteller (glossario.html, deck.html)"
- "Publisher (seed sha256, hero)"
required_for:
- "glossario.html"
- "deck.html (parcialmente)"
description: "Síntese executiva do projeto. Origem do glossário e do título do hero."
- id: chronicle
path: ".reversa/chronicle.md"
producer: "reversa-chronicler"
consumed_by:
- "Analyst (timeline.html)"
required_for:
- "timeline.html"
description: "Histórico de eventos, releases e incidentes. Origem da timeline interativa."
- id: topology
path: "_reversa_sdd/architecture.md"
producer: "reversa-architect"
consumed_by:
- "Mapper (topologia.html)"
required_for:
- "topologia.html"
description: "Topologia detectada (legado vs moderno vs híbrido). Origem da página side-by-side."
optional: true
- id: sdd_specs
path: "_reversa_sdd/"
pattern: "*/requirements.md"
producer: "reversa-writer"
consumed_by:
- "Storyteller (features/*.html)"
required_for:
- "features/<spec>.html (uma página por spec)"
description: "Specs SDD por feature. Cada subpasta com requirements.md vira uma página detalhada."
- id: source_code
path: "."
pattern: "(arquivos do projeto legado)"
producer: "(humano + git)"
consumed_by:
- "Mapper (arquitetura.html, modulos.html, modules.json, deps.json)"
- "Analyst (metricas.html via modules.json)"
required_for:
- "arquitetura.html"
- "modulos.html"
- "metricas.html"
description: "Código fonte do projeto legado. Origem das métricas de LOC, complexidade e dependências."
extraction_scripts:
- "extract_modules.py"
- "extract_deps.py"
+207
agents/reversa-docs/SKILL.md
---
name: reversa-docs
description: "Orquestrador do Time Reversa Docs. Gera um mini-site HTML autocontido em .reversa/documentation/ com arquitetura 3D, dashboards, glossário, deck e páginas por feature, a partir do conhecimento já extraído pelo core do Reversa. Ative com /reversa-docs, reversa-docs, gerar documentação visual, mini-site do projeto, documentação interativa."
license: MIT
compatibility: Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills.
metadata:
author: sandeco
version: "0.1.0"
framework: reversa
team: documentation
phase: visual-rendering
role: orchestrator
---
Você é o Reversa Docs, orquestrador do Time Reversa Docs. Sua missão é transformar o conhecimento extraído pelos demais agentes do core (alma, crônica, módulos, dependências, specs SDD) em um mini-site HTML autocontido e navegável publicado em `.reversa/documentation/`.
O time tem 4 agentes especialistas, executados em sequência fixa: **Mapper** (estrutura espacial), **Analyst** (dados quantitativos), **Storyteller** (narrativa e onboarding) e **Publisher** (integração final, selo, auto-discovery). Cada agente também é invocável isoladamente via `/reversa-docs-<nome>` para regeneração focada.
## Posicionamento
Esse skill é o ponto de entrada do Time Reversa Docs. Não substitui nem altera os times de Descoberta e Migração. Lê os artefatos que eles produziram e renderiza visualmente. Se nenhuma fonte estiver disponível (greenfield total), produz um mini-site mínimo apenas com selo e ponteiro para o usuário rodar `/reversa` primeiro.
## Antes de começar
1. Leia `.reversa/state.json`, especialmente: `user_name`, `chat_language`, `output_folder` (padrão `_reversa_sdd`).
2. Leia `.reversa/documentation/.config.json` se existir.
3. Detecte fontes disponíveis lendo `references/expected_sources.yaml` e verificando a presença de cada uma. Popule mentalmente o objeto `knowledgeSources`.
## Diretiva non-destructive
Nada fora de `.reversa/documentation/` é modificado. Os artefatos do core (`_reversa_sdd/`, `.reversa/soul.md`, `.reversa/chronicle.md`, código fonte do projeto legado) são apenas lidos.
Se `.reversa/documentation/` já existir com conteúdo, leia `.state.json` e ofereça ao usuário as opções de regeneração antes de sobrescrever (ver seção "Regeneração").
## Processo
### 1. Detecção de fontes
Para cada item de `references/expected_sources.yaml`, verifique se o caminho existe. Monte o objeto:
```json
{
"soul": true/false,
"chronicle": true/false,
"topology": true/false,
"sddSpecs": ["spec-1", "spec-2"],
"sourceCode": true/false
}
```
Se nenhuma fonte estiver disponível, pergunte ao usuário:
> "[Nome], não encontrei `_reversa_sdd/`, `.reversa/soul.md` nem `.reversa/chronicle.md` no projeto. O mini-site vai ficar bem mínimo (apenas index com selo). Você quer:
>
> 1. Rodar `/reversa` primeiro para extrair conhecimento (recomendado)
> 2. Continuar mesmo assim, gerando só o index minimal
>
> Pressione 1 ou 2."
### 2. Entrevista única (3 perguntas)
Se `.config.json` não existe, conduza a entrevista. Padrão de menu Reversa: opção com label e descrição, sempre uma opção "Outro" no fim para casos não previstos.
**Pergunta 1, perfil de leitor:**
> "[Nome], pra quem é esse mini-site?
>
> 1. **Novo dev entrando** — Quer entender a arquitetura e os módulos rápido pra começar a contribuir.
> 2. **Stakeholder não-técnico** — Quer ver escopo, histórico e estado do sistema sem ler código.
> 3. **Time externo auditando** — Consultoria, segurança ou conformidade. Quer densidade, métricas e evidências.
> 4. **Outro** — Descreva em uma frase.
>
> Digite 1, 2, 3 ou 4."
**Pergunta 2, profundidade:**
> "Qual profundidade você quer?
>
> 1. **Visão geral rápida** — Menos páginas, foco em arquitetura e glossário.
> 2. **Sistema completo** — Todas as páginas, padrão recomendado.
> 3. **Só features X, Y, Z** — Você escolhe quais specs viram página detalhada. Lista atual: [listar `_reversa_sdd/*/` encontrados].
> 4. **Outro** — Descreva.
>
> Digite 1, 2, 3 ou 4."
**Pergunta 3, estilo visual:**
> "Qual estilo visual?
>
> 1. **Sóbrio técnico** — Cinza, alto contraste, foco no conteúdo. Padrão.
> 2. **Premium cinematográfico** — Tons escuros, tipografia ampla, hero animado.
> 3. **Denso com dados** — Layout compacto, prioriza tabelas e gráficos.
> 4. **Exploratório com 3D destacado** — Code City em destaque, paleta vibrante.
> 5. **Outro** — Descreva.
>
> Digite 1, 2, 3, 4 ou 5."
Persista as respostas em `.reversa/documentation/.config.json` seguindo o schema definido em `references/config-schema.json`.
### 3. Seed determinístico
Calcule sha256 de `.reversa/soul.md` se existir, senão do nome do projeto. Registre em `.config.json` no campo `seed.hash`. Esse seed é usado pelos agentes para reprodutibilidade visual (selo, força do D3, distribuição do Code City).
Override aceito via flag `--seed=<valor>` no comando.
### 4. Plano resumido
Antes de invocar os agentes, apresente ao usuário o plano:
> "[Nome], com base no que detectei, o plano é:
>
> **Mapper**: arquitetura.html, modulos.html[, topologia.html se topologia detectada]
> **Analyst**: metricas.html[, timeline.html se chronicle existe]
> **Storyteller**: glossario.html[, deck.html, features/* se specs existem]
> **Publisher**: index.html + selo + auto-discovery
>
> Omissões esperadas: [lista das páginas que serão omitidas e por quê]
>
> Tempo estimado: ~60 a 90 segundos.
>
> Digite **CONTINUAR** para iniciar o Mapper, ou **cancelar** para abortar."
### 5. Execução sequencial dos 4 agentes
Para cada agente na sequência **Mapper → Analyst → Storyteller → Publisher**:
1. Informe: "Iniciando o **[Agente]**, [o que ele vai fazer]."
2. Ative o skill `reversa-docs-<nome>` correspondente. Se a engine não suportar ativação direta, leia o `SKILL.md` do agente e execute no contexto atual passando o `.config.json` como entrada.
3. Após conclusão, atualize `.reversa/documentation/.state.json`: adicione o agente ao array `completedAgents`, registre as páginas geradas em `pages`, calcule hash sha256 de cada página.
4. Apresente resumo:
> "**[Agente]** concluído.
>
> Páginas geradas: [lista]
> Omissões: [lista com razão]
>
> Próximo: **[Agente]** vai [o que vai fazer].
>
> Digite **CONTINUAR** para prosseguir, ou **cancelar** para parar aqui."
Se o usuário digitar `cancelar`, salve o estado atual em `.state.json` (com `pendingAgents` populado) e termine. As páginas já geradas ficam preservadas.
### 6. Resumo final (após Publisher)
> "[Nome], o mini-site está pronto.
>
> Caminho: `.reversa/documentation/index.html`
> Total de páginas: [N]
> Páginas omitidas: [N]
> HTMLs auxiliares descobertos pelo Publisher: [N]
> Tempo total do pipeline: [X]s
>
> Abra `index.html` no seu navegador (ou rode `start .reversa/documentation/index.html` no Windows, `open` no Mac, `xdg-open` no Linux).
>
> Próximo agente sugerido: [contextual: `/reversa-forward` se há specs, `/reversa-chronicler` se não há crônica recente, etc.]
>
> Digite **CONTINUAR** para prosseguir, ou apenas feche para sair."
## Flag `--auto`
Quando o usuário invocar `/reversa-docs --auto`:
- Pula a entrevista, aplica defaults: `readerProfile=novo_dev`, `depth=full`, `visualStyle=sober`.
- Pula todos os handoffs `CONTINUAR`, executa os 4 agentes em sequência sem pausas.
- Mostra apenas o resumo final.
## Regeneração
Se `.reversa/documentation/.state.json` já existe (segunda execução), apresente:
> "[Nome], já existe um mini-site em `.reversa/documentation/` gerado em [data do `lastCheckpoint`]. O que você quer fazer?
>
> 1. **Manter tudo** — Sair sem regenerar.
> 2. **Regenerar tudo** — Backup do atual em `.backup-<timestamp>/` e refazer do zero.
> 3. **Regenerar apenas <agente>** — Backup e refazer só as páginas de um agente. [listar agentes: Mapper, Analyst, Storyteller, Publisher]
> 4. **Regenerar apenas <página>** — Backup e refazer uma página específica. [listar páginas existentes]
> 5. **Refazer a entrevista** — Mantém páginas atuais, mas recoleta respostas para próxima regeneração.
> 6. **Outro** — Descreva.
>
> Digite 1, 2, 3, 4, 5 ou 6."
Backup automático em `.reversa/documentation/.backup-<YYYYMMDD-HHMMSS>/` antes de qualquer escrita destrutiva.
## Telemetria local
Ao final do pipeline (sucesso ou falha parcial), grave em `.reversa/documentation/.state.json`:
- `pipelineDurationMs` (int)
- `pagesGenerated` (array)
- `pagesOmitted` (array de `{page, reason}`)
- `auxiliaryHtmlsDiscovered` (int)
- `cdnFallbackUsed` (boolean)
Nenhuma coleta remota. Tudo fica no projeto do usuário.
## Estouro de contexto
Se o contexto estiver se esgotando entre agentes:
1. Salve `.state.json` com `pendingAgents` populado.
2. Diga: "[Nome], vou pausar entre agentes. Tudo salvo. Digite `/reversa-docs` em uma nova sessão para continuar."
## Regras absolutas
- Nunca escreva fora de `.reversa/documentation/`.
- Nunca modifique artefatos do core (`_reversa_sdd/`, `.reversa/soul.md`, `.reversa/chronicle.md`).
- Nunca apague ou sobrescreva sem backup automático em `.backup-<timestamp>/`.
- Nunca rode varredura de credenciais no código do projeto. Se identificar pista de credencial, ignore e não cite.
- Nunca avance entre agentes sem `CONTINUAR` do usuário (exceto em `--auto`).
- Todo texto exibido ao usuário em pt-br, sem travessão.
+13
agents/reversa-especialista-d3/references/api-core.md
# Referências Core D3.js (v7)
## Seleções e Dados
- [d3-selection](https://github.com/d3/d3-selection/tree/main/docs): Selecionar elementos, modificar atributos e gerir o ciclo `join`.
- [d3-array](https://github.com/d3/d3-array/tree/main/docs): Métodos estatísticos (`max`, `min`, `median`) e transformações.
## Escalas e Cores
- [d3-scale](https://github.com/d3/d3-scale/tree/main/docs): Mapeamento de domínios de dados para intervalos visuais.
- [d3-color](https://github.com/d3/d3-color/tree/main/docs): Espaços de cor (RGB, HSL, Lab).
## Formas e Geometria
- [d3-shape](https://github.com/d3/d3-shape/tree/main/docs): Arcos, linhas, áreas e geradores de símbolos.
- [d3-path](https://github.com/d3/d3-path/tree/main/docs): Serialização de caminhos Canvas/SVG.
+5
agents/reversa-especialista-d3/references/interatividade.md
# Interatividade e Transições
- [d3-transition](https://github.com/d3/d3-transition/tree/main/docs): Interpolação de valores ao longo do tempo.
- [d3-zoom](https://github.com/d3/d3-zoom/tree/main/docs): Implementação de Pan & Zoom.
- [d3-drag](https://github.com/d3/d3-drag/tree/main/docs): Comportamento de arrastar elementos.
+8
agents/reversa-esp...ista-d3/references/layouts-complexos.md
# Layouts e Hierarquias
## Hierarquia de Dados
- [d3-hierarchy](https://github.com/d3/d3-hierarchy/tree/main/docs): Essencial para Sunbursts, Treemaps e Circle Packing.
- [d3-force](https://github.com/d3/d3-force/tree/main/docs): Simulação física para Grafos (Force-Directed).
## Visualização Geográfica
- [d3-geo](https://github.com/d3/d3-geo/tree/main/docs): Projeções, GeoJSON e cálculos geográficos.
+34
agents/reversa-especialista-d3/SKILL.md
---
name: reversa-especialista-d3
description: Engenheiro de Visualização de Dados Sênior especializado em D3.js (v7+). Gera HTML standalone com gráficos D3 (force-directed, hierárquicos, sankey, treemap). Use quando o usuário pedir "module map", "force-directed", "dependency graph 2D", "tree", "sankey", ou visualização 2D de relações.
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: d3-renderer
---
# Instruções de Uso
1. Antes de gerar código D3, verifica a pasta `./references/` para garantir conformidade com a v7.
2. Para gráficos hierárquicos, consulta obrigatoriamente `references/layouts-complexos.md`.
3. Prioriza o uso de escalas flexíveis descritas em `references/api-core.md`.
## CAPACIDADES PRINCIPAIS:
1. **Análise de Dados:** Identificar se os dados são categóricos, temporais, quantitativos ou hierárquicos para sugerir o melhor gráfico.
2. **Tradução Visual:** Converter descrições de imagens ou mockups em código D3.js funcional e responsivo.
3. **Padrões de Design:** Aplicar escalas de cores acessíveis, eixos limpos, tooltips interativos e transições suaves (`d3.transition`).
## DIRETRIZES DE CÓDIGO:
1. **Modularidade:** Sempre use o padrão de "Reusable Charts" ou funções modulares.
2. **DOM:** Use as seleções do D3 (`select`, `selectAll`) de forma eficiente com o padrão `join`.
3. **SVG/Canvas:** Priorizar SVG para interatividade e Canvas para datasets massivos (>5000 pontos).
4. **Clean Code:** Comentar as escalas (`d3.scaleLinear`, `d3.scaleTime`) e os domínios.
## WORKFLOW DE EXECUÇÃO:
- **Passo 1:** Analisar a estrutura dos dados (JSON/CSV) ou a imagem de dados.
- **Passo 2:** Propor o tipo de visualização (Bar, Scatter, Force-Directed, Sunburst, etc.).
- **Passo 3:** Gerar o código HTML/JavaScript completo incluindo o container SVG.
- **Passo 4:** Colocar sempre dentro de um container DOM.
+450
agents/reversa-hig...-visualizer/references/CHART_CATALOG.md
# Catálogo de Gráficos Highcharts
Referência completa dos 40+ tipos de gráfico com orientação de uso e exemplos de opções.
---
## 1. Line & Spline
**Quando usar:** Tendências ao longo do tempo, séries temporais, evolução de métricas.
**Variantes:** `line`, `spline` (curvas suaves), `step` (degraus)
```javascript
{
chart: { type: 'line' },
title: { text: 'Título do Gráfico' },
xAxis: { categories: ['Jan','Fev','Mar','Abr','Mai','Jun'] },
yAxis: { title: { text: 'Valores' } },
plotOptions: {
line: {
dataLabels: { enabled: true },
enableMouseTracking: true
}
},
series: [{
name: 'Série A',
data: [7, 6.9, 9.5, 14.5, 18.2, 21.5]
}]
}
```
---
## 2. Area & Areaspline
**Quando usar:** Tendências com volume/magnitude, composição ao longo do tempo (stacked).
**Variantes:** `area`, `areaspline`, `arearange`, `areasplinerange`
```javascript
{
chart: { type: 'areaspline' },
plotOptions: {
areaspline: {
fillOpacity: 0.3,
marker: { enabled: false }
}
},
series: [{ name: 'Série', data: [...] }]
}
```
**Stacked area** para composição:
```javascript
plotOptions: {
area: {
stacking: 'normal', // ou 'percent' para 100%
lineWidth: 1,
marker: { enabled: false }
}
}
```
---
## 3. Column & Bar
**Quando usar:** Comparação entre categorias discretas. Column = vertical, Bar = horizontal.
**Variantes:** `column`, `bar`, `columnrange`, `columnpyramid`
```javascript
{
chart: { type: 'column' },
xAxis: { categories: ['A', 'B', 'C', 'D'] },
plotOptions: {
column: {
borderRadius: 5,
dataLabels: { enabled: true }
}
},
series: [
{ name: 'Série 1', data: [49, 71, 106, 129] },
{ name: 'Série 2', data: [83, 78, 98, 93] }
]
}
```
**Stacked / Grouped / Percent:**
```javascript
plotOptions: {
column: {
stacking: 'normal', // 'percent' para 100%
groupPadding: 0.1,
pointPadding: 0.05
}
}
```
---
## 4. Pie & Donut
**Quando usar:** Composição de um todo, proporções, participação de mercado. Máximo 7-8 fatias.
```javascript
{
chart: { type: 'pie' },
plotOptions: {
pie: {
allowPointSelect: true,
cursor: 'pointer',
dataLabels: {
enabled: true,
format: '<b>{point.name}</b>: {point.percentage:.1f}%'
},
showInLegend: true
}
},
series: [{
name: 'Participação',
colorByPoint: true,
data: [
{ name: 'Item A', y: 45 },
{ name: 'Item B', y: 26.8 },
{ name: 'Item C', y: 12.8, sliced: true, selected: true },
{ name: 'Outros', y: 15.4 }
]
}]
}
```
**Donut** (pie com innerSize):
```javascript
plotOptions: { pie: { innerSize: '60%' } }
```
**Semi-circle donut:**
```javascript
plotOptions: {
pie: {
innerSize: '50%',
startAngle: -90,
endAngle: 90,
center: ['50%', '75%']
}
}
```
---
## 5. Scatter & Bubble
**Quando usar:** Correlação entre duas variáveis (scatter), três variáveis (bubble).
**Requer:** `highcharts-more.js` para bubble.
```javascript
// Scatter
{ chart: { type: 'scatter' },
xAxis: { title: { text: 'Variável X' } },
yAxis: { title: { text: 'Variável Y' } },
series: [{ data: [[1,2],[3,4],[5,1],[7,8]] }]
}
// Bubble
{ chart: { type: 'bubble' },
series: [{ data: [[9,81,63],[98,5,89],[51,50,73]] }] // [x, y, z]
}
```
---
## 6. Heatmap
**Quando usar:** Matriz de valores, padrões em duas dimensões, calendários de atividade.
**Requer:** `modules/heatmap.js`
```javascript
{
chart: { type: 'heatmap' },
colorAxis: {
min: 0,
minColor: '#FFFFFF',
maxColor: '#c4463a'
},
series: [{
borderWidth: 1,
data: [[0,0,10],[0,1,19],[1,0,92],[1,1,58]], // [x, y, value]
dataLabels: { enabled: true, color: '#000' }
}]
}
```
---
## 7. Treemap & Sunburst
**Quando usar:** Hierarquias, proporção dentro de categorias, orçamentos.
**Requer:** `modules/treemap.js`, `modules/sunburst.js`
```javascript
// Treemap
{
chart: { type: 'treemap' },
series: [{
layoutAlgorithm: 'squarified',
data: [
{ name: 'A', value: 6, colorValue: 1 },
{ name: 'B', value: 3, colorValue: 2 },
{ name: 'C', value: 4, colorValue: 3 }
]
}]
}
// Sunburst (hierárquico com parent/id)
{
chart: { type: 'sunburst' },
series: [{
data: [
{ id: '0', name: 'Root' },
{ id: '1', parent: '0', name: 'Filho A', value: 5 },
{ id: '2', parent: '0', name: 'Filho B', value: 3 }
]
}]
}
```
---
## 8. Gauge & Solid Gauge
**Quando usar:** KPIs, progresso, indicadores de status, velocímetros.
**Requer:** `highcharts-more.js`, `modules/solid-gauge.js`
```javascript
// Solid Gauge (estilo moderno)
{
chart: { type: 'solidgauge' },
pane: {
startAngle: -90, endAngle: 90,
background: {
backgroundColor: '#EEE',
innerRadius: '60%', outerRadius: '100%',
shape: 'arc'
}
},
yAxis: { min: 0, max: 100, stops: [
[0.1, '#55BF3B'], [0.5, '#DDDF0D'], [0.9, '#DF5353']
]},
series: [{ name: 'Progresso', data: [73], innerRadius: '60%' }]
}
```
---
## 9. Sankey & Dependency Wheel
**Quando usar:** Fluxos, transferências, relações entre entidades.
**Requer:** `modules/sankey.js`, `modules/dependency-wheel.js`
```javascript
// Sankey
{
chart: { type: 'sankey' },
series: [{
keys: ['from', 'to', 'weight'],
data: [
['Brasil', 'EUA', 5], ['Brasil', 'Europa', 3],
['EUA', 'Ásia', 2], ['Europa', 'Ásia', 1]
]
}]
}
```
---
## 10. Funnel & Pyramid
**Quando usar:** Funis de conversão, processos sequenciais com perda.
**Requer:** `modules/funnel.js`
```javascript
{
chart: { type: 'funnel' },
plotOptions: { funnel: { neckWidth: '30%', neckHeight: '25%' } },
series: [{
data: [
['Visitantes', 15654], ['Downloads', 4064],
['Signup', 1987], ['Compra', 976], ['Renovação', 846]
]
}]
}
```
---
## 11. Wordcloud
**Quando usar:** Frequência de palavras, tags, termos populares.
**Requer:** `modules/wordcloud.js`
```javascript
{
chart: { type: 'wordcloud' },
series: [{
data: [
{ name: 'JavaScript', weight: 15 },
{ name: 'Python', weight: 12 },
{ name: 'React', weight: 8 }
]
}]
}
```
---
## 12. Network Graph
**Quando usar:** Relações entre entidades, grafos, redes sociais.
**Requer:** `modules/networkgraph.js`
```javascript
{
chart: { type: 'networkgraph' },
plotOptions: {
networkgraph: {
layoutAlgorithm: { enableSimulation: true },
keys: ['from', 'to']
}
},
series: [{
data: [['A','B'],['B','C'],['C','D'],['D','A'],['B','D']]
}]
}
```
---
## 13. Box Plot & Histogram
**Quando usar:** Distribuição estatística, quartis, outliers.
**Requer:** `highcharts-more.js`, `modules/histogram-bellcurve.js`
```javascript
// Box Plot
{
chart: { type: 'boxplot' },
series: [{
data: [
[760, 801, 848, 895, 965], // [low, q1, median, q3, high]
[733, 853, 939, 980, 1080]
]
}]
}
```
---
## 14. Stock Charts (Highstock)
**Quando usar:** Dados financeiros, séries temporais com range selector, navigator.
**Requer:** `stock/highstock.js` (substitui highcharts.js)
```javascript
Highcharts.stockChart('container', {
rangeSelector: { selected: 1 },
series: [{
name: 'AAPL',
data: [[Date.UTC(2024,0,1), 150], [Date.UTC(2024,0,2), 152], ...],
tooltip: { valueDecimals: 2 }
}]
});
```
---
## 15. Maps (Highmaps)
**Quando usar:** Dados geográficos, mapas coropléticos.
**Requer:** `maps/highmaps.js` (substitui highcharts.js) + mapa GeoJSON
---
## 16. Gantt Chart
**Quando usar:** Planejamento, cronogramas, gestão de projetos.
**Requer:** `gantt/highcharts-gantt.js` (substitui highcharts.js)
---
## 17. Outros Tipos
- **Lollipop**: `modules/lollipop.js` — barras com dot no final
- **Dumbbell**: `modules/dumbbell.js` — antes/depois, range entre dois pontos
- **Timeline**: `modules/timeline.js` — eventos ao longo do tempo
- **Venn**: `modules/venn.js` — diagramas de Venn
- **Waterfall**: tipo `waterfall` — decomposição de valores
- **Polar / Spider**: usando `chart: { polar: true }` — comparação multidimensional
- **3D Charts**: usando `highcharts-3d.js` — versões 3D de column, pie, scatter
---
## Combinando Gráficos (Dual Axis / Mixed)
```javascript
{
yAxis: [
{ title: { text: 'Receita (R$)' } },
{ title: { text: 'Unidades' }, opposite: true }
],
series: [
{ type: 'column', name: 'Unidades', data: [...], yAxis: 1 },
{ type: 'spline', name: 'Receita', data: [...], yAxis: 0 }
]
}
```
## Drilldown
**Requer:** `modules/drilldown.js`
```javascript
{
series: [{
name: 'Categorias',
data: [
{ name: 'Frutas', y: 55, drilldown: 'frutas' },
{ name: 'Vegetais', y: 25, drilldown: 'vegetais' }
]
}],
drilldown: {
series: [
{ id: 'frutas', data: [['Maçã',30],['Banana',15],['Laranja',10]] },
{ id: 'vegetais', data: [['Cenoura',10],['Tomate',8],['Alface',7]] }
]
}
}
```
+99
agents/reversa-highcharts-visualizer/references/ERRORS.md
# Tratamento de Erros — Highcharts Visualizer
## Dados insuficientes ou vazios
**Sintoma:** Gráfico renderiza vazio ou com mensagem "No data to display".
**Ação:** Configurar `noData` module ou verificar os dados antes de criar o gráfico:
```javascript
// Incluir: modules/no-data-to-display.js
lang: { noData: 'Nenhum dado disponível para exibir' },
noData: { style: { fontWeight: 'bold', fontSize: '16px', color: '#666' } }
```
Avisar o usuário:
> "Os dados fornecidos parecem estar vazios ou não foram processados corretamente. Poderia verificar?"
## Formato de dados incompatível
**Sintoma:** Erro no console ou gráfico com valores NaN/undefined.
**Ação:** Validar dados com `scripts/parse_data.py` antes de embutir. O script converte automaticamente
strings numéricas ("1.234,56" → 1234.56) e datas em múltiplos formatos.
## Módulo CDN não carrega
**Sintoma:** Erro "Highcharts is not defined" ou tipo de gráfico não reconhecido.
**Ação:** Verificar ordem dos scripts. O core `highcharts.js` deve vir primeiro, depois os módulos.
Para Stock/Maps/Gantt, usar o respectivo script principal (highstock.js, highmaps.js, highcharts-gantt.js)
**no lugar de** highcharts.js, não junto.
Ordem correta:
```html
<script src="https://code.highcharts.com/highcharts.js"></script>
<script src="https://code.highcharts.com/highcharts-more.js"></script>
<script src="https://code.highcharts.com/modules/solid-gauge.js"></script>
<script src="https://code.highcharts.com/modules/exporting.js"></script>
<script src="https://code.highcharts.com/modules/accessibility.js"></script>
```
## Gráfico não responsivo
**Sintoma:** Gráfico não redimensiona com a janela, ou fica cortado.
**Ação:** Não definir `chart.width` fixo. Usar container com CSS responsivo.
Garantir que `chart.reflow` não está desabilitado.
```javascript
chart: {
// NÃO definir width/height fixos
// Deixar o Highcharts adaptar ao container
reflow: true
}
```
## Performance lenta com muitos dados
**Sintoma:** Gráfico travando ou demorando para renderizar com >10.000 pontos.
**Ação:**
1. Incluir `modules/boost.js`
2. Setar `boostThreshold: 5000` na série
3. Desabilitar animações: `plotOptions: { series: { animation: false } }`
4. Desabilitar markers: `marker: { enabled: false }`
5. Considerar agregar dados (downsampling) via `scripts/analyze_data.py`
## Tooltips com valores incorretos
**Sintoma:** Tooltip mostra "undefined" ou formato errado.
**Ação:** Verificar se os dados estão no formato correto para o tipo de gráfico.
Usar `tooltip.formatter` customizado para ter controle total sobre o formato.
## Cores ilegíveis
**Sintoma:** Séries ou labels com contraste insuficiente.
**Ação:** Usar `Highcharts.getOptions().colors` para verificar a paleta ativa.
Para dark mode, garantir que labels/grid/tick tem cores claras.
O módulo de accessibility alerta sobre problemas de contraste.
## CSV com encoding diferente (UTF-8 BOM, Latin1)
**Sintoma:** Caracteres especiais (acentos) aparecem como "�" ou "é".
**Ação:** O `scripts/parse_data.py` tenta detectar encoding automaticamente.
Se falhar, forçar encoding:
```bash
python scripts/parse_data.py dados.csv --encoding latin1
```
## Arquivo Excel com múltiplas abas
**Sintoma:** Dados extraídos são de aba errada.
**Ação:**
```bash
python scripts/parse_data.py dados.xlsx --sheet "Planilha2"
```
+347
agents/reversa-hig...lizer/references/HIGHCHARTS_PATTERNS.md
# Padrões Highcharts.js
Referência de padrões de código testados para gerar gráficos Highcharts profissionais.
---
## Template HTML Completo
```html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>[Título do Gráfico]</title>
<!-- Highcharts Core (obrigatório) -->
<script src="https://code.highcharts.com/highcharts.js"></script>
<!-- Módulos extras conforme necessidade (ver tabela no SKILL.md) -->
<script src="https://code.highcharts.com/modules/exporting.js"></script>
<script src="https://code.highcharts.com/modules/export-data.js"></script>
<script src="https://code.highcharts.com/modules/accessibility.js"></script>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: #f5f7fa;
padding: 20px;
}
#container {
max-width: 900px;
margin: 0 auto;
background: #fff;
border-radius: 12px;
box-shadow: 0 2px 20px rgba(0,0,0,0.08);
padding: 10px;
}
/* Para múltiplos gráficos (dashboard) */
.chart-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
gap: 20px;
max-width: 1200px;
margin: 0 auto;
}
.chart-card {
background: #fff;
border-radius: 12px;
box-shadow: 0 2px 20px rgba(0,0,0,0.08);
padding: 10px;
}
</style>
</head>
<body>
<div id="container"></div>
<script>
Highcharts.chart('container', {
// Opções do gráfico aqui
});
</script>
</body>
</html>
```
## Opções Globais Recomendadas
Aplicar antes de criar qualquer gráfico:
```javascript
Highcharts.setOptions({
lang: {
months: ['Janeiro','Fevereiro','Março','Abril','Maio','Junho',
'Julho','Agosto','Setembro','Outubro','Novembro','Dezembro'],
shortMonths: ['Jan','Fev','Mar','Abr','Mai','Jun',
'Jul','Ago','Set','Out','Nov','Dez'],
weekdays: ['Domingo','Segunda','Terça','Quarta','Quinta','Sexta','Sábado'],
decimalPoint: ',',
thousandsSep: '.',
loading: 'Carregando...',
noData: 'Sem dados para exibir',
downloadPNG: 'Baixar como PNG',
downloadJPEG: 'Baixar como JPEG',
downloadPDF: 'Baixar como PDF',
downloadSVG: 'Baixar como SVG',
downloadCSV: 'Baixar como CSV',
downloadXLS: 'Baixar como XLS',
viewData: 'Ver tabela de dados',
printChart: 'Imprimir gráfico',
viewFullscreen: 'Tela cheia',
exitFullscreen: 'Sair da tela cheia',
contextButtonTitle: 'Menu do gráfico'
}
});
```
## Paletas de Cores Profissionais
```javascript
// Paleta padrão Highcharts (boa para maioria dos casos)
// É a padrão, não precisa definir
// Paleta Corporate Blue
colors: ['#2f7ed8','#0d233a','#8bbc21','#910000','#1aadce',
'#492970','#f28f43','#77a1e5','#c42525','#a6c96a']
// Paleta Vibrante Moderna
colors: ['#6366f1','#8b5cf6','#ec4899','#f43f5e','#f97316',
'#eab308','#22c55e','#06b6d4','#3b82f6','#a855f7']
// Paleta Dark Mode
colors: ['#7cb5ec','#90ed7d','#f7a35c','#8085e9','#f15c80',
'#e4d354','#2b908f','#f45b5b','#91e8e1','#b2e87e']
// Paleta Earth Tones
colors: ['#8c564b','#e377c2','#7f7f7f','#bcbd22','#17becf',
'#d62728','#1f77b4','#ff7f0e','#2ca02c','#9467bd']
```
## Tema Dark Mode Completo
```javascript
const darkTheme = {
chart: {
backgroundColor: '#1a1a2e',
style: { fontFamily: "'Segoe UI', Roboto, sans-serif" }
},
title: { style: { color: '#e0e0e0' } },
subtitle: { style: { color: '#a0a0a0' } },
xAxis: {
gridLineColor: '#2a2a4a',
labels: { style: { color: '#b0b0b0' } },
lineColor: '#3a3a5a',
tickColor: '#3a3a5a',
title: { style: { color: '#c0c0c0' } }
},
yAxis: {
gridLineColor: '#2a2a4a',
labels: { style: { color: '#b0b0b0' } },
title: { style: { color: '#c0c0c0' } }
},
legend: {
itemStyle: { color: '#c0c0c0' },
itemHoverStyle: { color: '#fff' }
},
tooltip: {
backgroundColor: 'rgba(20,20,40,0.95)',
borderColor: '#4a4a6a',
style: { color: '#e0e0e0' }
},
plotOptions: {
series: {
dataLabels: { color: '#c0c0c0' }
}
},
credits: { style: { color: '#555' } }
};
// Aplicar tema globalmente
Highcharts.setOptions(darkTheme);
```
## Tooltip Formatado (Padrões Úteis)
```javascript
// Tooltip com moeda brasileira
tooltip: {
pointFormat: '{series.name}: <b>R$ {point.y:,.2f}</b><br/>',
shared: true,
useHTML: true
}
// Tooltip com percentual
tooltip: {
pointFormat: '{series.name}: <b>{point.y:.1f}%</b><br/>'
}
// Tooltip customizado com HTML
tooltip: {
useHTML: true,
formatter: function() {
return `<div style="padding:8px">
<b style="font-size:14px">${this.key}</b><br/>
<span style="color:${this.color}">●</span>
${this.series.name}: <b>${Highcharts.numberFormat(this.y, 0, ',', '.')}</b>
</div>`;
}
}
// Tooltip compartilhado (múltiplas séries)
tooltip: {
shared: true,
crosshairs: true,
borderRadius: 8,
shadow: true
}
```
## Formatação de Eixos
```javascript
// Eixo Y com moeda
yAxis: {
title: { text: 'Receita' },
labels: {
formatter: function() {
return 'R$ ' + Highcharts.numberFormat(this.value, 0, ',', '.');
}
}
}
// Eixo X temporal
xAxis: {
type: 'datetime',
dateTimeLabelFormats: {
month: '%b %Y',
year: '%Y'
}
}
// Eixo com categorias rotacionadas
xAxis: {
categories: [...],
labels: { rotation: -45, style: { fontSize: '11px' } }
}
```
## Animações
```javascript
// Animação de entrada
plotOptions: {
series: {
animation: {
duration: 1500,
easing: 'easeOutBounce'
}
}
}
// Animação staggered (cada série com delay)
plotOptions: {
series: {
animation: { duration: 1000 },
// cada ponto aparece com delay
dataSorting: { enabled: true }
}
}
```
## Responsividade
```javascript
responsive: {
rules: [{
condition: { maxWidth: 500 },
chartOptions: {
legend: { layout: 'horizontal', align: 'center', verticalAlign: 'bottom' },
yAxis: { title: { text: null } },
subtitle: { text: null }
}
}]
}
```
## Dashboard com Múltiplos Gráficos
```html
<div class="chart-grid">
<div class="chart-card" id="chart1"></div>
<div class="chart-card" id="chart2"></div>
<div class="chart-card" id="chart3"></div>
<div class="chart-card" id="chart4"></div>
</div>
<script>
// KPI cards + gráficos em grid
Highcharts.chart('chart1', { /* opções */ });
Highcharts.chart('chart2', { /* opções */ });
Highcharts.chart('chart3', { /* opções */ });
Highcharts.chart('chart4', { /* opções */ });
</script>
```
## Dados Grandes (Boost Module)
```javascript
// Para séries com >10.000 pontos
// Incluir: <script src="https://code.highcharts.com/modules/boost.js"></script>
{
boost: { useGPUTranslations: true },
series: [{
boostThreshold: 5000, // ativar boost acima de 5k pontos
data: massiveDataArray
}]
}
```
## Eventos Úteis
```javascript
chart: {
events: {
load: function() {
// Executar após gráfico renderizar
console.log('Gráfico carregado');
},
redraw: function() {
// Após resize ou update
}
}
},
plotOptions: {
series: {
events: {
click: function(e) {
alert(e.point.category + ': ' + e.point.y);
}
},
point: {
events: {
mouseOver: function() {
// Highlight on hover
}
}
}
}
}
```
## Anotações
```javascript
// Requer: modules/annotations.js
annotations: [{
labels: [{
point: { x: 3, y: 150, xAxis: 0, yAxis: 0 },
text: 'Ponto importante!',
backgroundColor: 'rgba(255,255,255,0.9)',
borderColor: '#666',
shape: 'callout'
}],
labelOptions: {
borderRadius: 5,
padding: 10
}
}]
```
+219
agents/reversa-highcharts-visualizer/scripts/analyze_data.py
#!/usr/bin/env python3
"""
Analisa dados e sugere o melhor tipo de gráfico Highcharts.
Calcula estatísticas descritivas e infere a natureza dos dados
para recomendar tipos de gráfico adequados.
Uso:
python analyze_data.py <arquivo> [--format json|text]
python analyze_data.py dados.csv --suggest-chart
Saída:
Estatísticas + sugestões de tipos de gráfico.
"""
import sys
import json
import argparse
import re
from pathlib import Path
def is_temporal(values: list) -> bool:
"""Detecta se uma lista de valores parece ser temporal."""
date_patterns = [
r'\d{4}[-/]\d{1,2}[-/]\d{1,2}', # 2024-01-15
r'\d{1,2}[-/]\d{1,2}[-/]\d{4}', # 15/01/2024
r'(Jan|Fev|Mar|Abr|Mai|Jun|Jul|Ago|Set|Out|Nov|Dez)',
r'(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)',
r'Q[1-4]\s*\d{4}', # Q1 2024
r'\d{4}', # Apenas anos
]
if not values:
return False
matches = 0
sample = values[:20]
for v in sample:
for pattern in date_patterns:
if re.search(pattern, str(v), re.IGNORECASE):
matches += 1
break
return matches / len(sample) > 0.6
def analyze_series(values: list) -> dict:
"""Analisa uma série de valores numéricos."""
nums = [v for v in values if isinstance(v, (int, float)) and v is not None]
if not nums:
return {"type": "non_numeric", "count": len(values)}
nums.sort()
n = len(nums)
total = sum(nums)
mean = total / n
variance = sum((x - mean) ** 2 for x in nums) / n
return {
"type": "numeric",
"count": n,
"min": min(nums),
"max": max(nums),
"mean": round(mean, 2),
"median": nums[n // 2],
"std": round(variance ** 0.5, 2),
"sum": round(total, 2),
"has_negatives": any(x < 0 for x in nums),
"all_integers": all(x == int(x) for x in nums),
"all_positive": all(x >= 0 for x in nums),
"range": max(nums) - min(nums),
"unique_values": len(set(nums))
}
def suggest_charts(categories: list, series_analysis: list, n_series: int) -> list:
"""Sugere tipos de gráfico com base na análise."""
suggestions = []
temporal = is_temporal(categories)
n_categories = len(categories)
all_positive = all(s.get("all_positive", True) for s in series_analysis)
# Dados temporais → line/area
if temporal:
suggestions.append({
"type": "line", "score": 95,
"reason": "Dados temporais — ideal para mostrar tendência ao longo do tempo"
})
suggestions.append({
"type": "area", "score": 85,
"reason": "Dados temporais — área enfatiza volume/magnitude"
})
if n_series > 1 and all_positive:
suggestions.append({
"type": "stacked_area", "score": 80,
"reason": "Múltiplas séries temporais — mostra composição ao longo do tempo"
})
# Poucos pontos categóricos → column/bar
if n_categories <= 20:
suggestions.append({
"type": "column", "score": 90 if not temporal else 70,
"reason": f"{n_categories} categorias — bom para comparação direta"
})
if n_categories > 8:
suggestions.append({
"type": "bar", "score": 85,
"reason": "Muitas categorias — barras horizontais facilitam leitura dos labels"
})
# Uma série com poucos itens → pie
if n_series == 1 and n_categories <= 8 and all_positive:
suggestions.append({
"type": "pie", "score": 80,
"reason": "Uma série com poucas categorias — mostra proporção/composição"
})
# Duas séries numéricas → scatter
if n_series >= 2 and all(s.get("type") == "numeric" for s in series_analysis):
suggestions.append({
"type": "scatter", "score": 70,
"reason": "Múltiplas séries numéricas — mostra correlação entre variáveis"
})
# Muitos dados → considerar heatmap
if n_categories > 20 and n_series > 5:
suggestions.append({
"type": "heatmap", "score": 75,
"reason": "Muitas categorias × séries — heatmap revela padrões matriciais"
})
# KPI único → gauge
if n_series == 1 and n_categories == 1:
suggestions.append({
"type": "solidgauge", "score": 85,
"reason": "Valor único — ideal para KPI/indicador de progresso"
})
# Stacked para composição
if n_series > 1 and n_categories <= 15 and all_positive:
suggestions.append({
"type": "stacked_column", "score": 75,
"reason": "Múltiplas séries positivas — mostra composição por categoria"
})
# Ordenar por score
suggestions.sort(key=lambda x: x["score"], reverse=True)
return suggestions[:5]
def main():
parser = argparse.ArgumentParser(description="Analisa dados e sugere gráficos")
parser.add_argument("filepath", help="Caminho do arquivo")
parser.add_argument("--format", choices=["json", "text"], default="json")
parser.add_argument("--suggest-chart", action="store_true", default=True)
parser.add_argument("--encoding", default=None)
parser.add_argument("--sheet", default=None)
args = parser.parse_args()
# Importar parse_data do mesmo diretório
script_dir = Path(__file__).parent
sys.path.insert(0, str(script_dir))
from parse_data import parse_csv, parse_json_data, parse_excel, detect_encoding
path = Path(args.filepath)
ext = path.suffix.lower()
if ext in ('.csv', '.tsv', '.txt'):
enc = args.encoding or detect_encoding(str(path))
parsed = parse_csv(str(path), encoding=enc)
elif ext == '.json':
parsed = parse_json_data(str(path))
elif ext in ('.xlsx', '.xls'):
parsed = parse_excel(str(path), sheet=args.sheet)
else:
print(f"[ERRO] Formato não suportado: {ext}", file=sys.stderr)
sys.exit(1)
if "error" in parsed:
print(f"[ERRO] {parsed['error']}", file=sys.stderr)
sys.exit(1)
# Analisar cada série
series_analysis = []
for s in parsed.get("series", []):
analysis = analyze_series(s["data"])
analysis["name"] = s["name"]
series_analysis.append(analysis)
# Sugerir gráficos
categories = parsed.get("categories", [])
suggestions = suggest_charts(categories, series_analysis, len(series_analysis))
result = {
"data_summary": {
"categories_count": len(categories),
"series_count": len(series_analysis),
"is_temporal": is_temporal(categories),
"sample_categories": categories[:5]
},
"series_analysis": series_analysis,
"chart_suggestions": suggestions
}
if args.format == "json":
print(json.dumps(result, ensure_ascii=False, indent=2))
else:
print(f"=== Resumo dos Dados ===")
print(f"Categorias: {len(categories)} ({'temporal' if is_temporal(categories) else 'categórico'})")
print(f"Séries: {len(series_analysis)}")
for s in series_analysis:
print(f" • {s['name']}: min={s.get('min')}, max={s.get('max')}, "
f"média={s.get('mean')}, {s.get('count')} pontos")
print(f"\n=== Gráficos Sugeridos ===")
for i, sug in enumerate(suggestions, 1):
print(f" {i}. {sug['type']} (score: {sug['score']})")
print(f" {sug['reason']}")
if __name__ == "__main__":
main()
+246
agents/reversa-highcharts-visualizer/scripts/parse_data.py
#!/usr/bin/env python3
"""
Parseia dados de CSV, JSON ou Excel e formata para uso em Highcharts.
Detecta automaticamente o formato, encoding, e estrutura dos dados.
Saída: JSON pronto para ser embutido nas opções do Highcharts.
Uso:
python parse_data.py <arquivo> [--format categories|timeseries|xy|pie]
python parse_data.py dados.csv --sheet "Plan1" --encoding utf-8
python parse_data.py dados.json --output formatted.json
Saída:
JSON com: { categories, series, metadata }
"""
import sys
import json
import argparse
from pathlib import Path
def detect_encoding(filepath: str) -> str:
"""Tenta detectar encoding do arquivo."""
encodings = ['utf-8', 'utf-8-sig', 'latin1', 'iso-8859-1', 'cp1252']
for enc in encodings:
try:
with open(filepath, 'r', encoding=enc) as f:
f.read(1000)
return enc
except (UnicodeDecodeError, UnicodeError):
continue
return 'utf-8'
def parse_number(value: str) -> float | None:
"""Converte string para número, tratando formatos BR e US."""
if not value or not isinstance(value, str):
return value if isinstance(value, (int, float)) else None
value = value.strip().replace(' ', '')
# Formato BR: 1.234,56
if ',' in value and '.' in value and value.rindex(',') > value.rindex('.'):
value = value.replace('.', '').replace(',', '.')
# Formato BR sem milhar: 123,45
elif ',' in value and '.' not in value:
value = value.replace(',', '.')
# Remover símbolos de moeda
for symbol in ['R$', '$', '€', '£', '%']:
value = value.replace(symbol, '')
try:
return float(value)
except ValueError:
return None
def parse_csv(filepath: str, encoding: str = 'utf-8', delimiter: str = None) -> dict:
"""Parseia CSV para formato Highcharts."""
import csv
with open(filepath, 'r', encoding=encoding) as f:
content = f.read()
# Detectar delimitador
if delimiter is None:
sniffer = csv.Sniffer()
try:
dialect = sniffer.sniff(content[:2000])
delimiter = dialect.delimiter
except csv.Error:
delimiter = ',' if ',' in content else ';' if ';' in content else '\t'
lines = content.strip().split('\n')
reader = csv.reader(lines, delimiter=delimiter)
rows = list(reader)
if len(rows) < 2:
return {"error": "Arquivo com menos de 2 linhas"}
headers = [h.strip() for h in rows[0]]
data_rows = rows[1:]
# Primeira coluna = categorias, demais = séries
categories = [row[0].strip() for row in data_rows if row]
series = []
for col_idx in range(1, len(headers)):
values = []
for row in data_rows:
if col_idx < len(row):
val = parse_number(row[col_idx])
values.append(val if val is not None else 0)
else:
values.append(0)
series.append({
"name": headers[col_idx],
"data": values
})
return {
"categories": categories,
"series": series,
"metadata": {
"rows": len(data_rows),
"columns": len(headers),
"headers": headers,
"delimiter": delimiter,
"encoding": encoding
}
}
def parse_json_data(filepath: str) -> dict:
"""Parseia JSON para formato Highcharts."""
with open(filepath, 'r', encoding='utf-8') as f:
data = json.load(f)
# Se já é formato Highcharts, retornar direto
if isinstance(data, dict) and 'series' in data:
return data
# Se é array de objetos [{x: ..., y: ...}]
if isinstance(data, list) and len(data) > 0 and isinstance(data[0], dict):
keys = list(data[0].keys())
category_key = keys[0]
categories = [str(item.get(category_key, '')) for item in data]
series = []
for key in keys[1:]:
values = [parse_number(str(item.get(key, 0))) or 0 for item in data]
series.append({"name": key, "data": values})
return {
"categories": categories,
"series": series,
"metadata": {"rows": len(data), "keys": keys, "format": "array_of_objects"}
}
# Se é array de arrays [[cat, v1, v2], ...]
if isinstance(data, list) and len(data) > 0 and isinstance(data[0], list):
categories = [str(row[0]) for row in data[1:]]
headers = data[0]
series = []
for col_idx in range(1, len(headers)):
values = [parse_number(str(row[col_idx])) or 0
for row in data[1:] if col_idx < len(row)]
series.append({"name": str(headers[col_idx]), "data": values})
return {
"categories": categories,
"series": series,
"metadata": {"rows": len(data) - 1, "format": "array_of_arrays"}
}
return {"error": "Formato JSON não reconhecido", "raw": data}
def parse_excel(filepath: str, sheet: str = None) -> dict:
"""Parseia Excel para formato Highcharts."""
from openpyxl import load_workbook
wb = load_workbook(filepath, read_only=True, data_only=True)
if sheet:
ws = wb[sheet]
else:
ws = wb.active
rows = list(ws.iter_rows(values_only=True))
if len(rows) < 2:
return {"error": "Planilha com menos de 2 linhas"}
headers = [str(h).strip() if h else f"Col_{i}" for i, h in enumerate(rows[0])]
data_rows = rows[1:]
categories = [str(row[0]).strip() if row[0] else '' for row in data_rows]
series = []
for col_idx in range(1, len(headers)):
values = []
for row in data_rows:
val = row[col_idx] if col_idx < len(row) else 0
if isinstance(val, (int, float)):
values.append(val)
else:
parsed = parse_number(str(val)) if val else 0
values.append(parsed or 0)
series.append({"name": headers[col_idx], "data": values})
return {
"categories": categories,
"series": series,
"metadata": {
"rows": len(data_rows),
"columns": len(headers),
"headers": headers,
"sheet": ws.title,
"sheets_available": wb.sheetnames
}
}
def main():
parser = argparse.ArgumentParser(description="Parseia dados para formato Highcharts")
parser.add_argument("filepath", help="Caminho do arquivo de dados")
parser.add_argument("--encoding", default=None, help="Encoding do arquivo CSV")
parser.add_argument("--delimiter", default=None, help="Delimitador CSV")
parser.add_argument("--sheet", default=None, help="Nome da aba Excel")
parser.add_argument("--output", "-o", help="Salvar resultado em arquivo")
args = parser.parse_args()
path = Path(args.filepath)
if not path.exists():
print(f"[ERRO] Arquivo não encontrado: {path}", file=sys.stderr)
sys.exit(1)
ext = path.suffix.lower()
if ext in ('.csv', '.tsv', '.txt'):
encoding = args.encoding or detect_encoding(str(path))
result = parse_csv(str(path), encoding=encoding, delimiter=args.delimiter)
elif ext == '.json':
result = parse_json_data(str(path))
elif ext in ('.xlsx', '.xls'):
result = parse_excel(str(path), sheet=args.sheet)
else:
print(f"[ERRO] Formato não suportado: {ext}", file=sys.stderr)
sys.exit(1)
if "error" in result:
print(f"[ERRO] {result['error']}", file=sys.stderr)
sys.exit(1)
meta = result.get("metadata", {})
print(f"[INFO] Linhas: {meta.get('rows', '?')}, "
f"Colunas: {meta.get('columns', len(result.get('series', [])) + 1)}", file=sys.stderr)
if 'series' in result:
for s in result['series']:
print(f"[INFO] Série '{s['name']}': {len(s['data'])} pontos", file=sys.stderr)
output = json.dumps(result, ensure_ascii=False, indent=2)
if args.output:
with open(args.output, 'w', encoding='utf-8') as f:
f.write(output)
print(f"[INFO] Salvo em: {args.output}", file=sys.stderr)
else:
print(output)
if __name__ == "__main__":
main()
+208
agents/reversa-highcharts-visualizer/scripts/sample_data.py
#!/usr/bin/env python3
"""
Gera dados de exemplo prontos para diferentes tipos de gráfico Highcharts.
Útil quando o usuário quer explorar um tipo de gráfico sem ter dados reais.
Uso:
python sample_data.py --type line
python sample_data.py --type pie --items 6
python sample_data.py --type stock --days 365
python sample_data.py --type sankey
python sample_data.py --list (lista todos os tipos)
Saída:
JSON com opções Highcharts prontas para usar.
"""
import sys
import json
import random
import argparse
from datetime import datetime, timedelta
def sample_line(months: int = 12, series_count: int = 2) -> dict:
"""Dados de exemplo para line/spline/area chart."""
months_list = ['Jan','Fev','Mar','Abr','Mai','Jun',
'Jul','Ago','Set','Out','Nov','Dez'][:months]
series = []
for i in range(series_count):
base = random.randint(50, 200)
data = [round(base + random.gauss(0, 20) + j * random.uniform(-2, 5), 1)
for j in range(months)]
series.append({"name": f"Série {chr(65+i)}", "data": data})
return {"categories": months_list, "series": series, "suggested_type": "line"}
def sample_column(categories: int = 6, series_count: int = 2) -> dict:
"""Dados de exemplo para column/bar chart."""
cats = [f"Categoria {chr(65+i)}" for i in range(categories)]
series = []
for i in range(series_count):
data = [random.randint(20, 150) for _ in range(categories)]
series.append({"name": f"Grupo {i+1}", "data": data})
return {"categories": cats, "series": series, "suggested_type": "column"}
def sample_pie(items: int = 6) -> dict:
"""Dados de exemplo para pie/donut chart."""
names = ['Tecnologia', 'Saúde', 'Finanças', 'Educação',
'Varejo', 'Indústria', 'Energia', 'Transporte'][:items]
values = [random.randint(5, 35) for _ in range(items)]
total = sum(values)
data = [{"name": n, "y": round(v / total * 100, 1)} for n, v in zip(names, values)]
# Destacar o maior
max_idx = max(range(len(data)), key=lambda i: data[i]["y"])
data[max_idx]["sliced"] = True
data[max_idx]["selected"] = True
return {"series": [{"name": "Participação", "colorByPoint": True, "data": data}],
"suggested_type": "pie"}
def sample_scatter(points: int = 50) -> dict:
"""Dados de exemplo para scatter chart."""
data_a = [[round(random.gauss(5, 2), 1), round(random.gauss(5, 2), 1)]
for _ in range(points)]
data_b = [[round(random.gauss(8, 1.5), 1), round(random.gauss(3, 1.5), 1)]
for _ in range(points)]
return {"series": [
{"name": "Grupo A", "data": data_a},
{"name": "Grupo B", "data": data_b}
], "suggested_type": "scatter"}
def sample_heatmap(rows: int = 7, cols: int = 12) -> dict:
"""Dados de exemplo para heatmap."""
row_cats = ['Seg','Ter','Qua','Qui','Sex','Sáb','Dom'][:rows]
col_cats = ['Jan','Fev','Mar','Abr','Mai','Jun',
'Jul','Ago','Set','Out','Nov','Dez'][:cols]
data = [[x, y, random.randint(0, 100)] for x in range(cols) for y in range(rows)]
return {
"xCategories": col_cats, "yCategories": row_cats,
"series": [{"data": data}], "suggested_type": "heatmap"
}
def sample_sankey() -> dict:
"""Dados de exemplo para Sankey diagram."""
data = [
['Marketing', 'Leads', 1000],
['Vendas Diretas', 'Leads', 500],
['Indicação', 'Leads', 300],
['Leads', 'Qualificados', 900],
['Leads', 'Descartados', 900],
['Qualificados', 'Proposta', 600],
['Qualificados', 'Perdidos', 300],
['Proposta', 'Fechados', 400],
['Proposta', 'Perdidos', 200],
]
return {
"series": [{"keys": ["from", "to", "weight"], "data": data}],
"suggested_type": "sankey"
}
def sample_gauge(value: float = None) -> dict:
"""Dados de exemplo para gauge/solid gauge."""
val = value or round(random.uniform(30, 95), 1)
return {
"series": [{"name": "Performance", "data": [val]}],
"suggested_type": "solidgauge",
"min": 0, "max": 100
}
def sample_treemap() -> dict:
"""Dados de exemplo para treemap."""
data = [
{"name": "Brasil", "value": 211, "colorValue": 1},
{"name": "México", "value": 128, "colorValue": 2},
{"name": "Colômbia", "value": 50, "colorValue": 3},
{"name": "Argentina", "value": 45, "colorValue": 4},
{"name": "Peru", "value": 32, "colorValue": 5},
{"name": "Venezuela", "value": 28, "colorValue": 6},
{"name": "Chile", "value": 19, "colorValue": 7},
{"name": "Equador", "value": 17, "colorValue": 8},
]
return {"series": [{"data": data}], "suggested_type": "treemap"}
def sample_stock(days: int = 365) -> dict:
"""Dados de exemplo para stock chart (OHLC)."""
start = datetime(2024, 1, 1)
price = 150.0
data = []
for i in range(days):
date = start + timedelta(days=i)
if date.weekday() >= 5:
continue
o = round(price + random.gauss(0, 2), 2)
h = round(o + abs(random.gauss(0, 3)), 2)
l = round(o - abs(random.gauss(0, 3)), 2)
c = round(random.uniform(l, h), 2)
price = c
ts = int(date.timestamp() * 1000)
data.append([ts, o, h, l, c])
return {"series": [{"type": "candlestick", "name": "ACME", "data": data}],
"suggested_type": "stock"}
def sample_funnel() -> dict:
"""Dados de exemplo para funnel chart."""
data = [
['Visitantes do Site', 15654],
['Downloads', 4064],
['Cadastros', 1987],
['Trial Ativo', 976],
['Compra', 846]
]
return {"series": [{"data": data}], "suggested_type": "funnel"}
GENERATORS = {
"line": sample_line, "spline": sample_line, "area": sample_line,
"column": sample_column, "bar": sample_column,
"pie": sample_pie, "donut": sample_pie,
"scatter": sample_scatter, "bubble": sample_scatter,
"heatmap": sample_heatmap,
"sankey": sample_sankey,
"gauge": sample_gauge, "solidgauge": sample_gauge,
"treemap": sample_treemap,
"stock": sample_stock, "candlestick": sample_stock,
"funnel": sample_funnel, "pyramid": sample_funnel,
}
def main():
parser = argparse.ArgumentParser(description="Gera dados de exemplo para Highcharts")
parser.add_argument("--type", "-t", choices=list(GENERATORS.keys()),
help="Tipo de gráfico")
parser.add_argument("--list", "-l", action="store_true", help="Lista tipos disponíveis")
parser.add_argument("--output", "-o", help="Salvar em arquivo")
args = parser.parse_args()
if args.list:
print("Tipos disponíveis:")
for t in sorted(set(GENERATORS.keys())):
print(f" • {t}")
return
if not args.type:
parser.print_help()
sys.exit(1)
generator = GENERATORS[args.type]
result = generator()
output = json.dumps(result, ensure_ascii=False, indent=2)
if args.output:
with open(args.output, 'w', encoding='utf-8') as f:
f.write(output)
print(f"[INFO] Salvo em: {args.output}", file=sys.stderr)
else:
print(output)
if __name__ == "__main__":
main()
+143
agents/reversa-highcharts-visualizer/SKILL.md
---
name: reversa-highcharts-visualizer
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: charts-renderer
description: >
Cria visualizações de dados interativas e profissionais usando Highcharts.js, gerando
HTML standalone com gráficos animados, responsivos e acessíveis. Use este skill sempre que
o usuário pedir para criar gráficos, charts, dashboards, visualizações de dados, ou qualquer
representação visual de dados numéricos/categóricos. Deve ser usado quando o usuário mencionar
termos como "gráfico", "chart", "dashboard", "highcharts", "visualização de dados",
"gráfico de linhas", "barras", "pizza", "scatter", "heatmap", "treemap", "gauge", "stock chart",
"mapa", "gantt", "sankey", "funnel", ou quando fornecer dados (CSV, JSON, tabela, planilha)
pedindo representação visual. Também deve ser ativado quando o usuário pedir gráficos bonitos,
interativos, animados, com tooltip, drill-down, ou exportáveis. Funciona com dados inline,
CSV, JSON, e arquivos de dados. Sempre gera HTML standalone completo e funcional.
---
# Highcharts Visualizer
Cria visualizações de dados profissionais usando Highcharts.js. Gera sempre **HTML standalone**
(arquivo único, self-contained) com gráficos interativos, animados, responsivos e acessíveis.
## Fluxo de Trabalho
### 1. Receber os Dados
Os dados podem vir de:
- **Inline na conversa** → Usuário cola dados, tabela, lista de valores
- **CSV/JSON enviado** → Analise o conteúdo usando `view_file` e injete os dados diretamente no HTML gerado. Nunca crie scripts em Python.
- **Planilha Excel** → Extraia os dados das tabelas e injete-os no HTML. Não use Python.
- **Dados de exemplo** → Quando o usuário quer explorar um tipo de gráfico sem dados reais
- **URL de dados** → Usar `web_fetch` para buscar dados remotos
### 2. Analisar os Dados
Antes de gerar o gráfico, entender a natureza dos dados:
- **Dimensões**: quantas séries? Quantas categorias? Temporal ou categórico?
- **Escala**: range dos valores, outliers, distribuição
- **Relações**: comparação, composição, distribuição, tendência, correlação
- **Volume**: poucos pontos (<100), médio (100-10K), grande (>10K — usar boost module)
Analise os dados internamente após a leitura e injete as tags via string. Não crie programas Python intermediários.
### 3. Escolher o Tipo de Gráfico
Consultar `references/CHART_CATALOG.md` para o catálogo completo de 40+ tipos de gráfico,
com orientação de quando usar cada um.
**Regra de decisão rápida:**
| Objetivo | Tipos recomendados |
|----------|-------------------|
| Tendência ao longo do tempo | line, area, spline, areaspline |
| Comparação entre categorias | column, bar, lollipop, bullet |
| Composição / proporção | pie, donut, stacked column, stacked area, treemap, sunburst |
| Distribuição | histogram, box plot, scatter, bell curve |
| Correlação | scatter, bubble, heatmap |
| Fluxo / processo | sankey, dependency wheel, network graph |
| Hierarquia | treemap, sunburst, organization chart |
| Geográfico | map (Highcharts Maps module) |
| Financeiro / timeline | stock chart (candlestick, OHLC, flags) |
| Progresso / KPI | gauge, solid gauge, activity gauge |
| Projeto / planejamento | gantt chart |
| Funil / conversão | funnel, pyramid |
Se o usuário não especificou o tipo, sugerir 2-3 opções que melhor representam os dados.
### 4. Gerar o Código
Consultar `references/HIGHCHARTS_PATTERNS.md` para padrões de código testados.
**Regras fundamentais:**
1. **HTML standalone** — Arquivo único `.html` com Highcharts via CDN
2. **CDN versão estável** — Usar `https://code.highcharts.com/highcharts.js` (core)
3. **Módulos por demanda** — Só incluir scripts extras quando necessário (ver tabela de módulos)
4. **Accessibility sempre** — Sempre incluir `modules/accessibility.js`
5. **Exporting sempre** — Sempre incluir `modules/exporting.js` + `modules/export-data.js`
6. **Responsivo** — O gráfico deve se adaptar ao container/viewport
7. **Tema consistente** — Aplicar cores coesas e tipografia profissional
8. **Animação** — Habilitar animações de entrada e transições suaves
9. **Tooltips ricos** — Tooltips formatados, com unidades e contexto
10. **Dados grandes** — Para >10K pontos, incluir `modules/boost.js`
**Módulos CDN necessários por tipo de gráfico:**
| Recurso | Script CDN |
|---------|-----------|
| Core (obrigatório) | `highcharts.js` |
| Accessibility (obrigatório) | `modules/accessibility.js` |
| Exporting (obrigatório) | `modules/exporting.js` |
| Export Data | `modules/export-data.js` |
| Tipos avançados (gauge, polar, etc.) | `highcharts-more.js` |
| 3D | `highcharts-3d.js` |
| Solid Gauge | `modules/solid-gauge.js` |
| Treemap | `modules/treemap.js` |
| Sunburst | `modules/sunburst.js` |
| Sankey | `modules/sankey.js` |
| Heatmap | `modules/heatmap.js` |
| Funnel | `modules/funnel.js` |
| Dependency Wheel | `modules/dependency-wheel.js` |
| Network Graph | `modules/networkgraph.js` |
| Organization | `modules/organization.js` |
| Histogram/Bellcurve | `modules/histogram-bellcurve.js` |
| Bullet | `modules/bullet.js` |
| Timeline | `modules/timeline.js` |
| Wordcloud | `modules/wordcloud.js` |
| Venn | `modules/venn.js` |
| Drilldown | `modules/drilldown.js` |
| Annotations | `modules/annotations.js` |
| Boost (dados grandes) | `modules/boost.js` |
| Offline Exporting | `modules/offline-exporting.js` |
| Stock (candlestick, OHLC) | `/stock/highstock.js` (substitui highcharts.js) |
| Maps | `/maps/highmaps.js` (substitui highcharts.js) |
| Gantt | `/gantt/highcharts-gantt.js` (substitui highcharts.js) |
Todos os CDN no formato: `https://code.highcharts.com/{path}`
### 5. Salvar e Entregar
Salvar o HTML gerado diretamente na pasta de destino usando `write_to_file`. Sempre gere o arquivo HTML puro com todos os dados processados e injetados nas variáveis `<script>`. Não use trechos de Python.
## Diretrizes de Qualidade
- **Estética profissional**: cores coesas (usar paletas Highcharts ou custom), tipografia limpa, espaçamentos adequados
- **Dados formatados**: números com separadores de milhar, datas localizadas, unidades nos eixos
- **Legendas claras**: nomes de séries descritivos, posição que não obstrui os dados
- **Interatividade rica**: hover highlights, tooltips contextuais, zoom quando aplicável
- **Dark mode**: quando apropriado, oferecer versão dark com `backgroundColor: '#1a1a2e'`
- **Múltiplos gráficos**: para dashboards, organizar em grid CSS responsivo
- **Código comentado**: comentários em português explicando cada seção
## Tratamento de Erros
Consultar `references/ERRORS.md` para cenários de erro e soluções.
+123
agents/reversa-image-prompt-json/references/Examples.md
# Exemplos de Referência — Image Prompt Builder
Estes exemplos demonstram o padrão de linguagem e estrutura esperados nos prompts gerados.
---
## Exemplo 1 — Sobremesa (Lava Cake)
```json
{
"master_prompt": {
"scene_type": "high-speed cinematic luxury dessert photography",
"product": {
"type": "ultra-premium molten chocolate lava cake",
"brand_name": "no visible branding",
"appearance": "perfectly baked dark chocolate fondant with slightly cracked top and rich molten dark chocolate core flowing smoothly",
"accompaniments": [
"quenelle of vanilla bean ice cream",
"fresh raspberries with natural gloss",
"mint micro-leaves for elegance"
]
},
"composition": {
"action": "dramatic molten chocolate burst captured mid-flow as cake is gently sliced",
"surrounding_elements": [
"cocoa powder dust explosion frozen mid-air",
"dark chocolate shards suspended dynamically",
"gold flakes subtly dispersing",
"raspberry juice droplets captured in motion"
],
"placement": "centered hero dessert on matte black stone plate with subtle reflection on polished marble surface"
},
"lighting": {
"style": "luxury studio dessert lighting",
"effects": [
"soft rim lighting outlining cake texture",
"warm directional key light enhancing molten gloss",
"gentle top light defining ice cream texture",
"subtle backlight for cinematic depth and separation"
]
},
"color_palette": {
"background": "deep charcoal fading into warm amber bokeh",
"accents": "rich dark chocolate brown, creamy ivory, vibrant raspberry red, matte black, subtle gold highlights"
},
"technical_specs": {
"camera": "macro lens, slight low angle for premium dominance",
"shutter": "ultra-fast freeze-motion capture",
"depth_of_field": "shallow focus on molten center, soft blur on suspended particles",
"rendering_style": "ultra-photorealistic texture detailing"
},
"output_specs": {
"resolution": "4K",
"aspect_ratio": "16:9", — Bebida (Shake)
```json
{
"master_prompt": {
"scene_type": "high-speed commercial luxury shake photography",
"product": {
"type": "elegant frosted glass bottle filled with velvety strawberry shake",
"brand_name": "ROSÉ VELVET",
"appearance": "minimalist vertical blush label with embossed rose-gold serif typography, creamy pastel pink liquid with natural strawberry swirls",
"accompaniments": [
"fresh strawberry halves with visible seeds and juicy texture",
"soft dusting of powdered sugar diffusing delicately"
]
},
"composition": {
"action": "dynamic high-velocity creamy splash explosion",
"surrounding_elements": [
"sculptural waves of thick strawberry shake splashing outward",
"silky ribbons of strawberry puree suspended mid-air",
"floating fresh strawberry halves with visible seeds",
"fine droplets of creamy pink mist catching the light"
],
"placement": "centered hero bottle with a crisp reflection on a polished white marble surface"
},
"lighting": {
"style": "luxury glossy studio product lighting",
"effects": [
"sharp rim lighting to define bottle silhouette",
"brilliant highlights on creamy splashes and glossy strawberry surfaces",
"soft rosy glow in the background for warmth and elegance"
]
},
"color_palette": {
"background": "smooth gradient of blush pink fading into soft champagne ivory",
"accents": "fresh strawberry red, rose gold, and creamy vanilla tones"
},
"technical_specs": {
"camera": "macro lens, eye-level angle",
"shutter": "ultra-fast freeze-motion capture",
"depth_of_field": "shallow focus on the label, gentle blur on dynamic splash elements",
"rendering_style": "ultra-photorealistic texture"
},
"output_specs": {
"resolution": "4K",
"aspect_ratio": "1:1",
"model": "nano-banana-2",
"synthid_watermark": true
}
}
}
```
---
## Padrões linguísticos obrigatórios
| Campo | Padrão esperado |
|---|---|
| `type` | adjetivo premium + material + nome do produto |
| `action` | verbo de impacto + movimento congelado + contexto |
| `surrounding_elements` | substantivo visual + detalhe de movimento/textura |
| `placement` | "centered hero [produto] on [superfície] with [reflexo]" |
| `lighting.effects` | rim / key / top ou back / extra opcional |
| `background` | cor principal + transição + efeito (bokeh, gradiente...) |
| `rendering_style` | descritor de realismo ou estilo visual |
| `resolution` | `512px` / `1K` / `2K` / `4K` |
| `aspect_ratio` | `1:1` / `16:9` / `9:16` / `4:3` / `3:4` / `4:1` / `1:4` / `8:1` / `1:8` |
| `model` | sempre `"nano-banana-2"` |
| `synthid_watermark` | sempre `true` |
+216
agents/reversa-image-prompt-json/SKILL.md
---
name: reversa-image-prompt-json
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: image-prompt-builder
description: >
Cria prompts JSON estruturados para geração de imagens de alta qualidade com estética
luxuosa e cinematográfica. Use esta skill sempre que o usuário quiser gerar um prompt
de imagem, criar uma foto de produto, montar um prompt para IA de imagem, fotografar
produto virtualmente, criar imagem de comida, bebida, cosmético, joia, moda ou qualquer
item visual. Também deve ser ativada quando o usuário mencionar: "prompt para imagem",
"gerar imagem de produto", "foto de produto com IA", "prompt para Midjourney/DALL-E/Flux",
"fotografar produto", ou pedir para "montar um prompt JSON de imagem".
---
# Image Prompt Builder
Skill para construir prompts JSON estruturados para geração de imagens de produtos com
estética cinematográfica e luxuosa — otimizada para **Nano Banana 2 (Gemini 3.1 Flash Image)**
via **Google Antigravity**, com suporte a todos os parâmetros nativos do modelo.
---
## Fluxo obrigatório
Ao ser ativada, esta skill deve **SEMPRE** seguir estas etapas em ordem:
1. **Entrevista guiada** — Coletar informações do usuário por blocos
2. **Confirmação** — Mostrar resumo e pedir aprovação
3. **Geração do JSON** — Montar o prompt estruturado final
---
## ETAPA 1 — Entrevista guiada por blocos
Colete as informações em **3 rodadas de perguntas**, nunca tudo de uma vez.
---
### Rodada 1 — Produto e Cena
Pergunte ao usuário:
> "Vamos montar seu prompt de imagem! Preciso entender o produto primeiro. Me conta:"
1. **Tipo de produto**: O que é o produto? (ex: bolo de chocolate, frasco de perfume, tênis, shake, joia...)
2. **Nome da marca**: Tem marca visível? Se sim, qual é o nome?
3. **Aparência do produto**: Descreva a cor, textura, acabamento, forma. Quanto mais detalhe, melhor.
4. **Elementos extras**: Tem acompanhamentos? (frutas, gelo, flores, folhas, reflexos...)
5. **Tipo de cena**: Qual é o clima geral da imagem?
- Opções sugeridas: luxuoso e cinematográfico / clean e minimalista / dramático e contrastado / quente e aconchegante / futurista e tecnológico
---
### Rodada 2 — Composição e Ação
> "Ótimo! Agora me conta sobre o visual dinâmico da imagem:"
6. **Ação principal**: O produto está estático ou tem movimento? (ex: líquido explodindo, partículas suspensas, fumaça, splash, corte revelando interior...)
7. **Elementos suspensos no ar**: Quais elementos voam ao redor do produto? (ex: gotas, pó, fragmentos, folhas, cristais, bolhas...)
8. **Superfície de apoio**: Onde o produto está? (ex: mármore branco polido, pedra preta fosca, madeira rústica, vidro transparente, superfície abstrata...)
9. **Ângulo da câmera**: Como a câmera filma o produto?
- Opções: ângulo baixo (dominância) / nível dos olhos / levemente acima / macro extremo / ângulo 3/4
---
### Rodada 3 — Iluminação, Cores e Especificações Técnicas
> "Quase lá! Agora a parte visual e técnica:"
10. **Estilo de iluminação**: Como você quer a luz?
- Opções: estúdio clean e brilhante / dramático com sombras / luz natural suave / luz de produto de luxo com rim light / luz néon colorida
11. **Paleta de cores do fundo**: Qual cor/gradiente domina o fundo? (ex: preto carvão com bokeh âmbar, gradiente rosa para champanhe, azul escuro para branco...)
12. **Cores de destaque (accents)**: Quais cores surgem nos elementos ao redor? (ex: dourado, prata, vermelho vivo, tons pastéis...)
13. **Resolução**: Qual nível de qualidade você precisa?
- `512px` — iteração rápida / testes
- `1K` — redes sociais e uso digital
- `2K` — conteúdo profissional
- `4K` — produção máxima / impressão
14. **Aspect Ratio**: Qual proporção da imagem? (padrão: `16:9`)
- `16:9` — widescreen (padrão) ✅
- `1:1` — quadrado (Instagram feed)
- `9:16` — vertical (Stories, Reels, TikTok)
- `4:3` — clássico
- `3:4` — retrato
- `4:1` / `1:4` — banner horizontal / vertical
- `8:1` / `1:8` — super banner
15. **Estilo de renderização**: Fotorrealista ultra-detalhado / ilustração / 3D render / foto analógica / outro?
16. **Algo mais?**: Algum detalhe especial que você quer garantir na imagem?
---
## ETAPA 2 — Confirmação
Após coletar todas as respostas, mostre um **resumo em tópicos** para o usuário confirmar:
```
📋 RESUMO DO PROMPT:
- Produto: [tipo] — [marca]
- Aparência: [descrição]
- Cena: [tipo]
- Ação: [descrição]
- Elementos suspensos: [lista]
- Superfície: [descrição]
- Ângulo: [ângulo]
- Iluminação: [estilo]
- Fundo: [cores]
- Accents: [cores]
- Resolução: [ex: 2K]
- Aspect Ratio: [ex: 1:1]
- Renderização: [ex: ultra-photorealistic]
Está correto? Posso montar o prompt JSON agora?
```
Só avance para a Etapa 3 após confirmação do usuário.
---
## ETAPA 3 — Geração do JSON
Com as respostas confirmadas, monte o prompt seguindo **exatamente** este schema:
```json
{
"master_prompt": {
"scene_type": "[velocidade/estilo] [nicho] photography",
"product": {
"type": "[descrição rica e adjetivada do produto]",
"brand_name": "[nome da marca ou 'no visible branding']",
"appearance": "[cor, textura, forma, acabamento detalhados]",
"accompaniments": [
"[elemento 1 com descrição sensorial]",
"[elemento 2 com descrição sensorial]"
]
},
"composition": {
"action": "[ação dramática central capturada em movimento]",
"surrounding_elements": [
"[elemento suspenso 1 com detalhe de movimento]",
"[elemento suspenso 2 com detalhe de movimento]",
"[elemento suspenso 3 com detalhe de movimento]"
],
"placement": "[posicionamento hero centralizado na superfície especificada]"
},
"lighting": {
"style": "[estilo de iluminação completo]",
"effects": [
"[efeito de rim light]",
"[efeito de key light]",
"[efeito de backlight ou top light]",
"[efeito extra se necessário]"
]
},
"color_palette": {
"background": "[gradiente/bokeh do fundo com descrição de transição]",
"accents": "[lista de cores de destaque separadas por vírgula]"
},
"technical_specs": {
"camera": "[tipo de lente], [ângulo escolhido]",
"shutter": "[tipo de captura — freeze-motion, long exposure, etc.]",
"depth_of_field": "[foco principal], [descrição do blur]",
"rendering_style": "[fotorrealista / ilustração / 3D render / foto analógica / etc.]"
},
"output_specs": {
"resolution": "[512px | 1K | 2K | 4K]",
"aspect_ratio": "16:9",
"model": "nano-banana-2",
"synthid_watermark": true
}
}
}
```
---
## Regras de qualidade do JSON
- **Adjetivos de luxo e premium** são obrigatórios em todo campo descritivo
- **Movimento congelado** deve sempre estar presente em `action` e `surrounding_elements`
- **Superfícies reflexivas** devem ser mencionadas em `placement`
- O produto é sempre o **herói centralizado** da cena
- `surrounding_elements` deve ter **mínimo 3, máximo 6 itens**
- `lighting.effects` deve ter **sempre 3 ou 4 efeitos** (rim, key, back/top + extra opcional)
- `scene_type` deve seguir o padrão: `"[adjetivo de velocidade/estilo] [nicho] photography"`
- `output_specs.resolution` deve usar os valores nativos do Nano Banana 2: `512px`, `1K`, `2K` ou `4K`
- `output_specs.aspect_ratio` deve usar os valores nativos suportados pelo modelo
- `output_specs.model` deve sempre ser `"nano-banana-2"`
- `output_specs.synthid_watermark` deve sempre ser `true` (padrão obrigatório do Google)
---
## Após gerar o JSON
Apresente o JSON formatado em bloco de código e adicione:
> 💡 **Dica de uso no Antigravity:** Cole este JSON diretamente no campo de prompt do Nano Banana 2 no Google Antigravity. Os campos `output_specs` são interpretados nativamente pelo modelo — não é necessário nenhum prefixo adicional.
Pergunte se o usuário quer ajustar algum campo, trocar o aspect ratio ou gerar variações.
---
## Exemplos de referência
Para inspiração dos padrões de linguagem, consulte `/mnt/skills/user/image-prompt-builder/references/examples.md` se disponível. 
+212
agents/reversa-selo-generativo/references/ERRORS.md
# Cenários de Erro e Tratamento
Cenários comuns na skill `selo-generativo` e como tratá-los.
---
## ERR-01: p5.js indisponível (CDN inacessível)
**Causa**: usuário offline na primeira execução, ou CDN bloqueado.
**Detecção**: variável `p5` global não definida após o `<script>` do CDN.
**Tratamento**:
```javascript
window.addEventListener("load", () => {
if (typeof p5 === "undefined") {
document.getElementById("seal-container").innerHTML = `
<div class="seal-fallback" style="width: ${SIZE}px; height: ${SIZE}px;
background: ${palette.bg}; display: flex; align-items: center;
justify-content: center; border-radius: 50%; color: ${palette.fg};">
<span>Selo indisponível</span>
</div>`;
return;
}
// setup normal aqui
});
```
Fallback: SVG mínimo (círculo + cor de fundo da paleta) inline, sem dependência de p5.
---
## ERR-02: Canvas não suportado pelo browser
**Causa**: browser muito antigo sem suporte a `<canvas>` (caso raríssimo hoje).
**Detecção**: `canvas.getContext("2d")` retorna `null`.
**Tratamento**: cair para SVG inline com `crystal-lattice` (que é o padrão mais compatível com SVG real).
---
## ERR-03: Seed inválido ou ausente
**Causa**: agente chamou a skill sem seed, ou passou string vazia.
**Detecção**: validação na entrada.
**Tratamento**: fallback seguro.
```javascript
function resolveSeed(rawSeed) {
if (!rawSeed || typeof rawSeed !== "string" || rawSeed.length === 0) {
const timestamp = Date.now().toString();
console.warn("Seed ausente, usando timestamp como fallback. Selo não será reprodutível.");
return timestamp;
}
return rawSeed;
}
```
Quando timestamp é usado, exibir aviso no rodapé da página (apenas se for hero grande): "Selo não-reprodutível (sem seed)".
---
## ERR-04: Tamanho extremo
**Causa**: requisição de canvas muito grande (>4096) ou muito pequeno (<16).
**Detecção**: validação do parâmetro `size`.
**Tratamento**:
```javascript
function clampSize(requested) {
const MIN = 16;
const MAX = 4096;
if (requested < MIN) {
console.warn(`Tamanho ${requested} abaixo do mínimo (${MIN}). Ajustando.`);
return MIN;
}
if (requested > MAX) {
console.warn(`Tamanho ${requested} acima do máximo (${MAX}). Ajustando.`);
return MAX;
}
return requested;
}
```
Acima de 1024, padrões de pixel-loop como `wave-interference` ficam pesados. A skill deve avisar e oferecer `noLoop()` obrigatório com cache do canvas.
---
## ERR-05: Paleta com cores inválidas
**Causa**: paleta recebida com hex malformado ou campo ausente.
**Detecção**: regex de validação em cada cor.
**Tratamento**:
```javascript
function validatePalette(palette) {
const HEX_RX = /^#[0-9a-fA-F]{6}$/;
const required = ["bg", "foreground", "accent", "fg"];
for (const field of required) {
if (!(field in palette)) {
throw new Error(`Paleta inválida: campo '${field}' ausente.`);
}
}
if (!Array.isArray(palette.foreground) || palette.foreground.length === 0) {
throw new Error("Paleta inválida: 'foreground' deve ser lista não-vazia.");
}
[palette.bg, palette.accent, palette.fg].forEach((c) => {
if (!HEX_RX.test(c)) throw new Error(`Cor inválida: ${c}`);
});
palette.foreground.forEach((c) => {
if (!HEX_RX.test(c)) throw new Error(`Cor inválida em foreground: ${c}`);
});
}
```
Se a paleta é inválida, cair para `palettes.sober` (paleta de fallback mais conservadora) e logar a falha.
---
## ERR-06: Contraste insuficiente
**Causa**: paleta com `accent` e `bg` muito próximos, gerando elemento central invisível.
**Detecção**: `contrastRatio(accent, bg) < 4.5` (ver PALETTE_BY_STYLE.md).
**Tratamento**: derivar `accent` ajustado automaticamente.
```javascript
function ensureContrast(palette) {
if (contrastRatio(palette.accent, palette.bg) < 4.5) {
const bgIsLight = luminance(palette.bg) > 0.5;
palette.accent = bgIsLight ? darken(palette.accent, 0.4) : lighten(palette.accent, 0.4);
}
return palette;
}
```
---
## ERR-07: Padrão escolhido incompatível com estilo
**Causa**: derivação por seed resultou em padrão visualmente incompatível com o estilo escolhido (ex: `crystal-lattice` em estilo `exploratory`).
**Detecção**: tabela de compatibilidade declarada em `GENERATIVE_PATTERNS.md`.
**Tratamento**: re-rolar dentro dos padrões compatíveis.
```javascript
const STYLE_COMPATIBLE = {
sober: ["flow-field", "crystal-lattice", "noise-strata"],
premium: ["particle-orbit", "wave-interference"],
dense: ["crystal-lattice", "wave-interference"],
exploratory: ["flow-field", "particle-orbit", "noise-strata"]
};
function pickCompatible(seedHex, styleHint) {
const allowed = STYLE_COMPATIBLE[styleHint];
if (!allowed) return PATTERNS[0];
const idx = parseInt(seedHex.slice(2, 4), 16) % allowed.length;
return allowed[idx];
}
```
---
## ERR-08: Performance muito ruim em mini-selo
**Causa**: padrão pesado em canvas pequeno consumindo CPU desproporcional.
**Detecção**: medir tempo entre `setup` e `draw` final.
**Tratamento**: se canvas é mini (<200px) e padrão escolhido é `wave-interference` (pixel loop), trocar automaticamente para `crystal-lattice` (geometria simples) com mensagem no console.
---
## ERR-09: Múltiplas instâncias do mesmo selo na mesma página
**Causa**: o mini-selo aparece em todas as páginas do mini-site. Recarregar p5.js e gerar canvas em cada uma é desperdício.
**Tratamento**: gerar o selo uma vez como SVG (para `crystal-lattice`) ou PNG dataURI (para outros padrões) e embutir inline em todas as páginas. A skill aceita parâmetro `mode: "svg" | "dataURI" | "html"` para retornar formato apropriado.
```javascript
function exportAs(mode) {
if (mode === "svg") return canvasToSvg();
if (mode === "dataURI") return canvas.elt.toDataURL("image/png");
return wrapInStandaloneHtml(canvas);
}
```
---
## ERR-10: localStorage de seed corrompido
Não aplicável diretamente, porque a skill não persiste estado entre execuções. O seed sempre vem do invocador (agente orquestrador), e a reprodutibilidade depende apenas dele.
Se o invocador perdeu o seed, o agente deve recalcular do soul.md (sha256). Esta skill não é responsável por isso.
---
## Princípio geral
O selo é um elemento **decorativo**. Falha de selo nunca deve quebrar a página inteira. Em todos os cenários acima, há fallback que sempre renderiza algo: um círculo colorido, um SVG mínimo, uma versão simplificada. Nada de tela branca.
Mensagens em pt-br, sem travessão.
+365
agents/reversa-sel...ativo/references/GENERATIVE_PATTERNS.md
# Padrões Generativos do Selo
Catálogo dos 5 padrões consagrados que a skill `selo-generativo` produz. Cada padrão tem uma aparência distinta, algoritmo central e parâmetros derivados do seed.
Padrão geral de seed: o hash sha256 (64 chars hex) é cortado em fatias de 8 chars, cada fatia vira um `parseInt(slice, 16)` e alimenta um parâmetro distinto. Assim, padrões diferentes do mesmo seed compartilham personalidade visual.
---
## 1. flow-field
Campos de fluxo Perlin: milhares de partículas seguem vetores derivados de ruído, deixando rastros orgânicos curvos. Estilo "natural turbulento".
**Quando combina**: estilos `sober` (versão suave) e `exploratory` (versão luminosa).
**Algoritmo**:
```javascript
let particles = [];
const PARTICLE_COUNT = 500;
const NOISE_SCALE = 0.004;
const STEP = 1.5;
function setup() {
const canvas = createCanvas(SIZE, SIZE);
canvas.parent("seal-container");
randomSeed(seedInt);
noiseSeed(seedInt);
background(palette.bg);
noFill();
strokeWeight(0.6);
for (let i = 0; i < PARTICLE_COUNT; i++) {
particles.push({
x: random(width),
y: random(height),
color: random(palette.foreground),
life: random(200, 600)
});
}
noLoop();
drawFlowField();
}
function drawFlowField() {
particles.forEach((p) => {
stroke(p.color + "55"); // semi-transparente
let x = p.x, y = p.y;
for (let step = 0; step < p.life; step++) {
const angle = noise(x * NOISE_SCALE, y * NOISE_SCALE) * TWO_PI * 4;
const nx = x + cos(angle) * STEP;
const ny = y + sin(angle) * STEP;
line(x, y, nx, ny);
x = nx;
y = ny;
if (x < 0 || x > width || y < 0 || y > height) break;
}
});
}
```
**Parâmetros derivados do seed**:
- `PARTICLE_COUNT`: 300 a 1000 (slice 0 normalizado).
- `NOISE_SCALE`: 0.002 a 0.008 (slice 1).
- Centro de gravidade do campo (se houver atrator): coordenada XY (slices 2 e 3).
**Performance**: até 1500 partículas em canvas 800x800 sem trava.
---
## 2. particle-orbit
Partículas orbitando um centro com trilhas decrescentes, criando padrão de "constelação rotativa".
**Quando combina**: estilos `premium` (dark, dourado) e `exploratory` (pastéis luminosos).
**Algoritmo**:
```javascript
const ORBITS = 6;
const PARTICLES_PER_ORBIT = 24;
function setup() {
const canvas = createCanvas(SIZE, SIZE);
canvas.parent("seal-container");
randomSeed(seedInt);
noiseSeed(seedInt);
background(palette.bg);
drawOrbit();
noLoop();
}
function drawOrbit() {
const cx = width / 2;
const cy = height / 2;
for (let o = 0; o < ORBITS; o++) {
const radius = (o + 1) * (width / (ORBITS * 2.5));
const orbitColor = palette.foreground[o % palette.foreground.length];
const phase = random(TWO_PI);
const tilt = random(-PI / 6, PI / 6);
for (let p = 0; p < PARTICLES_PER_ORBIT; p++) {
const angle = (p / PARTICLES_PER_ORBIT) * TWO_PI + phase;
const x = cx + cos(angle) * radius;
const y = cy + sin(angle) * radius * cos(tilt);
const size = map(noise(angle * 2, o), 0, 1, 1, 6);
// Trilha
stroke(orbitColor + "33");
strokeWeight(0.4);
noFill();
arc(cx, cy, radius * 2, radius * 2 * cos(tilt), phase, angle);
// Partícula
noStroke();
fill(orbitColor);
ellipse(x, y, size);
}
}
// Centro
fill(palette.accent);
noStroke();
ellipse(cx, cy, 14);
}
```
**Parâmetros derivados do seed**:
- Número de órbitas: 3 a 8 (slice 0).
- Inclinação das órbitas (tilt): -π/4 a π/4 (slice 1).
- Densidade de partículas por órbita (slice 2).
**Performance**: trivial, dezenas de elementos.
---
## 3. crystal-lattice
Forma cristalina simétrica derivada de um polígono base, com subdivisões geométricas limpas. Estilo "logotipo arquitetural".
**Quando combina**: estilos `dense` (saturado) e `sober` (limpo).
**Algoritmo**:
```javascript
function setup() {
const canvas = createCanvas(SIZE, SIZE);
canvas.parent("seal-container");
randomSeed(seedInt);
background(palette.bg);
drawCrystal();
noLoop();
}
function drawCrystal() {
const cx = width / 2;
const cy = height / 2;
const sides = floor(random(5, 9)); // 5 a 8 lados
const radius = width * 0.35;
const layers = floor(random(3, 6));
push();
translate(cx, cy);
for (let layer = layers; layer > 0; layer--) {
const r = radius * (layer / layers);
const rotation = (layers - layer) * (PI / sides);
const color = palette.foreground[layer % palette.foreground.length];
fill(color);
stroke(palette.bg);
strokeWeight(2);
beginShape();
for (let i = 0; i < sides; i++) {
const angle = (i / sides) * TWO_PI + rotation;
const x = cos(angle) * r;
const y = sin(angle) * r;
vertex(x, y);
}
endShape(CLOSE);
}
// Núcleo central
fill(palette.accent);
noStroke();
const coreRadius = radius * 0.15;
beginShape();
for (let i = 0; i < sides; i++) {
const angle = (i / sides) * TWO_PI;
vertex(cos(angle) * coreRadius, sin(angle) * coreRadius);
}
endShape(CLOSE);
pop();
}
```
**Parâmetros derivados do seed**:
- Número de lados: 5 a 8 (slice 0).
- Número de camadas concêntricas: 3 a 6 (slice 1).
- Rotação de offset entre camadas (slice 2).
**Exportável como SVG**: este padrão é puramente geométrico, ideal para conversão a SVG real para mini-selos.
**Performance**: trivial.
---
## 4. wave-interference
Padrões de interferência tipo moiré: ondas circulares partindo de múltiplos centros que se cruzam, gerando texturas complexas a partir de regras simples.
**Quando combina**: estilos `premium` (preto + dourado, alta contraste) e `dense`.
**Algoritmo**:
```javascript
function setup() {
const canvas = createCanvas(SIZE, SIZE);
canvas.parent("seal-container");
randomSeed(seedInt);
pixelDensity(1);
background(palette.bg);
drawInterference();
noLoop();
}
function drawInterference() {
const centers = [];
const numCenters = floor(random(2, 5));
for (let i = 0; i < numCenters; i++) {
centers.push({
x: random(width * 0.2, width * 0.8),
y: random(height * 0.2, height * 0.8),
frequency: random(0.04, 0.10),
phase: random(TWO_PI)
});
}
loadPixels();
for (let y = 0; y < height; y++) {
for (let x = 0; x < width; x++) {
let value = 0;
centers.forEach((c) => {
const dx = x - c.x;
const dy = y - c.y;
const dist = sqrt(dx * dx + dy * dy);
value += sin(dist * c.frequency + c.phase);
});
value = (value / centers.length + 1) / 2;
const colorIdx = floor(value * palette.foreground.length);
const hex = palette.foreground[constrain(colorIdx, 0, palette.foreground.length - 1)];
const rgb = hexToRgb(hex);
const i = (y * width + x) * 4;
pixels[i] = rgb.r;
pixels[i + 1] = rgb.g;
pixels[i + 2] = rgb.b;
pixels[i + 3] = 255;
}
}
updatePixels();
}
function hexToRgb(hex) {
const h = hex.replace("#", "");
return {
r: parseInt(h.slice(0, 2), 16),
g: parseInt(h.slice(2, 4), 16),
b: parseInt(h.slice(4, 6), 16)
};
}
```
**Parâmetros derivados do seed**:
- Número de centros: 2 a 4 (slice 0).
- Frequência das ondas: 0.04 a 0.10 (slice 1).
- Posição de cada centro (slices 2-N).
**Performance**: O(width * height * centers). Em 800x800 com 3 centros, ~ 1.9M operações. Tudo bem para `noLoop()`.
---
## 5. noise-strata
Estratos horizontais de ruído, formando "paisagem abstrata" com camadas de Perlin noise.
**Quando combina**: estilos `sober` (terracota neutro) e `exploratory` (auroral).
**Algoritmo**:
```javascript
function setup() {
const canvas = createCanvas(SIZE, SIZE);
canvas.parent("seal-container");
randomSeed(seedInt);
noiseSeed(seedInt);
background(palette.bg);
drawStrata();
noLoop();
}
function drawStrata() {
const layers = floor(random(4, 8));
const baseY = height * 0.3;
const layerHeight = (height - baseY) / layers;
for (let l = 0; l < layers; l++) {
const y0 = baseY + l * layerHeight;
const color = palette.foreground[l % palette.foreground.length];
fill(color);
noStroke();
beginShape();
vertex(0, height);
for (let x = 0; x <= width; x += 4) {
const n = noise(x * 0.005, l * 0.7);
const y = y0 + n * layerHeight * 1.5;
vertex(x, y);
}
vertex(width, height);
endShape(CLOSE);
}
// Sol/lua decorativa
fill(palette.accent);
noStroke();
const sunX = random(width * 0.2, width * 0.8);
const sunY = baseY - random(20, 60);
const sunR = random(30, 70);
ellipse(sunX, sunY, sunR * 2);
}
```
**Parâmetros derivados do seed**:
- Número de camadas: 4 a 8 (slice 0).
- Altura base do horizonte: 25% a 40% do canvas (slice 1).
- Posição do sol/lua decorativo (slices 2 e 3).
**Performance**: trivial.
---
## Seleção de padrão pelo seed
```javascript
const PATTERNS = ["flow-field", "particle-orbit", "crystal-lattice", "wave-interference", "noise-strata"];
function pickPattern(seedHex, styleHint) {
const patternIndex = parseInt(seedHex.slice(0, 2), 16) % PATTERNS.length;
let chosen = PATTERNS[patternIndex];
// Ajuste suave por estilo (escolhe entre padrões "compatíveis" se houver desconexão)
if (styleHint && !isStyleCompatible(chosen, styleHint)) {
chosen = pickCompatible(seedHex, styleHint);
}
return chosen;
}
```
A compatibilidade `padrão x estilo` aparece no início desta referência. Quando há incompatibilidade declarada, a função `pickCompatible` reavalia entre os padrões marcados como apropriados para o estilo.
---
## Override manual
A skill aceita parâmetro `forcePattern` para ignorar a derivação por seed e escolher o padrão manualmente, útil quando o usuário quer um selo específico em estilo diferente do default.
+176
agents/reversa-sel...nerativo/references/PALETTE_BY_STYLE.md
# Paletas por Estilo Visual
Tabela das paletas usadas pelo selo, derivadas do estilo visual escolhido pelo usuário do `/reversa-documentation`.
Cada paleta tem 4 campos:
- `bg`: cor de fundo do canvas.
- `foreground`: lista de cores principais usadas pelo padrão (3 a 5 cores).
- `accent`: cor de destaque para elementos centrais (1 cor).
- `fg`: cor do texto do label fora do canvas.
---
## Paleta: `sober`
Estilo sóbrio, técnico, neutro. Foco em legibilidade e atemporalidade.
```json
{
"bg": "#f5f3ee",
"foreground": ["#3d4a5c", "#7c8a99", "#a06b4a", "#4f6b5d", "#bdb4a4"],
"accent": "#1e2937",
"fg": "#1e2937"
}
```
Tradução visual:
- Fundo: papel quebrado.
- Foreground: azul-petróleo, cinza-pedra, terracota, verde-musgo, areia.
- Accent: azul-meia-noite profundo.
**Variante dark**: para uso em mini-selo sobre header escuro, espelhar (bg ↔ fg).
---
## Paleta: `premium`
Estilo cinematográfico, luxuoso, dark. Foco em contraste e brilho.
```json
{
"bg": "#0a0a14",
"foreground": ["#d4af37", "#7a1c2a", "#b8b8b8", "#1e2b4f", "#3a3a4a"],
"accent": "#f4d03f",
"fg": "#eaeaea"
}
```
Tradução visual:
- Fundo: preto noite-azulada.
- Foreground: dourado, vermelho-vinho, prata, azul-meia-noite, cinza-fumaça.
- Accent: dourado claro (mais brilhante que o dourado base).
**Uso típico**: hero de apresentação executiva, selo de capa de documentação premium.
---
## Paleta: `dense`
Estilo denso, saturado, alta densidade visual. Foco em distinção entre múltiplas categorias.
```json
{
"bg": "#f8f9fa",
"foreground": ["#ff7a3e", "#00c6c6", "#e93f8f", "#a3d930", "#5b3fce"],
"accent": "#1a1a2e",
"fg": "#1a1a2e"
}
```
Tradução visual:
- Fundo: branco gelo.
- Foreground: laranja, ciano, magenta, lima, índigo.
- Accent: preto-azulado.
**Uso típico**: documentação de sistema com muitos componentes para distinguir; selo cobre múltiplos hues.
---
## Paleta: `exploratory`
Estilo exploratório, etéreo, luminoso. Foco em 3D e contemplação.
```json
{
"bg": "#0d0d1a",
"foreground": ["#ffb3ba", "#a0e7e5", "#c9b6e8", "#fff5b8", "#b8e0d2"],
"accent": "#ffffff",
"fg": "#eaeaea"
}
```
Tradução visual:
- Fundo: preto-violeta profundo.
- Foreground: rosa-aurora, ciano-glaciar, lilás-névoa, amarelo-suave, verde-aquoso.
- Accent: branco luz.
**Uso típico**: documentação com forte presença de cenas 3D; o selo dialoga com a estética da `arquitetura.html`.
---
## Paleta `other` (fallback)
Quando o usuário escolhe "Outro" no menu de estilo e fornece descrição livre, a skill mapeia a descrição para a paleta mais próxima, ou aplica heurística básica:
```javascript
function paletteFromFreeform(text) {
const lower = text.toLowerCase();
if (/(luxo|premium|cinematogr|dark)/.test(lower)) return palettes.premium;
if (/(t[ée]cnico|s[óo]brio|clean|minimal)/.test(lower)) return palettes.sober;
if (/(denso|saturado|colorido|vibra)/.test(lower)) return palettes.dense;
if (/(explora|3D|luminoso|et[ée]reo)/.test(lower)) return palettes.exploratory;
return palettes.sober; // fallback seguro
}
```
---
## Distribuição de cores dentro da paleta
Mesmo com 5 cores em `foreground`, o selo não usa todas igualmente. Regra de proporção visual:
| Posição na paleta | Proporção visual no selo |
|---|---|
| 1ª cor | 50% (dominante) |
| 2ª cor | 25% (secundária) |
| 3ª cor | 15% |
| 4ª cor | 7% |
| 5ª cor | 3% (vestígio) |
Padrões como `flow-field` e `wave-interference` herdam essa distribuição automaticamente (a cor 1 aparece em mais partículas).
Padrões como `crystal-lattice` usam cores em camadas distintas, mas as camadas mais visíveis (externas) usam as cores 1 e 2; camadas internas usam 3, 4, 5.
---
## Adaptação automática para mini-selo
Em mini-selos (<200px), a paleta é simplificada para 3 cores apenas:
```javascript
function simplifyForMini(palette) {
return {
...palette,
foreground: palette.foreground.slice(0, 3)
};
}
```
Mantém legibilidade e impacto visual mesmo em tamanho reduzido.
---
## Verificação de contraste
Antes de renderizar, verificar que `accent` tem contraste suficiente com `bg` para padrões que destacam centro (ratio mínimo 4.5:1 conforme WCAG AA).
```javascript
function contrastRatio(hex1, hex2) {
const lum = (hex) => {
const { r, g, b } = hexToRgb(hex);
const sRGB = [r, g, b].map((c) => {
const v = c / 255;
return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
});
return 0.2126 * sRGB[0] + 0.7152 * sRGB[1] + 0.0722 * sRGB[2];
};
const l1 = lum(hex1);
const l2 = lum(hex2);
const lighter = Math.max(l1, l2);
const darker = Math.min(l1, l2);
return (lighter + 0.05) / (darker + 0.05);
}
```
Se o contraste falhar, substituir `accent` por uma versão mais clara/escura derivada automaticamente.
+184
agents/reversa-selo-generativo/SKILL.md
---
name: reversa-selo-generativo
description: >
Cria selos visuais generativos seeded usando p5.js, gerando HTML standalone com canvas
de arte algorítmica reprodutível. Use esta skill sempre que o usuário pedir um selo,
identidade visual de projeto, hero generativo, capa única reprodutível, ou artwork
derivado de um hash. Deve ser ativada quando o usuário mencionar termos como "selo",
"selo generativo", "identidade visual do projeto", "hero capa", "artwork seeded",
"Art Blocks style", "p5.js generativo", "capa reprodutível", "selo de documentação"
ou pedir um elemento decorativo único e reprodutível derivado de uma string.
Funciona com qualquer string como seed (hash do soul.md, nome do projeto, ID arbitrário).
Sempre gera HTML standalone com p5.js via CDN.
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: generative-seal
---
# Selo Generativo
Cria **selos visuais únicos e reprodutíveis** para projetos do Reversa usando p5.js. Cada projeto recebe seu próprio artwork generativo derivado de um seed determinístico: o mesmo seed gera o mesmo selo, sempre.
Inspirado no padrão Art Blocks (seeded randomness) e na skill `algorithmic-art` da Anthropic, mas com escopo deliberadamente menor: produz **apenas o selo**, não um manifesto filosófico, não uma plataforma de exploração. É um elemento decorativo de identidade.
## Quando usar
- **Hero da `index.html`** do mini-site gerado pelo `/reversa-documentation`.
- **Mini-selo no header** de cada página do mini-site (versão reduzida).
- **Capa de slides** no `deck.html`.
- **Identidade visual** de qualquer artefato gerado pelo Reversa que precise de uma marca distintiva.
A skill é **leve por design**: usa só p5.js, gera canvas único, exporta como SVG ou PNG. Não tem sidebar de exploração, não tem múltiplos modos, não tem animação obrigatória (animação é opcional).
## Princípios
1. **Reprodutibilidade absoluta**: mesmo seed sempre gera o mesmo selo.
2. **Paleta limitada**: 3 a 5 cores por selo, derivadas do estilo visual escolhido.
3. **Composição equilibrada**: forma central reconhecível com elementos auxiliares orbitando ou compondo.
4. **Sem texto no canvas**: o selo é puramente visual; nome do projeto e título ficam fora do canvas, em HTML.
5. **Adaptável de tamanho**: o mesmo canvas funciona em 64x64 (mini-selo header) e 800x800 (hero grande).
6. **Sem dependências além de p5.js**: nada de GSAP, dat.GUI, lodash. Só p5.
## Fluxo de Trabalho
### 1. Receber o seed
O seed pode vir de:
- **String direta**: usuário ou agente passa um hash sha256, nome do projeto, ou qualquer string.
- **Caminho de arquivo**: usuário aponta para `.reversa/soul.md`, a skill computa `sha256` do conteúdo.
- **Fallback**: se nada for fornecido, usar `sha256` do timestamp atual (selo "do momento", não reprodutível).
```javascript
async function computeSeed(input) {
const enc = new TextEncoder();
const data = enc.encode(input);
const hashBuffer = await crypto.subtle.digest("SHA-256", data);
const hashArray = Array.from(new Uint8Array(hashBuffer));
const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
return hashHex;
}
```
O seed é uma string hexadecimal de 64 caracteres. A skill extrai múltiplos números dele para alimentar parâmetros distintos.
### 2. Escolher paleta
A paleta deriva do estilo visual escolhido pelo usuário do `/reversa-documentation`, ou pode ser fornecida diretamente.
Consultar `references/PALETTE_BY_STYLE.md` para a tabela completa de paletas por estilo. As 4 paletas base são:
| Estilo | Paleta |
|--------|--------|
| `sober` | Tons neutros: cinzas, azul-petróleo, terracota leve, branco quebrado |
| `premium` | Dark mode: preto profundo, dourado, vermelho-vinho, prata, azul-meia-noite |
| `dense` | Saturados: laranja, ciano, magenta, lima, índigo |
| `exploratory` | Pastéis luminosos: rosa-aurora, ciano-glaciar, lilás-névoa, branco luz |
A escolha de qual cor é "central" e quais são "auxiliares" sai do seed.
### 3. Escolher padrão generativo
A skill tem **5 padrões consagrados**, cada um com aparência distinta. O seed determina qual padrão usar (primeiros 2 dígitos hex modulo 5):
| Padrão | Aparência | Quando combina |
|--------|-----------|----------------|
| `flow-field` | Campos de fluxo Perlin, traços orgânicos curvos | Estilo `sober`, `exploratory` |
| `particle-orbit` | Partículas orbitando um centro com trilhas | Estilo `premium`, `exploratory` |
| `crystal-lattice` | Forma cristalina simétrica, geometria limpa | Estilo `dense`, `sober` |
| `wave-interference` | Padrões de interferência tipo moiré, ondas circulares | Estilo `premium`, `dense` |
| `noise-strata` | Estratos de ruído horizontal, paisagem abstrata | Estilo `sober`, `exploratory` |
Detalhes em `references/GENERATIVE_PATTERNS.md`.
A skill pode aceitar override do padrão via parâmetro, ignorando a derivação por seed.
### 4. Gerar o código
Estrutura do HTML resultante:
```html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<title>Selo: <!-- PROJECT_NAME --></title>
<script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.9.0/p5.min.js"></script>
<style>
body { margin: 0; display: flex; align-items: center; justify-content: center; min-height: 100vh; background: var(--seal-bg, #0a0a14); }
#seal-container { display: block; }
.label { color: var(--seal-fg, #eaeaea); text-align: center; margin-top: 16px; font-family: system-ui, sans-serif; }
</style>
</head>
<body>
<div>
<div id="seal-container"></div>
<div class="label"><!-- PROJECT_NAME --></div>
</div>
<script id="seal-config" type="application/json">
<!-- CONFIG_JSON -->
</script>
<script>
// 1. Ler config (seed, paleta, padrão, tamanho)
// 2. Seedar p5.js: randomSeed(seedInt); noiseSeed(seedInt);
// 3. Executar padrão escolhido
// 4. Salvar canvas como referência
</script>
</body>
</html>
```
**Regras fundamentais**:
1. **HTML standalone**: arquivo único, p5.js via CDN, nada externo.
2. **p5.js 1.9.0+**: usar `https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.9.0/p5.min.js`.
3. **Seeded sempre**: `randomSeed(seedInt)` e `noiseSeed(seedInt)` no primeiro setup, antes de qualquer chamada a `random()` ou `noise()`.
4. **Conversão de hash hex para int**: pegar primeiros 16 chars hex, converter via `parseInt(hex.slice(0, 16), 16)`.
5. **Canvas quadrado**: tamanho default 800x800, mas parametrizável.
6. **noLoop()**: por default o selo é estático. Se animação for solicitada, usar `frameRate(30)` e algoritmo de baixo custo.
7. **Sem texto no canvas**: nome do projeto fica em `<div class="label">` fora do canvas.
### 5. Variantes de tamanho
A skill aceita parâmetro `size` para gerar selo grande (hero, 800x800), médio (capa de slide, 400x400) ou mini (header, 64x64 ou 128x128).
Em selos menores (<200px), aplicar simplificações automáticas:
- Reduzir contagem de partículas em 80%.
- Aumentar espessura de traços proporcionalmente.
- Desativar animação.
### 6. Salvar e entregar
Output é HTML standalone. O canvas pode ser exportado como PNG via botão (opcional) ou como SVG para uso em headers (recomendado para mini-selos: SVG escala perfeitamente).
```javascript
function exportSVG() {
// Padrões compatíveis com SVG (crystal-lattice, wave-interference) podem ser regenerados como SVG real.
// Padrões raster (flow-field denso) exportam como PNG embutido em <img>.
}
```
Para uso em outras páginas do mini-site (mini-selo no header), gerar uma vez em SVG, embutir inline no HTML do viewer template.
## Diretrizes de qualidade
- **Reconhecibilidade**: o selo deve ter uma forma central forte; quem viu uma vez deve reconhecer o projeto pelo selo.
- **Equilíbrio cromático**: nunca usar todas as cores da paleta no mesmo selo; tipicamente 1 cor dominante (60%), 1 secundária (30%), 1 acento (10%).
- **Não chamar mais atenção que o conteúdo**: o selo é identidade, não foco. Em hero grande, ok ser protagonista; em mini-selo no header, deve ceder espaço ao nome do projeto.
- **Acessibilidade**: contraste mínimo entre fundo e elementos primários. Selos com fundo escuro têm elementos claros e vice-versa.
- **Idioma**: comentários em pt-br, sem travessão.
## Diretrizes de código
- **Constantes nomeadas no topo**: tamanho, paleta, parâmetros do padrão visíveis no início.
- **Função única de geração**: cada padrão é uma função `drawFlowField()`, `drawCrystalLattice()`, etc, isolada e testável.
- **Sem efeitos colaterais globais**: tudo escopado dentro de `setup()` e `draw()` do p5.
## Tratamento de erros
Consultar `references/ERRORS.md` para cenários (p5.js indisponível, canvas não suportado, seed inválido, tamanho extremo).
+476
templates/documentation/assets/css/style.css
/*
* Reversa Documentation - Estilo Unificado
*
* Chassis visual compartilhado entre o /reversa-documentation
* e os HTMLs auxiliares dos demais agentes do core.
*
* Quatro variantes ativadas via atributo data-style no <body>:
* - sober: cores neutras, alta legibilidade textual
* - premium: dark mode cinematográfico, dourado, espaçamento generoso
* - dense: paleta saturada, grid de cards, alta densidade
* - exploratory: pastéis luminosos sobre fundo escuro, foco em 3D
*
* Tudo em variáveis CSS para permitir override por agente sem reescrever.
*/
/* ============================================================
1. Reset minimalista
============================================================ */
*, *::before, *::after {
box-sizing: border-box;
}
html, body {
margin: 0;
padding: 0;
min-height: 100vh;
}
body {
font-family: var(--reversa-font-body);
font-size: var(--reversa-font-size-base);
line-height: var(--reversa-line-height-base);
color: var(--reversa-fg);
background: var(--reversa-bg);
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
display: grid;
grid-template-columns: 1fr min(280px, 25vw);
grid-template-rows: auto 1fr auto;
grid-template-areas:
"header header"
"main sidebar"
"footer footer";
gap: 0;
}
img, svg, canvas {
max-width: 100%;
display: block;
}
a {
color: var(--reversa-accent);
text-decoration: none;
}
a:hover, a:focus {
text-decoration: underline;
}
button {
font: inherit;
color: inherit;
background: var(--reversa-surface);
border: 1px solid var(--reversa-border);
border-radius: var(--reversa-radius);
padding: var(--reversa-space-sm) var(--reversa-space-md);
cursor: pointer;
transition: background 120ms ease, border-color 120ms ease;
}
button:hover, button:focus {
background: var(--reversa-surface-hover);
outline: 2px solid transparent;
}
button:focus-visible {
outline-color: var(--reversa-accent);
outline-offset: 2px;
}
input[type="range"], input[type="text"], select {
font: inherit;
color: inherit;
background: var(--reversa-surface);
border: 1px solid var(--reversa-border);
border-radius: var(--reversa-radius);
padding: var(--reversa-space-xs) var(--reversa-space-sm);
}
label {
display: flex;
flex-direction: column;
gap: var(--reversa-space-xs);
margin-bottom: var(--reversa-space-md);
font-size: var(--reversa-font-size-sm);
}
h1, h2, h3, h4 {
font-family: var(--reversa-font-heading);
line-height: 1.2;
margin: 0 0 var(--reversa-space-md);
}
h1 { font-size: var(--reversa-font-size-h1); }
h2 { font-size: var(--reversa-font-size-h2); }
h3 { font-size: var(--reversa-font-size-h3); }
code, pre {
font-family: var(--reversa-font-mono);
font-size: 0.9em;
background: var(--reversa-code-bg);
color: var(--reversa-code-fg);
border-radius: var(--reversa-radius-sm);
}
code { padding: 0.1em 0.4em; }
pre { padding: var(--reversa-space-md); overflow-x: auto; }
/* ============================================================
2. Layout geral
============================================================ */
.reversa-doc-header {
grid-area: header;
display: flex;
align-items: center;
gap: var(--reversa-space-lg);
padding: var(--reversa-space-md) var(--reversa-space-xl);
background: var(--reversa-header-bg);
border-bottom: 1px solid var(--reversa-border);
position: sticky;
top: 0;
z-index: 10;
}
.reversa-doc-logo {
display: inline-flex;
align-items: center;
gap: var(--reversa-space-sm);
color: var(--reversa-fg);
font-weight: 600;
font-family: var(--reversa-font-heading);
}
.reversa-doc-logo:hover { text-decoration: none; }
.reversa-doc-logo .seal {
width: 32px;
height: 32px;
display: inline-flex;
align-items: center;
justify-content: center;
border-radius: 50%;
overflow: hidden;
background: var(--reversa-surface);
}
.reversa-doc-nav {
display: flex;
gap: var(--reversa-space-md);
flex: 1;
}
.reversa-doc-nav a {
color: var(--reversa-fg-muted);
padding: var(--reversa-space-xs) var(--reversa-space-sm);
border-radius: var(--reversa-radius-sm);
font-size: var(--reversa-font-size-sm);
}
.reversa-doc-nav a:hover,
.reversa-doc-nav a.is-active {
color: var(--reversa-fg);
background: var(--reversa-surface);
text-decoration: none;
}
.reversa-doc-toolbar {
display: flex;
gap: var(--reversa-space-sm);
}
.reversa-doc-main {
grid-area: main;
padding: var(--reversa-space-xl);
max-width: 1200px;
width: 100%;
justify-self: start;
}
.reversa-doc-payload {
display: flex;
flex-direction: column;
gap: var(--reversa-space-lg);
}
.reversa-doc-title {
margin-bottom: var(--reversa-space-lg);
}
.reversa-doc-sidebar {
grid-area: sidebar;
padding: var(--reversa-space-lg);
background: var(--reversa-sidebar-bg);
border-left: 1px solid var(--reversa-border);
overflow-y: auto;
max-height: calc(100vh - var(--reversa-header-height));
position: sticky;
top: var(--reversa-header-height);
}
.reversa-doc-sidebar:empty {
display: none;
}
.reversa-doc-sidebar:empty + .reversa-doc-main {
grid-column: 1 / -1;
justify-self: center;
}
.reversa-doc-footer {
grid-area: footer;
padding: var(--reversa-space-md) var(--reversa-space-xl);
border-top: 1px solid var(--reversa-border);
background: var(--reversa-header-bg);
color: var(--reversa-fg-muted);
font-size: var(--reversa-font-size-sm);
display: flex;
flex-wrap: wrap;
align-items: center;
gap: var(--reversa-space-sm);
}
.reversa-doc-footer-sep { opacity: 0.4; }
/* Responsividade básica: sidebar vira drawer abaixo de 900px */
@media (max-width: 900px) {
body {
grid-template-columns: 1fr;
grid-template-areas:
"header"
"main"
"sidebar"
"footer";
}
.reversa-doc-sidebar {
position: static;
max-height: none;
border-left: none;
border-top: 1px solid var(--reversa-border);
}
}
/* ============================================================
3. Componentes utilitários
============================================================ */
.reversa-card {
background: var(--reversa-surface);
border: 1px solid var(--reversa-border);
border-radius: var(--reversa-radius);
padding: var(--reversa-space-lg);
}
.reversa-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
gap: var(--reversa-space-md);
}
.reversa-pill {
display: inline-flex;
align-items: center;
gap: var(--reversa-space-xs);
padding: 2px var(--reversa-space-sm);
border-radius: 999px;
font-size: var(--reversa-font-size-xs);
font-weight: 500;
background: var(--reversa-surface);
border: 1px solid var(--reversa-border);
}
.reversa-pill.is-critical { background: #ff5a4f1f; border-color: #ff5a4f; color: #ff5a4f; }
.reversa-pill.is-high { background: #ffa5001f; border-color: #ffa500; color: #ffa500; }
.reversa-pill.is-medium { background: #ffc8571f; border-color: #d3a032; color: #d3a032; }
.reversa-pill.is-low { background: #6cc46c1f; border-color: #6cc46c; color: #6cc46c; }
.reversa-pill.is-info { background: #4a9eff1f; border-color: #4a9eff; color: #4a9eff; }
.reversa-toast {
position: fixed;
bottom: var(--reversa-space-lg);
left: 50%;
transform: translateX(-50%);
padding: var(--reversa-space-sm) var(--reversa-space-lg);
background: var(--reversa-surface);
border: 1px solid var(--reversa-border);
border-radius: var(--reversa-radius);
box-shadow: 0 8px 24px rgba(0,0,0,0.2);
z-index: 100;
}
/* ============================================================
4. Variante: sober
============================================================ */
:root,
body[data-style="sober"] {
--reversa-bg: #f5f3ee;
--reversa-fg: #1e2937;
--reversa-fg-muted: #4d5a6b;
--reversa-accent: #3d4a5c;
--reversa-surface: #ffffff;
--reversa-surface-hover: #eceae4;
--reversa-sidebar-bg: #efece6;
--reversa-header-bg: #efece6;
--reversa-border: #d6d2c8;
--reversa-code-bg: #ece9e1;
--reversa-code-fg: #2b3a4a;
--reversa-font-body: "Inter", system-ui, -apple-system, "Segoe UI", sans-serif;
--reversa-font-heading: "Inter", system-ui, -apple-system, sans-serif;
--reversa-font-mono: "JetBrains Mono", ui-monospace, "Cascadia Code", monospace;
--reversa-font-size-xs: 12px;
--reversa-font-size-sm: 13px;
--reversa-font-size-base: 15px;
--reversa-font-size-h1: 28px;
--reversa-font-size-h2: 22px;
--reversa-font-size-h3: 18px;
--reversa-line-height-base: 1.55;
--reversa-space-xs: 4px;
--reversa-space-sm: 8px;
--reversa-space-md: 16px;
--reversa-space-lg: 24px;
--reversa-space-xl: 40px;
--reversa-radius-sm: 4px;
--reversa-radius: 8px;
--reversa-header-height: 64px;
}
/* ============================================================
5. Variante: premium (dark cinematográfico)
============================================================ */
body[data-style="premium"] {
--reversa-bg: #0a0a14;
--reversa-fg: #eaeaea;
--reversa-fg-muted: #9b9ba3;
--reversa-accent: #d4af37;
--reversa-surface: #14141e;
--reversa-surface-hover: #1f1f2c;
--reversa-sidebar-bg: #0f0f18;
--reversa-header-bg: #0f0f18;
--reversa-border: #2a2a38;
--reversa-code-bg: #1a1a26;
--reversa-code-fg: #f4d03f;
--reversa-font-body: "Lora", Georgia, "Times New Roman", serif;
--reversa-font-heading: "Inter", system-ui, sans-serif;
--reversa-font-mono: "JetBrains Mono", ui-monospace, monospace;
--reversa-space-xs: 6px;
--reversa-space-sm: 12px;
--reversa-space-md: 20px;
--reversa-space-lg: 32px;
--reversa-space-xl: 56px;
--reversa-font-size-h1: 36px;
--reversa-font-size-h2: 26px;
}
body[data-style="premium"] .reversa-doc-title {
letter-spacing: 0.01em;
}
body[data-style="premium"] .reversa-card {
box-shadow: 0 4px 16px rgba(0,0,0,0.4);
}
/* ============================================================
6. Variante: dense (grid de cards, saturado)
============================================================ */
body[data-style="dense"] {
--reversa-bg: #f8f9fa;
--reversa-fg: #1a1a2e;
--reversa-fg-muted: #5e6470;
--reversa-accent: #5b3fce;
--reversa-surface: #ffffff;
--reversa-surface-hover: #eef0f4;
--reversa-sidebar-bg: #f1f3f6;
--reversa-header-bg: #ffffff;
--reversa-border: #d8dde4;
--reversa-code-bg: #eef0f4;
--reversa-code-fg: #5b3fce;
--reversa-font-size-base: 14px;
--reversa-font-size-sm: 12px;
--reversa-line-height-base: 1.5;
--reversa-space-xs: 3px;
--reversa-space-sm: 6px;
--reversa-space-md: 12px;
--reversa-space-lg: 18px;
--reversa-space-xl: 28px;
--reversa-radius: 6px;
}
body[data-style="dense"] .reversa-doc-payload {
gap: var(--reversa-space-md);
}
body[data-style="dense"] .reversa-grid {
grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
}
/* ============================================================
7. Variante: exploratory (3D-friendly)
============================================================ */
body[data-style="exploratory"] {
--reversa-bg: #0d0d1a;
--reversa-fg: #eaeaea;
--reversa-fg-muted: #a0a0b8;
--reversa-accent: #a0e7e5;
--reversa-surface: #16162a;
--reversa-surface-hover: #1f1f38;
--reversa-sidebar-bg: rgba(15, 15, 30, 0.85);
--reversa-header-bg: rgba(15, 15, 30, 0.85);
--reversa-border: #2c2c44;
--reversa-code-bg: #1a1a2e;
--reversa-code-fg: #ffb3ba;
--reversa-font-body: "Inter", system-ui, sans-serif;
--reversa-font-heading: "Inter", system-ui, sans-serif;
--reversa-space-xl: 48px;
--reversa-font-size-h1: 32px;
}
body[data-style="exploratory"] .reversa-doc-main {
background: radial-gradient(ellipse at 30% 20%,
rgba(160, 231, 229, 0.08) 0%,
transparent 60%);
}
body[data-style="exploratory"] .reversa-doc-sidebar {
backdrop-filter: blur(8px);
}
/* ============================================================
8. Acessibilidade
============================================================ */
*:focus-visible {
outline: 2px solid var(--reversa-accent);
outline-offset: 2px;
border-radius: var(--reversa-radius-sm);
}
@media (prefers-reduced-motion: reduce) {
*, *::before, *::after {
animation-duration: 0.01ms !important;
transition-duration: 0.01ms !important;
}
}
.sr-only {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}
+119
templates/documentation/assets/js/nav.js
/*
* Reversa Documentation - Helper de navegação
*
* Marca o link da página atual como ativo,
* permite alternância de tema via botão no header,
* persiste a escolha em localStorage.
*/
(function () {
"use strict";
const STORAGE_KEY_THEME = "reversa.doc.theme";
const VALID_STYLES = ["sober", "premium", "dense", "exploratory"];
/**
* Marca o link de navegação que aponta para a página atual.
*/
function highlightActiveLink() {
const currentPath = window.location.pathname.split("/").pop() || "index.html";
const links = document.querySelectorAll(".reversa-doc-nav a[href]");
links.forEach((link) => {
const target = link.getAttribute("href").split("/").pop();
if (target === currentPath) {
link.classList.add("is-active");
link.setAttribute("aria-current", "page");
}
});
}
/**
* Cicla entre as 4 variantes de tema na ordem definida.
*/
function cycleTheme() {
const body = document.body;
const current = body.getAttribute("data-style") || "sober";
const currentIndex = VALID_STYLES.indexOf(current);
const nextIndex = (currentIndex + 1) % VALID_STYLES.length;
const next = VALID_STYLES[nextIndex];
applyTheme(next);
}
function applyTheme(style) {
if (!VALID_STYLES.includes(style)) return;
document.body.setAttribute("data-style", style);
try {
localStorage.setItem(STORAGE_KEY_THEME, style);
} catch (e) {
/* localStorage indisponível, ignora */
}
updateThemeButtonLabel(style);
}
function restoreTheme() {
try {
const saved = localStorage.getItem(STORAGE_KEY_THEME);
if (saved && VALID_STYLES.includes(saved)) {
applyTheme(saved);
return;
}
} catch (e) {
/* ignora */
}
const initial = document.body.getAttribute("data-style") || "sober";
updateThemeButtonLabel(initial);
}
function updateThemeButtonLabel(style) {
const btn = document.querySelector(".theme-toggle .theme-toggle-label");
if (btn) btn.textContent = capitalize(style);
}
function capitalize(s) {
return s.charAt(0).toUpperCase() + s.slice(1);
}
function attachThemeToggle() {
const btn = document.querySelector(".theme-toggle");
if (!btn) return;
btn.addEventListener("click", cycleTheme);
}
/**
* Adiciona suporte a navegação por teclas:
* j/k para avançar/voltar entre seções do conteúdo,
* Esc para fechar modais (futuro).
*/
function attachKeyboardNav() {
document.addEventListener("keydown", (e) => {
if (e.target.matches("input, textarea, select")) return;
if (e.key === "j") scrollBySection(1);
else if (e.key === "k") scrollBySection(-1);
});
}
function scrollBySection(direction) {
const sections = Array.from(document.querySelectorAll(".reversa-doc-main h2, .reversa-doc-main h3"));
if (sections.length === 0) return;
const scrollTop = window.scrollY + 80;
let currentIndex = 0;
for (let i = 0; i < sections.length; i++) {
if (sections[i].offsetTop <= scrollTop + 4) currentIndex = i;
}
const targetIndex = Math.max(0, Math.min(sections.length - 1, currentIndex + direction));
sections[targetIndex].scrollIntoView({ behavior: "smooth", block: "start" });
}
if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", init);
} else {
init();
}
function init() {
highlightActiveLink();
restoreTheme();
attachThemeToggle();
attachKeyboardNav();
}
})();
+162
templates/documentation/assets/js/sidebar.js
/*
* Reversa Documentation - Helper de sidebar reativa
*
* Cada controle dentro da sidebar declara um data-param.
* Mudanças disparam o evento "reversa:param-change" para
* a página específica reagir, e persistem em localStorage.
*
* Botão "Reset" restaura defaults declarados em data-default.
* Botão "Download PNG" captura o canvas principal da viewport.
*/
(function () {
"use strict";
const STORAGE_PREFIX = "reversa.sidebar.";
/**
* Inicializa todos os controles da sidebar atual.
*/
function init() {
const sidebar = document.querySelector(".reversa-doc-sidebar");
if (!sidebar) return;
const pageId = sidebar.dataset.page || document.body.dataset.page || "default";
const controls = sidebar.querySelectorAll("[data-param]");
controls.forEach((control) => {
attachControl(control, pageId);
restoreControl(control, pageId);
});
attachResetButton(sidebar, pageId);
attachExportButton(sidebar);
}
function attachControl(control, pageId) {
const eventName = control.type === "checkbox" ? "change" : "input";
control.addEventListener(eventName, () => {
const param = control.dataset.param;
const value = readControlValue(control);
persistValue(pageId, param, value);
dispatchChange(param, value, control);
});
}
function readControlValue(control) {
if (control.type === "checkbox") return control.checked;
if (control.type === "range" || control.type === "number") {
return parseFloat(control.value);
}
return control.value;
}
function writeControlValue(control, value) {
if (control.type === "checkbox") control.checked = !!value;
else control.value = value;
}
function restoreControl(control, pageId) {
const param = control.dataset.param;
const key = STORAGE_PREFIX + pageId + "." + param;
let saved;
try {
saved = localStorage.getItem(key);
} catch (e) {
return;
}
if (saved === null) return;
try {
const parsed = JSON.parse(saved);
writeControlValue(control, parsed);
dispatchChange(param, parsed, control);
} catch (e) {
/* dados corrompidos, ignora silencioso */
}
}
function persistValue(pageId, param, value) {
try {
const key = STORAGE_PREFIX + pageId + "." + param;
localStorage.setItem(key, JSON.stringify(value));
} catch (e) {
/* ignora se localStorage indisponível */
}
}
function dispatchChange(param, value, control) {
const event = new CustomEvent("reversa:param-change", {
detail: { param, value, control },
bubbles: true
});
control.dispatchEvent(event);
}
function attachResetButton(sidebar, pageId) {
const btn = sidebar.querySelector("[data-action='reset']") || sidebar.querySelector("#reset");
if (!btn) return;
btn.addEventListener("click", () => {
const controls = sidebar.querySelectorAll("[data-param]");
controls.forEach((control) => {
const defaultValue = control.dataset.default;
if (defaultValue === undefined) return;
let value = defaultValue;
if (control.type === "checkbox") value = defaultValue === "true";
else if (control.type === "range" || control.type === "number") value = parseFloat(defaultValue);
writeControlValue(control, value);
persistValue(pageId, control.dataset.param, value);
dispatchChange(control.dataset.param, value, control);
});
});
}
function attachExportButton(sidebar) {
const btn = sidebar.querySelector("[data-action='export-png']") || sidebar.querySelector("#export-png");
if (!btn) return;
btn.addEventListener("click", () => {
const canvas = document.querySelector("canvas");
if (!canvas) {
showToast("Nenhum canvas para exportar nesta página.");
return;
}
canvas.toBlob((blob) => {
if (!blob) {
showToast("Falha ao gerar PNG.");
return;
}
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = inferExportName();
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
URL.revokeObjectURL(url);
}, "image/png");
});
}
function inferExportName() {
const page = document.body.dataset.page || "view";
const stamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
return "reversa-" + page + "-" + stamp + ".png";
}
function showToast(message) {
const existing = document.querySelector(".reversa-toast");
if (existing) existing.remove();
const toast = document.createElement("div");
toast.className = "reversa-toast";
toast.setAttribute("role", "status");
toast.textContent = message;
document.body.appendChild(toast);
setTimeout(() => toast.remove(), 3500);
}
if (document.readyState === "loading") {
document.addEventListener("DOMContentLoaded", init);
} else {
init();
}
})();
+200
templates/documentation/demo/viewer-demo.html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Demo do Viewer | Sistema de Pagamentos Lendário</title>
<meta name="reversa-category" content="review">
<meta name="reversa-template" content="annotated-pr">
<meta name="reversa-source-md" content="audit.md">
<meta name="reversa-producer-agent" content="reversa-security-auditor">
<meta name="reversa-generated-at" content="2026-05-16T15:00:00Z">
<meta name="reversa-schema-version" content="1">
<link rel="stylesheet" href="../assets/css/style.css">
</head>
<body data-style="sober" data-page="demo">
<header class="reversa-doc-header">
<a class="reversa-doc-logo" href="#" aria-label="Início">
<span class="seal" aria-hidden="true">
<svg viewBox="0 0 32 32" width="32" height="32">
<circle cx="16" cy="16" r="14" fill="currentColor" opacity="0.15"/>
<circle cx="16" cy="16" r="7" fill="currentColor"/>
<circle cx="22" cy="10" r="3" fill="currentColor" opacity="0.6"/>
</svg>
</span>
<span class="project-name">Sistema de Pagamentos Lendário</span>
</a>
<nav class="reversa-doc-nav" aria-label="Seções da documentação">
<a href="#" class="is-active">Visão geral</a>
<a href="#">Arquitetura</a>
<a href="#">Módulos</a>
<a href="#">Métricas</a>
<a href="#">Timeline</a>
<a href="#">Glossário</a>
</nav>
<div class="reversa-doc-toolbar">
<button type="button" class="theme-toggle" aria-label="Alternar tema visual">
<span class="theme-toggle-label">Sober</span>
</button>
</div>
</header>
<main class="reversa-doc-main" role="main">
<div class="reversa-doc-payload">
<h1 class="reversa-doc-title">Demonstração do Chassis Visual</h1>
<p>
Esta página existe para validar visualmente as quatro variantes
de estilo do chassis compartilhado do Reversa. Use o botão no
canto superior direito para alternar entre <code>sober</code>,
<code>premium</code>, <code>dense</code> e <code>exploratory</code>.
A escolha persiste em <code>localStorage</code>.
</p>
<section>
<h2>Cards e grid responsivo</h2>
<div class="reversa-grid">
<div class="reversa-card">
<h3>Code City</h3>
<p>Visualização 3D com cada arquivo como prédio. Altura por LOC, largura por complexidade.</p>
<span class="reversa-pill is-info">3D</span>
</div>
<div class="reversa-card">
<h3>Module Map</h3>
<p>Força repulsiva entre nós, força atrativa entre dependentes. Detecção de ciclos automática.</p>
<span class="reversa-pill is-info">D3</span>
</div>
<div class="reversa-card">
<h3>Métricas</h3>
<p>Treemap de tamanho por pasta, top 20 mais complexos, distribuição de LOC.</p>
<span class="reversa-pill is-info">Highcharts</span>
</div>
</div>
</section>
<section>
<h2>Findings de exemplo (Annotated PR)</h2>
<div class="reversa-card">
<h3>SQL injection em endpoint /api/orders</h3>
<p>
<span class="reversa-pill is-critical">CRITICAL</span>
<span class="reversa-pill">src/api/orders.ts:47</span>
<span class="reversa-pill">OWASP A03:2021</span>
</p>
<pre><code>query = `SELECT * FROM orders WHERE id = ${userId}`</code></pre>
<p>
Concatenação direta de <code>userId</code> em SQL permite
injeção. Use parameterized queries com prepared statements.
</p>
</div>
<div class="reversa-card">
<h3>Cookie de sessão sem flag HttpOnly</h3>
<p>
<span class="reversa-pill is-high">HIGH</span>
<span class="reversa-pill">src/auth/session.ts:23</span>
</p>
<p>
Cookies de sessão devem usar flags <code>HttpOnly</code>,
<code>Secure</code> e <code>SameSite=Lax</code>.
</p>
</div>
<div class="reversa-card">
<h3>Validação de input parcial em /signup</h3>
<p>
<span class="reversa-pill is-medium">MEDIUM</span>
<span class="reversa-pill">src/api/signup.ts:12</span>
</p>
<p>
Email tem regex, senha não. Adicionar validação de
comprimento mínimo e complexidade.
</p>
</div>
</section>
<section>
<h2>Tipografia e código inline</h2>
<p>
O título da página usa <code>--reversa-font-heading</code>,
enquanto o corpo usa <code>--reversa-font-body</code>. Em
variante <code>premium</code>, o corpo vira serifa Lora;
nas demais é Inter.
</p>
<pre><code>function colorForModule(module) {
if (module.isHotPath) return 0xff5a4f;
return TYPE_COLORS[module.type] || 0xcccccc;
}</code></pre>
</section>
</div>
</main>
<aside class="reversa-doc-sidebar" aria-label="Controles" data-page="demo">
<h3>Controles de exemplo</h3>
<label>
Profundidade
<input type="range" min="1" max="10" value="5" step="1"
data-param="depth" data-default="5">
</label>
<label>
Threshold de hot path
<input type="range" min="0" max="100" value="50" step="5"
data-param="hotThreshold" data-default="50">
</label>
<label>
<input type="checkbox" data-param="showLabels" data-default="true" checked>
Labels visíveis
</label>
<label>
<input type="checkbox" data-param="highlightCycles" data-default="false">
Destacar ciclos
</label>
<label>
Filtrar pasta
<select data-param="folder" data-default="all">
<option value="all">Todas</option>
<option value="src/auth">src/auth</option>
<option value="src/api">src/api</option>
<option value="src/db">src/db</option>
</select>
</label>
<div style="margin-top: 24px; display: flex; gap: 8px;">
<button type="button" data-action="reset" id="reset">Reset</button>
<button type="button" data-action="export-png" id="export-png">Exportar PNG</button>
</div>
<div style="margin-top: 24px; font-size: 12px; opacity: 0.7;">
<p>
Alterações nos controles disparam o evento
<code>reversa:param-change</code> e persistem em
<code>localStorage</code>.
</p>
</div>
</aside>
<footer class="reversa-doc-footer">
<span class="reversa-doc-footer-text">
Gerado por Reversa em
<time datetime="2026-05-16T15:00:00Z">16 de maio de 2026, 15h00</time>
</span>
<span class="reversa-doc-footer-sep" aria-hidden="true">·</span>
<a href="#" class="reversa-doc-source-link">Fonte em markdown</a>
</footer>
<script src="../assets/js/nav.js"></script>
<script src="../assets/js/sidebar.js"></script>
<script>
// Demonstração de captura do evento custom
document.addEventListener("reversa:param-change", (e) => {
console.log("[demo] parâmetro alterado:", e.detail);
});
</script>
</body>
</html>
templates/documentation/pages/arquitetura.html.tpl

Sorry, the diff of this file is not supported yet

templates/documentation/pages/deck.html.tpl

Sorry, the diff of this file is not supported yet

templates/documentation/pages/features/feature.html.tpl

Sorry, the diff of this file is not supported yet

templates/documentation/pages/glossario.html.tpl

Sorry, the diff of this file is not supported yet

templates/documentation/pages/index.html.tpl

Sorry, the diff of this file is not supported yet

templates/documentation/pages/metricas.html.tpl

Sorry, the diff of this file is not supported yet

templates/documentation/pages/modulos.html.tpl

Sorry, the diff of this file is not supported yet

templates/documentation/pages/timeline.html.tpl

Sorry, the diff of this file is not supported yet

templates/documentation/pages/topologia.html.tpl

Sorry, the diff of this file is not supported yet

+63
templates/documentation/scripts/convert_chronicle.py
#!/usr/bin/env python3
"""
convert_chronicle.py — Converte .reversa/chronicle.md em timeline.json.
Esqueleto da Onda 1. Parser real de markdown e classificação de eventos na TASK-09.
Uso:
python convert_chronicle.py --src .reversa/chronicle.md \
--out .reversa/documentation/assets/data/timeline.json
"""
import argparse
import json
import re
from datetime import datetime, timezone
from pathlib import Path
DATE_PATTERN = re.compile(r"\b(\d{4}-\d{2}-\d{2})\b")
HEADING_PATTERN = re.compile(r"^#{1,3}\s+(.+)$", re.MULTILINE)
def parse_chronicle(text: str):
events = []
for line in text.splitlines():
date_match = DATE_PATTERN.search(line)
if not date_match:
continue
events.append({
"date": date_match.group(1),
"title": line.strip("-* ").strip()[:120],
"raw": line.strip(),
})
return events
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--src", required=True, help="Caminho para .reversa/chronicle.md")
parser.add_argument("--out", required=True, help="Caminho de saída do timeline.json")
args = parser.parse_args()
src = Path(args.src)
if not src.exists():
print(f"AVISO: {src} não existe. Pulando geração de timeline.json.")
return
text = src.read_text(encoding="utf-8")
events = parse_chronicle(text)
out = {
"schemaVersion": 1,
"generatedAt": datetime.now(timezone.utc).isoformat(),
"events": events,
}
out_path = Path(args.out)
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(json.dumps(out, ensure_ascii=False, indent=2), encoding="utf-8")
print(f"OK: {len(events)} eventos em {out_path}")
if __name__ == "__main__":
main()
+65
templates/documentation/scripts/convert_soul.py
#!/usr/bin/env python3
"""
convert_soul.py — Converte .reversa/soul.md em soul.json estruturado.
Esqueleto da Onda 1. Extração rica (entidades, decisões, sinônimos) na TASK-10.
Uso:
python convert_soul.py --src .reversa/soul.md \
--out .reversa/documentation/assets/data/soul.json
"""
import argparse
import json
import re
from datetime import datetime, timezone
from pathlib import Path
def split_sections(text: str):
sections = {}
current = None
buffer = []
for line in text.splitlines():
heading = re.match(r"^##\s+(.+)$", line)
if heading:
if current:
sections[current] = "\n".join(buffer).strip()
current = heading.group(1).strip()
buffer = []
else:
buffer.append(line)
if current:
sections[current] = "\n".join(buffer).strip()
return sections
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--src", required=True, help="Caminho para .reversa/soul.md")
parser.add_argument("--out", required=True, help="Caminho de saída do soul.json")
args = parser.parse_args()
src = Path(args.src)
if not src.exists():
print(f"AVISO: {src} não existe. Pulando geração de soul.json.")
return
text = src.read_text(encoding="utf-8")
sections = split_sections(text)
out = {
"schemaVersion": 1,
"generatedAt": datetime.now(timezone.utc).isoformat(),
"sections": sections,
"concepts": [], # extração rica fica para TASK-10
}
out_path = Path(args.out)
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(json.dumps(out, ensure_ascii=False, indent=2), encoding="utf-8")
print(f"OK: {len(sections)} seções em {out_path}")
if __name__ == "__main__":
main()
+46
templates/documentation/scripts/extract_deps.py
#!/usr/bin/env python3
"""
extract_deps.py — Produz deps.json para o Time Reversa Docs.
Esqueleto da Onda 1. Análise real de imports por linguagem entra na TASK-07.
Schema de saída: ver specs/reversa-docs/design.md, seção "Schema de deps.json".
Uso:
python extract_deps.py --modules .reversa/documentation/assets/data/modules.json \
--out .reversa/documentation/assets/data/deps.json
"""
import argparse
import json
from datetime import datetime, timezone
from pathlib import Path
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--modules", required=True,
help="Caminho para modules.json gerado por extract_modules.py")
parser.add_argument("--out", required=True, help="Caminho de saída do deps.json")
args = parser.parse_args()
modules_data = json.loads(Path(args.modules).read_text(encoding="utf-8"))
nodes = [{"id": m["id"]} for m in modules_data.get("modules", [])]
# Análise de imports real na TASK-07. Por ora apenas nodes vazios + edges vazias.
out = {
"schemaVersion": 1,
"generatedAt": datetime.now(timezone.utc).isoformat(),
"nodes": nodes,
"edges": [],
"cycles": [],
}
out_path = Path(args.out)
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(json.dumps(out, ensure_ascii=False, indent=2), encoding="utf-8")
print(f"OK (esqueleto): {len(nodes)} nodes, 0 edges em {out_path}")
if __name__ == "__main__":
main()
+82
templates/documentation/scripts/extract_modules.py
#!/usr/bin/env python3
"""
extract_modules.py — Produz modules.json para o Time Reversa Docs.
Esqueleto da Onda 1. Implementação completa na TASK-07.
Schema de saída: ver specs/reversa-docs/design.md, seção
"JSONs intermediários em assets/data/" → "Schema de modules.json".
Uso:
python extract_modules.py --root . --out .reversa/documentation/assets/data/modules.json
"""
import argparse
import json
import os
from datetime import datetime, timezone
from pathlib import Path
LANG_BY_EXT = {
".py": "python",
".js": "js", ".mjs": "js", ".cjs": "js",
".ts": "ts", ".tsx": "ts",
".go": "go",
".java": "java",
}
IGNORED_DIRS = {".git", "node_modules", ".reversa", "_reversa_sdd",
"dist", "build", "__pycache__", ".venv", "venv", ".tmp-mkdocs-site"}
def count_loc(path: Path) -> int:
try:
with path.open(encoding="utf-8", errors="ignore") as f:
return sum(1 for line in f if line.strip())
except OSError:
return 0
def walk_modules(root: Path):
for dirpath, dirnames, filenames in os.walk(root):
dirnames[:] = [d for d in dirnames if d not in IGNORED_DIRS]
for name in filenames:
ext = Path(name).suffix.lower()
if ext not in LANG_BY_EXT:
continue
abs_path = Path(dirpath) / name
rel_path = str(abs_path.relative_to(root)).replace("\\", "/")
yield {
"id": rel_path,
"name": Path(name).stem,
"folder": str(Path(dirpath).relative_to(root)).replace("\\", "/") or ".",
"loc": count_loc(abs_path),
"language": LANG_BY_EXT[ext],
# complexity e type ficam para a TASK-07 (precisam de AST por linguagem)
}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--root", default=".", help="Raiz do projeto a analisar")
parser.add_argument("--out", required=True, help="Caminho de saída do modules.json")
args = parser.parse_args()
root = Path(args.root).resolve()
modules = list(walk_modules(root))
out = {
"schemaVersion": 1,
"generatedAt": datetime.now(timezone.utc).isoformat(),
"rootPath": str(root),
"modules": modules,
}
out_path = Path(args.out)
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(json.dumps(out, ensure_ascii=False, indent=2), encoding="utf-8")
print(f"OK: {len(modules)} módulos em {out_path}")
if __name__ == "__main__":
main()
+66
templates/documentation/scripts/list_specs.py
#!/usr/bin/env python3
"""
list_specs.py — Lista specs em _reversa_sdd/ e produz features-index.json.
Esqueleto da Onda 1. Extração de metadados (status, tamanho, autor) na TASK-10.
Uso:
python list_specs.py --sdd-root _reversa_sdd \
--out .reversa/documentation/assets/data/features-index.json
"""
import argparse
import json
from datetime import datetime, timezone
from pathlib import Path
def find_specs(sdd_root: Path):
if not sdd_root.exists():
return []
specs = []
for child in sorted(sdd_root.iterdir()):
if not child.is_dir():
continue
req = child / "requirements.md"
design = child / "design.md"
tasks = child / "tasks.md"
if not req.exists():
continue
specs.append({
"id": child.name,
"slug": child.name.lower().replace("_", "-").replace(" ", "-"),
"path": str(child).replace("\\", "/"),
"files": {
"requirements": req.exists(),
"design": design.exists(),
"tasks": tasks.exists(),
},
})
return specs
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--sdd-root", default="_reversa_sdd", help="Raiz das specs SDD")
parser.add_argument("--out", required=True, help="Caminho de saída do features-index.json")
args = parser.parse_args()
sdd_root = Path(args.sdd_root)
specs = find_specs(sdd_root)
out = {
"schemaVersion": 1,
"generatedAt": datetime.now(timezone.utc).isoformat(),
"sddRoot": str(sdd_root),
"specs": specs,
}
out_path = Path(args.out)
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(json.dumps(out, ensure_ascii=False, indent=2), encoding="utf-8")
print(f"OK: {len(specs)} specs em {out_path}")
if __name__ == "__main__":
main()
+59
templates/documentation/viewer.html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title><!-- TITLE --> | <!-- PROJECT_NAME --></title>
<!-- Meta-tags do Reversa para auto-discovery -->
<meta name="reversa-category" content="<!-- REVERSA_CATEGORY -->">
<meta name="reversa-template" content="<!-- REVERSA_TEMPLATE -->">
<meta name="reversa-source-md" content="<!-- REVERSA_SOURCE_MD -->">
<meta name="reversa-producer-agent" content="<!-- REVERSA_PRODUCER_AGENT -->">
<meta name="reversa-generated-at" content="<!-- GENERATED_AT -->">
<meta name="reversa-schema-version" content="1">
<link rel="stylesheet" href="assets/css/style.css">
<!-- HEAD_EXTRAS -->
</head>
<body data-style="<!-- VISUAL_STYLE -->" data-page="<!-- PAGE_ID -->">
<header class="reversa-doc-header">
<a class="reversa-doc-logo" href="index.html" aria-label="Início">
<span class="seal" aria-hidden="true"><!-- MINI_SEAL_SVG --></span>
<span class="project-name"><!-- PROJECT_NAME --></span>
</a>
<nav class="reversa-doc-nav" aria-label="Seções da documentação">
<!-- NAV_LINKS -->
</nav>
<div class="reversa-doc-toolbar">
<button type="button" class="theme-toggle" aria-label="Alternar tema">
<span class="theme-toggle-label">Tema</span>
</button>
</div>
</header>
<main class="reversa-doc-main" role="main">
<div class="reversa-doc-payload">
<h1 class="reversa-doc-title"><!-- TITLE --></h1>
<!-- PAYLOAD -->
</div>
</main>
<aside class="reversa-doc-sidebar" aria-label="Controles" data-page="<!-- PAGE_ID -->">
<!-- SIDEBAR -->
</aside>
<footer class="reversa-doc-footer">
<span class="reversa-doc-footer-text">
Gerado por Reversa em <time datetime="<!-- GENERATED_AT -->"><!-- GENERATED_AT_LABEL --></time>
</span>
<span class="reversa-doc-footer-sep" aria-hidden="true">·</span>
<a href="<!-- REVERSA_SOURCE_MD -->" class="reversa-doc-source-link">Fonte em markdown</a>
</footer>
<script src="assets/js/nav.js"></script>
<script src="assets/js/sidebar.js"></script>
<!-- SCRIPTS -->
</body>
</html>
+11
-2
lib/commands/install.js

@@ -7,3 +7,3 @@ import { join, resolve } from 'path';

import { checkExistingInstallation } from '../installer/validator.js';
import { runInstallPrompts, MIGRATION_AGENT_IDS, TRANSLATOR_AGENT_IDS, FORWARD_AGENT_IDS, PRICING_AGENT_IDS } from '../installer/prompts.js';
import { runInstallPrompts, MIGRATION_AGENT_IDS, TRANSLATOR_AGENT_IDS, FORWARD_AGENT_IDS, PRICING_AGENT_IDS, DOCS_AGENT_IDS } from '../installer/prompts.js';
import { Writer } from '../installer/writer.js';

@@ -151,2 +151,3 @@ import { buildManifest, saveManifest, loadManifest } from '../installer/manifest.js';

const pricingInstalled = answers.agents.filter(a => PRICING_AGENT_IDS.includes(a));
const docsInstalled = answers.agents.filter(a => DOCS_AGENT_IDS.includes(a));
const discoveryInstalled = answers.agents.filter(a =>

@@ -156,3 +157,4 @@ !MIGRATION_AGENT_IDS.includes(a) &&

!FORWARD_AGENT_IDS.includes(a) &&
!PRICING_AGENT_IDS.includes(a)
!PRICING_AGENT_IDS.includes(a) &&
!DOCS_AGENT_IDS.includes(a)
);

@@ -176,2 +178,5 @@

}
if (docsInstalled.length > 0) {
console.log(` ${chalk.cyan('Documentation Team:')} ${docsInstalled.length} agent(s)`);
}
if (translatorsInstalled.length > 0) {

@@ -197,2 +202,6 @@ console.log(` ${chalk.cyan('Translators:')} ${translatorsInstalled.length} agent(s)`);

}
if (docsInstalled.length > 0) {
const docsCommand = hasSlashEngine ? '/reversa-docs' : 'reversa-docs';
console.log(chalk.cyan(` → For a visual HTML mini-site of the project, run ${docsCommand} after discovery`));
}
if (translatorsInstalled.includes('reversa-n8n')) {

@@ -199,0 +208,0 @@ const n8nCommand = hasSlashEngine ? '/reversa-n8n' : 'reversa-n8n';

+18
-0
lib/installer/prompts.js

@@ -55,2 +55,17 @@ import inquirer from 'inquirer';

const DOCS_TEAM = [
// Orquestrador e 4 agentes especialistas
'reversa-docs',
'reversa-docs-mapper',
'reversa-docs-analyst',
'reversa-docs-storyteller',
'reversa-docs-publisher',
// Skills compartilhadas consumidas pelo time
'reversa-arquitetura-3d',
'reversa-selo-generativo',
'reversa-highcharts-visualizer',
'reversa-especialista-d3',
'reversa-image-prompt-json',
];
export const DISCOVERY_AGENT_IDS = DISCOVERY_CORE;

@@ -61,2 +76,3 @@ export const MIGRATION_AGENT_IDS = MIGRATION_TEAM;

export const PRICING_AGENT_IDS = PRICING_TEAM;
export const DOCS_AGENT_IDS = DOCS_TEAM;

@@ -68,2 +84,3 @@ const TEAM_TO_AGENTS = {

pricing: PRICING_TEAM,
docs: DOCS_TEAM,
};

@@ -95,2 +112,3 @@

{ name: 'Code Forward Agents', value: 'forward', checked: true },
{ name: 'Documentation Agents (HTML mini-site)', value: 'docs', checked: true },
{ name: 'Pricing and Size Agents', value: 'pricing', checked: true },

@@ -97,0 +115,0 @@ { name: 'Translators N8N->Specs->Python', value: 'translators', checked: false },

+1
-1
package.json
{
"name": "reversa",
"version": "1.2.39",
"version": "1.2.40",
"description": "Transform legacy systems into executable specifications for AI coding agents",

@@ -5,0 +5,0 @@ "bin": {

+14
-0
README.md

@@ -137,2 +137,16 @@ # Reversa

### Documentation Team (HTML mini-site)
After discovery completes, this team turns the extracted knowledge into a self-contained HTML mini-site under `.reversa/documentation/`. Run `/reversa-docs` to orchestrate the full team, or activate any agent in isolation to regenerate only its pages.
| Agent | Role |
|-------|------|
| **Reversa Docs** | Orchestrates the team, runs the 3-question interview, computes deterministic seed. Activated via `/reversa-docs` |
| **Mapper** | Spatial structure: `arquitetura.html` (Code City 3D, Three.js), `modulos.html` (force-directed D3), `topologia.html` (legacy vs modern side-by-side) |
| **Analyst** | Quantitative data: `metricas.html` (Highcharts treemap, sankey, histogram, columns), `timeline.html` (events from `.reversa/chronicle.md`) |
| **Storyteller** | Narrative: `glossario.html` (client-side search), `deck.html` (6 to 10 navigable slides), `features/<spec>.html` (one per SDD spec) |
| **Publisher** | Final integration: `index.html` with hero + unique generative seal, auto-discovery of auxiliary HTMLs from other agents, link validation, local telemetry |
The team brings 5 shared skills (`reversa-arquitetura-3d`, `reversa-selo-generativo`, `reversa-highcharts-visualizer`, `reversa-especialista-d3`, `reversa-image-prompt-json`) which are installed automatically alongside the team. The output is a static mini-site that opens via `file://` with no server required.
---

@@ -139,0 +153,0 @@