# Visual QA SVG

Usa questa reference quando un task modifica resa visiva, geometria, stroke/fill,
transform, viewport, conversione o export.

## Gate

Prima di chiudere:

1. valida struttura/sintassi;
2. tenta verifica browser con Playwright su `file://`;
3. acquisisci screenshot o fallback render locale;
4. controlla console/network se hai usato il browser;
5. compila l'output standard.

Solo una richiesta esplicita di sola validazione sintattica puo' chiudere senza
prova visiva.

## Pre-flight Playwright

Prima del fallback visuale:

1. esegui `browser_session` con `action="get_capabilities"`;
2. se capability legacy/non disponibile, prova comunque `navigate`;
3. usa `action="navigate"` su `file://` con `project_path` alla root progetto;
4. passa a fallback locale solo dopo errore raw esplicito.

## Retry Policy

Se il primo `navigate` fallisce:

1. classifica errore transiente o strutturale;
2. per errore transiente, ritenta una seconda volta con stessi `url` e
   `project_path`;
3. se il secondo tentativo riesce, continua senza fallback;
4. se fallisce ancora, usa fallback locale;
5. per errore strutturale, non insistere oltre due tentativi.

Esempi:

- transiente: `Cannot read properties of null (reading 'goto')`;
- strutturale: protocollo non supportato, navigazione non consentita, root fuori
  allowed roots.

## Path Windows

Normalizza sempre:

```text
url = file:///D:/mcp-servers/skills/svg/evals/fixtures/valid-minimal.svg
project_path = D:/mcp-servers
```

Regole:

- URL `file:///D:/path/to/file.svg`;
- slash `/` nella URL e nel `project_path`;
- `project_path` alla root che contiene il file target;
- niente workaround se la root non e' consentita;
- evita protocolli non supportati come `about:`.

## Error Taxonomy

- `E_RUNTIME_TRANSIENT`: page/context nullo o sessione instabile. Ritenta una
  volta.
- `E_PROTOCOL_UNSUPPORTED`: correggi URL a `file:///...`.
- `E_ROOT_NOT_ALLOWED`: riallinea `project_path` a root valida, se disponibile.
- `E_CAPABILITY_MISMATCH`: capability assente/legacy; prova comunque `navigate`
  e valuta errore raw.

## Output Standard

Per task con verifica visiva riporta:

- `MCP attempt`: `success|fail` + errore raw se presente;
- `Attempt count`: tentativi `navigate` eseguiti;
- `Tool actions run`: `get_capabilities`, `navigate`, `screenshot`,
  `get_console_logs`, `get_network_errors` se applicabili;
- `Raw error (last)`: ultimo errore raw o `none`;
- `Fallback reason`: motivo fallback o `none`;
- `Evidence path`: path assoluto screenshot/render;
- `Function used`: helper `tools/` usato oppure `none` + motivo.

## Pre-Close Checklist

- helper-first rispettato quando applicabile;
- comando helper realmente eseguito e output verificabile;
- controllo strutturale/sintattico completato;
- prova visiva acquisita o fallback locale con evidenza;
- console/network controllati quando browser disponibile;
- output standard compilato.