> ## Documentation Index
> Fetch the complete documentation index at: https://docs-attestly.code4source.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Builder visual

> Escreva rulesets visualmente no playground — arraste nós, conecte e rode no mapa.

O **playground** é um ambiente visual onde você escreve e testa
rulesets sem precisar mexer em JSON na mão. Ele junta um mapa com um
**builder** baseado em grafo: você desenha um polígono, solta nós em
um canvas, conecta, e vê o verdict na mesma tela.

## Visão geral

O playground divide a tela em três áreas:

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/overview-light.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=eb7c85222168f8f3a6f1add07d4ef223" alt="Layout do playground: mapa à esquerda, canvas do builder no centro, painel de resultados à direita" width="2880" height="1800" data-path="images/builder/overview-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/overview-dark.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=ff294e5f7c5ca2ca3393bf5dcfe7b365" alt="Layout do playground: mapa à esquerda, canvas do builder no centro, painel de resultados à direita" width="2880" height="1800" data-path="images/builder/overview-dark.png" />
</Frame>

1. **Mapa** — desenhe ou cole uma geometria. Ela vira o `$input` de
   todo set ancorado nela.
2. **Canvas do builder** — o ruleset visual. Cada nó é um `set`,
   `projection`, `check` ou `verdict`; arestas representam
   referências (ex.: um check apontando para um set).
3. **Painel** — o botão **Run** ao vivo, a visualização JSON, o
   verdict e a evidence após cada execução.

## Loop de autoria

O loop típico:

1. Desenhe um polígono no mapa (ou cole GeoJSON).
2. Escolha um ponto de partida — canvas vazio ou um
   [template](#templates).
3. Adicione nós da paleta e conecte-os.
4. Clique em **Run** para avaliar contra o polígono.
5. Inspecione o verdict e a evidence por check.
6. Itere.

## A paleta

A paleta na sidebar tem os tipos de nó que você pode soltar no
canvas:

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/palette-light.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=29c7ab1b58fa1211b2370e81526cd026" alt="Paleta do builder com os cinco tipos de nó" width="2880" height="1800" data-path="images/builder/palette-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/palette-dark.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=db525815d80a6a1668b5ea5e164d70eb" alt="Paleta do builder com os cinco tipos de nó" width="2880" height="1800" data-path="images/builder/palette-dark.png" />
</Frame>

| Nó            | O que produz                                                                           |
| ------------- | -------------------------------------------------------------------------------------- |
| `source_set`  | Um set ancorado em um source espacial (ex.: `icmbio_ucs_federais`).                    |
| `subject_set` | Um set ancorado em um subject register (ex.: `ofac_sdn`).                              |
| `setop_set`   | Um set construído via `union` / `intersection` / `difference` de outros sets.          |
| `projection`  | Um valor escalar ou geométrico computado sobre um set (`count`, `total_area_m2`, ...). |
| `check`       | Um predicate booleano com uma severity. Alimenta o verdict.                            |

Solte um nó, depois clique nele para abrir o **editor** dele na
sidebar direita.

## Editores

Todo nó tem um editor tipado. O editor aplica as mesmas regras que a
API aplica — configurações inválidas são sinalizadas antes do run.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/source-set-editor-light.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=4f017459e29d166a47b953fdcc430cc2" alt="Editor de source set: seletor de source, op de join, target, filter opcional" width="2880" height="1800" data-path="images/builder/source-set-editor-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/source-set-editor-dark.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=e902fb10a6408484136672bace77a8fa" alt="Editor de source set: seletor de source, op de join, target, filter opcional" width="2880" height="1800" data-path="images/builder/source-set-editor-dark.png" />
</Frame>

Para um `source_set`, você escolhe:

* O **source** do catálogo (auto-sugerido via `GET /v1/sources`).
* O **join** — `intersects`, `contains`, `within`, `covers`,
  `covered_by`, `overlaps`, `touches`, `crosses`, `disjoint`,
  `equals`, `dwithin`, `beyond` para sets espaciais; `equals` /
  `ilike` quando o set está ancorado em um subject register.
* O **target** — `$input` ou outro set do grafo.
* Um **filter** opcional (ex.: temporal, property-equals).

Para um `check`, você escolhe:

* A **severity** — `critical`, `high`, `medium`, `low`, `info`.
* O **predicate** — `exists` (set não-vazio) ou `threshold`
  (projection referenciada passa por uma comparação).

## Conectando nós

Arraste do handle de saída de um nó até o handle de entrada de
outro. O builder rejeita conexões que criariam ciclos ou que
violam tipos.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/connections-light.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=7c3166e42fecab0c0b0335db07e3d198" alt="Dois source sets alimentando um setop set, que alimenta um check" width="2880" height="1800" data-path="images/builder/connections-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/connections-dark.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=7f35db95383a4fdeb7b39fe1f2542b06" alt="Dois source sets alimentando um setop set, que alimenta um check" width="2880" height="1800" data-path="images/builder/connections-dark.png" />
</Frame>

## Run e inspeção

Clique em **Run** na topbar para avaliar o canvas contra a
geometria atual do mapa. O painel atualiza com:

* O `status` (`ok` / `degraded`) e o `outcome` (`compliant`,
  `warning`, `non_compliant`, `degraded`) no topo.
* Cada check: `triggered`, `severity`, lista de evidence.
* Cada projection: valor computado.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/run-result-light.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=48bd6b04f98557410a24e8d527ffa039" alt="Painel de resultado mostrando um outcome non_compliant com a evidence destacada no mapa" width="2880" height="1800" data-path="images/builder/run-result-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/run-result-dark.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=0bcad10d7d57fb2977c9011e9a23514f" alt="Painel de resultado mostrando um outcome non_compliant com a evidence destacada no mapa" width="2880" height="1800" data-path="images/builder/run-result-dark.png" />
</Frame>

As feições de evidence ficam destacadas no mapa para você ver
exatamente quais polígonos provocaram o verdict.

## Visualização JSON

Toda edição visual sincroniza nos dois sentidos com um documento
JSON. Clique em **Show JSON** para abrir o modal — copie o body para
usar direto em `POST /v1/evaluate`, ou cole um ruleset para carregá-lo
no canvas.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/json-view-light.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=3b1d260797f91fa004456f9a39b43942" alt="Modal JSON mostrando o body canônico do ruleset" width="2880" height="1800" data-path="images/builder/json-view-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/code4source/xWaIkEoznkZrpr3A/images/builder/json-view-dark.png?fit=max&auto=format&n=xWaIkEoznkZrpr3A&q=85&s=f106854c908a7436fca1ddee3e2090d7" alt="Modal JSON mostrando o body canônico do ruleset" width="2880" height="1800" data-path="images/builder/json-view-dark.png" />
</Frame>

## Templates

A sidebar oferece pontos de partida prontos cobrindo padrões comuns:

| Template              | O que mostra                                                              |
| --------------------- | ------------------------------------------------------------------------- |
| `overlap_ratio_tiers` | Checks em camadas sobre razões de sobreposição (majority vs partial).     |
| `distance_tiers`      | Camadas de severity baseadas em distância (very close / close / far).     |
| `distance_band`       | Match de feições em uma faixa de distância `[min, max]`.                  |
| `chained_sets`        | Um set cruzado contra outro set em vez de `$input`.                       |
| `dynamic_buffer_app`  | Buffer cuja distância é lida de uma propriedade da feição.                |
| `merged_hazard_zone`  | Projection `merge` unificando geometrias de um set numa camada de hazard. |
| `temporal_recency`    | Filtra feições mais novas/velhas que uma janela relativa.                 |
| `multi_join`          | Múltiplos sources em um único ruleset.                                    |

Templates carregam no canvas; a partir daí você adapta nomes,
sources, severities e thresholds à sua política.

## Quando usar o builder vs JSON cru

* **Builder**: explorar políticas, demos para stakeholders, escrever
  uma primeira versão visualmente antes de revisar.
* **JSON cru**: editar um ruleset salvo de forma programática, code
  review em um PR, geração automática a partir de uma config de
  alto nível.

Os dois são intercambiáveis — a visualização JSON é canônica e o
builder é só uma renderização sobre ela.