# SVG Framework - Analisi Approfondita Fase 3 (Tooling conversione/trasformazione)

Versione: 2026-04-21  
Stato: proposta tecnica per decisione implementativa nel branch incubatore

---

## 1) Obiettivo della Fase 3

Definire una stack minima e sostenibile per:

- conversione raster -> SVG (`from-raster.md`);
- export SVG -> PNG/PDF (baseline, non workflow avanzato);
- fallback espliciti quando i tool esterni non sono disponibili.

Vincoli di governance da rispettare:

- dipendenze necessarie e non invasive;
- compatibilita' cross-host (Linux/macOS/Windows) con degradazione esplicita;
- test/smoke anche in assenza tool;
- nessun ampliamento non necessario del perimetro (asset libraries e composizione avanzata restano fuori scope Fase 3).
- vincolo operativo aggiuntivo: evitare Python come dipendenza runtime/setup per Fase 3.
- assunzione operativa Linux: baseline Ubuntu (APT) per setup automatico.

---

## 2) Candidati valutati

### 2.1 Raster -> SVG

1. `vtracer` (Rust CLI)
- Pro: migliore gestione immagini a colori rispetto a `potrace`; output compatto; CLI semplice.
- Contro: dipendenza Rust/cargo se installato da sorgente (mitigabile con binari release).
- Fit Fase 3: **alto** come default.

2. `potrace`
- Pro: robusto su loghi B/N, silhouette, scansioni binarizzate.
- Contro: pipeline meno diretta su input colore; richiede pre-processing in diversi casi.
- Fit Fase 3: **alto** come fallback specializzato B/N.

3. `inkscape` CLI
- Pro: tool universale, copre molti casi edge.
- Contro: installazione pesante, comportamento meno uniforme tra host/versioni.
- Fit Fase 3: **medio** solo come fallback di ultima istanza.

### 2.2 SVG -> PNG/PDF

1. `rsvg-convert` (librsvg)
- Pro: CLI leggera, ottimo per rendering statico, converte verso PNG/PDF/PS.
- Contro: disponibilita' meno immediata su alcuni setup Windows.
- Fit Fase 3: **alto** per Linux/macOS.

2. `CairoSVG`
- Pro: convertitore valido e diffuso.
- Contro: introduce dipendenza Python + stack Cairo/FFI; fuori dal vincolo operativo richiesto.
- Fit Fase 3: **escluso** per il profilo attuale "no Python".

3. `inkscape` CLI
- Pro: export PNG/PDF molto completo.
- Contro: peso installativo elevato.
- Fit Fase 3: **medio** fallback finale.

4. `sharp` (Node)
- Pro: eccellente per pipeline raster.
- Contro: in output non copre PDF; quindi non puo' essere tool unico per l'export richiesto in Fase 3.
- Fit Fase 3: **basso** per questo perimetro (utile semmai in fasi future per post-processing raster).

5. `resvg`
- Pro: binario piccolo, portabile, riproducibile; molto valido per SVG statici.
- Contro: CLI orientata a output PNG (non copre PDF come target diretto Fase 3).
- Fit Fase 3: **medio-alto** per pipeline PNG-only, non sufficiente da solo.

---

## 3) Decisione proposta (stack minima)

### 3.1 Scelta primaria

1. Raster -> SVG
- default: `vtracer`
- fallback specialistico: `potrace` (B/N)
- fallback finale: `inkscape`

2. SVG -> PNG/PDF
- default Linux/macOS: `rsvg-convert`
- fallback cross-host: `inkscape`
- fallback finale: `inkscape`

### 3.2 Motivazione

- Mantiene copertura funzionale completa con minimo lock-in.
- Evita di rendere `inkscape` dipendenza obbligatoria.
- Preserva la regola "dipendenze opzionali + degradazione esplicita".
- Riduce il rischio di regressioni cross-host usando fallback multipli documentati.

---

## 4) Submodule: quando usarli e quando no

### 4.1 Conclusione netta

Per **tool CLI di conversione** (`vtracer`, `potrace`, `rsvg-convert`, `inkscape`) i **git submodule non sono la scelta consigliata**.

### 4.2 Perche' non usare submodule per i tool

- Un submodule porta sorgente, non installazione pronta lato host.
- Il costo build/runtime resta sull'utente (toolchain Rust/C e package manager host).
- Aumenta il peso di manutenzione nel repo senza risolvere la portability operativa.
- Non allinea bene il modello MCP host-agnostic (diversi host hanno policy installative diverse).

### 4.3 Dove i submodule hanno senso

- asset libraries versionate (tema Fase 4);
- wrapper/tool interni sviluppati dal team (codice proprio da versionare insieme al repo).

Per Fase 3, meglio:

- installazione tramite package manager host (`apt`/`brew`/`choco`/`pip`/`cargo`);
- script di bootstrap non invasivi in `scripts/`;
- capability detection runtime con fallback dichiarato.

---

## 5) Modello operativo di integrazione

### 5.1 Capability matrix runtime (da introdurre)

All'avvio di ogni workflow Fase 3 verificare disponibilita':

- `vtracer --version`
- `potrace --version`
- `rsvg-convert --version`
- `inkscape --version`

Mappare in un report sintetico:

- available / missing;
- tool selezionato;
- fallback previsto.

### 5.2 Strategia di selezione tool

`from-raster.md`

1. Se input e' colore/fotografico -> prova `vtracer`.
2. Se input e' logo B/N o binarizzabile -> prova `potrace`.
3. Se entrambi assenti o output non accettabile -> `inkscape` fallback.
4. Se nessun tool disponibile -> failure esplicita con next-step installativo.

`export` (PNG/PDF)

1. Se disponibile `rsvg-convert` -> default.
2. Altrimenti `inkscape`.
3. Nessun tool -> failure esplicita + istruzioni installazione.

### 5.3 Policy sicurezza minima

- validare path input/output e impedire overwrite involontari;
- mantenere log chiaro del tool effettivamente usato e del fallback applicato.

---

## 6) Impatti su repository e deliverable Fase 3

## 6.1 File skill/documentazione

- `skills/svg/from-raster.md` (decision tree aggiornato)
- `skills/svg/export/to-png-batch.md` (tool chain e fallback)
- `skills/svg/export/to-pdf.md` (tool chain e fallback)
- eventuale `skills/svg/references/tooling-phase3.md` (tabella capability/install)

## 6.2 Script supporto (proposti)

- `scripts/check-svg-tooling.js`  
  output JSON con capability disponibili.
- `scripts/smoke-svg-phase3.js`  
  smoke con profili:
  - `no-tools` (atteso: errore esplicito)
  - `raster-vtracer`
  - `export-rsvg-convert`
  - fallback chain (simulata o reale in base host)

## 6.3 Done minimo Fase 3 (esteso)

- routing skill coerente con fallback;
- nessun fallimento silenzioso;
- smoke pass in almeno un profilo "tool presenti" e uno "tool assenti";
- documentazione installazione per Linux/macOS/Windows;
- nota di riavvio server MCP se introdotte nuove capability runtime lato server.

---

## 7) Piano incrementale consigliato

1. Implementare detection tool + fallback messaging (senza conversioni complesse).
2. Integrare `from-raster.md` con `vtracer` + `potrace` + fallback.
3. Integrare export baseline PNG/PDF con `rsvg-convert` + fallback `inkscape`.
4. Aggiungere fallback `inkscape` solo come ultimo livello.
5. Chiudere con smoke/documentazione e verifica promovibilita' verso `master`.

---

## 8) Decisioni aperte da confermare

1. Windows baseline: decisione consolidata = export PNG/PDF `inkscape` only; `rsvg-convert` non supportato su Windows nel perimetro MVP.
2. Livello di pinning versioni (strict vs minimum-supported).
3. Se mantenere solo l'opzione sui setup esistenti (`setup.ps1`/`setup.sh`) o aggiungere un check-only dedicato in `scripts/`.

---

## 9) Fonti primarie consultate

- VTracer (README + CLI + release):  
  https://github.com/visioncortex/vtracer  
  https://github.com/visioncortex/vtracer/releases

- Potrace (sito ufficiale):  
  https://potrace.sourceforge.net/

- Inkscape CLI/man page:  
  https://inkscape.org/doc/inkscape-man-1.3.x.html

- resvg (README + release):  
  https://github.com/linebender/resvg  
  https://github.com/linebender/resvg/releases

- sharp output formats (per confronto):  
  https://sharp.pixelplumbing.com/api-output/

- Git submodule official docs:  
  https://git-scm.com/docs/git-submodule