feat(voice): 实时语音对话页（React 完全复刻原版 UI）

- /voice 页面：中间圆球 + 左右按钮 + 状态图标 + 右下角气泡（进场/淡出/阶梯字号/上限8）+ 噪声门弧线电平，结构类名与原版一致
- s2s WebSocket 客户端 + worklet 音频（mic-capture/audio-playback）+ orb 可视化
- 摄像头实时预览（默认开启）+ 视觉识别状态条（后端 YOLO 推理）
- 底部园区概览条（复用 ParkOverviewStrip），orb-wrap 视窗居中
- 页眉复用 ScreenLayout；左右键导航加入 /voice
- 文档：docs/voice-integration-plan.md

public/voice-demo/config.js

@@ -0,0 +1,3 @@
+// voice-demo 语音对话页 WS 地址：自动取自当前页面 hostname（与 DPM 后端同机/同网段）
+// 如服务器 IP 是 192.168.1.9 → ws://192.168.1.9:8765/v1/realtime
+window.VOICE_WS_URL = window.VOICE_WS_URL || ("ws://" + location.hostname + ":8765/v1/realtime");

public/voice-demo/index.html

@@ -0,0 +1,353 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>Minimal Conversation · S2S backend (WebSocket)</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Geist+Mono:wght@400;500;600&family=Inter:wght@400;500;600;700;800&display=swap"
+      rel="stylesheet"
+    />
+    <link rel="stylesheet" href="style.css?v=3" />
+  </head>
+  <!--
+    `booting` disables transitions/animations until the first paint commits.
+    Without this the orb visibly fades/scales in on the very first frame
+    because `state-idle` and the generic `.ind` defaults differ. The
+    bootstrap script at the end of main.js strips the class after one rAF.
+  -->
+  <body style="background:#0d1117" class="booting">
+    <!-- Digital-human video, fixed as a full-viewport background layer -->
+    <div id="avatar-stage" class="avatar-stage" aria-hidden="true">
+    </div>
+
+    <div id="app">
+      <header class="topbar">
+        <div class="topbar-right">
+          <!-- HF login chip / sign-in pill. Populated by ui/account.js; only
+               shown when the deploy runs behind a load balancer with OAuth. -->
+          <div id="account" class="account" hidden></div>
+          <button id="about-btn-m" class="icon-btn about-btn-mobile" title="About this space" aria-label="About this space">
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>
+          </button>
+          <button id="tools-btn" class="icon-btn" title="Tools" aria-label="Tools">
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/></svg>
+          </button>
+          <button id="chat-btn" class="icon-btn" title="Conversation history" aria-label="Conversation history">
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
+            <span id="chat-badge" class="chat-badge" aria-hidden="true"></span>
+          </button>
+          <button id="settings-btn" class="icon-btn" title="Settings" aria-label="Settings">
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9c0 .66.39 1.25 1 1.51H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"/></svg>
+          </button>
+        </div>
+      </header>
+
+      <main class="stage">
+        <div class="orb-wrap">
+          <div id="mic-gate" class="mic-gate">
+            <svg id="mic-gate-arc" class="mic-gate-arc" viewBox="0 0 100 100" aria-hidden="true">
+              <path id="mga-track" class="mga-track" fill="none" />
+              <path id="mga-fill" class="mga-fill" fill="none" />
+              <path id="mga-hit" class="mga-hit" fill="none" />
+              <circle id="mga-handle" class="mga-handle" r="3" />
+            </svg>
+            <button id="mic-btn" class="side-btn" type="button" aria-label="Mute" title="Mute" aria-hidden="true">
+              <svg class="mic-on" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="2" width="6" height="12" rx="3"/><path d="M5 10a7 7 0 0 0 14 0"/><line x1="12" y1="19" x2="12" y2="22"/></svg>
+              <svg class="mic-off" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><line x1="2" y1="2" x2="22" y2="22"/><path d="M9 5a3 3 0 0 1 6 0v4"/><path d="M9 10v1a3 3 0 0 0 5.1 2.1"/><path d="M19 10a7 7 0 0 1-1.24 3.97"/><path d="M5 10a7 7 0 0 0 11 5.67"/><line x1="12" y1="19" x2="12" y2="22"/></svg>
+            </button>
+          </div>
+
+          <button
+            id="main-circle"
+            class="circle state-idle"
+            type="button"
+            aria-label="Start voice conversation"
+          >
+            <span class="circle-glow" aria-hidden="true"></span>
+            <span class="circle-ring" aria-hidden="true"></span>
+            <span class="circle-ring-outer" aria-hidden="true"></span>
+            <span class="circle-core">
+              <span class="circle-indicator" aria-hidden="true">
+                <svg class="ind ind-mic" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                  <rect x="9" y="2" width="6" height="12" rx="3" fill="currentColor" stroke="none"/>
+                  <path d="M5 10a7 7 0 0 0 14 0"/>
+                  <line x1="12" y1="19" x2="12" y2="22"/>
+                  <line x1="8" y1="22" x2="16" y2="22"/>
+                </svg>
+                <svg class="ind ind-error" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><line x1="12" y1="8" x2="12" y2="13"/><line x1="12" y1="16" x2="12" y2="16"/></svg>
+                <span class="ind ind-spinner"></span>
+                <span class="ind ind-thinking">
+                  <span class="dot"></span>
+                  <span class="dot"></span>
+                  <span class="dot"></span>
+                </span>
+                <span class="ind ind-bars">
+                  <span class="bar"></span>
+                  <span class="bar"></span>
+                  <span class="bar"></span>
+                  <span class="bar"></span>
+                  <span class="bar"></span>
+                </span>
+                <svg class="ind ind-voice" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                  <path d="M3 10v4a1 1 0 0 0 1 1h3l5 4V5L7 9H4a1 1 0 0 0-1 1z" fill="currentColor" stroke="none"/>
+                  <path class="wave wave-1" d="M16 8a5 5 0 0 1 0 8"/>
+                  <path class="wave wave-2" d="M19 5a9 9 0 0 1 0 14"/>
+                </svg>
+              </span>
+            </span>
+          </button>
+
+          <button id="stop-btn" class="side-btn" type="button" aria-label="End" title="End" aria-hidden="true">
+            <svg viewBox="0 0 24 24" fill="currentColor"><rect x="6" y="6" width="12" height="12" rx="2"/></svg>
+          </button>
+        </div>
+
+        <p id="circle-caption" class="circle-caption" role="status">Tap to start</p>
+        <p id="circle-subcaption" class="circle-subcaption" hidden></p>
+
+        <div id="queue-actions" class="queue-actions" hidden>
+          <button id="join-queue-btn" class="join-queue-btn" type="button" hidden>
+            Join now
+          </button>
+          <button id="leave-queue-btn" class="leave-queue-btn" type="button" hidden>
+            Leave queue
+          </button>
+        </div>
+
+        <div id="text-input-bar" class="text-input-bar">
+          <input id="text-input" type="text" class="text-input" placeholder="Type a message..." autocomplete="off" spellcheck="false" />
+          <button id="text-send-btn" class="text-send-btn" type="button" aria-label="Send" title="Send">
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="22" y1="2" x2="11" y2="13"/><polygon points="22 2 15 22 11 13 2 9 22 2"/></svg>
+          </button>
+        </div>
+      </main>
+
+      
+    </div>
+
+    <!-- Ephemeral chat bubbles anchored to the top-right -->
+    <div id="bubble-stack" class="bubble-stack" aria-live="polite" aria-atomic="false"></div>
+
+    <!-- Webcam self-view, shown bottom-left while the camera tool is enabled -->
+    <div id="cam-pip" class="cam-pip" aria-hidden="true">
+      <video id="cam-video" class="cam-video" autoplay playsinline muted></video>
+      <span class="cam-flash" aria-hidden="true"></span>
+      <span class="cam-label">camera</span>
+    </div>
+
+    <!-- Conversation history panel (overlay) -->
+    <div id="chat-panel" class="chat-panel">
+      <div id="chat-panel-backdrop" class="chat-panel-backdrop"></div>
+      <div class="chat-panel-inner">
+        <header class="chat-panel-header">
+          <h3>Conversation</h3>
+          <button id="chat-panel-close" class="icon-btn" aria-label="Close">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+          </button>
+        </header>
+        <div id="chat-history" class="chat-history"></div>
+      </div>
+    </div>
+
+    <dialog id="about-modal" class="modal about-modal">
+      <div class="modal-content">
+        <header class="modal-header">
+          <h2>About</h2>
+          <button id="about-close" class="icon-btn" aria-label="Close">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+          </button>
+        </header>
+
+        <!-- General intro to the speech-to-speech project -->
+        <div class="about-intro">
+          <p>Speech-to-speech is Hugging Face's open framework for real-time voice agents. Rather than one end-to-end model, it chains four open models from the Hub (speech detection, transcription, a vision-language model, and synthesis), so any stage can be swapped or run locally. This demo wires that pipeline to hosted inference.</p>
+          <a class="about-repo" href="https://github.com/huggingface/speech-to-speech" target="_blank" rel="noopener">View the project on GitHub<svg class="ext" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 17 17 7"/><path d="M8 7h9v9"/></svg></a>
+        </div>
+
+        <!-- The backend, shown as the path a turn actually travels -->
+        <div class="about-pipeline">
+          <p class="pipeline-title">The pipeline</p>
+          <ol class="pipeline">
+            <li class="pipe-endpoint">You speak</li>
+            <li class="pipe-stage">
+              <span class="pipe-tag">VAD</span>
+              <span class="pipe-job">detects speech</span>
+              <a class="pipe-model" href="https://github.com/snakers4/silero-vad" target="_blank" rel="noopener">silero-vad<svg class="ext" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 17 17 7"/><path d="M8 7h9v9"/></svg></a>
+            </li>
+            <li class="pipe-stage">
+              <span class="pipe-tag">STT</span>
+              <span class="pipe-job">transcribes it</span>
+              <a class="pipe-model" href="https://huggingface.co/nvidia/parakeet-tdt-1.1b" target="_blank" rel="noopener">nvidia/parakeet-tdt-1.1b<svg class="ext" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 17 17 7"/><path d="M8 7h9v9"/></svg></a>
+            </li>
+            <li class="pipe-stage">
+              <span class="pipe-tag">VLM</span>
+              <span class="pipe-job">analyses and composes the reply <span class="pipe-note">· via <a class="cerebras-credit" href="https://cerebras.ai" target="_blank" rel="noopener"><svg class="cerebras-mark" viewBox="0 0 50 50" aria-hidden="true"><path fill-rule="evenodd" clip-rule="evenodd" d="M29.4186 5.62713C24.2806 5.62713 19.353 7.6682 15.7199 11.3013C12.0868 14.9345 10.0457 19.862 10.0457 25C10.0457 30.1381 12.0868 35.0656 15.7199 38.6988C19.353 42.3319 24.2806 44.373 29.4186 44.373V47.2917C17.1061 47.2917 7.12695 37.3105 7.12695 24.998C7.12695 12.6855 17.104 2.7063 29.4165 2.7063V5.62505L29.4186 5.62713ZM39.3186 13.2875C37.7794 11.9809 35.9971 10.9915 34.0741 10.3761C32.1512 9.76067 30.1256 9.53147 28.1137 9.70166C26.1019 9.87185 24.1435 10.4381 22.3513 11.3677C20.559 12.2974 18.9683 13.5722 17.6704 15.1189C16.3726 16.6655 15.3933 18.4534 14.7888 20.3798C14.1844 22.3062 13.9667 24.3332 14.1483 26.344C14.33 28.3548 14.9073 30.3099 15.8472 32.0968C16.787 33.8838 18.0709 35.4673 19.6249 36.7563L17.7478 38.9938C15.9126 37.4545 14.3987 35.5687 13.2924 33.4442C12.1862 31.3197 11.5092 28.9981 11.3003 26.6119C11.0914 24.2258 11.3545 21.8219 12.0747 19.5374C12.7949 17.253 13.9581 15.1328 15.4978 13.298C17.0373 11.4628 18.9233 9.94877 21.0479 8.84247C23.1726 7.73618 25.4944 7.05923 27.8807 6.8503C30.267 6.64136 32.6711 6.90453 34.9557 7.62477C37.2403 8.34501 39.3607 9.50822 41.1957 11.048L39.3186 13.2875ZM34.6207 15.0459C31.9818 13.6829 28.9113 13.4172 26.0776 14.3068C23.2438 15.1964 20.876 17.1691 19.4895 19.7958C18.1029 22.4224 17.8099 25.4903 18.6741 28.332C19.5384 31.1736 21.4899 33.5589 24.104 34.9688L22.7374 37.5521C19.4721 35.7617 17.0418 32.7592 15.9707 29.1927C14.8996 25.6261 15.2737 21.7815 17.0123 18.4883C18.7509 15.1952 21.7146 12.7176 25.2637 11.5903C28.8129 10.463 32.663 10.7763 35.9832 12.4625L34.6207 15.0459ZM29.4165 17.7896C27.5042 17.7896 25.6702 18.5493 24.318 19.9015C22.9658 21.2537 22.2061 23.0877 22.2061 25C22.2061 26.9124 22.9658 28.7464 24.318 30.0986C25.6702 31.4508 27.5042 32.2105 29.4165 32.2105V35.1313C26.7296 35.1313 24.1526 34.0639 22.2527 32.1639C20.3527 30.2639 19.2853 27.687 19.2853 25C19.2853 22.3131 20.3527 19.7362 22.2527 17.8362C24.1526 15.9362 26.7296 14.8688 29.4165 14.8688V17.7896Z" fill="#F15A29"/><path d="M32.0981 22.5749C31.7875 22.2404 31.4295 21.9534 31.0356 21.7228C30.6925 21.519 30.3014 21.4097 29.9023 21.4062C29.371 21.4062 28.896 21.5041 28.4773 21.6978C28.0725 21.8802 27.7089 22.1425 27.4081 22.469C27.1074 22.7955 26.8758 23.1795 26.7273 23.5978C26.5731 24.0207 26.4981 24.4645 26.4981 24.9124C26.4981 25.3666 26.5731 25.8082 26.7273 26.227C26.877 26.6449 27.1091 27.0286 27.4096 27.3553C27.7102 27.682 28.0733 27.9451 28.4773 28.1291C28.8939 28.3228 29.3731 28.4207 29.9023 28.4207C30.3523 28.4207 30.771 28.3249 31.1564 28.1395C31.5481 27.952 31.8856 27.6707 32.146 27.3228L34.0794 29.4187C33.7877 29.7103 33.4544 29.9624 33.0752 30.1749C32.374 30.566 31.6108 30.8338 30.8189 30.9666C30.4648 31.0207 30.1585 31.0499 29.9023 31.0499C29.0617 31.0552 28.2271 30.9069 27.4398 30.6124C26.6954 30.3371 26.0144 29.914 25.4377 29.3687C24.8643 28.8208 24.4078 28.1624 24.096 27.4332C23.7572 26.6366 23.5883 25.778 23.6002 24.9124C23.6002 23.9874 23.7669 23.1478 24.096 22.3916C24.4085 21.6624 24.8627 21.0041 25.4356 20.4562C26.0148 19.9124 26.696 19.4895 27.4398 19.2145C28.2271 18.92 29.0617 18.7717 29.9023 18.777C30.6419 18.777 31.3856 18.9187 32.1356 19.202C32.8877 19.4895 33.5627 19.952 34.1023 20.5541L32.0981 22.5749Z" fill="#fff"/></svg>Cerebras</a></span></span>
+              <a class="pipe-model" href="https://huggingface.co/google/gemma-4-31B-it" target="_blank" rel="noopener">google/gemma-4-31B-it<svg class="ext" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 17 17 7"/><path d="M8 7h9v9"/></svg></a>
+            </li>
+            <li class="pipe-stage">
+              <span class="pipe-tag">TTS</span>
+              <span class="pipe-job">speaks it back</span>
+              <a class="pipe-model" href="https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice" target="_blank" rel="noopener">Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice<svg class="ext" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 17 17 7"/><path d="M8 7h9v9"/></svg></a>
+            </li>
+            <li class="pipe-endpoint">The orb replies</li>
+          </ol>
+        </div>
+      </div>
+    </dialog>
+
+    <dialog id="settings-modal" class="modal">
+      <form method="dialog" class="modal-content">
+        <header class="modal-header">
+          <h2>Settings</h2>
+          <button class="icon-btn" value="close" aria-label="Close">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+          </button>
+        </header>
+
+        <div class="tab-panels">
+          <section class="tab-panel active" role="tabpanel">
+            <label class="field" id="conn-field">
+              <span id="conn-label">Speech-to-speech server URL</span>
+              <input id="lb-url" type="text" autocomplete="off" spellcheck="false" placeholder="http://localhost:port" />
+              <small id="conn-hint">
+                URL of your speech-to-speech server, e.g.
+                <code>http://localhost:8080</code> (the app adds <code>/v1/realtime</code>).
+              </small>
+            </label>
+
+            <div class="field-row">
+              <label class="field">
+                <span>Voice</span>
+                <select id="voice">
+                  <option value="Aiden" selected>Aiden</option>
+                  <option value="Ryan">Ryan</option>
+                  <option value="Dylan">Dylan</option>
+                  <option value="Eric">Eric</option>
+                  <option value="Ono_Anna">Ono_Anna</option>
+                  <option value="Serena">Serena</option>
+                  <option value="Sohee">Sohee</option>
+                  <option value="Uncle_Fu">Uncle_Fu</option>
+                  <option value="Vivian">Vivian</option>
+                </select>
+                <label for="voice-upload" class="btn-upload" role="button" tabindex="0" id="voice-upload-btn">📤 Upload</label>
+                <input type="file" id="voice-upload" accept="audio/*" style="display:none">
+              </label>
+            </div>
+
+            <div class="field">
+              <span class="field-head">
+                Noise gate
+                <span id="gate-value" class="field-value">Off</span>
+              </span>
+              <div class="gate">
+                <div class="gate-track" aria-hidden="true">
+                  <div id="gate-meter-fill" class="gate-meter-fill"></div>
+                  <input
+                    id="noise-gate"
+                    type="range"
+                    min="-66"
+                    max="-3"
+                    step="1"
+                    value="-50"
+                    aria-label="Noise gate threshold"
+                  />
+                </div>
+                <div class="gate-ends">
+                  <span>Off</span>
+                  <span>−3 dB</span>
+                </div>
+              </div>
+              <small>
+                Mutes the mic below the handle so room noise isn't sent. Slide fully
+                left to turn it off; the bar shows your live input while in a call.
+              </small>
+            </div>
+
+            <label class="field">
+              <span>Instructions</span>
+              <textarea id="instructions" rows="5" placeholder="You are a friendly voice assistant..."></textarea>
+            </label>
+
+            <div class="field">
+              <button id="restart-conversation" type="button" class="btn primary wide" disabled>
+                Restart conversation with these settings
+              </button>
+              <small id="restart-hint">Connect first, then come back here to apply live changes.</small>
+            </div>
+          </section>
+        </div>
+
+        <footer class="modal-footer">
+          <button id="settings-save" type="submit" class="btn primary" value="save">Save</button>
+        </footer>
+      </form>
+    </dialog>
+
+    <dialog id="tools-modal" class="modal">
+      <div class="modal-content">
+        <header class="modal-header">
+          <h2>Tools</h2>
+          <button id="tools-close" class="icon-btn" aria-label="Close">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+          </button>
+        </header>
+
+        <p class="tools-intro">Let the assistant act during the conversation. Changes apply live.</p>
+
+        <div class="tool-list">
+          <div class="tool-row" id="tool-web-row">
+            <div class="tool-info">
+              <span class="tool-name">Web search</span>
+              <span class="tool-desc">Look things up on Google, via Serper.</span>
+            </div>
+            <label class="switch">
+              <input id="tool-web" type="checkbox" />
+              <span class="switch-track" aria-hidden="true"></span>
+            </label>
+          </div>
+          <label class="field tools-key">
+            <span>Search API key</span>
+            <input id="search-key" type="password" autocomplete="off" spellcheck="false" />
+            <small id="tool-web-hint"></small>
+          </label>
+
+          <div class="tool-row tool-row-sep" id="tool-cam-row">
+            <div class="tool-info">
+              <span class="tool-name">Camera</span>
+              <span class="tool-desc">Let the assistant see through your webcam.</span>
+            </div>
+            <label class="switch">
+              <input id="tool-cam" type="checkbox" />
+              <span class="switch-track" aria-hidden="true"></span>
+            </label>
+          </div>
+          <small id="tool-cam-hint" class="tool-hint">A live preview shows bottom-left while the camera is on.</small>
+        </div>
+      </div>
+    </dialog>
+
+    <!-- Shown when the per-day conversation budget is spent (mid-call or at
+         start). Title / message / CTA / note are filled per tier by
+         ui/account.js. The hero is the HF mark — a friendly smiling face. -->
+    <dialog id="limit-modal" class="modal limit-modal">
+      <div class="modal-content limit-card">
+        <button id="limit-close" class="icon-btn limit-close" aria-label="Close">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+        </button>
+        <div class="limit-badge" aria-hidden="true">
+          <svg class="hf-logo" viewBox="0 0 95 88" fill="none" aria-hidden="true"><path fill="#FFD21E" d="M47.21 76.5a34.75 34.75 0 1 0 0-69.5 34.75 34.75 0 0 0 0 69.5Z"/><path fill="#FF9D0B" d="M81.96 41.75a34.75 34.75 0 1 0-69.5 0 34.75 34.75 0 0 0 69.5 0Zm-73.5 0a38.75 38.75 0 1 1 77.5 0 38.75 38.75 0 0 1-77.5 0Z"/><path fill="#3A3B45" d="M58.5 32.3c1.28.44 1.78 3.06 3.07 2.38a5 5 0 1 0-6.76-2.07c.61 1.15 2.55-.72 3.7-.32ZM34.95 32.3c-1.28.44-1.79 3.06-3.07 2.38a5 5 0 1 1 6.76-2.07c-.61 1.15-2.56-.72-3.7-.32Z"/><path fill="#FF323D" d="M46.96 56.29c9.83 0 13-8.76 13-13.26 0-2.34-1.57-1.6-4.09-.36-2.33 1.15-5.46 2.74-8.9 2.74-7.19 0-13-6.88-13-2.38s3.16 13.26 13 13.26Z"/><path fill="#3A3B45" fill-rule="evenodd" d="M39.43 54a8.7 8.7 0 0 1 5.3-4.49c.4-.12.81.57 1.24 1.28.4.68.82 1.37 1.24 1.37.45 0 .9-.68 1.33-1.35.45-.7.89-1.38 1.32-1.25a8.61 8.61 0 0 1 5 4.17c3.73-2.94 5.1-7.74 5.1-10.7 0-2.34-1.57-1.6-4.09-.36l-.14.07c-2.31 1.15-5.39 2.67-8.77 2.67s-6.45-1.52-8.77-2.67c-2.6-1.29-4.23-2.1-4.23.29 0 3.05 1.46 8.06 5.47 10.97Z" clip-rule="evenodd"/><path fill="#FF9D0B" d="M70.71 37a3.25 3.25 0 1 0 0-6.5 3.25 3.25 0 0 0 0 6.5ZM24.21 37a3.25 3.25 0 1 0 0-6.5 3.25 3.25 0 0 0 0 6.5ZM17.52 48c-1.62 0-3.06.66-4.07 1.87a5.97 5.97 0 0 0-1.33 3.76 7.1 7.1 0 0 0-1.94-.3c-1.55 0-2.95.59-3.94 1.66a5.8 5.8 0 0 0-.8 7 5.3 5.3 0 0 0-1.79 2.82c-.24.9-.48 2.8.8 4.74a5.22 5.22 0 0 0-.37 5.02c1.02 2.32 3.57 4.14 8.52 6.1 3.07 1.22 5.89 2 5.91 2.01a44.33 44.33 0 0 0 10.93 1.6c5.86 0 10.05-1.8 12.46-5.34 3.88-5.69 3.33-10.9-1.7-15.92-2.77-2.78-4.62-6.87-5-7.77-.78-2.66-2.84-5.62-6.25-5.62a5.7 5.7 0 0 0-4.6 2.46c-1-1.26-1.98-2.25-2.86-2.82A7.4 7.4 0 0 0 17.52 48Zm0 4c.51 0 1.14.22 1.82.65 2.14 1.36 6.25 8.43 7.76 11.18.5.92 1.37 1.31 2.14 1.31 1.55 0 2.75-1.53.15-3.48-3.92-2.93-2.55-7.72-.68-8.01.08-.02.17-.02.24-.02 1.7 0 2.45 2.93 2.45 2.93s2.2 5.52 5.98 9.3c3.77 3.77 3.97 6.8 1.22 10.83-1.88 2.75-5.47 3.58-9.16 3.58-3.81 0-7.73-.9-9.92-1.46-.11-.03-13.45-3.8-11.76-7 .28-.54.75-.76 1.34-.76 2.38 0 6.7 3.54 8.57 3.54.41 0 .7-.17.83-.6.79-2.85-12.06-4.05-10.98-8.17.2-.73.71-1.02 1.44-1.02 3.14 0 10.2 5.53 11.68 5.53.11 0 .2-.03.24-.1.74-1.2.33-2.04-4.9-5.2-5.21-3.16-8.88-5.06-6.8-7.33.24-.26.58-.38 1-.38 3.17 0 10.66 6.82 10.66 6.82s2.02 2.1 3.25 2.1c.28 0 .52-.1.68-.38.86-1.46-8.06-8.22-8.56-11.01-.34-1.9.24-2.85 1.31-2.85Z"/><path fill="#FFD21E" d="M38.6 76.69c2.75-4.04 2.55-7.07-1.22-10.84-3.78-3.77-5.98-9.3-5.98-9.3s-.82-3.2-2.69-2.9c-1.87.3-3.24 5.08.68 8.01 3.91 2.93-.78 4.92-2.29 2.17-1.5-2.75-5.62-9.82-7.76-11.18-2.13-1.35-3.63-.6-3.13 2.2.5 2.79 9.43 9.55 8.56 11-.87 1.47-3.93-1.71-3.93-1.71s-9.57-8.71-11.66-6.44c-2.08 2.27 1.59 4.17 6.8 7.33 5.23 3.16 5.64 4 4.9 5.2-.75 1.2-12.28-8.53-13.36-4.4-1.08 4.11 11.77 5.3 10.98 8.15-.8 2.85-9.06-5.38-10.74-2.18-1.7 3.21 11.65 6.98 11.76 7.01 4.3 1.12 15.25 3.49 19.08-2.12Z"/><path fill="#FF9D0B" d="M77.4 48c1.62 0 3.07.66 4.07 1.87a5.97 5.97 0 0 1 1.33 3.76 7.1 7.1 0 0 1 1.95-.3c1.55 0 2.95.59 3.94 1.66a5.8 5.8 0 0 1 .8 7 5.3 5.3 0 0 1 1.78 2.82c.24.9.48 2.8-.8 4.74a5.22 5.22 0 0 1 .37 5.02c-1.02 2.32-3.57 4.14-8.51 6.1-3.08 1.22-5.9 2-5.92 2.01a44.33 44.33 0 0 1-10.93 1.6c-5.86 0-10.05-1.8-12.46-5.34-3.88-5.69-3.33-10.9 1.7-15.92 2.78-2.78 4.63-6.87 5.01-7.77.78-2.66 2.83-5.62 6.24-5.62a5.7 5.7 0 0 1 4.6 2.46c1-1.26 1.98-2.25 2.87-2.82A7.4 7.4 0 0 1 77.4 48Zm0 4c-.51 0-1.13.22-1.82.65-2.13 1.36-6.25 8.43-7.76 11.18a2.43 2.43 0 0 1-2.14 1.31c-1.54 0-2.75-1.53-.14-3.48 3.91-2.93 2.54-7.72.67-8.01a1.54 1.54 0 0 0-.24-.02c-1.7 0-2.45 2.93-2.45 2.93s-2.2 5.52-5.97 9.3c-3.78 3.77-3.98 6.8-1.22 10.83 1.87 2.75 5.47 3.58 9.15 3.58 3.82 0 7.73-.9 9.93-1.46.1-.03 13.45-3.8 11.76-7-.29-.54-.75-.76-1.34-.76-2.38 0-6.71 3.54-8.57 3.54-.42 0-.71-.17-.83-.6-.8-2.85 12.05-4.05 10.97-8.17-.19-.73-.7-1.02-1.44-1.02-3.14 0-10.2 5.53-11.68 5.53-.1 0-.19-.03-.23-.1-.74-1.2-.34-2.04 4.88-5.2 5.23-3.16 8.9-5.06 6.8-7.33-.23-.26-.57-.38-.98-.38-3.18 0-10.67 6.82-10.67 6.82s-2.02 2.1-3.24 2.1a.74.74 0 0 1-.68-.38c-.87-1.46 8.05-8.22 8.55-11.01.34-1.9-.24-2.85-1.31-2.85Z"/><path fill="#FFD21E" d="M56.33 76.69c-2.75-4.04-2.56-7.07 1.22-10.84 3.77-3.77 5.97-9.3 5.97-9.3s.82-3.2 2.7-2.9c1.86.3 3.23 5.08-.68 8.01-3.92 2.93.78 4.92 2.28 2.17 1.51-2.75 5.63-9.82 7.76-11.18 2.13-1.35 3.64-.6 3.13 2.2-.5 2.79-9.42 9.55-8.55 11 .86 1.47 3.92-1.71 3.92-1.71s9.58-8.71 11.66-6.44c2.08 2.27-1.58 4.17-6.8 7.33-5.23 3.16-5.63 4-4.9 5.2.75 1.2 12.28-8.53 13.36-4.4 1.08 4.11-11.76 5.3-10.97 8.15.8 2.85 9.05-5.38 10.74-2.18 1.69 3.21-11.65 6.98-11.76 7.01-4.31 1.12-15.26 3.49-19.08-2.12Z"/></svg>
+        </div>
+        <h2 id="limit-title" class="limit-title">That's a wrap for now</h2>
+        <p id="limit-msg" class="limit-msg"></p>
+        <a id="limit-cta" class="btn primary wide limit-cta" href="#"></a>
+        <p id="limit-note" class="limit-note"></p>
+      </div>
+    </dialog>
+
+    <script src="config.js"></script>
+    <script type="module" src="main.js"></script>
+  </body>
+</html>

public/voice-demo/ui/account.js

@@ -0,0 +1,189 @@
+// @ts-check
+/**
+ * Account — the HF login chip and the daily-limit modal.
+ *
+ * Reads `/api/me` to learn the current tier (anonymous / signed-in / PRO) and
+ * remaining daily talk-time, renders a sign-in pill or a signed-in chip with a
+ * small popover (tier, remaining, sign out, upgrade), and shows the limit modal
+ * when a conversation is refused or cut. The time metering itself lives in
+ * main.js (heartbeat loop) + the server; this module is just the surface.
+ *
+ * Inert unless the deploy is in LB mode (`/api/me` → `{enabled:true}`).
+ */
+
+import { $, escHtml } from "./dom.js";
+
+const PRO_URL = "https://huggingface.co/subscribe/pro";
+
+// Official multi-color Hugging Face logo, used in the badge + sign-in CTA.
+const HF_MARK = `<svg class="hf-logo" viewBox="0 0 95 88" fill="none" aria-hidden="true"><path fill="#FFD21E" d="M47.21 76.5a34.75 34.75 0 1 0 0-69.5 34.75 34.75 0 0 0 0 69.5Z"/><path fill="#FF9D0B" d="M81.96 41.75a34.75 34.75 0 1 0-69.5 0 34.75 34.75 0 0 0 69.5 0Zm-73.5 0a38.75 38.75 0 1 1 77.5 0 38.75 38.75 0 0 1-77.5 0Z"/><path fill="#3A3B45" d="M58.5 32.3c1.28.44 1.78 3.06 3.07 2.38a5 5 0 1 0-6.76-2.07c.61 1.15 2.55-.72 3.7-.32ZM34.95 32.3c-1.28.44-1.79 3.06-3.07 2.38a5 5 0 1 1 6.76-2.07c-.61 1.15-2.56-.72-3.7-.32Z"/><path fill="#FF323D" d="M46.96 56.29c9.83 0 13-8.76 13-13.26 0-2.34-1.57-1.6-4.09-.36-2.33 1.15-5.46 2.74-8.9 2.74-7.19 0-13-6.88-13-2.38s3.16 13.26 13 13.26Z"/><path fill="#3A3B45" fill-rule="evenodd" d="M39.43 54a8.7 8.7 0 0 1 5.3-4.49c.4-.12.81.57 1.24 1.28.4.68.82 1.37 1.24 1.37.45 0 .9-.68 1.33-1.35.45-.7.89-1.38 1.32-1.25a8.61 8.61 0 0 1 5 4.17c3.73-2.94 5.1-7.74 5.1-10.7 0-2.34-1.57-1.6-4.09-.36l-.14.07c-2.31 1.15-5.39 2.67-8.77 2.67s-6.45-1.52-8.77-2.67c-2.6-1.29-4.23-2.1-4.23.29 0 3.05 1.46 8.06 5.47 10.97Z" clip-rule="evenodd"/><path fill="#FF9D0B" d="M70.71 37a3.25 3.25 0 1 0 0-6.5 3.25 3.25 0 0 0 0 6.5ZM24.21 37a3.25 3.25 0 1 0 0-6.5 3.25 3.25 0 0 0 0 6.5ZM17.52 48c-1.62 0-3.06.66-4.07 1.87a5.97 5.97 0 0 0-1.33 3.76 7.1 7.1 0 0 0-1.94-.3c-1.55 0-2.95.59-3.94 1.66a5.8 5.8 0 0 0-.8 7 5.3 5.3 0 0 0-1.79 2.82c-.24.9-.48 2.8.8 4.74a5.22 5.22 0 0 0-.37 5.02c1.02 2.32 3.57 4.14 8.52 6.1 3.07 1.22 5.89 2 5.91 2.01a44.33 44.33 0 0 0 10.93 1.6c5.86 0 10.05-1.8 12.46-5.34 3.88-5.69 3.33-10.9-1.7-15.92-2.77-2.78-4.62-6.87-5-7.77-.78-2.66-2.84-5.62-6.25-5.62a5.7 5.7 0 0 0-4.6 2.46c-1-1.26-1.98-2.25-2.86-2.82A7.4 7.4 0 0 0 17.52 48Zm0 4c.51 0 1.14.22 1.82.65 2.14 1.36 6.25 8.43 7.76 11.18.5.92 1.37 1.31 2.14 1.31 1.55 0 2.75-1.53.15-3.48-3.92-2.93-2.55-7.72-.68-8.01.08-.02.17-.02.24-.02 1.7 0 2.45 2.93 2.45 2.93s2.2 5.52 5.98 9.3c3.77 3.77 3.97 6.8 1.22 10.83-1.88 2.75-5.47 3.58-9.16 3.58-3.81 0-7.73-.9-9.92-1.46-.11-.03-13.45-3.8-11.76-7 .28-.54.75-.76 1.34-.76 2.38 0 6.7 3.54 8.57 3.54.41 0 .7-.17.83-.6.79-2.85-12.06-4.05-10.98-8.17.2-.73.71-1.02 1.44-1.02 3.14 0 10.2 5.53 11.68 5.53.11 0 .2-.03.24-.1.74-1.2.33-2.04-4.9-5.2-5.21-3.16-8.88-5.06-6.8-7.33.24-.26.58-.38 1-.38 3.17 0 10.66 6.82 10.66 6.82s2.02 2.1 3.25 2.1c.28 0 .52-.1.68-.38.86-1.46-8.06-8.22-8.56-11.01-.34-1.9.24-2.85 1.31-2.85Z"/><path fill="#FFD21E" d="M38.6 76.69c2.75-4.04 2.55-7.07-1.22-10.84-3.78-3.77-5.98-9.3-5.98-9.3s-.82-3.2-2.69-2.9c-1.87.3-3.24 5.08.68 8.01 3.91 2.93-.78 4.92-2.29 2.17-1.5-2.75-5.62-9.82-7.76-11.18-2.13-1.35-3.63-.6-3.13 2.2.5 2.79 9.43 9.55 8.56 11-.87 1.47-3.93-1.71-3.93-1.71s-9.57-8.71-11.66-6.44c-2.08 2.27 1.59 4.17 6.8 7.33 5.23 3.16 5.64 4 4.9 5.2-.75 1.2-12.28-8.53-13.36-4.4-1.08 4.11 11.77 5.3 10.98 8.15-.8 2.85-9.06-5.38-10.74-2.18-1.7 3.21 11.65 6.98 11.76 7.01 4.3 1.12 15.25 3.49 19.08-2.12Z"/><path fill="#FF9D0B" d="M77.4 48c1.62 0 3.07.66 4.07 1.87a5.97 5.97 0 0 1 1.33 3.76 7.1 7.1 0 0 1 1.95-.3c1.55 0 2.95.59 3.94 1.66a5.8 5.8 0 0 1 .8 7 5.3 5.3 0 0 1 1.78 2.82c.24.9.48 2.8-.8 4.74a5.22 5.22 0 0 1 .37 5.02c-1.02 2.32-3.57 4.14-8.51 6.1-3.08 1.22-5.9 2-5.92 2.01a44.33 44.33 0 0 1-10.93 1.6c-5.86 0-10.05-1.8-12.46-5.34-3.88-5.69-3.33-10.9 1.7-15.92 2.78-2.78 4.63-6.87 5.01-7.77.78-2.66 2.83-5.62 6.24-5.62a5.7 5.7 0 0 1 4.6 2.46c1-1.26 1.98-2.25 2.87-2.82A7.4 7.4 0 0 1 77.4 48Zm0 4c-.51 0-1.13.22-1.82.65-2.13 1.36-6.25 8.43-7.76 11.18a2.43 2.43 0 0 1-2.14 1.31c-1.54 0-2.75-1.53-.14-3.48 3.91-2.93 2.54-7.72.67-8.01a1.54 1.54 0 0 0-.24-.02c-1.7 0-2.45 2.93-2.45 2.93s-2.2 5.52-5.97 9.3c-3.78 3.77-3.98 6.8-1.22 10.83 1.87 2.75 5.47 3.58 9.15 3.58 3.82 0 7.73-.9 9.93-1.46.1-.03 13.45-3.8 11.76-7-.29-.54-.75-.76-1.34-.76-2.38 0-6.71 3.54-8.57 3.54-.42 0-.71-.17-.83-.6-.8-2.85 12.05-4.05 10.97-8.17-.19-.73-.7-1.02-1.44-1.02-3.14 0-10.2 5.53-11.68 5.53-.1 0-.19-.03-.23-.1-.74-1.2-.34-2.04 4.88-5.2 5.23-3.16 8.9-5.06 6.8-7.33-.23-.26-.57-.38-.98-.38-3.18 0-10.67 6.82-10.67 6.82s-2.02 2.1-3.24 2.1a.74.74 0 0 1-.68-.38c-.87-1.46 8.05-8.22 8.55-11.01.34-1.9-.24-2.85-1.31-2.85Z"/><path fill="#FFD21E" d="M56.33 76.69c-2.75-4.04-2.56-7.07 1.22-10.84 3.77-3.77 5.97-9.3 5.97-9.3s.82-3.2 2.7-2.9c1.86.3 3.23 5.08-.68 8.01-3.92 2.93.78 4.92 2.28 2.17 1.51-2.75 5.63-9.82 7.76-11.18 2.13-1.35 3.64-.6 3.13 2.2-.5 2.79-9.42 9.55-8.55 11 .86 1.47 3.92-1.71 3.92-1.71s9.58-8.71 11.66-6.44c2.08 2.27-1.58 4.17-6.8 7.33-5.23 3.16-5.63 4-4.9 5.2.75 1.2 12.28-8.53 13.36-4.4 1.08 4.11-11.76 5.3-10.97 8.15.8 2.85 9.05-5.38 10.74-2.18 1.69 3.21-11.65 6.98-11.76 7.01-4.31 1.12-15.26 3.49-19.08-2.12Z"/></svg>`;
+
+/** @param {number} sec @returns {string} "m:ss" */
+function fmt(sec) {
+  const s = Math.max(0, Math.round(sec));
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+
+export class Account {
+  constructor() {
+    /** @type {HTMLElement} */
+    this._root = $("#account");
+    /** @type {HTMLDialogElement} */
+    this._modal = $("#limit-modal");
+    this._modalTitle = $("#limit-title");
+    this._modalMsg = $("#limit-msg");
+    this._modalNote = $("#limit-note");
+    /** @type {HTMLAnchorElement} */
+    this._modalCta = /** @type {any} */ ($("#limit-cta"));
+
+    /** @type {{enabled:boolean, auth?:boolean, loggedIn?:boolean, username?:string, avatar?:string, tier?:string, remainingSec?:number|null, limitSec?:number|null, loginUrl?:string|null, logoutUrl?:string|null}} */
+    this._me = { enabled: false };
+    this._popoverOpen = false;
+
+    $("#limit-close").addEventListener("click", () => this._modal.close());
+    this._modal.addEventListener("click", (e) => {
+      if (e.target === this._modal) this._modal.close();
+    });
+    // Close the popover on an outside click.
+    document.addEventListener("click", (e) => {
+      if (this._popoverOpen && !this._root.contains(/** @type {Node} */ (e.target))) {
+        this._closePopover();
+      }
+    });
+  }
+
+  get tier() {
+    return this._me.tier || "anon";
+  }
+
+  /** Fetch `/api/me` and (re)render the chip. Safe to call repeatedly (load,
+   *  after the OAuth redirect, after a conversation ends). */
+  async refresh() {
+    try {
+      const res = await fetch("api/me");
+      this._me = res.ok ? await res.json() : { enabled: false };
+    } catch {
+      this._me = { enabled: false };
+    }
+    this._render();
+  }
+
+  _render() {
+    const me = this._me;
+    if (!me.enabled) {
+      this._root.hidden = true;
+      this._root.innerHTML = "";
+      return;
+    }
+    this._root.hidden = false;
+
+    if (!me.loggedIn) {
+      // Signed-out: a sign-in pill (only when OAuth is actually available).
+      if (me.auth && me.loginUrl) {
+        this._root.innerHTML = `<a class="signin-pill" href="${escHtml(me.loginUrl)}" title="Sign in for more time"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4"/><polyline points="10 17 15 12 10 7"/><line x1="15" y1="12" x2="3" y2="12"/></svg><span>Sign in</span></a>`;
+      } else {
+        this._root.innerHTML = "";
+        this._root.hidden = true;
+      }
+      return;
+    }
+
+    // Signed-in: avatar + handle chip that toggles a popover.
+    const isPro = me.tier === "pro";
+    // Org members get unlimited usage too, but aren't PRO — don't brand them so.
+    const isUnlimited = isPro || me.tier === "org";
+    const avatar = me.avatar
+      ? `<img class="account-avatar" src="${escHtml(me.avatar)}" alt="" />`
+      : `<span class="account-avatar account-avatar-fallback">${escHtml((me.username || "?")[0].toUpperCase())}</span>`;
+    const remaining =
+      isUnlimited || me.remainingSec == null
+        ? "Unlimited"
+        : `${fmt(me.remainingSec)} left today`;
+    const tierLabel = isPro ? "PRO" : isUnlimited ? "Team" : "Free";
+
+    this._root.innerHTML = `
+      <button id="account-chip" class="account-chip" aria-haspopup="true" aria-expanded="false">
+        ${avatar}
+        <span class="account-handle">${escHtml(me.username || "you")}</span>
+        ${isPro
+          ? '<span class="account-pro">PRO</span>'
+          : me.tier === "org"
+            ? '<span class="account-pro account-team">TEAM</span>'
+            : ""}
+      </button>
+      <div id="account-pop" class="account-pop" hidden>
+        <div class="account-pop-row account-pop-name">${escHtml(me.username || "you")}</div>
+        <div class="account-pop-row account-pop-meta">
+          <span class="account-tier">${tierLabel}</span>
+          <span class="account-remaining">${escHtml(remaining)}</span>
+        </div>
+        ${isUnlimited ? "" : `<a class="account-pop-link" href="${PRO_URL}" target="_blank" rel="noopener">Upgrade to PRO</a>`}
+        <a class="account-pop-link account-signout" href="${escHtml(me.logoutUrl || "#")}">Sign out</a>
+      </div>`;
+
+    const chip = $("#account-chip");
+    chip.addEventListener("click", (e) => {
+      e.stopPropagation();
+      this._popoverOpen ? this._closePopover() : this._openPopover();
+    });
+  }
+
+  _openPopover() {
+    const pop = document.getElementById("account-pop");
+    const chip = document.getElementById("account-chip");
+    if (!pop || !chip) return;
+    pop.hidden = false;
+    chip.setAttribute("aria-expanded", "true");
+    this._popoverOpen = true;
+  }
+
+  _closePopover() {
+    const pop = document.getElementById("account-pop");
+    const chip = document.getElementById("account-chip");
+    if (pop) pop.hidden = true;
+    if (chip) chip.setAttribute("aria-expanded", "false");
+    this._popoverOpen = false;
+  }
+
+  /**
+   * Show the limit modal for a tier — used both when a conversation is refused
+   * at start (402) and when a live one is cut (heartbeat `expired`).
+   * @param {string} [tier]
+   */
+  showLimit(tier = this.tier) {
+    const canSignIn = this._me.auth && this._me.loginUrl;
+    this._modalTitle.textContent = "Thanks for chatting!";
+    if (tier === "anon") {
+      this._modalMsg.textContent =
+        "Guest conversations run for 5 minutes. Sign in with Hugging Face to get 10 minutes a day for free, and PRO members chat with no limit at all.";
+      this._modalNote.textContent = "Your free minutes refresh tomorrow.";
+      if (canSignIn) {
+        this._modalCta.innerHTML = `${HF_MARK}<span>Sign in with Hugging Face</span>`;
+        this._modalCta.href = /** @type {string} */ (this._me.loginUrl);
+        this._modalCta.hidden = false;
+      } else {
+        this._modalCta.hidden = true;
+      }
+    } else {
+      // Signed-in, non-PRO.
+      this._modalMsg.textContent =
+        "You've enjoyed your 10 minutes for today. Go PRO for unlimited conversations and to support open source AI.";
+      this._modalNote.textContent = "Or come back tomorrow. Your minutes reset daily.";
+      this._modalCta.innerHTML = "<span>Upgrade to PRO</span>";
+      this._modalCta.href = PRO_URL;
+      this._modalCta.hidden = false;
+    }
+    if (!this._modal.open) this._modal.showModal();
+  }
+
+  /** Show a warm "we're at capacity" message when even the waiting line is full.
+   *  Reuses the limit modal shell; no call-to-action, just reassurance. */
+  showBusy() {
+    this._modalTitle.textContent = "Hugged to the limit 🤗";
+    this._modalMsg.textContent =
+      "Every slot and the whole line are full right now. Too much love! Grab a coffee and pop back in a minute.";
+    this._modalNote.textContent = "A spot usually opens up within a few minutes.";
+    this._modalCta.hidden = true;
+    if (!this._modal.open) this._modal.showModal();
+  }
+}

public/voice-demo/ui/chat.js

@@ -0,0 +1,422 @@
+// @ts-check
+/**
+ * ChatView — owns the whole conversation surface: the slide-in history panel,
+ * the ephemeral on-orb bubbles, and all the transcript/tool/streaming
+ * bookkeeping. main.js wires the realtime client's events straight to the
+ * `on*` methods here and otherwise doesn't touch chat state.
+ *
+ * Two parallel surfaces share one shape (see `_buildMessageEl`):
+ *   - ephemeral bubbles  (`.bubble` / `.bubble-*`)  fade on a timer
+ *   - persistent history (`.hist-msg` / `.hist-*`)  the durable panel log
+ *
+ * Keying:
+ *   - user transcripts by the server's `item_id` — a speculative continuation
+ *     REUSES it, so both segments land in one row/bubble; deltas are CUMULATIVE
+ *     (each carries the full sentence so far), so we replace text wholesale.
+ *   - assistant transcripts by `response_id`, so a cancelled speculative reply
+ *     can be marked interrupted without erasing what was already shown.
+ */
+
+import { $, escHtml, DEBUG } from "./dom.js";
+
+const WRENCH_PATH = `<path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/>`;
+const CHAT_BUBBLE_SVG = `<svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>`;
+const EMPTY_STATE_HTML = `<div id="chat-empty" class="chat-empty">${CHAT_BUBBLE_SVG}<span class="chat-empty-title">No messages yet</span><span class="chat-empty-hint">Tap the orb and start talking</span></div>`;
+
+export class ChatView {
+  constructor() {
+    /** @type {HTMLButtonElement} */
+    this._chatBtn = $("#chat-btn");
+    /** @type {HTMLSpanElement} */
+    this._chatBadge = $("#chat-badge");
+    /** @type {HTMLDivElement} */
+    this._chatPanel = $("#chat-panel");
+    /** @type {HTMLDivElement} */
+    this._chatPanelBackdrop = $("#chat-panel-backdrop");
+    /** @type {HTMLButtonElement} */
+    this._chatPanelClose = $("#chat-panel-close");
+    /** @type {HTMLDivElement} */
+    this._chatHistory = $("#chat-history");
+    /** @type {HTMLDivElement} */
+    this._bubbleStack = $("#bubble-stack");
+
+    this._panelOpen = false;
+    this._scrollQueued = false;
+
+    // ── User transcript state (keyed by item_id) ───────────────────────────
+    /** @type {Map<string, HTMLElement>} */
+    this._userHistByItem = new Map();
+    /** @type {HTMLElement | null} */
+    this._activeUserBubble = null;
+    this._activeUserItemId = "";
+    // Monotonic counter for synthesizing unique keys when the server omits an
+    // item_id / response_id, so id-less messages never collapse onto each other.
+    this._anonSeq = 0;
+
+    // ── Assistant transcript state (keyed by response_id) ──────────────────
+    /** @type {Map<string, { bubble: HTMLElement, hist: HTMLElement }>} */
+    this._asstByResp = new Map();
+
+    // ── Ephemeral bubble auto-dismiss ──────────────────────────────────────
+    // Per-element expiry (epoch ms). A bubble fades once its expiry passes —
+    // but only in stack order (see _reapBubbles). Refreshing the expiry keeps a
+    // bubble alive while it updates (e.g. the live user utterance).
+    /** @type {WeakMap<HTMLElement, number>} */
+    this._bubbleExpiry = new WeakMap();
+    // Single pending reaper handle: one timer for the whole stack (not one per
+    // bubble) so dismissal is strictly oldest-first regardless of per-bubble delays.
+    this._reaperHandle = 0;
+
+    this._chatBtn.addEventListener("click", () => (this._panelOpen ? this._closePanel() : this._openPanel()));
+    this._chatPanelClose.addEventListener("click", () => this._closePanel());
+    this._chatPanelBackdrop.addEventListener("click", () => this._closePanel());
+    document.addEventListener("keydown", (e) => {
+      if (e.key === "Escape" && this._panelOpen) this._closePanel();
+    });
+  }
+
+  // ── Panel ───────────────────────────────────────────────────────────────
+
+  _openPanel() {
+    this._panelOpen = true;
+    this._chatPanel.classList.add("open");
+    this._chatBadge.classList.remove("visible");
+    this._scrollToBottom();
+  }
+
+  _closePanel() {
+    this._panelOpen = false;
+    this._chatPanel.classList.remove("open");
+  }
+
+  // Coalesce scroll-to-bottom: a burst of cumulative transcript deltas would
+  // otherwise queue one rAF per delta, all writing the same scrollTop.
+  _scrollToBottom() {
+    if (!this._panelOpen || this._scrollQueued) return;
+    this._scrollQueued = true;
+    requestAnimationFrame(() => {
+      this._scrollQueued = false;
+      this._chatHistory.scrollTop = this._chatHistory.scrollHeight;
+    });
+  }
+
+  _markUnread() {
+    if (this._panelOpen) {
+      this._scrollToBottom();
+      return;
+    }
+    this._chatBadge.classList.add("visible");
+  }
+
+  // ── Shared rendering ──────────────────────────────────────────────────────
+
+  /**
+   * Build a role-labelled message element. Ephemeral bubbles and persistent
+   * history rows share the same shape and differ only in their class prefix
+   * (`bubble`/`bubble-*` vs `hist-msg`/`hist-*`).
+   * @param {{ container: string, prefix: string, role: "user"|"assistant", text: string, partial?: boolean }} o
+   * @returns {HTMLElement}
+   */
+  _buildMessageEl({ container, prefix, role, text, partial = false }) {
+    const el = document.createElement("div");
+    el.className = `${container} ${role}`;
+    const label = role === "user" ? "You" : "Assistant";
+    el.innerHTML = `<div class="${prefix}-role">${label}</div><div class="${prefix}-body${partial ? " partial" : ""}">${escHtml(text)}</div>`;
+    return el;
+  }
+
+  // ── Ephemeral bubbles ───────────────────────────────────────────────────
+
+  /** @param {"user"|"assistant"|"tool"} role @param {string} text @returns {HTMLElement} */
+  _spawnBubble(role, text) {
+    let el;
+    if (role === "tool") {
+      el = document.createElement("div");
+      el.className = "bubble tool";
+      el.innerHTML = `<svg class="bubble-tool-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${WRENCH_PATH}</svg><span class="bubble-tool-text">${escHtml(text)}</span>`;
+    } else {
+      el = this._buildMessageEl({ container: "bubble", prefix: "bubble", role, text });
+    }
+    this._bubbleStack.appendChild(el);
+    // Cap the stack at 8, but never evict the bubble the caller is still
+    // actively updating (the live user bubble) — drop the next-oldest instead.
+    const visible = /** @type {HTMLElement[]} */ ([...this._bubbleStack.querySelectorAll(".bubble:not(.out)")]);
+    if (visible.length > 8) {
+      this._dismissBubble(visible.find((b) => b !== this._activeUserBubble) ?? visible[0]);
+    }
+    requestAnimationFrame(() => el.classList.add("in"));
+    return el;
+  }
+
+  /** @param {HTMLElement} el @param {string} text */
+  _updateBubbleText(el, text) {
+    const t = el.querySelector(".bubble-body");
+    if (t) t.textContent = text;
+  }
+
+  /** @param {HTMLElement} el */
+  _dismissBubble(el) {
+    if (!el || el.classList.contains("out")) return; // idempotent
+    this._bubbleExpiry.delete(el);
+    el.classList.remove("in");
+    el.classList.add("out");
+    const remove = () => el.remove();
+    el.addEventListener("transitionend", remove, { once: true });
+    // Fallback: transitionend never fires if the bubble's visual state didn't
+    // change (dismissed pre-paint) or the tab is backgrounded. The transition
+    // is 0.3s, so force removal a little after.
+    setTimeout(remove, 400);
+  }
+
+  /**
+   * Fade bubbles whose expiry has passed — strictly oldest-first. We walk the
+   * stack top (oldest) to bottom (newest) and stop at the first bubble still
+   * alive: nothing newer may leave while an older bubble is still on screen. A
+   * bubble that keeps updating pushes its own expiry forward, so it (and
+   * everything behind it) stays put until it finally goes quiet.
+   */
+  _reapBubbles() {
+    this._reaperHandle = 0;
+    const now = Date.now();
+    const visible = /** @type {HTMLElement[]} */ ([...this._bubbleStack.querySelectorAll(".bubble:not(.out)")]);
+    let nextWake = Infinity;
+    for (const el of visible) {
+      const exp = this._bubbleExpiry.get(el) ?? now; // no expiry recorded → treat as due
+      if (exp <= now) {
+        this._dismissBubble(el);
+      } else {
+        // Oldest survivor isn't due yet; stop so nothing newer leaves before it.
+        nextWake = exp;
+        break;
+      }
+    }
+    if (nextWake !== Infinity) {
+      this._reaperHandle = setTimeout(() => this._reapBubbles(), Math.max(50, nextWake - Date.now()));
+    }
+  }
+
+  /**
+   * (Re)arm a bubble's auto-dismiss by pushing its expiry out by `delay`.
+   * Calling it again resets the countdown — so a bubble that keeps updating
+   * stays on screen and only fades once it goes quiet. Removal is ordered by the
+   * shared reaper, so the oldest bubble always disappears first.
+   * @param {HTMLElement} el @param {number} [delay]
+   */
+  _bumpDismiss(el, delay = 4000) {
+    this._bubbleExpiry.set(el, Date.now() + delay);
+    if (!this._reaperHandle) this._reaperHandle = setTimeout(() => this._reapBubbles(), delay);
+  }
+
+  // ── History ───────────────────────────────────────────────────────────────
+
+  /** Render the empty-state placeholder into the history panel. */
+  renderEmptyState() {
+    this._chatHistory.innerHTML = EMPTY_STATE_HTML;
+  }
+
+  /** Reset the panel to the empty state and clear the unread badge. */
+  clear() {
+    this.renderEmptyState();
+    this._chatBadge.classList.remove("visible");
+  }
+
+  /** @param {"user"|"assistant"} role @param {string} text @param {boolean} partial @returns {HTMLElement} */
+  _appendHistMsg(role, text, partial) {
+    const empty = this._chatHistory.querySelector(".chat-empty");
+    if (empty) empty.remove();
+    const el = this._buildMessageEl({ container: "hist-msg", prefix: "hist", role, text, partial });
+    this._chatHistory.appendChild(el);
+    this._scrollToBottom();
+    return el;
+  }
+
+  /** @param {HTMLElement | null} el @param {string} text @param {boolean} partial */
+  _updateHistMsg(el, text, partial) {
+    if (!el) return;
+    const body = /** @type {HTMLElement | null} */ (el.querySelector(".hist-body"));
+    if (!body) return;
+    body.textContent = text;
+    body.classList.toggle("partial", partial);
+    this._scrollToBottom();
+  }
+
+  /**
+   * Append a tool-call row to the conversation. We only add it once the tool
+   * has run, so the expandable toggle carries BOTH the call input and its result.
+   * @param {string} name @param {string} argsJson @param {string} output
+   */
+  _appendHistTool(name, argsJson, output) {
+    const empty = this._chatHistory.querySelector(".chat-empty");
+    if (empty) empty.remove();
+    let pretty = argsJson;
+    try { pretty = JSON.stringify(JSON.parse(argsJson), null, 2); } catch {}
+    const el = document.createElement("div");
+    el.className = "hist-msg tool";
+    el.innerHTML = `
+      <div class="hist-role">Tool call</div>
+      <button class="hist-tool-header" aria-expanded="false">
+        <svg class="hist-tool-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${WRENCH_PATH}</svg>
+        <span class="hist-tool-name">${escHtml(name)}</span>
+        <svg class="hist-tool-chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"/></svg>
+      </button>
+      <div class="hist-tool-body">
+        <div class="hist-tool-label">Input</div>
+        <div class="hist-tool-block">${escHtml(pretty)}</div>
+        <div class="hist-tool-label">Output</div>
+        <div class="hist-tool-block hist-tool-output">${escHtml(output || "(no output)")}</div>
+      </div>
+    `;
+    const header = /** @type {HTMLButtonElement} */ (el.querySelector(".hist-tool-header"));
+    const body = /** @type {HTMLDivElement} */ (el.querySelector(".hist-tool-body"));
+    header.addEventListener("click", () => {
+      const expanded = header.getAttribute("aria-expanded") === "true";
+      header.setAttribute("aria-expanded", String(!expanded));
+      body.classList.toggle("open", !expanded);
+    });
+    this._chatHistory.appendChild(el);
+    this._scrollToBottom();
+  }
+
+  /** Tag an assistant history row as interrupted (user barged in mid-reply).
+   *  @param {HTMLElement | null} hist */
+  _markHistInterrupted(hist) {
+    if (!hist || hist.querySelector(".hist-note")) return;
+    hist.classList.add("interrupted");
+    const note = document.createElement("div");
+    note.className = "hist-note";
+    note.textContent = "Interrupted";
+    hist.appendChild(note);
+  }
+
+  /** Render a captured webcam frame in the transcript (the camera tool result).
+   *  @param {string} dataUrl */
+  _appendHistImage(dataUrl) {
+    const empty = this._chatHistory.querySelector(".chat-empty");
+    if (empty) empty.remove();
+    const el = document.createElement("div");
+    el.className = "hist-msg tool";
+    el.innerHTML = `<div class="hist-role">Snapshot</div><img class="hist-image" alt="Webcam snapshot sent to the model" />`;
+    const img = /** @type {HTMLImageElement} */ (el.querySelector("img"));
+    img.src = dataUrl;
+    this._chatHistory.appendChild(el);
+    this._scrollToBottom();
+  }
+
+  /**
+   * Reset all streaming bookkeeping for session start / teardown. Pass
+   * `dismiss` to also fade any bubbles still on screen.
+   * @param {{ dismiss?: boolean }} [opts]
+   */
+  reset(opts) {
+    if (opts?.dismiss) {
+      if (this._activeUserBubble) this._dismissBubble(this._activeUserBubble);
+      for (const { bubble } of this._asstByResp.values()) this._dismissBubble(bubble);
+    }
+    this._userHistByItem.clear();
+    this._activeUserBubble = null;
+    this._activeUserItemId = "";
+    this._asstByResp.clear();
+  }
+
+  // ── Client event handlers ─────────────────────────────────────────────────
+
+  /**
+   * A streamed transcript delta (user or assistant).
+   * @param {{ role: "user" | "assistant"; text: string; partial: boolean; itemId?: string; responseId?: string }} d
+   */
+  onTranscript(d) {
+    if (DEBUG) console.debug(`[ui] transcript role=${d.role} partial=${d.partial} item=${d.itemId} resp=${d.responseId} text=${JSON.stringify(d.text)}`);
+
+    if (d.role === "user") {
+      // Group by item_id: a speculative continuation reuses the same id, so it
+      // updates the same row/bubble. A missing id falls back to the active item
+      // (same utterance) or a fresh unique key, never a shared sentinel that
+      // would collapse distinct turns into one row.
+      const id = d.itemId || this._activeUserItemId || `_u${++this._anonSeq}`;
+      const text = d.text;
+
+      let hist = this._userHistByItem.get(id);
+      if (!hist) {
+        hist = this._appendHistMsg("user", text, d.partial);
+        this._userHistByItem.set(id, hist);
+      } else {
+        this._updateHistMsg(hist, text, d.partial);
+      }
+
+      // One ephemeral bubble per active item. Purely timer-based: the timer is
+      // refreshed on every delta, so it stays while the user keeps talking and
+      // fades a few seconds after they stop — no dependency on a response ever
+      // arriving, so it can never get stuck.
+      if (this._activeUserItemId !== id || !this._activeUserBubble) {
+        this._activeUserBubble = this._spawnBubble("user", text);
+        this._activeUserItemId = id;
+      } else {
+        this._updateBubbleText(this._activeUserBubble, text);
+      }
+      this._markUnread();
+    } else if (d.role === "assistant") {
+      // Assistant transcript arrives once, as the full text, keyed by
+      // response_id so a cancelled speculative response can be removed later. A
+      // missing id gets a unique key so two id-less replies never collide.
+      const rid = d.responseId || `_a${++this._anonSeq}`;
+      const entry = this._asstByResp.get(rid);
+      if (!entry) {
+        const bubble = this._spawnBubble("assistant", d.text);
+        this._asstByResp.set(rid, { bubble, hist: this._appendHistMsg("assistant", d.text, false) });
+      } else {
+        this._updateBubbleText(entry.bubble, d.text);
+        this._updateHistMsg(entry.hist, d.text, false);
+      }
+      this._markUnread();
+    }
+  }
+
+  /**
+   * A response closed (completed or cancelled).
+   * @param {{ responseId: string; status: string; audible?: boolean; transcript?: string }} detail
+   */
+  onResponseFinished(detail) {
+    const { responseId, status, audible, transcript } = detail;
+    if (DEBUG) console.debug(`[ui] response-finished resp=${responseId} status=${status} audible=${audible} known=${this._asstByResp.has(responseId)}`);
+    // Without an id we can't target a specific response; the bubble will
+    // auto-dismiss on its own timer regardless.
+    if (!responseId) return;
+    const entry = this._asstByResp.get(responseId);
+
+    if (status === "cancelled") {
+      // Keep every transcript that was received — mark it interrupted rather
+      // than erasing it. If the `*.transcript.done` never fired, build the row
+      // from the text carried in response.done.
+      let hist = entry?.hist ?? null;
+      if (!hist && transcript) {
+        hist = this._appendHistMsg("assistant", transcript, false);
+      } else if (hist && transcript) {
+        this._updateHistMsg(hist, transcript, false);
+      }
+      if (hist) this._markHistInterrupted(hist);
+      this._asstByResp.delete(responseId);
+      return;
+    }
+
+    // Any other terminal close (completed / failed / incomplete / …): just
+    // release the map entry. The bubble already auto-dismisses on its timer and
+    // the history row persists as the conversation log. Crucially we do NOT
+    // touch user state here — that lifecycle is fully independent.
+    this._asstByResp.delete(responseId);
+  }
+
+  /** The model called a tool — show an ephemeral "running" bubble.
+   *  @param {string} name */
+  onToolCall(name) {
+    this._bumpDismiss(this._spawnBubble("tool", name));
+    this._markUnread();
+  }
+
+  /** The tool finished — append its call+result row (and any captured image).
+   *  @param {string} name @param {string} argsJson @param {string} output @param {string} [image] */
+  onToolResult(name, argsJson, output, image) {
+    this._appendHistTool(name, argsJson, output);
+    if (image) this._appendHistImage(image); // show the captured frame below the call
+    this._markUnread();
+  }
+}

public/voice-demo/ui/dom.js

@@ -0,0 +1,37 @@
+// @ts-check
+/** Small shared helpers used across the UI modules: a strict query selector,
+ *  HTML escaping for text we drop into innerHTML, error-string trimming, and
+ *  the opt-in debug flag. */
+
+/** Opt-in tracing: `localStorage.setItem("s2s.debug", "1")` then reload. */
+export const DEBUG = (() => {
+  try {
+    return localStorage.getItem("s2s.debug") === "1";
+  } catch {
+    return false;
+  }
+})();
+
+/**
+ * Query a single element, throwing if it's missing (so a broken selector fails
+ * loudly at startup rather than as a later null-deref).
+ * @template {HTMLElement} T
+ * @param {string} selector
+ * @returns {T}
+ */
+export function $(selector) {
+  const el = document.querySelector(selector);
+  if (!el) throw new Error(`Missing element: ${selector}`);
+  return /** @type {T} */ (el);
+}
+
+/** @param {string} s @returns {string} */
+export function escHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Trim a long error message to fit the orb caption. @param {string} text */
+export function truncateError(text) {
+  if (text.length <= 90) return text;
+  return text.slice(0, 87) + "…";
+}

public/voice-demo/worklets/audio-playback.js

@@ -0,0 +1,211 @@
+// @ts-check
+/**
+ * AudioWorkletProcessor that plays back Float32 mono samples received from
+ * the main thread, upsampling whatever incoming rate the server uses
+ * (typically 16 kHz PCM16) to the AudioContext rate (typically 48 kHz).
+ *
+ * Lifecycle / messaging:
+ *
+ *   main -> worklet:
+ *     { kind: "config", inputRate: 16000, muted: false }  one-shot at startup
+ *     { kind: "audio", samples: Float32Array }             per chunk
+ *     { kind: "clear" }                                    wipe queue (barge-in)
+ *
+ *   worklet -> main:
+ *     { kind: "stats", queuedMs, played }                  every ~250 ms
+ *     { kind: "underrun" }                                 every time the queue
+ *                                                          runs dry mid-playback
+ *
+ * `muted` (default false): the Live Avatar (LiveTalking WebRTC) carries the
+ * same audio, so the page mutes its own playback to avoid double audio. When
+ * the avatar is NOT running (e.g. dev on macOS), keep muted=false so the page
+ * plays the backend audio itself.
+ *
+ * IMPORTANT: the read position only advances while audio is actually being
+ * played (`_playing`). Advancing during idle would drift `_readIdx` far past
+ * the next chunk's length and turn every read into NaN (silence) once audio
+ * arrives.
+ */
+
+const STATS_INTERVAL_FRAMES = 12000;
+const FADE_FRAMES = 32;
+
+class AudioPlaybackProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this._inputRate = 16000;
+    this._stepRatio = this._inputRate / sampleRate;
+    this._muted = false;
+    this._queue = [];
+    this._readIdx = 0;
+    this._fracPos = 0;
+    this._playing = false;
+    this._lastSample = 0;
+    this._framesSinceStats = 0;
+    this._totalPlayed = 0;
+    this._dbgReceived = 0;
+    this._dbgOutPeak = 0;
+    this._fadeIn = 0;
+    this._fadeOut = 0;
+
+    this.port.onmessage = (e) => {
+      const data = e.data;
+      if (!data || typeof data !== "object") return;
+      switch (data.kind) {
+        case "config":
+          if (typeof data.inputRate === "number" && data.inputRate > 0) {
+            this._inputRate = data.inputRate;
+            this._stepRatio = this._inputRate / sampleRate;
+          }
+          if (typeof data.muted === "boolean") this._muted = data.muted;
+          break;
+        case "audio": {
+          // Accept Float32Array, a transferred ArrayBuffer, or a plain
+          // {buffer, byteOffset, length} descriptor: cross-realm structured
+          // cloning can deliver the samples in any of these shapes.
+          let arr = data.samples;
+          let f32 = null;
+          if (arr instanceof Float32Array) {
+            f32 = arr;
+          } else if (arr instanceof ArrayBuffer) {
+            f32 = new Float32Array(arr);
+          } else if (arr && typeof arr === "object" && arr.buffer instanceof ArrayBuffer) {
+            f32 = new Float32Array(arr.buffer, arr.byteOffset || 0, (arr.byteLength || arr.buffer.byteLength) >> 2);
+          }
+          if (f32 && f32.length > 0) {
+            this._queue.push(f32);
+            this._dbgReceived += 1;
+            if (!this._playing) {
+              this._playing = true;
+              this._fadeIn = FADE_FRAMES;
+              this._fadeOut = 0;
+            }
+          }
+          break;
+        }
+        case "clear":
+          this._queue.length = 0;
+          this._readIdx = 0;
+          this._fracPos = 0;
+          this._playing = false;
+          this._lastSample = 0;
+          this._fadeOut = FADE_FRAMES;
+          break;
+      }
+    };
+  }
+
+  _queuedSamples() {
+    let total = -this._readIdx;
+    for (const buf of this._queue) total += buf.length;
+    return Math.max(0, total);
+  }
+
+  /** Linear-interp read at the current fractional position. */
+  _readInterpolated() {
+    if (this._queue.length === 0) return null;
+    const head = this._queue[0];
+    const idx = this._readIdx;
+    const frac = this._fracPos;
+
+    let a = head[idx];
+    let b;
+    if (idx + 1 < head.length) {
+      b = head[idx + 1];
+    } else if (this._queue.length > 1) {
+      b = this._queue[1][0];
+    } else {
+      b = a;
+    }
+    return a + (b - a) * frac;
+  }
+
+  /** Advance the read position by `stepRatio`; pop consumed buffers. */
+  _advance() {
+    this._fracPos += this._stepRatio;
+    while (this._fracPos >= 1) {
+      this._fracPos -= 1;
+      this._readIdx += 1;
+    }
+    while (this._queue.length > 0 && this._readIdx >= this._queue[0].length) {
+      this._readIdx -= this._queue[0].length;
+      this._queue.shift();
+    }
+  }
+
+  process(_, outputs) {
+    const channels = outputs[0];
+    if (!channels || channels.length === 0) return true;
+    const out = channels[0];
+    const stereo = channels.length > 1 ? channels[1] : null;
+
+    // Muted mode (Live Avatar WebRTC carries the audio): output silence.
+    if (this._muted) {
+      for (let i = 0; i < out.length; i++) {
+        out[i] = 0;
+        if (stereo) stereo[i] = 0;
+      }
+      this._framesSinceStats += out.length;
+      return true;
+    }
+
+    for (let i = 0; i < out.length; i++) {
+      let sample = 0;
+
+      if (this._playing) {
+        const v = this._readInterpolated();
+        if (v === null) {
+          // Underrun: ramp out cleanly to avoid clicks.
+          sample = this._lastSample * Math.max(0, 1 - 1 / FADE_FRAMES);
+          this._lastSample = sample;
+          if (Math.abs(sample) < 1e-4) {
+            this._playing = false;
+            this._lastSample = 0;
+            this.port.postMessage({ kind: "underrun" });
+          }
+        } else {
+          sample = v;
+          this._lastSample = v;
+          this._advance();
+        }
+
+        if (this._fadeIn > 0) {
+          const gain = 1 - this._fadeIn / FADE_FRAMES;
+          sample *= gain;
+          this._fadeIn -= 1;
+        }
+        if (this._fadeOut > 0) {
+          const gain = this._fadeOut / FADE_FRAMES;
+          sample *= gain;
+          this._fadeOut -= 1;
+          if (this._fadeOut === 0) {
+            this._playing = false;
+            this._lastSample = 0;
+          }
+        }
+
+        this._totalPlayed += 1;
+        const abs = sample < 0 ? -sample : sample;
+        if (abs > this._dbgOutPeak) this._dbgOutPeak = abs;
+      }
+
+      out[i] = sample;
+      if (stereo) stereo[i] = sample;
+    }
+
+    this._framesSinceStats += out.length;
+    if (this._framesSinceStats >= STATS_INTERVAL_FRAMES) {
+      this.port.postMessage({
+        kind: "stats",
+        queuedMs: Math.round((this._queuedSamples() / this._inputRate) * 1000),
+        played: this._totalPlayed,
+        received: this._dbgReceived,
+        outPeak: this._dbgOutPeak,
+      });
+      this._framesSinceStats = 0;
+    }
+    return true;
+  }
+}
+
+registerProcessor("audio-playback", AudioPlaybackProcessor);

public/voice-demo/worklets/mic-capture.js

@@ -0,0 +1,159 @@
+// @ts-check
+/**
+ * AudioWorkletProcessor that resamples the AudioContext rate (typically 48 kHz)
+ * down to 16 kHz, packs the result as little-endian Int16 PCM, and posts it
+ * back to the main thread in fixed-size chunks.
+ *
+ * The Hugging Face speech-to-speech WebSocket route expects the
+ * `input_audio_buffer.append` payload at 16 kHz PCM16 mono.
+ *
+ * Design notes:
+ *   - 48 -> 16 is an exact 3:1 ratio so we use a 3-tap boxcar average as a
+ *     cheap low-pass before decimating. Good enough for voice STT; we lose
+ *     a tiny bit of >8 kHz content which the pipeline discards anyway.
+ *   - Output frames are emitted at the cadence dictated by `chunkMs`
+ *     (default 40 ms = 640 samples = 1280 bytes). The OpenAI Realtime
+ *     server batches incoming audio so the cadence is flexible; 20-100 ms
+ *     is the sweet spot.
+ *   - Float -> Int16 saturates to [-1, 1] before scaling.
+ *   - Optional noise gate: per-chunk RMS decides open/closed against a
+ *     threshold; the gain ramps (fast attack, hold, slow release) so word
+ *     onsets aren't clipped and quiet tails don't click. The gate only
+ *     affects the audio we SEND; the main-thread visualiser taps the raw
+ *     mic separately. We post the chunk RMS up every frame so the Settings
+ *     mic meter can show the live level against the threshold.
+ */
+
+const TARGET_RATE = 16000;
+const DEFAULT_CHUNK_MS = 40;
+// Gate envelope timing (fixed; only the threshold is user-tunable).
+const GATE_ATTACK_MS = 5; // open almost instantly so word onsets survive
+const GATE_HOLD_MS = 250; // stay open this long after the level drops back under
+const GATE_RELEASE_MS = 80; // then fade closed over this long (no click)
+
+class MicCaptureProcessor extends AudioWorkletProcessor {
+  constructor(options) {
+    super();
+    const chunkMs = options?.processorOptions?.chunkMs ?? DEFAULT_CHUNK_MS;
+    this._inputRate = sampleRate;
+    this._ratio = this._inputRate / TARGET_RATE;
+    this._chunkSamples16k = Math.round((TARGET_RATE * chunkMs) / 1000);
+    this._scratch = new Float32Array(0);
+    this._decimated = new Float32Array(this._chunkSamples16k);
+    this._enabled = true;
+
+    // Noise gate state. Disabled by default (pure passthrough).
+    this._gateEnabled = false;
+    this._thresholdLin = 0; // linear amplitude; signal RMS must exceed this to open
+    this._gateGain = 1; // smoothed gain currently applied
+    this._holdRemaining = 0; // samples left before the gate may start closing
+    this._attackCoef = Math.exp(-1 / ((GATE_ATTACK_MS / 1000) * TARGET_RATE));
+    this._releaseCoef = Math.exp(-1 / ((GATE_RELEASE_MS / 1000) * TARGET_RATE));
+    this._holdSamples = Math.round((GATE_HOLD_MS / 1000) * TARGET_RATE);
+
+    this.port.onmessage = (e) => {
+      const data = e.data;
+      if (data?.kind === "enable") this._enabled = !!data.value;
+      else if (data?.kind === "gate") {
+        this._gateEnabled = !!data.enabled;
+        // dB -> linear amplitude. When off, threshold 0 keeps the gate open.
+        this._thresholdLin = data.enabled ? Math.pow(10, data.thresholdDb / 20) : 0;
+      }
+    };
+  }
+
+  /**
+   * Append `incoming` to the internal scratch buffer, then emit as many
+   * full output chunks as we have material for.
+   * @param {Float32Array} incoming
+   */
+  _ingest(incoming) {
+    if (incoming.length === 0) return;
+    const next = new Float32Array(this._scratch.length + incoming.length);
+    next.set(this._scratch, 0);
+    next.set(incoming, this._scratch.length);
+    this._scratch = next;
+    this._maybeEmit();
+  }
+
+  _maybeEmit() {
+    const r = this._ratio;
+    const n = this._chunkSamples16k;
+    const needIn = Math.ceil(n * r);
+    const dec = this._decimated;
+    while (this._scratch.length >= needIn) {
+      // 1. Decimate to 16 kHz floats and accumulate energy for the gate/meter.
+      let sumSq = 0;
+      if (Math.abs(r - 3) < 1e-6) {
+        // 48 kHz -> 16 kHz fast path with boxcar lowpass.
+        for (let i = 0; i < n; i++) {
+          const idx = i * 3;
+          const s = (this._scratch[idx] + this._scratch[idx + 1] + this._scratch[idx + 2]) / 3;
+          dec[i] = s;
+          sumSq += s * s;
+        }
+      } else {
+        // Generic path: linear interpolation. Slower but works at any rate
+        // (e.g. some Windows boxes report sampleRate=44100).
+        for (let i = 0; i < n; i++) {
+          const srcPos = i * r;
+          const idx = Math.floor(srcPos);
+          const frac = srcPos - idx;
+          const a = this._scratch[idx];
+          const b = this._scratch[idx + 1] ?? a;
+          const s = a + (b - a) * frac;
+          dec[i] = s;
+          sumSq += s * s;
+        }
+      }
+      const rms = Math.sqrt(sumSq / n);
+
+      // 2. Decide the gate target for this chunk, then ramp sample-by-sample.
+      let target = 1;
+      if (this._gateEnabled) {
+        if (rms >= this._thresholdLin) {
+          this._holdRemaining = this._holdSamples; // re-arm the hold
+        } else if (this._holdRemaining > 0) {
+          this._holdRemaining -= n; // coasting through the hold window
+        } else {
+          target = 0;
+        }
+      }
+
+      // 3. Apply the (smoothed) gain and pack to Int16.
+      const out = new Int16Array(n);
+      let gain = this._gateGain;
+      for (let i = 0; i < n; i++) {
+        const coef = target > gain ? this._attackCoef : this._releaseCoef;
+        gain = target + (gain - target) * coef;
+        const s = dec[i] * gain;
+        const clamped = s < -1 ? -1 : s > 1 ? 1 : s;
+        out[i] = clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff;
+      }
+      this._gateGain = gain;
+
+      // Shift the scratch buffer to keep only the trailing unused samples.
+      const consumed = Math.floor(n * r);
+      this._scratch = this._scratch.slice(consumed);
+
+      // Live input level for the Settings meter (raw RMS, pre-gate).
+      this.port.postMessage({ kind: "level", rms });
+
+      if (this._enabled) {
+        this.port.postMessage(out.buffer, [out.buffer]);
+      }
+      // When disabled (mic muted) we silently consume input so the worklet
+      // stays alive and the buffer never grows unbounded.
+    }
+  }
+
+  process(inputs) {
+    const input = inputs[0];
+    if (!input || input.length === 0 || !input[0]) return true;
+    const mono = input[0];
+    if (mono.length > 0) this._ingest(mono);
+    return true;
+  }
+}
+
+registerProcessor("mic-capture", MicCaptureProcessor);

public/voice-demo/ws/codec.js

@@ -0,0 +1,57 @@
+// @ts-check
+/**
+ * Pure, stateless helpers for the WebSocket realtime client: base64 <-> PCM
+ * conversion for the audio frames on the wire, transcript extraction from a
+ * `response.done` payload, and a tiny URL helper. Kept separate from the client
+ * so the protocol/state logic stays readable.
+ */
+
+/** @param {string} url */
+export function trimTrailingSlash(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+/**
+ * Pull the assistant transcript out of a `response.done` payload. The text
+ * lives in `response.output[].content[].transcript` (audio) or `.text`. Used as
+ * the source of truth for interrupted replies, where the dedicated
+ * `*.transcript.done` event may never arrive.
+ * @param {any} response
+ * @returns {string}
+ */
+export function extractResponseTranscript(response) {
+  const output = response?.output;
+  if (!Array.isArray(output)) return "";
+  /** @type {string[]} */
+  const parts = [];
+  for (const item of output) {
+    for (const part of item?.content ?? []) {
+      const text = part?.transcript ?? part?.text;
+      if (typeof text === "string" && text.trim()) parts.push(text.trim());
+    }
+  }
+  return parts.join(" ").trim();
+}
+
+/** @param {ArrayBuffer} buf */
+export function base64FromArrayBuffer(buf) {
+  const bytes = new Uint8Array(buf);
+  // Chunked encoding so we don't blow up the call stack on long buffers.
+  let binary = "";
+  const chunk = 0x8000;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode.apply(null, /** @type {number[]} */ (
+      /** @type {unknown} */ (bytes.subarray(i, i + chunk))
+    ));
+  }
+  return btoa(binary);
+}
+
+/** @param {string} b64 */
+export function base64ToBytes(b64) {
+  const binary = atob(b64);
+  const len = binary.length;
+  const out = new Uint8Array(len);
+  for (let i = 0; i < len; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}

public/voice-demo/ws/orb-visualizer.js

@@ -0,0 +1,98 @@
+// @ts-check
+/**
+ * Orb spectrum visualiser. Each animation frame it reads two AnalyserNodes (the
+ * mic input and the TTS output) and maps the low-frequency speech energy onto
+ * the orb's CSS custom properties:
+ *   - `--bar0`..`--bar4`   the 5-band level meter
+ *   - `--ai-audio-level`   the global "Reachy talks" glow / scale pulse
+ *
+ * The bottom of the FFT is where speech energy lives, so the band edges stay
+ * low — that keeps the bars dancing on voice rather than on noise. While the AI
+ * is speaking we source the bars from the OUTPUT analyser so the orb pulses with
+ * Reachy's voice instead of sitting dead while the user is silent.
+ */
+
+// Exported so the client can size its AnalyserNodes to match our buffer.
+export const VIS_FFT_SIZE = 256;
+const VIS_BAND_COUNT = 5;
+const VIS_BAND_EDGES = [2, 5, 9, 16, 28, 52];
+const VIS_ATTACK = 0.6; // weight for new sample on upswing (snappy)
+const VIS_RELEASE = 0.18; // weight for new sample on decay (gentle fade)
+
+export class OrbVisualiser {
+  /**
+   * @param {AnalyserNode} micAnalyser
+   * @param {AnalyserNode} outAnalyser
+   * @param {() => boolean} isAiSpeaking Source the bars from the AI output when
+   *   true, otherwise from the mic.
+   */
+  constructor(micAnalyser, outAnalyser, isAiSpeaking) {
+    this._mic = micAnalyser;
+    this._out = outAnalyser;
+    this._isAiSpeaking = isAiSpeaking;
+    this._buf = new Uint8Array(micAnalyser.frequencyBinCount);
+    this._bands = new Float32Array(VIS_BAND_COUNT);
+    this._aiLevel = 0;
+    /** @type {number | null} */
+    this._frame = null;
+  }
+
+  /** Begin the rAF loop (idempotent). */
+  start() {
+    if (this._frame !== null) return;
+    const root = document.documentElement;
+    const tick = () => {
+      this._frame = requestAnimationFrame(tick);
+      this._update(root);
+    };
+    this._frame = requestAnimationFrame(tick);
+  }
+
+  /** Stop the loop and clear the CSS vars so the orb returns to rest. */
+  stop() {
+    if (this._frame !== null) {
+      cancelAnimationFrame(this._frame);
+      this._frame = null;
+    }
+    const root = document.documentElement;
+    for (let i = 0; i < VIS_BAND_COUNT; i++) root.style.removeProperty(`--bar${i}`);
+    root.style.removeProperty("--ai-audio-level");
+  }
+
+  /** @param {HTMLElement} root */
+  _update(root) {
+    // Mic bars: split FFT into 5 log-ish bands, smooth, write CSS vars.
+    const source = this._isAiSpeaking() ? this._out : this._mic;
+    source.getByteFrequencyData(this._buf);
+
+    for (let b = 0; b < VIS_BAND_COUNT; b++) {
+      const lo = VIS_BAND_EDGES[b];
+      const hi = VIS_BAND_EDGES[b + 1];
+      let sum = 0;
+      let n = 0;
+      for (let i = lo; i < hi && i < this._buf.length; i++) {
+        sum += this._buf[i];
+        n += 1;
+      }
+      const target = n > 0 ? sum / (n * 255) : 0;
+      const prev = this._bands[b];
+      const k = target > prev ? VIS_ATTACK : VIS_RELEASE;
+      const next = prev + (target - prev) * k;
+      this._bands[b] = next;
+      root.style.setProperty(`--bar${b}`, next.toFixed(3));
+    }
+
+    // Global AI audio level: peak of the output analyser, used by the CSS to
+    // make the orb's glow / scale react to Reachy's voice.
+    this._out.getByteFrequencyData(this._buf);
+    let peak = 0;
+    const limit = Math.min(this._buf.length, VIS_BAND_EDGES[VIS_BAND_COUNT]);
+    for (let i = 0; i < limit; i++) {
+      if (this._buf[i] > peak) peak = this._buf[i];
+    }
+    const aiTarget = peak / 255;
+    const k = aiTarget > this._aiLevel ? VIS_ATTACK : VIS_RELEASE;
+    this._aiLevel = this._aiLevel + (aiTarget - this._aiLevel) * k;
+    root.style.setProperty("--ai-audio-level", this._aiLevel.toFixed(3));
+  }
+}