---
name: svg-quality-audit
description: >-
  Audits a folder of SVGs for XML integrity, executable-script risk, and visual
  quality via Chrome headless render plus a free vision-language model. Use when
  asked to analyze, check, or audit SVG quality, or before shipping a generated
  SVG batch. Not for creating or restyling SVGs (use svg-creator). Never claim
  visual quality from XML structure alone.
version: 1.0.1
---

# SVG quality audit

## When to Use
- User wants a quality read on a collection of SVGs.
- Before committing / shipping a generated SVG batch (pairs with the project's vision-verify-before-ship rule).
- Diagnosing "why do these render wrong / look like sludge".

## Prerequisites
- **Target folder:** the SVG directory the user named. Do not assume a private vault path.
- **Project rules:** if the repo has SVG shipping rules, read those first.
- **Vision gap:** many agents cannot judge binary PNGs by reading pixels. Render each sample SVG → PNG (Chrome headless is reliable) and score the PNG with a vision-language model (OpenRouter free vision or local Ollama). Do not claim visual quality from XML structure alone.

## Procedure

**Phase 1 — Structural scan (100% of files, fast, no render needed).**
1. Run `scripts/structure_scan.py <dir>`.
2. Review the output: valid-XML count, drawable-shape distribution, gradient/filter/text/image counts, and defect buckets. Pure stdlib, no deps.

**Phase 2 — Render sample (only what you'll vision-judge).**
1. Run `scripts/render_vision_judge.py --render-only <dir> <out>`.
2. This renders each SVG to a 400×400 PNG with a checkerboard (transparency) backdrop via Chrome headless. Resumable.

**Phase 3 — Vision judge (the ONLY way to catch visual defects structure misses).**
1. Run `scripts/render_vision_judge.py --judge <out>`.
2. Scores each PNG 1–10 with a strict rubric (`SCORE:` / `FLAGS:` / `WHY:`) via the free VLM. Resumable, per-call timeout, 429 backoff, incremental JSON. Run large passes in the background.

**Working recipe:**
- **OpenRouter free vision:** list live free vision models via `GET https://openrouter.ai/api/v1/models` and pick one with image input. Pass the key via env `OPENROUTER_API_KEY`. Never print the key. Never read a redacted placeholder from a local config and treat it as live.
- **Local Ollama:** a local vision-capable model is fine for small samples; flaky for large batches under VRAM pressure.
- Load `references/free-vision-endpoints.md` when configuring VLM endpoints.

**Defect taxonomy:**
- Load `references/svg-defect-taxonomy.md` for per-defect counts, example files, and recovery one-liners.
- **Escape-bug (dominant):** literal `\n` / `\t` / `\"` where real newlines / quotes belong (JSON / `repr()` serialization bug). ~735 recover by un-escaping; Chrome already renders them. NOT corruption.
- **JSON-LD `<script>` is BENIGN.** `type="application/ld+json"` = schema.org metadata. The "65% have `<script>`" alarm is false — 0 executable JS. ALWAYS separate `application/ld+json` from `text/javascript` / `application/javascript`.
- **LLM-junk-after-`</svg>`:** model commentary leaked after the close tag. Renders but must be trimmed for a clean library.
- **Duplicate attributes** (e.g. two `opacity=`), **mismatched tags**, **undefined entities** — invalid XML, fix required.
- **Structure ≠ visual quality:** a file can be valid XML yet score 3 ("empty / basic shapes"). Vision is mandatory for a real quality verdict.

## Pitfalls
- ElementTree's strict parser over-flags: "invalid token at line 1 col 38" is almost always the escape-bug, NOT corruption. Test un-escape recovery before declaring a file dead.
- Do NOT claim "done / shipped" from structure alone — render + vision a stratified sample first (vision-verify-before-ship rule).
- agy/* generation needs heavy handholding or it emits low-quality / near-duplicate sludge — if you regenerate fixes via Jules / agy, over-specify the brief (subject, palette, shape budget, no `Math.random()`, no template recycling).
- Free VLM tiers are rate-limited; loop with 429 backoff and run large passes in the background.
- The escape-bug un-escape is a **no-op on clean files** (verified: 186 clean files stayed valid after the replace) — safe to apply across the whole set.

## Verification
- Confirm `scripts/structure_scan.py` outputs valid-XML count and defect buckets.
- Confirm `scripts/render_vision_judge.py --render-only` generates 400×400 PNGs in the output directory.
- Confirm `scripts/render_vision_judge.py --judge` outputs `SCORE:`, `FLAGS:`, and `WHY:` for the rendered PNGs.
- Ensure no file is declared "dead" without testing un-escape recovery for the escape-bug.
- Ensure no executable JS is falsely flagged from JSON-LD `<script>` tags.