feat: v0.2.0 — API REST, TTS support, documentazione completa e UI mobile-first

✨ Nuove funzionalità:
- Nuovo endpoint API REST /api/v1/query (GET+POST) per consumo programmatico
- Campo speakable_text ottimizzato per sintesi vocale (Alexa, Google Home)
- Funzione strip_markdown() per conversione Markdown → plain text TTS
- Supporto CORS per accesso cross-origin
- UI responsive mobile-first con micro-interazioni e stati
- Nuovo pulsante 'Nuova ricerca' e metadata bar

📚 Documentazione completa:
- docs/ARCHITECTURE.md — architettura di sistema, stack, componenti
- docs/FLOW.md — diagrammi Mermaid della pipeline e flussi
- docs/API.md — documentazione endpoint REST con esempi curl
- docs/WIKI.md — FAQ, glossario, roadmap
- docs/DEPLOYMENT.md — guida deployment (Gunicorn, Nginx, Docker, systemd)
- docs/CONTRIBUTING.md — guida alla contribuzione

🔧 Migliorie tecniche:
- Pipeline di ricerca condivisa in _run_search_pipeline()
- Gestione errori Gemini migliorata con _clean_error()
- Sanitizzazione HTML con allowlist per prevenzione XSS
- .env.example completo con commenti

🧪 Test: 109/109 passati

static/app.js

@@ -1,5 +1,6 @@
 /**
  * Sibilla — Frontend search interface
+ * Mobile-friendly, smooth UX
  */
 
 document.addEventListener('DOMContentLoaded', () => {
@@ -10,19 +11,34 @@ document.addEventListener('DOMContentLoaded', () => {
     const loading = document.getElementById('loading');
     const answerDiv = document.getElementById('answer');
     const sourcesDiv = document.getElementById('sources');
+    const metaBar = document.getElementById('meta-bar');
+    const newSearchBtn = document.getElementById('new-search-btn');
+
+    const btnText = submitBtn.querySelector('span').textContent;
+    let isSearching = false;
 
     form.addEventListener('submit', async (e) => {
         e.preventDefault();
 
+        if (isSearching) return;
+
         const query = queryInput.value.trim();
         if (!query) return;
 
-        // Show response area + loading
+        // Reset and show UI
+        isSearching = true;
         responseArea.style.display = 'block';
         loading.style.display = 'flex';
         answerDiv.innerHTML = '';
         sourcesDiv.innerHTML = '';
+        metaBar.innerHTML = '';
+        metaBar.style.display = 'none';
+        newSearchBtn.classList.remove('visible');
         submitBtn.disabled = true;
+        submitBtn.querySelector('span').textContent = 'Consultando...';
+
+        // Scroll to loading indicator on mobile
+        loading.scrollIntoView({ behavior: 'smooth', block: 'start' });
 
         try {
             const res = await fetch('/api/ask', {
@@ -38,29 +54,63 @@ document.addEventListener('DOMContentLoaded', () => {
 
             const data = await res.json();
 
-            // Render answer as Markdown
-            answerDiv.innerHTML = renderMarkdown(data.answer);
+            // Render answer — prefer server-rendered HTML, fall back to client-side markdown
+            if (data.html_answer) {
+                answerDiv.innerHTML = data.html_answer;
+            } else {
+                answerDiv.innerHTML = renderMarkdown(data.answer);
+            }
+
+            // Render metadata bar
+            if (data.search_engine || data.tokens_used) {
+                let metaHtml = '';
+                if (data.search_engine && data.search_engine !== 'none') {
+                    metaHtml += `<span class="meta-badge engine">🔍 ${data.search_engine}</span>`;
+                }
+                if (data.model) {
+                    metaHtml += `<span class="meta-badge">🧠 ${data.model}</span>`;
+                }
+                if (data.tokens_used) {
+                    metaHtml += `<span class="meta-badge">📊 ~${data.tokens_used} token</span>`;
+                }
+                metaBar.innerHTML = metaHtml;
+                metaBar.style.display = 'flex';
+            }
 
             // Render sources
             if (data.sources && data.sources.length > 0) {
                 sourcesDiv.innerHTML = '<h3>📚 Fonti</h3>' +
                     data.sources.map(s =>
                         `<a href="${escapeHtml(s.url)}" target="_blank" rel="noopener" class="source-item">
+                            <span class="source-index">${s.index}</span>
                             <span class="source-title">${escapeHtml(s.title)}</span>
                             <span class="source-url">${escapeHtml(s.url)}</span>
                         </a>`
                     ).join('');
             }
 
+            // Show "new search" button and scroll to results
+            newSearchBtn.classList.add('visible');
+            answerDiv.scrollIntoView({ behavior: 'smooth', block: 'start' });
+
         } catch (err) {
             answerDiv.innerHTML = `<div class="error-box">⚠️ ${escapeHtml(err.message)}</div>`;
+            answerDiv.scrollIntoView({ behavior: 'smooth', block: 'start' });
         } finally {
             loading.style.display = 'none';
             submitBtn.disabled = false;
+            submitBtn.querySelector('span').textContent = btnText;
+            isSearching = false;
         }
     });
 
-    // Allow Ctrl+Enter to submit
+    // "New search" button — scroll back to query input
+    newSearchBtn.addEventListener('click', () => {
+        queryInput.focus();
+        queryInput.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    });
+
+    // Allow Ctrl+Enter or Cmd+Enter to submit
     queryInput.addEventListener('keydown', (e) => {
         if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) {
             form.dispatchEvent(new Event('submit'));
@@ -69,6 +119,7 @@ document.addEventListener('DOMContentLoaded', () => {
 });
 
 // ── Tiny Markdown renderer ─────────────────────────────────────
+
 function renderMarkdown(text) {
     if (!text) return '';
 

static/favicon.svg

@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <!-- Background gradient: deep indigo to purple -->
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#312E81"/>
+      <stop offset="50%" stop-color="#4F46E5"/>
+      <stop offset="100%" stop-color="#7C3AED"/>
+    </linearGradient>
+    <!-- Glow for the eye -->
+    <radialGradient id="eyeGlow" cx="0.45" cy="0.4" r="0.55">
+      <stop offset="0%" stop-color="#FFFFFF"/>
+      <stop offset="60%" stop-color="#E0E7FF"/>
+      <stop offset="100%" stop-color="#A5B4FC"/>
+    </radialGradient>
+    <!-- Pupil gradient -->
+    <radialGradient id="pupil" cx="0.4" cy="0.35" r="0.5">
+      <stop offset="0%" stop-color="#1E1B4B"/>
+      <stop offset="100%" stop-color="#0F0D2E"/>
+    </radialGradient>
+    <!-- Subtle shadow -->
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="0" stdDeviation="2" flood-color="#1E1B4B" flood-opacity="0.5"/>
+    </filter>
+  </defs>
+
+  <!-- Base circle -->
+  <circle cx="32" cy="32" r="30" fill="url(#bg)" filter="url(#shadow)"/>
+
+  <!-- Outer ring -->
+  <circle cx="32" cy="32" r="28" fill="none" stroke="#A5B4FC" stroke-width="0.8" opacity="0.5"/>
+  <circle cx="32" cy="32" r="25" fill="none" stroke="#C7D2FE" stroke-width="0.5" opacity="0.25"/>
+
+  <!-- Eye shape (almond) -->
+  <ellipse cx="32" cy="31" rx="14" ry="10" fill="url(#eyeGlow)" opacity="0.95"/>
+
+  <!-- Upper eyelid arc -->
+  <path d="M18 30 Q32 18 46 30" fill="none" stroke="#312E81" stroke-width="1.5" stroke-linecap="round" opacity="0.8"/>
+  <!-- Lower lid hint -->
+  <path d="M20 33 Q32 42 44 33" fill="none" stroke="#312E81" stroke-width="0.8" stroke-linecap="round" opacity="0.4"/>
+
+  <!-- Pupil -->
+  <circle cx="32" cy="31" r="5.5" fill="url(#pupil)"/>
+
+  <!-- Pupil highlight / sparkle -->
+  <circle cx="30" cy="29" r="1.8" fill="#FFFFFF" opacity="0.85"/>
+  <circle cx="34" cy="33" r="0.8" fill="#FFFFFF" opacity="0.4"/>
+
+  <!-- Small oracle sparkle in top-right -->
+  <g transform="translate(48, 16)" opacity="0.9">
+    <path d="M0 -6 L1.5 -1.5 L6 0 L1.5 1.5 L0 6 L-1.5 1.5 L-6 0 L-1.5 -1.5 Z" fill="#FDE68A"/>
+    <circle cx="0" cy="0" r="1" fill="#FEF3C7"/>
+  </g>
+</svg>

static/style.css

@@ -1,5 +1,6 @@
 /* ═══════════════════════════════════════════════════════════════
    Sibilla — L'Oracolo AI
+   Mobile-first responsive stylesheet
    ═══════════════════════════════════════════════════════════════ */
 
 :root {
@@ -14,6 +15,7 @@
     --success: #34d399;
     --danger: #f87171;
     --radius: 12px;
+    --radius-sm: 8px;
     --transition: 0.2s ease;
 }
 
@@ -23,46 +25,84 @@
     box-sizing: border-box;
 }
 
+html {
+    scroll-behavior: smooth;
+    -webkit-text-size-adjust: 100%;
+}
+
 body {
     font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif;
     background: var(--bg);
     color: var(--text);
     min-height: 100vh;
+    min-height: 100dvh;
     display: flex;
     justify-content: center;
+    line-height: 1.6;
+    -webkit-font-smoothing: antialiased;
+}
+
+/* Subtle background ambience */
+body::before {
+    content: '';
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background:
+        radial-gradient(ellipse at 50% 0%, rgba(167, 139, 250, 0.06) 0%, transparent 60%),
+        radial-gradient(ellipse at 80% 100%, rgba(139, 92, 246, 0.04) 0%, transparent 50%);
+    pointer-events: none;
+    z-index: 0;
 }
 
 .container {
+    position: relative;
+    z-index: 1;
     max-width: 800px;
     width: 100%;
-    padding: 2rem 1.5rem;
+    padding: 1rem 1rem;
     display: flex;
     flex-direction: column;
     min-height: 100vh;
+    min-height: 100dvh;
 }
 
 /* ── Header ──────────────────────────────────────────────────── */
 
 header {
     text-align: center;
-    margin-bottom: 3rem;
-    padding-top: 3rem;
+    margin-bottom: 1.5rem;
+    padding-top: 1.5rem;
 }
 
 header h1 {
-    font-size: 2.8rem;
+    font-size: 1.8rem;
     font-weight: 700;
     background: linear-gradient(135deg, var(--accent), var(--accent-glow));
     -webkit-background-clip: text;
     -webkit-text-fill-color: transparent;
     background-clip: text;
-    margin-bottom: 0.5rem;
+    margin-bottom: 0.35rem;
     letter-spacing: -0.02em;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.4rem;
+}
+
+.logo {
+    width: 1.8rem;
+    height: 1.8rem;
+    filter: drop-shadow(0 0 10px rgba(167, 139, 250, 0.45));
+    flex-shrink: 0;
 }
 
 .subtitle {
     color: var(--text-muted);
-    font-size: 1.05rem;
+    font-size: 0.9rem;
+    padding: 0 0.5rem;
 }
 
 /* ── Search Box ──────────────────────────────────────────────── */
@@ -70,23 +110,24 @@ header h1 {
 .search-box {
     display: flex;
     flex-direction: column;
-    gap: 0.75rem;
-    margin-bottom: 2rem;
+    gap: 0.6rem;
+    margin-bottom: 1.5rem;
 }
 
 .search-box textarea {
     width: 100%;
-    padding: 1rem 1.25rem;
+    padding: 0.85rem 1rem;
     background: var(--surface);
     border: 2px solid var(--border);
     border-radius: var(--radius);
     color: var(--text);
-    font-size: 1.05rem;
+    font-size: 1rem;
     font-family: inherit;
     resize: vertical;
-    min-height: 80px;
+    min-height: 70px;
     transition: border-color var(--transition), box-shadow var(--transition);
     outline: none;
+    -webkit-appearance: none;
 }
 
 .search-box textarea:focus {
@@ -96,11 +137,12 @@ header h1 {
 
 .search-box textarea::placeholder {
     color: var(--text-muted);
+    opacity: 0.7;
 }
 
 #submit-btn {
-    align-self: flex-end;
-    padding: 0.75rem 1.75rem;
+    width: 100%;
+    padding: 0.85rem 1.5rem;
     background: linear-gradient(135deg, var(--accent), #8b5cf6);
     border: none;
     border-radius: var(--radius);
@@ -109,6 +151,12 @@ header h1 {
     font-weight: 600;
     cursor: pointer;
     transition: transform var(--transition), box-shadow var(--transition), opacity var(--transition);
+    -webkit-tap-highlight-color: transparent;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.4rem;
+    min-height: 48px;
 }
 
 #submit-btn:hover {
@@ -117,13 +165,14 @@ header h1 {
 }
 
 #submit-btn:active {
-    transform: translateY(0);
+    transform: scale(0.98);
 }
 
 #submit-btn:disabled {
-    opacity: 0.6;
+    opacity: 0.55;
     cursor: not-allowed;
     transform: none;
+    box-shadow: none;
 }
 
 /* ── Response Area ───────────────────────────────────────────── */
@@ -144,14 +193,14 @@ header h1 {
     display: flex;
     flex-direction: column;
     align-items: center;
-    gap: 1rem;
-    padding: 2rem;
+    gap: 0.85rem;
+    padding: 2rem 1rem;
     color: var(--text-muted);
 }
 
 .spinner {
-    width: 36px;
-    height: 36px;
+    width: 32px;
+    height: 32px;
     border: 3px solid var(--border);
     border-top-color: var(--accent);
     border-radius: 50%;
@@ -162,61 +211,149 @@ header h1 {
     to { transform: rotate(360deg); }
 }
 
+.loading p {
+    font-size: 0.9rem;
+}
+
+/* ── New Search ──────────────────────────────────────────────── */
+
+.new-search-btn {
+    display: none;
+    width: 100%;
+    padding: 0.65rem 1rem;
+    background: transparent;
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    color: var(--text-muted);
+    font-size: 0.9rem;
+    cursor: pointer;
+    -webkit-tap-highlight-color: transparent;
+    margin-bottom: 1rem;
+    transition: border-color var(--transition), color var(--transition);
+    min-height: 44px;
+}
+
+.new-search-btn:hover {
+    border-color: var(--accent);
+    color: var(--accent-glow);
+}
+
+.new-search-btn.visible {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.35rem;
+}
+
 /* ── Answer ──────────────────────────────────────────────────── */
 
 .answer {
     background: var(--surface);
     border: 1px solid var(--border);
     border-radius: var(--radius);
-    padding: 1.5rem;
-    margin-bottom: 1.5rem;
+    padding: 1.15rem;
+    margin-bottom: 1rem;
     line-height: 1.7;
-    font-size: 1.02rem;
+    font-size: 0.95rem;
+    word-wrap: break-word;
+    overflow-wrap: break-word;
+}
+
+.answer:empty {
+    display: none;
 }
 
 .answer h1, .answer h2, .answer h3 {
-    margin-top: 1.25rem;
-    margin-bottom: 0.5rem;
+    margin-top: 1.1rem;
+    margin-bottom: 0.4rem;
     color: var(--accent-glow);
+    line-height: 1.3;
 }
 
-.answer h1 { font-size: 1.5rem; }
-.answer h2 { font-size: 1.25rem; }
-.answer h3 { font-size: 1.1rem; }
+.answer h1 { font-size: 1.35rem; }
+.answer h2 { font-size: 1.15rem; }
+.answer h3 { font-size: 1.05rem; }
 
 .answer p {
-    margin-bottom: 0.75rem;
+    margin-bottom: 0.65rem;
 }
 
 .answer ul, .answer ol {
-    padding-left: 1.5rem;
-    margin-bottom: 0.75rem;
+    padding-left: 1.25rem;
+    margin-bottom: 0.65rem;
 }
 
 .answer li {
-    margin-bottom: 0.35rem;
+    margin-bottom: 0.3rem;
+}
+
+.answer a {
+    color: var(--accent-glow);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+}
+
+.answer a:hover {
+    color: var(--accent);
 }
 
 .answer code {
     background: rgba(167, 139, 250, 0.1);
     padding: 0.15rem 0.4rem;
     border-radius: 4px;
-    font-size: 0.9em;
+    font-size: 0.88em;
+    word-break: break-word;
 }
 
 .answer pre {
-    background: rgba(0, 0, 0, 0.3);
-    padding: 1rem;
-    border-radius: 8px;
+    background: rgba(0, 0, 0, 0.35);
+    padding: 0.85rem;
+    border-radius: var(--radius-sm);
     overflow-x: auto;
-    margin-bottom: 0.75rem;
+    margin-bottom: 0.65rem;
+    font-size: 0.85em;
+    -webkit-overflow-scrolling: touch;
+}
+
+.answer pre code {
+    background: none;
+    padding: 0;
+    border-radius: 0;
 }
 
 .answer blockquote {
     border-left: 3px solid var(--accent);
-    padding-left: 1rem;
+    padding-left: 0.85rem;
     color: var(--text-muted);
+    margin-bottom: 0.65rem;
+    font-style: italic;
+}
+
+/* ── Metadata bar ────────────────────────────────────────────── */
+
+.meta-bar {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
     margin-bottom: 0.75rem;
+    font-size: 0.75rem;
+    color: var(--text-muted);
+    align-items: center;
+}
+
+.meta-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    padding: 0.2rem 0.5rem;
+    background: rgba(167, 139, 250, 0.08);
+    border-radius: 100px;
+    font-size: 0.72rem;
+}
+
+.meta-badge.engine {
+    background: rgba(52, 211, 153, 0.1);
+    color: var(--success);
 }
 
 /* ── Sources ─────────────────────────────────────────────────── */
@@ -225,32 +362,57 @@ header h1 {
     background: var(--surface);
     border: 1px solid var(--border);
     border-radius: var(--radius);
-    padding: 1.25rem;
+    padding: 1rem;
+    margin-bottom: 1rem;
+}
+
+.sources:empty {
+    display: none;
 }
 
 .sources h3 {
     color: var(--accent-glow);
-    font-size: 0.95rem;
-    margin-bottom: 0.75rem;
+    font-size: 0.82rem;
+    margin-bottom: 0.6rem;
     text-transform: uppercase;
-    letter-spacing: 0.05em;
+    letter-spacing: 0.06em;
+    display: flex;
+    align-items: center;
+    gap: 0.35rem;
 }
 
 .source-item {
     display: block;
-    padding: 0.6rem 0.75rem;
-    border-radius: 8px;
+    padding: 0.55rem 0.65rem;
+    border-radius: var(--radius-sm);
     color: var(--text);
     text-decoration: none;
     transition: background var(--transition);
-    margin-bottom: 0.25rem;
-    font-size: 0.9rem;
+    margin-bottom: 0.15rem;
+    font-size: 0.85rem;
+    -webkit-tap-highlight-color: transparent;
 }
 
+.source-item:active,
 .source-item:hover {
     background: var(--surface-hover);
 }
 
+.source-item .source-index {
+    display: inline-block;
+    width: 1.3rem;
+    height: 1.3rem;
+    line-height: 1.3rem;
+    text-align: center;
+    background: rgba(167, 139, 250, 0.15);
+    color: var(--accent-glow);
+    border-radius: 4px;
+    font-size: 0.7rem;
+    font-weight: 700;
+    margin-right: 0.4rem;
+    flex-shrink: 0;
+}
+
 .source-item .source-title {
     font-weight: 500;
     color: var(--accent-glow);
@@ -258,28 +420,138 @@ header h1 {
 
 .source-item .source-url {
     color: var(--text-muted);
-    font-size: 0.8rem;
+    font-size: 0.75rem;
     display: block;
-    margin-top: 0.15rem;
+    margin-top: 0.1rem;
     word-break: break-all;
 }
 
 /* ── Error ───────────────────────────────────────────────────── */
 
 .error-box {
-    background: rgba(248, 113, 113, 0.1);
+    background: rgba(248, 113, 113, 0.08);
     border: 1px solid var(--danger);
     border-radius: var(--radius);
-    padding: 1rem 1.25rem;
+    padding: 0.85rem 1rem;
     color: var(--danger);
+    font-size: 0.9rem;
 }
 
 /* ── Footer ──────────────────────────────────────────────────── */
 
 footer {
     text-align: center;
-    padding: 1.5rem 0;
+    padding: 1.25rem 0 0.75rem;
     color: var(--text-muted);
-    font-size: 0.8rem;
+    font-size: 0.72rem;
     margin-top: auto;
 }
+
+/* ═══════════════════════════════════════════════════════════════
+   Tablet / Desktop ≥ 640px
+   ═══════════════════════════════════════════════════════════════ */
+
+@media (min-width: 640px) {
+    .container {
+        padding: 2rem 2rem;
+    }
+
+    header {
+        margin-bottom: 2.5rem;
+        padding-top: 2.5rem;
+    }
+
+    header h1 {
+        font-size: 2.4rem;
+        gap: 0.5rem;
+    }
+
+    .logo {
+        width: 2.4rem;
+        height: 2.4rem;
+    }
+
+    .subtitle {
+        font-size: 1rem;
+    }
+
+    .search-box {
+        gap: 0.75rem;
+        margin-bottom: 2rem;
+    }
+
+    .search-box textarea {
+        padding: 1rem 1.25rem;
+        font-size: 1.05rem;
+        min-height: 80px;
+    }
+
+    #submit-btn {
+        width: auto;
+        align-self: flex-end;
+        padding: 0.75rem 2rem;
+    }
+
+    .answer {
+        padding: 1.5rem;
+        font-size: 1rem;
+    }
+
+    .answer h1 { font-size: 1.5rem; }
+    .answer h2 { font-size: 1.25rem; }
+    .answer h3 { font-size: 1.1rem; }
+
+    .sources {
+        padding: 1.25rem;
+    }
+
+    .source-item {
+        font-size: 0.9rem;
+    }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Desktop ≥ 900px
+   ═══════════════════════════════════════════════════════════════ */
+
+@media (min-width: 900px) {
+    header {
+        padding-top: 3.5rem;
+        margin-bottom: 3rem;
+    }
+
+    header h1 {
+        font-size: 2.8rem;
+    }
+
+    .logo {
+        width: 2.8rem;
+        height: 2.8rem;
+    }
+
+    .answer {
+        padding: 1.75rem;
+    }
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Reduce motion for accessibility
+   ═══════════════════════════════════════════════════════════════ */
+
+@media (prefers-reduced-motion: reduce) {
+    html {
+        scroll-behavior: auto;
+    }
+
+    .response-area {
+        animation: none;
+    }
+
+    .spinner {
+        animation-duration: 1.5s;
+    }
+
+    * {
+        transition-duration: 0.01ms !important;
+    }
+}