# Registro delle decisioni Ogni scelta non banale presa durante lo sviluppo (brief §0.4). Formato: data · contesto · scelta · alternative scartate · motivazione. --- ## D-001 — Repository esistente su Forgejo e branch di lavoro - **Data:** 2026-10-15 - **Contesto:** il brief (§14.0) prevede `git init`, ma il repository `BalboSoft/Studio_Grasso` esiste già su Forgejo con un commit iniziale (README di due righe e `.gitignore`). - **Scelta:** si lavora sul clone del repository esistente. Lo sviluppo avviene sul branch `feat/sito-v1` (un commit per fase, Conventional Commits in italiano); a fine fase 8 il branch viene unito in `main` con un merge commit (`--no-ff`), così `main` locale è pronto per il push. - **Alternative scartate:** `git init` di un nuovo repository (perderebbe la storia remota e richiederebbe un push forzato); commit diretti su `main` (meno leggibile la storia per fasi). - **Motivazione:** conserva la storia remota, nessun push forzato necessario, `main` resta pulito fino al merge finale. ## D-002 — Sostituzione del `.gitignore` iniziale - **Data:** 2026-10-15 - **Contesto:** il `.gitignore` del commit iniziale è il modello «VisualStudio» (C#/.NET), non pertinente a un progetto Node/Astro. - **Scelta:** sostituito con un `.gitignore` specifico (`node_modules`, `dist`, `release`, `.astro`, `test-results`, `playwright-report`, `.lighthouseci`, file di sistema). - **Alternative scartate:** aggiungere le voci in coda al modello esistente (centinaia di regole inutili, alcune potenzialmente fuorvianti). - **Motivazione:** semplicità e chiarezza (§0.3, punto 4). ## D-003 — Versione di Node.js - **Data:** 2026-10-15 - **Contesto:** il brief chiede «Node.js LTS corrente (≥ 22)». A ottobre 2026 la LTS attiva è Node 24 (Krypton); Node 22 è in manutenzione. `eslint-plugin-astro` 3.x richiede Node `^22.22.3 || ^24.16.0 || >=26.3.0`, Astro 7 richiede `>=22.22.0`. - **Scelta:** `.nvmrc` = `24`; `engines.node` = `>=22.22.3`. Sviluppo e test eseguiti con Node 24.22.0. - **Alternative scartate:** Node 22 come riferimento (LTS in manutenzione); `engines` `>=24` (escluderebbe inutilmente Node 22 aggiornato). - **Motivazione:** LTS attiva per lo sviluppo, compatibilità dichiarata con il minimo realmente supportato dalle dipendenze. ## D-004 — Astro 7.4.0 - **Data:** 2026-10-15 - **Contesto:** il brief chiede l'ultima versione stabile di Astro, verificata con `npm view astro version`. - **Scelta:** `astro@7.4.0` (risultato di `npm view astro version` il 2026-10-15), con `@astrojs/sitemap@3.7.4`. - **Alternative scartate:** nessuna (requisito esplicito). - **Motivazione:** requisito del brief §3.1. ## D-005 — TypeScript 6.0.3 invece di 7.0.2 - **Data:** 2026-10-15 - **Contesto:** l'ultima TypeScript è la 7.0.2, ma `@astrojs/check@0.9.10` dichiara `typescript ^5 || ^6` e `typescript-eslint@8.71.2` richiede `typescript <6.1.0`. - **Scelta:** `typescript@6.0.3` (ultima 6.x), modalità `strict` tramite `astro/tsconfigs/strict`. - **Alternative scartate:** TypeScript 7 (fuori dai peer delle dipendenze, rischio di `astro check` non funzionante). - **Motivazione:** compatibilità garantita dalle dipendenze ufficiali. ## D-006 — Playwright 1.56.1 (versione bloccata) - **Data:** 2026-10-15 - **Contesto:** il brief usa come riferimento l'immagine CI `mcr.microsoft.com/playwright:v1.56.0-noble` e chiede che coincida con la versione di `@playwright/test`. L'ambiente di sviluppo dispone di Chromium revision 1194, quella usata da Playwright 1.56.x; le versioni successive (1.57+) richiedono un Chromium diverso. - **Scelta:** `@playwright/test@1.56.1` e `playwright@1.56.1` (ultima patch della 1.56); immagine CI `mcr.microsoft.com/playwright:v1.56.1-noble`. - **Alternative scartate:** Playwright 1.64.1 (richiederebbe lo scaricamento di un nuovo browser e un'immagine diversa da quella indicata nel brief). - **Motivazione:** test riproducibili in locale e in CI con lo stesso browser; aggiornare Playwright significa aggiornare insieme `package.json` e l'immagine dei workflow (documentato nel README). ## D-007 — Versioni esatte delle dipendenze - **Data:** 2026-10-15 - **Contesto:** riproducibilità della build e del pacchetto di rilascio. - **Scelta:** tutte le dipendenze sono dichiarate con versione esatta (senza `^`) e `package-lock.json` è committato; la CI usa `npm ci`. - **Alternative scartate:** intervalli semver (`^x.y.z`). - **Motivazione:** build identiche nel tempo; gli aggiornamenti diventano commit espliciti. ## D-008 — Avvisi di `npm audit` sulle dipendenze di sviluppo - **Data:** 2026-10-15 - **Contesto:** `npm audit` segnala 17 vulnerabilità, tutte in dipendenze transitive di strumenti di sviluppo (soprattutto `@lhci/cli`: `tmp`, `uuid`, `basic-ftp`, `extract-zip`). `npm audit --omit=dev` = 0 vulnerabilità. - **Scelta:** nessuna azione; nessuno di questi pacchetti finisce nel sito pubblicato (che contiene solo file statici). - **Alternative scartate:** `npm audit fix --force` (introdurrebbe versioni incompatibili e romperebbe Lighthouse CI). - **Motivazione:** rischio nullo per il sito pubblicato; gli strumenti girano solo in locale/CI su input fidato. ## D-009 — Nessun `eslint-plugin-jsx-a11y` - **Data:** 2026-10-15 - **Contesto:** le regole a11y di `eslint-plugin-astro` richiedono `eslint-plugin-jsx-a11y`, che non supporta ESLint 10. - **Scelta:** si usa la configurazione `recommended` di `eslint-plugin-astro`; l'accessibilità è verificata da axe-core (tutte le pagine, due viewport), html-validate (regole WCAG) e Lighthouse (punteggio 1.0). - **Alternative scartate:** declassare ESLint alla 9 solo per questo plugin. - **Motivazione:** copertura a11y più forte a runtime che in lint statico; toolchain aggiornata. ## D-010 — Icone Lucide senza `astro-icon` - **Data:** 2026-10-15 - **Contesto:** il brief consente `@iconify-json/lucide` + `astro-icon` oppure file SVG in `src/icons/`. - **Scelta:** componente `Icon.astro` che legge i tracciati da `@iconify-json/lucide` (JSON) a build time e genera SVG inline con `aria-hidden="true"`. Nessuna integrazione aggiuntiva. - **Alternative scartate:** `astro-icon` (porta con sé `@iconify/tools` e decine di dipendenze transitive, compatibilità con Astro 7 non dichiarata); copiare a mano i file SVG (manutenzione più scomoda). - **Motivazione:** zero runtime, meno dipendenze, stesso set di icone (Lucide, licenza ISC). ## D-011 — Script segnaposto in fase 0 - **Data:** 2026-10-15 - **Contesto:** il brief chiede di definire in fase 0 tutti gli script npm di §3.3 «anche se vuoti». - **Scelta:** gli script in `scripts/` sono creati come segnaposto e implementati nelle fasi 1 (icone), 6 (test) e 7 (packaging e release). - **Alternative scartate:** nessuna. - **Motivazione:** requisito del brief §14.0. ## D-012 — Mockup e brief in `docs/` - **Data:** 2026-10-15 - **Contesto:** i mockup sono stati forniti in formato WebP (non PNG come indicato nell'Appendice A). - **Scelta:** copiati in `docs/mockups/` con i nomi dell'Appendice A ed estensione `.webp`; il brief completo è conservato in `docs/BRIEF.md` come riferimento dei requisiti. - **Alternative scartate:** convertirli in PNG (file più pesanti senza benefici). - **Motivazione:** il riferimento visivo resta nel repository insieme ai requisiti. ## D-013 — Generazione di marchio e icone con tracciati vettoriali - **Data:** 2026-10-15 - **Contesto:** favicon, `apple-touch-icon`, immagine Open Graph e `logo.svg` devono riprodurre la «G» e il logotipo in Fraunces/Inter. Un SVG con testo dipende dai font installati sul sistema (librsvg/sharp usa fontconfig); `fontkit` non gestisce correttamente i font variabili WOFF2 e il motore di shaping di `opentype.js` non supporta tutte le tabelle GSUB di questi font. - **Scelta:** `scripts/generate-icons.mjs` legge le versioni statiche WOFF (`@fontsource/fraunces`, `@fontsource/inter`, solo sviluppo) con `opentype.js`, impagina i testi glifo per glifo e li converte in tracciati SVG; sharp genera i PNG e il file ICO (PNG incapsulati). I file generati sono committati e rigenerabili con `npm run icons`. - **Alternative scartate:** testo SVG con font di sistema (risultato diverso da macchina a macchina); screenshot con Chromium (dipendenza dal browser per un'operazione grafica); disegnare la «G» a mano (non sarebbe Fraunces). - **Motivazione:** risultato identico ovunque, nessun font di sistema richiesto, nessuna rete. ## D-014 — Menu mobile con `` modale e alternativa senza JavaScript - **Data:** 2026-10-15 - **Contesto:** il menu mobile deve avere pulsante con `aria-controls`/`aria-expanded`, chiusura con Esc e focus gestito, ma il sito deve restare navigabile senza JavaScript (§2.6). Script inline non sono ammessi dalla CSP. - **Scelta:** pulsante + `` aperto con `showModal()` (sfondo inerte, Esc nativo, focus sul pulsante «Chiudi» e ritorno al pulsante menu). Un blocco `