feat: welcome popup on every open (reads pitch aloud, voice/tap close, video link)

- modal shows on every open, narrates the proposal (browser TTS), big close button
- speak on first tap (mobile autoplay-safe); desktop tries on load
- close by voice (close/fechar + broad words), button, Esc, or auto-close after narration
- EN/PT toggle in the popup; tap the mark to replay; don't re-narrate on same-session reload
- dialog a11y: role=dialog, focus trap, focus close, return focus; reduced-motion honored
- replaces the old first-run onboarding; camera now starts when the popup closes
- styled with the taste-skill tokens (Outfit, one accent, soft shadow)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

frontend/app.js

@@ -6,6 +6,9 @@ const cam = $("cam"), canvas = $("canvas"), statusEl = $("status"),
       player = $("player"), stage = $("stage"),
       btnAsk = $("btn-ask"), btnDescribe = $("btn-describe"),
       btnLive = $("btn-live"), a11yBtn = $("a11y");
+const intro = $("intro"), introBodyEl = $("intro-body"), introCloseBtn = $("intro-close"),
+      introVideo = $("intro-video"), introEn = $("intro-en"), introPt = $("intro-pt"),
+      introReplay = $("intro-replay"), introHintEl = $("intro-hint");
 
 function vibrate(ms) { try { navigator.vibrate && navigator.vibrate(ms); } catch (e) {} }
 
@@ -19,8 +22,8 @@ const T = {
         langListen: "Listening… say your language",
         welcome: "Welcome to Iris. Tap the screen to describe what is in front of you. Hold to ask a question. Double-tap to turn live mode on or off, which announces new things around you.",
         liveOn: "Live mode on.", liveOff: "Live mode off.", confLang: "English selected.",
-        startTap: "Iris. Tap the screen to begin.",
-        welcomeAsk: "Welcome to Iris, in English. Tap the screen to describe what is in front of you, hold to ask a question, double-tap for live mode. To use Portuguese instead, say 'português' now.",
+        introBody: "This is Iris, your eyes by voice. Point your phone and it tells you what is in front of you, and reads your money, your bills, and your medicine, out loud.",
+        introClose: "Close", introVideo: "Watch the demo", introHint: "Say \"close\" or tap the button",
         bAsk: "Ask", bDescribe: "Describe", bLive: "Live" },
   pt: { idle: "Iris", listening: "Ouvindo…", thinking: "Pensando…",
         hint: "Toque: descrever · Segurar: perguntar · Toque duplo: ao vivo",
@@ -28,8 +31,8 @@ const T = {
         langListen: "Ouvindo… diga seu idioma",
         welcome: "Bem-vindo ao Iris. Toque na tela para descrever o que está à sua frente. Segure para fazer uma pergunta. Toque duas vezes para ligar ou desligar o modo ao vivo, que avisa o que aparece de novo à sua volta.",
         liveOn: "Modo ao vivo ligado.", liveOff: "Modo ao vivo desligado.", confLang: "Português selecionado.",
-        startTap: "Iris. Toque na tela para começar.",
-        welcomeAsk: "Bem-vindo ao Iris, em português. Toque na tela para descrever o que está à sua frente, segure para perguntar, e toque duas vezes para o modo ao vivo. Para usar em inglês, diga 'inglês' agora.",
+        introBody: "Este é o Iris, os seus olhos por voz. Aponte o celular e ele diz o que está à sua frente, e lê o seu dinheiro, suas contas e seus remédios, em voz alta.",
+        introClose: "Fechar", introVideo: "Ver o vídeo", introHint: "Diga \"fechar\" ou toque no botão",
         bAsk: "Perguntar", bDescribe: "Descrever", bLive: "Ao vivo" },
 };
 const t = (k) => T[lang][k];
@@ -50,9 +53,7 @@ function speak(text) {
 }
 
 // ---- state ----
-let onboarded = false;
-try { onboarded = localStorage.getItem("iris_onboarded") === "1"; } catch (e) {}
-let mode = onboarded ? "normal" : "onboarding";
+let mode = "intro";   // "intro" while the welcome popup is open, then "normal"
 let busy = false;
 let liveOn = false, liveTimer = null;
 let holding = false, recording = false, holdTimer = null;
@@ -63,9 +64,9 @@ langBtn.onclick = (e) => {
   lang = lang === "en" ? "pt" : "en";
   document.documentElement.lang = lang;
   langBtn.textContent = lang.toUpperCase();
-  hintEl.textContent = onboarded ? t("hint") : "";
+  hintEl.textContent = t("hint");
   updateLabels();
-  if (!busy) setState("", onboarded ? t("idle") : t("startTap"));
+  if (!busy) setState("", t("idle"));
 };
 
 // ---- unlock audio (autoplay) on the first tap ----
@@ -150,59 +151,121 @@ async function send(frame, audio, qtext = "") {
 function resetSoon() { setTimeout(() => { resumeSR(); if (!busy) setState("", t("idle")); }, 600); }
 player.addEventListener("ended", () => { setTimeout(resumeSR, 700); if (!busy) setState("", t("idle")); });
 
-// ---- first-run onboarding: default to the browser language, speak it, offer to switch ----
-function onboard() {
-  if (onboarded) return;
-  const u = new SpeechSynthesisUtterance(t("welcomeAsk"));
-  u.lang = lang === "pt" ? "pt-BR" : "en-US";
-  // mark onboarded only when speech actually STARTS — so if the browser blocks
-  // autoplay on load, the mode stays "onboarding" and the first tap triggers it.
-  u.onstart = () => {
-    onboarded = true; mode = "normal";
-    try { localStorage.setItem("iris_onboarded", "1"); } catch (e) {}
-    hintEl.textContent = t("hint");
-    updateLabels();
-    setState("speaking", t("idle"));
-  };
-  u.onend = listenForLangChoice;          // after the welcome, listen for a language switch
-  try { speechSynthesis.cancel(); speechSynthesis.speak(u); }
-  catch (e) { /* will retry on the first tap */ }
+// ---- welcome popup (shown on every open): pitch read aloud, closeable by voice/tap ----
+const DEMO_VIDEO_URL = "https://huggingface.co/spaces/build-small-hackathon/iris";   // placeholder, swap for the demo video
+let introOpen = true, autoCloseTimer = null, introRecog = null, introSpokenSession = false;
+try { introSpokenSession = sessionStorage.getItem("iris_introSpoken") === "1"; } catch (e) {}
+const CLOSE_WORDS = /\b(close|fechar|ok|okay|start|begin|continue|continuar|comecar|entendi|pode fechar|got it)\b/i;
+
+function renderIntro() {
+  introBodyEl.textContent = t("introBody");
+  introCloseBtn.textContent = t("introClose");
+  introVideo.textContent = t("introVideo");
+  introVideo.href = DEMO_VIDEO_URL;
+  introHintEl.textContent = t("introHint");
+  introEn.setAttribute("aria-pressed", lang === "en" ? "true" : "false");
+  introPt.setAttribute("aria-pressed", lang === "pt" ? "true" : "false");
+}
+
+function showIntro() {
+  mode = "intro";
+  renderIntro();
+  intro.hidden = false;
+  try { introCloseBtn.focus(); } catch (e) {}
+  speakIntro(false);                       // narrate on load where the browser allows (desktop)
+  intro.addEventListener("pointerdown", onIntroFirstTap);   // mobile: first tap unlocks audio + narrates
+  document.addEventListener("keydown", onIntroKey);
+}
+
+function onIntroFirstTap(e) {
+  unlockAudio();
+  if (e.target.closest("button, a")) return;   // controls handle themselves
+  if (!introSpokenSession) speakIntro(false);
+}
+
+function onIntroKey(e) {
+  if (!introOpen) return;
+  if (e.key === "Escape") { closeIntro(); return; }
+  if (e.key === "Tab") {                        // simple focus trap inside the card
+    const f = intro.querySelectorAll("button, a[href]");
+    if (!f.length) return;
+    const first = f[0], last = f[f.length - 1];
+    if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+    else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+  }
+}
+
+function speakIntro(force) {
+  if (!introOpen) return;
+  if (introSpokenSession && !force) return;     // don't re-narrate on a same-session reload
+  unlockAudio();
+  try {
+    speechSynthesis.cancel();
+    const u = new SpeechSynthesisUtterance(t("introBody") + " " + t("introHint") + ".");
+    u.lang = lang === "pt" ? "pt-BR" : "en-US";
+    u.onstart = () => {
+      introSpokenSession = true;
+      try { sessionStorage.setItem("iris_introSpoken", "1"); } catch (e) {}
+      armCloseListener();
+    };
+    u.onend = () => { if (introOpen) scheduleAutoClose(); };
+    speechSynthesis.speak(u);
+  } catch (e) { /* will retry on the first tap */ }
+}
+
+function scheduleAutoClose() {
+  cancelAutoClose();
+  autoCloseTimer = setTimeout(() => { if (introOpen) closeIntro(); }, 2500);   // hands-free close after the narration
 }
+function cancelAutoClose() { if (autoCloseTimer) { clearTimeout(autoCloseTimer); autoCloseTimer = null; } }
 
-function listenForLangChoice() {
+function armCloseListener() {
+  if (introRecog) return;
   const SR = window.SpeechRecognition || window.webkitSpeechRecognition;
-  if (!SR) { setState("", t("idle")); return; }
-  const r = new SR();
-  r.lang = lang === "pt" ? "pt-BR" : "en-US";
-  r.continuous = false; r.interimResults = false;
-  let handled = false;
-  const finish = () => { if (!handled) { handled = true; setState("", t("idle")); } };
-  const to = setTimeout(() => { try { r.stop(); } catch (e) {} finish(); }, 5000);
-  r.onresult = (e) => {
-    handled = true; clearTimeout(to);
-    const txt = (e.results[0][0].transcript || "").toLowerCase();
-    if (txt.includes("ingl") || txt.includes("english")) switchLang("en");
-    else if (txt.includes("portug") || txt.includes("brasil")) switchLang("pt");
-    else setState("", t("idle"));
-    try { r.stop(); } catch (e) {}
+  if (!SR) return;
+  introRecog = new SR();
+  introRecog.continuous = true; introRecog.interimResults = false;
+  introRecog.lang = lang === "pt" ? "pt-BR" : "en-US";
+  introRecog.onresult = (e) => {
+    const raw = (e.results[e.results.length - 1][0].transcript || "");
+    const txt = raw.normalize("NFD").replace(/[̀-ͯ]/g, "");   // strip accents
+    if (CLOSE_WORDS.test(txt)) closeIntro();
   };
-  r.onerror = () => { clearTimeout(to); finish(); };
-  setState("listening", t("listening"));
-  try { r.start(); } catch (e) { finish(); }
-}
-
-function switchLang(newLang) {
-  if (newLang !== lang) {
-    lang = newLang;
-    document.documentElement.lang = lang;
-    langBtn.textContent = lang.toUpperCase();
-    hintEl.textContent = t("hint");
-    updateLabels();
-  }
+  introRecog.onend = () => { if (introOpen && introRecog) { try { introRecog.start(); } catch (e) {} } };
+  introRecog.onerror = () => {};
+  try { introRecog.start(); } catch (e) {}
+}
+
+function closeIntro() {
+  if (!introOpen) return;
+  introOpen = false;
+  cancelAutoClose();
+  if (introRecog) { try { introRecog.stop(); } catch (e) {} introRecog = null; }
+  try { speechSynthesis.cancel(); } catch (e) {}
+  intro.hidden = true;
+  document.removeEventListener("keydown", onIntroKey);
+  mode = "normal";
+  try { btnDescribe.focus(); } catch (e) {}
   setState("", t("idle"));
-  speak(t("confLang") + " " + t("welcome"));
+  startCamera();   // start the app now (pitch first, camera permission after)
 }
 
+function setIntroLang(l) {
+  cancelAutoClose();
+  if (l !== lang) {
+    lang = l; document.documentElement.lang = lang;
+    langBtn.textContent = lang.toUpperCase(); hintEl.textContent = t("hint"); updateLabels();
+  }
+  renderIntro();
+  speakIntro(true);   // replay in the chosen language
+}
+
+introCloseBtn.addEventListener("click", (e) => { e.stopPropagation(); closeIntro(); });
+introVideo.addEventListener("click", (e) => { e.stopPropagation(); cancelAutoClose(); });   // let them watch (opens a new tab)
+introReplay.addEventListener("click", (e) => { e.stopPropagation(); cancelAutoClose(); speakIntro(true); });
+introEn.addEventListener("click", (e) => { e.stopPropagation(); setIntroLang("en"); });
+introPt.addEventListener("click", (e) => { e.stopPropagation(); setIntroLang("pt"); });
+
 // ---- live mode (toggled by voice command or double-tap) ----
 function handleCommand(cmd) {
   if (cmd === "live_on") setLive(true);
@@ -369,11 +432,7 @@ async function sendWatch(frame, hint = "") {
 
 // ---- interaction ----
 stage.addEventListener("pointerdown", async () => {
-  if (mode === "onboarding") {
-    unlockAudio();
-    onboard();             // speak welcome in the browser language + offer to switch
-    return;
-  }
+  if (mode !== "normal") return;   // welcome popup is open
   if (liveOn) { speechSynthesis.cancel(); player.pause(); }
   if (busy) return;
   unlockAudio();
@@ -389,7 +448,7 @@ let lastTapTime = 0, tapTimer = null;
 const DOUBLE_MS = 320;   // double-tap window
 
 async function endPress() {
-  if (mode === "onboarding") return;   // onboarding is handled on pointerdown
+  if (mode !== "normal") return;   // welcome popup is open
   if (!holding) return;
   holding = false;
   stage.classList.remove("armed");
@@ -483,10 +542,9 @@ function updateLabels() {
   document.documentElement.lang = lang;
   langBtn.textContent = lang.toUpperCase();
   updateLabels();
-  hintEl.textContent = onboarded ? t("hint") : "";
-  setState("", onboarded ? t("idle") : t("startTap"));
-  if (!onboarded) onboard();   // try to speak the welcome on load (works where the browser allows it)
-  await startCamera();
+  hintEl.textContent = t("hint");
+  setState("", t("idle"));
+  showIntro();      // welcome popup on every open (the camera starts when it closes)
   loadDetector();   // preload the object detector in the background (non-blocking)
   try { client = await Client.connect(window.location.origin); console.log("Iris connected"); }
   catch (e) { console.error("connect:", e); setState("", t("err")); }

frontend/index.html

@@ -60,6 +60,28 @@
     </button>
   </nav>
 
+  <!-- welcome popup: shows on every open, reads the pitch aloud, closeable by voice/tap -->
+  <div id="intro" role="dialog" aria-modal="true" aria-labelledby="intro-title" aria-describedby="intro-body">
+    <div class="intro-card" role="document">
+      <button id="intro-replay" class="intro-mark" aria-label="Replay the introduction">
+        <svg viewBox="0 0 120 120" class="iris-mark" aria-hidden="true">
+          <path d="M14 60 Q60 26 106 60 Q60 94 14 60 Z" fill="none" stroke="#fff" stroke-width="3.2" stroke-linejoin="round" opacity=".92"/>
+          <circle cx="60" cy="60" r="17" fill="none" stroke="#fff" stroke-width="3.2" opacity=".92"/>
+          <circle cx="60" cy="60" r="6" fill="#ff7a18"/>
+        </svg>
+      </button>
+      <h2 id="intro-title">Iris</h2>
+      <p id="intro-body"></p>
+      <div class="intro-langs" role="group" aria-label="Language">
+        <button id="intro-en" class="intro-lang">EN</button>
+        <button id="intro-pt" class="intro-lang">PT</button>
+      </div>
+      <a id="intro-video" class="intro-video" href="#" target="_blank" rel="noopener"></a>
+      <button id="intro-close" class="intro-close"></button>
+      <p id="intro-hint" class="intro-hint"></p>
+    </div>
+  </div>
+
   <audio id="player" playsinline></audio>
 
   <!-- in-browser object detection (gates live mode); falls back to pixel-diff if unavailable -->

frontend/style.css

@@ -175,6 +175,60 @@ body[data-state=""] #status, body:not([data-state]) #status { letter-spacing: .0
 }
 @keyframes livedot { 0%{box-shadow:0 0 0 0 rgba(255,59,48,.65)} 100%{box-shadow:0 0 0 11px rgba(255,59,48,0)} }
 
+/* ===== welcome popup (shown on every open) ===== */
+#intro {
+  position: fixed; inset: 0; z-index: 10;
+  display: grid; place-items: center; padding: 6vmin;
+  background: rgba(5,6,10,.72); backdrop-filter: blur(14px);
+  animation: introIn .3s ease;
+}
+#intro[hidden] { display: none; }
+@keyframes introIn { from { opacity: 0 } to { opacity: 1 } }
+
+.intro-card {
+  width: min(92vw, 460px); max-height: 88vh; overflow-y: auto;
+  display: flex; flex-direction: column; align-items: center; text-align: center; gap: 18px;
+  padding: clamp(24px, 6vmin, 40px) clamp(20px, 5vmin, 34px);
+  background: var(--glass); border: 1px solid var(--stroke); border-radius: var(--r-lg);
+  box-shadow: 0 24px 60px rgba(0,0,0,.55);
+  animation: introRise .42s cubic-bezier(.2,.7,.2,1);
+}
+@keyframes introRise { from { opacity: 0; transform: translateY(16px) } to { opacity: 1; transform: none } }
+
+.intro-mark { background: none; border: 0; padding: 6px; cursor: pointer; filter: drop-shadow(0 6px 22px rgba(0,0,0,.5)); }
+.intro-mark .iris-mark { width: 84px; height: auto; display: block; }
+
+#intro-title { font-family: var(--font-display); font-weight: 700; font-size: clamp(28px, 7vmin, 40px); letter-spacing: .04em; }
+#intro-body { font-family: var(--font-body); font-size: clamp(16px, 4vmin, 19px); line-height: 1.5; color: var(--fg); max-width: 34ch; }
+
+.intro-langs { display: flex; gap: 10px; }
+.intro-lang {
+  min-width: 56px; min-height: 44px; padding: 0 16px;
+  background: transparent; color: var(--fg); border: 2px solid var(--stroke); border-radius: var(--r-pill);
+  font-family: var(--font-display); font-weight: 700; font-size: 16px; cursor: pointer;
+}
+.intro-lang[aria-pressed="true"] { background: var(--accent); border-color: var(--accent); color: var(--accent-ink); }
+
+.intro-video {
+  display: inline-flex; align-items: center; justify-content: center; gap: 8px;
+  min-height: 48px; padding: 0 22px;
+  border: 2px solid var(--accent); border-radius: var(--r-pill); color: var(--fg);
+  font-family: var(--font-display); font-weight: 600; font-size: 16px; text-decoration: none;
+}
+
+.intro-close {
+  width: 100%; min-height: 64px; margin-top: 4px; padding: 0 24px;
+  background: var(--accent); color: var(--accent-ink); border: 0; border-radius: var(--r-lg);
+  font-family: var(--font-display); font-weight: 700; font-size: 20px; cursor: pointer;
+  box-shadow: 0 10px 28px rgba(0,0,0,.34);
+}
+.intro-close:active { transform: scale(.98); }
+
+.intro-hint { font-family: var(--font-body); font-size: 14px; color: var(--muted); }
+
+body.a11y-boost .intro-card { background: rgba(0,0,0,.94); }
+body.a11y-boost #intro-body { font-size: clamp(18px, 4.6vmin, 22px); font-weight: 700; }
+
 /* ===== accessible mode (max contrast + larger text) ===== */
 body.a11y-boost { --glass: rgba(0,0,0,.92); --stroke: #ffffff; }
 body.a11y-boost #cam { filter: brightness(.25); }