@oshara/voice-sdk 0.1.0

package/src/ui/ui.ts

@@ -0,0 +1,1672 @@
+import { AppearanceConfig, AppearanceLanguage, DEFAULT_APPEARANCE } from "../core/appearance";
+import {
+  FormDefinition,
+  FormFieldDef,
+  FormFieldOption,
+  fieldsForStep,
+  totalSteps,
+} from "../core/forms";
+import stylesheet from "./styles.css?inline";
+
+export interface FormInputBinding {
+  /** Read the current field value as a string (comma-joined for multi-select groups). */
+  read: () => string;
+  /** Toggle the disabled state across one or more underlying inputs. */
+  setDisabled: (busy: boolean) => void;
+  /** Show (or, with an empty string, clear) an inline validation error under the field. */
+  setError: (message: string) => void;
+}
+
+export type Screen = "welcome" | "call" | "form";
+
+export interface UIRefs {
+  host: HTMLDivElement;
+  shadow: ShadowRoot;
+  fab: HTMLButtonElement;
+  panel: HTMLDivElement;
+  closeBtn: HTMLButtonElement;
+
+  welcomeScreen: HTMLDivElement;
+  welcomeLogo: HTMLImageElement;
+  welcomeLogoFallback: HTMLDivElement;
+  welcomeName: HTMLDivElement;
+  welcomeDesc: HTMLDivElement;
+  langPicker: HTMLDivElement;
+  langTrigger: HTMLButtonElement;
+  langTriggerLabel: HTMLSpanElement;
+  langTriggerCode: HTMLSpanElement;
+  langMenu: HTMLDivElement;
+  startBtn: HTMLButtonElement;
+  startBtnLabel: HTMLSpanElement;
+  consent: HTMLDivElement;
+  consentText: HTMLSpanElement;
+  consentLink: HTMLAnchorElement;
+  poweredBy: HTMLAnchorElement;
+  /** Currently selected language code (BCP-47 short, e.g. "en"). */
+  selectedLanguage: string;
+
+  callScreen: HTMLDivElement;
+  callLogo: HTMLImageElement;
+  callLogoFallback: HTMLDivElement;
+  callName: HTMLDivElement;
+  callStatus: HTMLDivElement;
+  callTimer: HTMLDivElement;
+  callTimerText: HTMLSpanElement;
+  orb: HTMLDivElement;
+  orbLabel: HTMLDivElement;
+  /** Contextual processing line under the orb ("Searching the knowledge base…"). */
+  agentStatusLine: HTMLDivElement;
+  transcript: HTMLDivElement;
+  transcriptSegments: Map<string, HTMLDivElement>;
+  /**
+   * Per-role pointer to the bubble that is still in `interim` state. Used to
+   * coalesce streaming + final segments when the STT backend emits different
+   * `seg.id`s for interim vs final (e.g. sherpa), which would otherwise leave
+   * the half-finished interim bubble onscreen alongside a new final bubble.
+   */
+  transcriptInterimBubble: Map<"user" | "agent", HTMLDivElement>;
+  textInputRow: HTMLDivElement;
+  textInput: HTMLTextAreaElement;
+  textSendBtn: HTMLButtonElement;
+  muteBtn: HTMLButtonElement;
+  endBtn: HTMLButtonElement;
+  settingsBtn: HTMLButtonElement;
+
+  audioDrawer: HTMLDivElement;
+  audioDrawerClose: HTMLButtonElement;
+  audioMeterBar: HTMLDivElement;
+  audioMicSelect: HTMLSelectElement;
+  audioSpeakerSelect: HTMLSelectElement;
+  audioSpeakerRow: HTMLLabelElement;
+  audioVolume: HTMLInputElement;
+  audioVolumeValue: HTMLSpanElement;
+  audioNcEngine: HTMLSelectElement;
+  audioDfStrengthRow: HTMLLabelElement;
+  audioDfStrength: HTMLInputElement;
+  audioDfStrengthValue: HTMLSpanElement;
+  audioTogAec: HTMLInputElement;
+  audioTogNs: HTMLInputElement;
+  audioTogAgc: HTMLInputElement;
+  audioTogVi: HTMLInputElement;
+  audioTogViRow: HTMLLabelElement;
+  audioTogHp: HTMLInputElement;
+  audioTogTranscription: HTMLInputElement;
+  audioTogTextInput: HTMLInputElement;
+  audioDiagEngine: HTMLElement;
+  audioDiagAec: HTMLElement;
+  audioDiagNs: HTMLElement;
+  audioDiagAgc: HTMLElement;
+  audioDiagVi: HTMLElement;
+  audioDiagSr: HTMLElement;
+  audioDiagLoss: HTMLElement;
+  audioDiagJitter: HTMLElement;
+  audioDiagRtt: HTMLElement;
+
+  formScreen: HTMLDivElement;
+  formTranscript: HTMLDivElement;
+  formTranscriptSegments: Map<string, HTMLDivElement>;
+  formTranscriptInterimBubble: Map<"user" | "agent", HTMLDivElement>;
+  formTitle: HTMLDivElement;
+  formEyebrow: HTMLDivElement;
+  formSubtitle: HTMLDivElement;
+  formStepper: HTMLDivElement;
+  formFields: HTMLDivElement;
+  formError: HTMLDivElement;
+  formSuccess: HTMLDivElement;
+  formSubmitBtn: HTMLButtonElement;
+  formBackBtn: HTMLButtonElement;
+  formCancelBtn: HTMLButtonElement;
+  formStepBackBtn: HTMLButtonElement;
+  formCallControls: HTMLDivElement;
+  formMuteBtn: HTMLButtonElement;
+  formEndBtn: HTMLButtonElement;
+  formInputs: Map<string, FormInputBinding>;
+
+  appearance: AppearanceConfig;
+}
+
+const ICON_FAB = `
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 1a3 3 0 0 0-3 3v8a3 3 0 0 0 6 0V4a3 3 0 0 0-3-3z"/>
+  <path d="M19 10v2a7 7 0 0 1-14 0v-2"/>
+  <line x1="12" y1="19" x2="12" y2="23"/>
+  <line x1="8" y1="23" x2="16" y2="23"/>
+</svg>`;
+
+const ICON_CLOSE = `
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.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>`;
+
+const ICON_PHONE = `
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72c.13.96.37 1.9.72 2.81a2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45c.91.35 1.85.59 2.81.72A2 2 0 0 1 22 16.92z"/>
+</svg>`;
+
+const ICON_MIC_ON = `
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M12 1a3 3 0 0 0-3 3v8a3 3 0 0 0 6 0V4a3 3 0 0 0-3-3z"/>
+  <path d="M19 10v2a7 7 0 0 1-14 0v-2"/>
+  <line x1="12" y1="19" x2="12" y2="23"/>
+  <line x1="8" y1="23" x2="16" y2="23"/>
+</svg>`;
+
+const ICON_MIC_OFF = `
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <line x1="1" y1="1" x2="23" y2="23"/>
+  <path d="M9 9v3a3 3 0 0 0 5.12 2.12M15 9.34V4a3 3 0 0 0-5.94-.6"/>
+  <path d="M17 16.95A7 7 0 0 1 5 12v-2m14 0v2a7 7 0 0 1-.11 1.23"/>
+  <line x1="12" y1="19" x2="12" y2="23"/>
+  <line x1="8" y1="23" x2="16" y2="23"/>
+</svg>`;
+
+const ICON_HANGUP = `
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M10.68 13.31a16 16 0 0 0 3.41 2.6l1.27-1.27a2 2 0 0 1 2.11-.45 12.84 12.84 0 0 0 2.81.7 2 2 0 0 1 1.72 2v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.42 19.42 0 0 1-3.33-2.67m-2.67-3.34a19.79 19.79 0 0 1-3.07-8.63A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72 12.84 12.84 0 0 0 .7 2.81 2 2 0 0 1-.45 2.11L8.09 9.91"/>
+  <line x1="23" y1="1" x2="1" y2="23"/>
+</svg>`;
+
+const ICON_AGENT_FALLBACK = `
+<svg viewBox="0 0 24 24" fill="currentColor">
+  <path d="M12 2a4 4 0 0 0-4 4v2a4 4 0 0 0 8 0V6a4 4 0 0 0-4-4zm6 8a1 1 0 0 0-2 0 4 4 0 0 1-8 0 1 1 0 0 0-2 0 6 6 0 0 0 5 5.91V19H8a1 1 0 0 0 0 2h8a1 1 0 0 0 0-2h-3v-3.09A6 6 0 0 0 18 10z"/>
+</svg>`;
+
+const ICON_GLOBE = `
+<svg 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"/>
+  <path d="M3 12h18"/>
+  <path d="M12 3a13.5 13.5 0 0 1 0 18"/>
+  <path d="M12 3a13.5 13.5 0 0 0 0 18"/>
+</svg>`;
+
+const ICON_CHEVRON = `
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+  <polyline points="6 9 12 15 18 9"/>
+</svg>`;
+
+const ICON_CHECK = `
+<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round">
+  <polyline points="20 6 9 17 4 12"/>
+</svg>`;
+
+const ICON_SEND = `
+<svg 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>`;
+
+const ICON_SETTINGS = `
+<svg 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 0 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 0 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 0 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.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"/>
+</svg>`;
+
+export function buildUI(
+  rootId: string,
+  opts: {
+    inline?: boolean;
+    parent?: HTMLElement;
+    closeButtonHide?: boolean;
+  } = {},
+): UIRefs {
+  const host = document.createElement("div");
+  host.id = rootId;
+  if (opts.closeButtonHide) {
+    host.setAttribute("data-close-button-hide", "");
+  }
+  if (opts.inline) {
+    // Fill the embedding container (which must be a positioned ancestor)
+    // rather than floating in a viewport corner.
+    host.setAttribute("data-inline", "");
+    host.style.position = "absolute";
+    host.style.inset = "0";
+    host.style.zIndex = "1";
+  } else {
+    host.style.position = "fixed";
+    host.style.inset = "auto";
+    host.style.zIndex = "2147483647";
+  }
+  (opts.parent ?? document.body).appendChild(host);
+
+  const shadow = host.attachShadow({ mode: "open" });
+
+  const style = document.createElement("style");
+  style.textContent = stylesheet;
+  shadow.appendChild(style);
+
+  const fab = document.createElement("button");
+  fab.className = "fab";
+  fab.setAttribute("aria-label", "Open voice agent");
+  // Hidden until appearance has loaded — avoids a flash of defaults.
+  fab.style.visibility = "hidden";
+  fab.innerHTML = `
+    <span class="fab-icon">${ICON_FAB}</span>
+    <span class="fab-text">
+      <span class="fab-label"></span>
+      <span class="fab-sublabel"></span>
+    </span>
+  `;
+  shadow.appendChild(fab);
+
+  const panel = document.createElement("div");
+  panel.className = "panel";
+  panel.style.display = "none";
+  panel.innerHTML = `
+    <button class="close" aria-label="Close">${ICON_CLOSE}</button>
+
+    <section class="screen screen-welcome" data-screen="welcome">
+      <div class="welcome-inner">
+        <div class="welcome-logo">
+          <div class="welcome-logo-fallback">${ICON_AGENT_FALLBACK}</div>
+          <img class="welcome-logo-img" alt="" style="display:none" />
+        </div>
+        <div class="welcome-status"><span class="welcome-status-dot"></span><span class="welcome-status-text">Online</span></div>
+        <h1 class="welcome-name">Assistant</h1>
+        <p class="welcome-desc">Tap below to start a voice conversation.</p>
+        <div class="lang-picker" data-open="false">
+          <button class="lang-trigger" type="button" aria-haspopup="listbox" aria-expanded="false">
+            <span class="lang-trigger-icon">${ICON_GLOBE}</span>
+            <span class="lang-trigger-text">
+              <span class="lang-trigger-eyebrow">Language</span>
+              <span class="lang-trigger-label">English</span>
+            </span>
+            <span class="lang-trigger-code">EN</span>
+            <span class="lang-trigger-chev">${ICON_CHEVRON}</span>
+          </button>
+          <div class="lang-menu" role="listbox" hidden></div>
+        </div>
+        <button class="start-btn" aria-label="Start call">
+          <span class="start-btn-icon">${ICON_PHONE}</span>
+          <span class="start-btn-label">Start Call</span>
+        </button>
+        <div class="consent" hidden>
+          <span class="consent-text"></span>
+          <a class="consent-link" target="_blank" rel="noopener noreferrer"></a>
+        </div>
+      </div>
+      <a class="welcome-foot" target="_blank" rel="noopener noreferrer"></a>
+    </section>
+
+    <section class="screen screen-form" data-screen="form" style="display:none">
+      <header class="form-header">
+        <button class="form-back" type="button" aria-label="Back">${ICON_CHEVRON}</button>
+        <div class="form-header-text">
+          <div class="form-eyebrow">Review before submit</div>
+          <div class="form-title">Form</div>
+        </div>
+        <div class="form-call-controls" hidden>
+          <button class="form-mute" type="button" aria-label="Mute">${ICON_MIC_ON}</button>
+          <button class="form-end" type="button" aria-label="End call">${ICON_HANGUP}</button>
+        </div>
+      </header>
+      <div class="form-transcript" hidden aria-live="polite"></div>
+      <div class="form-stepper" hidden></div>
+      <div class="form-body">
+        <p class="form-subtitle"></p>
+        <div class="form-fields"></div>
+        <div class="form-error" hidden></div>
+        <div class="form-success" hidden></div>
+      </div>
+      <footer class="form-actions">
+        <button class="form-step-back" type="button" hidden>Back</button>
+        <button class="form-cancel" type="button">Cancel</button>
+        <button class="form-submit" type="button">
+          <span class="form-submit-label">Confirm &amp; send</span>
+        </button>
+      </footer>
+    </section>
+
+    <section class="screen screen-call" data-screen="call" style="display:none">
+      <header class="call-header">
+        <div class="call-id">
+          <div class="call-logo">
+            <div class="call-logo-fallback">${ICON_AGENT_FALLBACK}</div>
+            <img class="call-logo-img" alt="" style="display:none" />
+          </div>
+          <div class="call-id-text">
+            <div class="call-name">Assistant</div>
+            <div class="call-status">Connecting…</div>
+          </div>
+        </div>
+        <div class="call-timer" hidden aria-live="polite">
+          <span class="call-timer-text">0:00</span>
+        </div>
+      </header>
+
+      <div class="call-stage">
+        <div class="orb">
+          <span class="orb-ring orb-ring-1"></span>
+          <span class="orb-ring orb-ring-2"></span>
+          <span class="orb-ring orb-ring-3"></span>
+          <span class="orb-core"></span>
+        </div>
+        <div class="orb-label">Idle</div>
+        <div class="agent-status-line" aria-live="polite" hidden></div>
+      </div>
+
+      <div class="transcript" aria-live="polite" style="display: none;"></div>
+
+      <div class="text-input-row" hidden>
+        <textarea class="text-input" placeholder="Type a message…" rows="1" aria-label="Type a message"></textarea>
+        <button class="text-send-btn" type="button" aria-label="Send message">${ICON_SEND}</button>
+      </div>
+
+      <div class="call-controls">
+        <button class="ctl-btn ctl-mute" aria-label="Mute" disabled>
+          ${ICON_MIC_ON}
+        </button>
+        <button class="ctl-btn ctl-settings" aria-label="Audio settings" hidden>
+          ${ICON_SETTINGS}
+        </button>
+        <button class="ctl-btn ctl-end" aria-label="End call" disabled>
+          ${ICON_HANGUP}
+        </button>
+      </div>
+
+      <div class="audio-drawer" hidden aria-label="Audio settings">
+        <header class="audio-drawer-head">
+          <div class="audio-drawer-title">Audio settings</div>
+          <button class="audio-drawer-close" type="button" aria-label="Close audio settings">${ICON_CLOSE}</button>
+        </header>
+        <div class="audio-drawer-body">
+          <div class="audio-row audio-row-meter">
+            <span class="audio-row-label">Microphone level</span>
+            <div class="audio-meter"><div class="audio-meter-bar"></div></div>
+          </div>
+          <label class="audio-row audio-row-select">
+            <span class="audio-row-label">Microphone</span>
+            <select class="audio-mic-select"></select>
+          </label>
+          <label class="audio-row audio-row-select audio-row-speaker">
+            <span class="audio-row-label">Speaker</span>
+            <select class="audio-speaker-select"></select>
+          </label>
+          <label class="audio-row audio-row-slider">
+            <span class="audio-row-label">Speaker volume <span class="audio-volume-value">85%</span></span>
+            <input class="audio-volume" type="range" min="0" max="100" step="1" value="85" />
+          </label>
+          <label class="audio-row audio-row-select">
+            <span class="audio-row-label">Noise cancellation engine</span>
+            <select class="audio-nc-engine">
+              <option value="off">Off (browser only)</option>
+              <option value="krisp">Krisp (default)</option>
+              <option value="deepfilter">DeepFilterNet3</option>
+            </select>
+          </label>
+          <label class="audio-row audio-row-slider audio-row-df-strength" hidden>
+            <span class="audio-row-label">DeepFilter strength <span class="audio-df-strength-value">80</span></span>
+            <input class="audio-df-strength" type="range" min="0" max="100" step="1" value="80" />
+          </label>
+          <div class="audio-toggles">
+            <label class="audio-toggle">
+              <span class="audio-toggle-text">
+                <span class="audio-toggle-label">Echo cancellation</span>
+                <span class="audio-toggle-hint">Browser AEC</span>
+              </span>
+              <input class="audio-tog-aec" type="checkbox" />
+            </label>
+            <label class="audio-toggle">
+              <span class="audio-toggle-text">
+                <span class="audio-toggle-label">Noise suppression</span>
+                <span class="audio-toggle-hint">Browser noise filter</span>
+              </span>
+              <input class="audio-tog-ns" type="checkbox" />
+            </label>
+            <label class="audio-toggle">
+              <span class="audio-toggle-text">
+                <span class="audio-toggle-label">Auto gain</span>
+                <span class="audio-toggle-hint">Normalize my volume</span>
+              </span>
+              <input class="audio-tog-agc" type="checkbox" />
+            </label>
+            <label class="audio-toggle audio-toggle-vi">
+              <span class="audio-toggle-text">
+                <span class="audio-toggle-label">Voice isolation</span>
+                <span class="audio-toggle-hint">Edge/Chrome only</span>
+              </span>
+              <input class="audio-tog-vi" type="checkbox" />
+            </label>
+            <label class="audio-toggle">
+              <span class="audio-toggle-text">
+                <span class="audio-toggle-label">Headphones mode</span>
+                <span class="audio-toggle-hint">Disable mic ducking</span>
+              </span>
+              <input class="audio-tog-hp" type="checkbox" />
+            </label>
+            <label class="audio-toggle">
+              <span class="audio-toggle-text">
+                <span class="audio-toggle-label">Live Transcription</span>
+                <span class="audio-toggle-hint">Show conversation text</span>
+              </span>
+              <input class="audio-tog-transcription" type="checkbox" />
+            </label>
+            <label class="audio-toggle">
+              <span class="audio-toggle-text">
+                <span class="audio-toggle-label">Text Input</span>
+                <span class="audio-toggle-hint">Type messages to the agent</span>
+              </span>
+              <input class="audio-tog-text-input" type="checkbox" />
+            </label>
+          </div>
+          <details class="audio-diag">
+            <summary>Diagnostics</summary>
+            <dl class="audio-diag-list">
+              <dt>NC engine</dt><dd class="audio-diag-engine">—</dd>
+              <dt>Echo cancellation</dt><dd class="audio-diag-aec">—</dd>
+              <dt>Noise suppression</dt><dd class="audio-diag-ns">—</dd>
+              <dt>Auto gain</dt><dd class="audio-diag-agc">—</dd>
+              <dt>Voice isolation</dt><dd class="audio-diag-vi">—</dd>
+              <dt>Sample rate</dt><dd class="audio-diag-sr">—</dd>
+              <dt>Packet loss</dt><dd class="audio-diag-loss">—</dd>
+              <dt>Jitter</dt><dd class="audio-diag-jitter">—</dd>
+              <dt>RTT</dt><dd class="audio-diag-rtt">—</dd>
+            </dl>
+          </details>
+        </div>
+      </div>
+    </section>
+  `;
+  shadow.appendChild(panel);
+
+  const q = <T extends Element>(sel: string) => panel.querySelector(sel) as T;
+
+  return {
+    host,
+    shadow,
+    fab,
+    panel,
+    closeBtn: q<HTMLButtonElement>(".close"),
+
+    welcomeScreen: q<HTMLDivElement>(".screen-welcome"),
+    welcomeLogo: q<HTMLImageElement>(".welcome-logo-img"),
+    welcomeLogoFallback: q<HTMLDivElement>(".welcome-logo-fallback"),
+    welcomeName: q<HTMLDivElement>(".welcome-name"),
+    welcomeDesc: q<HTMLDivElement>(".welcome-desc"),
+    langPicker: q<HTMLDivElement>(".lang-picker"),
+    langTrigger: q<HTMLButtonElement>(".lang-trigger"),
+    langTriggerLabel: q<HTMLSpanElement>(".lang-trigger-label"),
+    langTriggerCode: q<HTMLSpanElement>(".lang-trigger-code"),
+    langMenu: q<HTMLDivElement>(".lang-menu"),
+    startBtn: q<HTMLButtonElement>(".start-btn"),
+    startBtnLabel: q<HTMLSpanElement>(".start-btn-label"),
+    consent: q<HTMLDivElement>(".consent"),
+    consentText: q<HTMLSpanElement>(".consent-text"),
+    consentLink: q<HTMLAnchorElement>(".consent-link"),
+    poweredBy: q<HTMLAnchorElement>(".welcome-foot"),
+
+    callScreen: q<HTMLDivElement>(".screen-call"),
+    callLogo: q<HTMLImageElement>(".call-logo-img"),
+    callLogoFallback: q<HTMLDivElement>(".call-logo-fallback"),
+    callName: q<HTMLDivElement>(".call-name"),
+    callStatus: q<HTMLDivElement>(".call-status"),
+    callTimer: q<HTMLDivElement>(".call-timer"),
+    callTimerText: q<HTMLSpanElement>(".call-timer-text"),
+    orb: q<HTMLDivElement>(".orb"),
+    orbLabel: q<HTMLDivElement>(".orb-label"),
+    agentStatusLine: q<HTMLDivElement>(".agent-status-line"),
+    transcript: q<HTMLDivElement>(".transcript"),
+    transcriptSegments: new Map<string, HTMLDivElement>(),
+    transcriptInterimBubble: new Map<"user" | "agent", HTMLDivElement>(),
+    textInputRow: q<HTMLDivElement>(".text-input-row"),
+    textInput: q<HTMLTextAreaElement>(".text-input"),
+    textSendBtn: q<HTMLButtonElement>(".text-send-btn"),
+    muteBtn: q<HTMLButtonElement>(".ctl-mute"),
+    endBtn: q<HTMLButtonElement>(".ctl-end"),
+    settingsBtn: q<HTMLButtonElement>(".ctl-settings"),
+
+    audioDrawer: q<HTMLDivElement>(".audio-drawer"),
+    audioDrawerClose: q<HTMLButtonElement>(".audio-drawer-close"),
+    audioMeterBar: q<HTMLDivElement>(".audio-meter-bar"),
+    audioMicSelect: q<HTMLSelectElement>(".audio-mic-select"),
+    audioSpeakerSelect: q<HTMLSelectElement>(".audio-speaker-select"),
+    audioSpeakerRow: q<HTMLLabelElement>(".audio-row-speaker"),
+    audioVolume: q<HTMLInputElement>(".audio-volume"),
+    audioVolumeValue: q<HTMLSpanElement>(".audio-volume-value"),
+    audioNcEngine: q<HTMLSelectElement>(".audio-nc-engine"),
+    audioDfStrengthRow: q<HTMLLabelElement>(".audio-row-df-strength"),
+    audioDfStrength: q<HTMLInputElement>(".audio-df-strength"),
+    audioDfStrengthValue: q<HTMLSpanElement>(".audio-df-strength-value"),
+    audioTogAec: q<HTMLInputElement>(".audio-tog-aec"),
+    audioTogNs: q<HTMLInputElement>(".audio-tog-ns"),
+    audioTogAgc: q<HTMLInputElement>(".audio-tog-agc"),
+    audioTogVi: q<HTMLInputElement>(".audio-tog-vi"),
+    audioTogViRow: q<HTMLLabelElement>(".audio-toggle-vi"),
+    audioTogHp: q<HTMLInputElement>(".audio-tog-hp"),
+    audioTogTranscription: q<HTMLInputElement>(".audio-tog-transcription"),
+    audioTogTextInput: q<HTMLInputElement>(".audio-tog-text-input"),
+    audioDiagEngine: q<HTMLElement>(".audio-diag-engine"),
+    audioDiagAec: q<HTMLElement>(".audio-diag-aec"),
+    audioDiagNs: q<HTMLElement>(".audio-diag-ns"),
+    audioDiagAgc: q<HTMLElement>(".audio-diag-agc"),
+    audioDiagVi: q<HTMLElement>(".audio-diag-vi"),
+    audioDiagSr: q<HTMLElement>(".audio-diag-sr"),
+    audioDiagLoss: q<HTMLElement>(".audio-diag-loss"),
+    audioDiagJitter: q<HTMLElement>(".audio-diag-jitter"),
+    audioDiagRtt: q<HTMLElement>(".audio-diag-rtt"),
+
+    formScreen: q<HTMLDivElement>(".screen-form"),
+    formTranscript: q<HTMLDivElement>(".form-transcript"),
+    formTranscriptSegments: new Map<string, HTMLDivElement>(),
+    formTranscriptInterimBubble: new Map<"user" | "agent", HTMLDivElement>(),
+    formTitle: q<HTMLDivElement>(".form-title"),
+    formEyebrow: q<HTMLDivElement>(".form-eyebrow"),
+    formSubtitle: q<HTMLDivElement>(".form-subtitle"),
+    formStepper: q<HTMLDivElement>(".form-stepper"),
+    formFields: q<HTMLDivElement>(".form-fields"),
+    formError: q<HTMLDivElement>(".form-error"),
+    formSuccess: q<HTMLDivElement>(".form-success"),
+    formSubmitBtn: q<HTMLButtonElement>(".form-submit"),
+    formBackBtn: q<HTMLButtonElement>(".form-back"),
+    formCancelBtn: q<HTMLButtonElement>(".form-cancel"),
+    formStepBackBtn: q<HTMLButtonElement>(".form-step-back"),
+    formCallControls: q<HTMLDivElement>(".form-call-controls"),
+    formMuteBtn: q<HTMLButtonElement>(".form-mute"),
+    formEndBtn: q<HTMLButtonElement>(".form-end"),
+    formInputs: new Map(),
+
+    appearance: DEFAULT_APPEARANCE,
+    selectedLanguage: DEFAULT_APPEARANCE.default_language,
+  };
+}
+
+function hostStyleVar(name: string, value: string) {
+  return `${name}: ${value};`;
+}
+
+export function applyAppearance(refs: UIRefs, appearance: AppearanceConfig) {
+  refs.appearance = appearance;
+
+  const t = appearance.theme;
+  const d = appearance.dimensions;
+  const primaryText = contrastingText(t.primary_color);
+  const accentText = contrastingText(t.accent_color);
+
+  const vars = [
+    hostStyleVar("--va-primary", t.primary_color),
+    hostStyleVar("--va-primary-text", primaryText),
+    hostStyleVar("--va-accent", t.accent_color),
+    hostStyleVar("--va-accent-text", accentText),
+    hostStyleVar("--va-background", t.background_color),
+    hostStyleVar("--va-surface", surfaceFromBackground(t.background_color)),
+    hostStyleVar("--va-text", t.text_color),
+    hostStyleVar("--va-text-muted", muteText(t.text_color, t.background_color)),
+    hostStyleVar("--va-user-bubble", t.user_bubble_color),
+    hostStyleVar("--va-user-bubble-text", t.user_bubble_text_color),
+    hostStyleVar("--va-agent-bubble", t.agent_bubble_color),
+    hostStyleVar("--va-agent-bubble-text", t.agent_bubble_text_color),
+    hostStyleVar("--va-fab-size", `${d.fab_size}px`),
+    hostStyleVar("--va-panel-width", `${d.panel_width}px`),
+    hostStyleVar("--va-panel-height", `${d.panel_height}px`),
+    hostStyleVar("--va-border-radius", `${d.border_radius}px`),
+    hostStyleVar("--va-font", appearance.layout.font_family),
+  ];
+  const inline = refs.host.hasAttribute("data-inline");
+  refs.host.style.cssText = inline
+    ? `position: absolute; inset: 0; z-index: 1; ${vars.join(" ")}`
+    : `position: fixed; inset: auto; z-index: 2147483647; ${vars.join(" ")}`;
+  // Corner anchoring is meaningless inline (the panel fills the host).
+  if (!inline) refs.host.setAttribute("data-position", appearance.layout.position);
+
+  refs.transcript.setAttribute(
+    "data-placeholder",
+    appearance.labels.transcript_placeholder ||
+      DEFAULT_APPEARANCE.labels.transcript_placeholder,
+  );
+
+  const name = appearance.name || DEFAULT_APPEARANCE.name;
+  const desc = appearance.subtitle || DEFAULT_APPEARANCE.subtitle;
+
+  refs.welcomeName.textContent = name;
+  refs.welcomeDesc.textContent = desc;
+  refs.callName.textContent = name;
+  refs.fab.setAttribute("aria-label", `Open ${name}`);
+
+  refs.startBtnLabel.textContent =
+    appearance.start_button_text || DEFAULT_APPEARANCE.start_button_text;
+  refs.startBtn.setAttribute(
+    "aria-label",
+    appearance.start_button_text || DEFAULT_APPEARANCE.start_button_text,
+  );
+
+  const poweredByText = appearance.powered_by_text ?? "";
+  refs.poweredBy.textContent = poweredByText;
+  refs.poweredBy.style.display = poweredByText ? "" : "none";
+  const poweredByHref = safeHref(appearance.powered_by_url);
+  if (poweredByHref) {
+    refs.poweredBy.href = poweredByHref;
+    refs.poweredBy.classList.add("is-link");
+  } else {
+    refs.poweredBy.removeAttribute("href");
+    refs.poweredBy.classList.remove("is-link");
+  }
+
+  const logoSrc = safeImageSrc(appearance.logo_url);
+  const hasLogo = Boolean(
+    logoSrc && logoSrc !== "https://example.com/logo.png",
+  );
+
+  if (hasLogo) {
+    refs.welcomeLogo.src = logoSrc;
+    refs.welcomeLogo.alt = name;
+    refs.welcomeLogo.style.display = "";
+    refs.welcomeLogoFallback.style.display = "none";
+
+    refs.callLogo.src = logoSrc;
+    refs.callLogo.alt = name;
+    refs.callLogo.style.display = "";
+    refs.callLogoFallback.style.display = "none";
+  } else {
+    refs.welcomeLogo.removeAttribute("src");
+    refs.welcomeLogo.style.display = "none";
+    refs.welcomeLogoFallback.style.display = "";
+
+    refs.callLogo.removeAttribute("src");
+    refs.callLogo.style.display = "none";
+    refs.callLogoFallback.style.display = "";
+  }
+
+  applyFabContent(refs, appearance, hasLogo, name);
+  renderLanguagePicker(refs, appearance);
+  renderConsent(refs, appearance);
+
+  // Reveal the FAB now that real values are in place.
+  refs.fab.style.visibility = "";
+}
+
+function renderConsent(refs: UIRefs, appearance: AppearanceConfig) {
+  const url = (appearance.terms_url || "").trim();
+  if (!url) {
+    refs.consent.hidden = true;
+    return;
+  }
+  refs.consent.hidden = false;
+
+  const prefix =
+    appearance.consent_text || DEFAULT_APPEARANCE.consent_text;
+  const label =
+    appearance.terms_label || DEFAULT_APPEARANCE.terms_label;
+
+  refs.consentText.textContent = `${prefix} `;
+  refs.consentLink.textContent = label;
+  refs.consentLink.href = safeHref(url);
+  refs.consentLink.setAttribute("aria-label", label);
+}
+
+function renderLanguagePicker(refs: UIRefs, appearance: AppearanceConfig) {
+  const languages = appearance.languages.length
+    ? appearance.languages
+    : DEFAULT_APPEARANCE.languages;
+
+  const previous = refs.selectedLanguage;
+  const initial =
+    languages.find((l) => l.code === previous) ??
+    languages.find((l) => l.code === appearance.default_language) ??
+    languages[0];
+
+  refs.selectedLanguage = initial.code;
+
+  if (languages.length <= 1) {
+    refs.langPicker.style.display = "none";
+    return;
+  }
+  refs.langPicker.style.display = "";
+
+  const eyebrowEl = refs.langTrigger.querySelector(
+    ".lang-trigger-eyebrow",
+  ) as HTMLSpanElement | null;
+  if (eyebrowEl) {
+    eyebrowEl.textContent =
+      appearance.labels.language_label ||
+      DEFAULT_APPEARANCE.labels.language_label;
+  }
+
+  refs.langMenu.innerHTML = "";
+  for (const lang of languages) {
+    const opt = document.createElement("button");
+    opt.type = "button";
+    opt.className = "lang-option";
+    opt.setAttribute("role", "option");
+    opt.dataset.code = lang.code;
+    opt.innerHTML = `
+      <span class="lang-option-text">
+        <span class="lang-option-native">${escapeHtml(lang.native_label)}</span>
+        <span class="lang-option-label">${escapeHtml(lang.label)}</span>
+      </span>
+      <span class="lang-option-code">${escapeHtml(lang.code.toUpperCase())}</span>
+      <span class="lang-option-check">${ICON_CHECK}</span>
+    `;
+    opt.addEventListener("click", (e) => {
+      e.stopPropagation();
+      selectLanguage(refs, languages, lang.code);
+      closeLanguageMenu(refs);
+    });
+    refs.langMenu.appendChild(opt);
+  }
+
+  selectLanguage(refs, languages, initial.code);
+  wireLanguageTrigger(refs);
+}
+
+function wireLanguageTrigger(refs: UIRefs) {
+  const picker = refs.langPicker;
+  if (picker.dataset.wired === "1") return;
+  picker.dataset.wired = "1";
+
+  refs.langTrigger.addEventListener("click", (e) => {
+    e.stopPropagation();
+    const open = picker.dataset.open === "true";
+    if (open) closeLanguageMenu(refs);
+    else openLanguageMenu(refs);
+  });
+
+  refs.shadow.addEventListener("click", (e) => {
+    if (picker.dataset.open !== "true") return;
+    const target = e.target as Node | null;
+    if (target && picker.contains(target)) return;
+    closeLanguageMenu(refs);
+  });
+
+  refs.shadow.addEventListener("keydown", (e) => {
+    if ((e as KeyboardEvent).key === "Escape" && picker.dataset.open === "true") {
+      closeLanguageMenu(refs);
+      refs.langTrigger.focus();
+    }
+  });
+}
+
+function openLanguageMenu(refs: UIRefs) {
+  refs.langPicker.dataset.open = "true";
+  refs.langMenu.hidden = false;
+  refs.langTrigger.setAttribute("aria-expanded", "true");
+}
+
+function closeLanguageMenu(refs: UIRefs) {
+  refs.langPicker.dataset.open = "false";
+  refs.langMenu.hidden = true;
+  refs.langTrigger.setAttribute("aria-expanded", "false");
+}
+
+function selectLanguage(
+  refs: UIRefs,
+  languages: AppearanceLanguage[],
+  code: string,
+) {
+  const lang =
+    languages.find((l) => l.code === code) ??
+    languages[0];
+  refs.selectedLanguage = lang.code;
+
+  refs.langTriggerLabel.textContent = lang.native_label || lang.label;
+  refs.langTriggerCode.textContent = lang.code.toUpperCase();
+  refs.langTrigger.setAttribute(
+    "aria-label",
+    `${refs.appearance.labels.language_label || "Language"}: ${lang.label}`,
+  );
+
+  const options = refs.langMenu.querySelectorAll<HTMLButtonElement>(".lang-option");
+  options.forEach((el) => {
+    const isActive = el.dataset.code === lang.code;
+    el.classList.toggle("is-active", isActive);
+    el.setAttribute("aria-selected", isActive ? "true" : "false");
+  });
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Return `url` only if it uses a safe protocol, else "". The widget runs in the
+ * host page's origin, and appearance config (powered_by_url / terms_url /
+ * logo_url) is tenant-controlled — without this, a `javascript:` URL assigned
+ * to an anchor href or image src is stored XSS against every visitor.
+ */
+function safeHref(url: string | undefined): string {
+  if (!url) return "";
+  try {
+    const proto = new URL(url, location.href).protocol;
+    return ["https:", "http:", "mailto:"].includes(proto) ? url : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Like safeHref but for image sources — http/https only (no data:/javascript:). */
+function safeImageSrc(url: string | undefined): string {
+  if (!url) return "";
+  try {
+    const proto = new URL(url, location.href).protocol;
+    return ["https:", "http:"].includes(proto) ? url : "";
+  } catch {
+    return "";
+  }
+}
+
+function renderInline(text: string): string {
+  return escapeHtml(text)
+    .replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>")
+    .replace(/__(.+?)__/g, "<strong>$1</strong>")
+    .replace(/\*(.+?)\*/g, "<em>$1</em>")
+    .replace(/_(.+?)_/g, "<em>$1</em>")
+    .replace(/`([^`]+)`/g, "<code>$1</code>")
+    .replace(/\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g, '<a href="$2" target="_blank" rel="noopener noreferrer">$1</a>');
+}
+
+function renderMarkdown(text: string): string {
+  const lines = text.split("\n");
+  const blocks: string[] = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    const h3 = line.match(/^### (.+)/);
+    const h2 = line.match(/^## (.+)/);
+    const h1 = line.match(/^# (.+)/);
+    if (h3) { blocks.push(`<h3>${renderInline(h3[1])}</h3>`); i++; continue; }
+    if (h2) { blocks.push(`<h2>${renderInline(h2[1])}</h2>`); i++; continue; }
+    if (h1) { blocks.push(`<h1>${renderInline(h1[1])}</h1>`); i++; continue; }
+
+    if (line.match(/^[-*] /)) {
+      const items: string[] = [];
+      while (i < lines.length && lines[i].match(/^[-*] /)) {
+        items.push(`<li>${renderInline(lines[i].slice(2))}</li>`);
+        i++;
+      }
+      blocks.push(`<ul>${items.join("")}</ul>`);
+      continue;
+    }
+
+    if (line.match(/^\d+\. /)) {
+      const items: string[] = [];
+      while (i < lines.length && lines[i].match(/^\d+\. /)) {
+        items.push(`<li>${renderInline(lines[i].replace(/^\d+\. /, ""))}</li>`);
+        i++;
+      }
+      blocks.push(`<ol>${items.join("")}</ol>`);
+      continue;
+    }
+
+    if (line.startsWith("```")) {
+      const codeLines: string[] = [];
+      i++;
+      while (i < lines.length && !lines[i].startsWith("```")) {
+        codeLines.push(escapeHtml(lines[i]));
+        i++;
+      }
+      if (i < lines.length) i++;
+      blocks.push(`<pre><code>${codeLines.join("\n")}</code></pre>`);
+      continue;
+    }
+
+    if (!line.trim()) { i++; continue; }
+
+    const paraLines: string[] = [];
+    while (i < lines.length && lines[i].trim() && !lines[i].match(/^(#{1,3} |[-*] |\d+\. |```)/)) {
+      paraLines.push(renderInline(lines[i]));
+      i++;
+    }
+    if (paraLines.length) blocks.push(`<p>${paraLines.join("<br>")}</p>`);
+  }
+
+  return blocks.join("");
+}
+
+function applyFabContent(
+  refs: UIRefs,
+  appearance: AppearanceConfig,
+  hasLogo: boolean,
+  name: string,
+) {
+  const label = (appearance.fab_label || "").trim();
+  const sublabel = (appearance.fab_sublabel || "").trim();
+  const iconEl = refs.fab.querySelector(".fab-icon") as HTMLSpanElement | null;
+  const textEl = refs.fab.querySelector(".fab-text") as HTMLSpanElement | null;
+  const labelEl = refs.fab.querySelector(".fab-label") as HTMLSpanElement | null;
+  const sublabelEl = refs.fab.querySelector(".fab-sublabel") as HTMLSpanElement | null;
+
+  if (!iconEl || !textEl || !labelEl || !sublabelEl) return;
+
+  if (hasLogo) {
+    iconEl.innerHTML = `<img class="fab-logo" alt="${escapeAttr(name)}" src="${escapeAttr(safeImageSrc(appearance.logo_url))}" />`;
+  } else {
+    iconEl.innerHTML = ICON_FAB;
+  }
+
+  if (label) {
+    labelEl.textContent = label;
+    refs.fab.classList.add("has-label");
+    refs.fab.setAttribute(
+      "aria-label",
+      sublabel ? `${label}, ${sublabel} — open ${name}` : `${label} — open ${name}`,
+    );
+  } else {
+    labelEl.textContent = "";
+    refs.fab.classList.remove("has-label");
+    refs.fab.setAttribute("aria-label", `Open ${name}`);
+  }
+
+  if (label && sublabel) {
+    sublabelEl.textContent = sublabel;
+    refs.fab.classList.add("has-sublabel");
+  } else {
+    sublabelEl.textContent = "";
+    refs.fab.classList.remove("has-sublabel");
+  }
+
+  textEl.style.display = label ? "" : "none";
+}
+
+export function setScreen(refs: UIRefs, screen: Screen) {
+  refs.panel.setAttribute("data-screen", screen);
+  refs.welcomeScreen.style.display = screen === "welcome" ? "flex" : "none";
+  refs.callScreen.style.display = screen === "call" ? "flex" : "none";
+  refs.formScreen.style.display = screen === "form" ? "flex" : "none";
+}
+
+export interface RenderFormArgs {
+  definition: FormDefinition;
+  values: Record<string, string>;
+  /** Label for the cancel/back button — "Back to call" while connected, etc. */
+  cancelLabel?: string;
+  /** Which step (0-indexed) to render; ignored when the form has no `steps`. */
+  stepIndex?: number;
+  /** Fired whenever the user edits a field. Used to push state to the agent. */
+  onFieldChange?: () => void;
+}
+
+/**
+ * Render a form definition's fields into the form screen. Existing values are
+ * read from `values`; the on-screen inputs are kept in `refs.formInputs` so
+ * the controller can pull current values back out at submit time.
+ */
+export function renderForm(refs: UIRefs, args: RenderFormArgs) {
+  const { definition, values, cancelLabel } = args;
+  const steps = totalSteps(definition);
+  const stepIndex = Math.max(0, Math.min(args.stepIndex ?? 0, steps - 1));
+  const isStepper = steps > 1;
+  const isFinalStep = stepIndex === steps - 1;
+  const currentStep = definition.steps?.[stepIndex];
+
+  refs.formTitle.textContent = currentStep?.title ?? definition.title;
+  refs.formEyebrow.textContent = isStepper
+    ? `Step ${stepIndex + 1} of ${steps}${definition.title ? ` · ${definition.title}` : ""}`
+    : "Review before submit";
+
+  const subtitle = currentStep?.subtitle ?? (stepIndex === 0 ? definition.subtitle : "");
+  refs.formSubtitle.textContent = subtitle ?? "";
+  refs.formSubtitle.style.display = subtitle ? "" : "none";
+
+  renderStepper(refs, steps, stepIndex);
+
+  const submitLabel = refs.formSubmitBtn.querySelector(".form-submit-label");
+  if (submitLabel) {
+    submitLabel.textContent = isFinalStep
+      ? definition.submit_label ?? "Confirm & send"
+      : currentStep?.next_label ?? "Continue";
+  }
+
+  refs.formCancelBtn.textContent = cancelLabel ?? "Cancel";
+
+  // Step-back button: visible only on stepper, hidden on first step.
+  const showStepBack = isStepper && stepIndex > 0;
+  refs.formStepBackBtn.hidden = !showStepBack;
+  if (showStepBack) {
+    refs.formStepBackBtn.textContent = currentStep?.back_label ?? "Back";
+  }
+
+  // Apply layout modifiers on the fields wrapper.
+  const layout = definition.layout ?? {};
+  refs.formFields.classList.toggle("is-grid", layout.field_layout === "grid");
+  refs.formFields.classList.toggle("is-compact", layout.density === "compact");
+  refs.formFields.classList.toggle("is-inline-labels", layout.label_position === "inline");
+
+  setFormError(refs, "");
+  setFormSuccess(refs, "");
+
+  refs.formFields.innerHTML = "";
+  refs.formInputs.clear();
+
+  for (const field of fieldsForStep(definition, stepIndex)) {
+    refs.formFields.appendChild(
+      buildFieldNode(
+        refs,
+        field,
+        field.name ? values[field.name] ?? "" : "",
+        args.onFieldChange,
+      ),
+    );
+  }
+}
+
+function renderStepper(refs: UIRefs, steps: number, current: number) {
+  if (steps <= 1) {
+    refs.formStepper.hidden = true;
+    refs.formStepper.innerHTML = "";
+    return;
+  }
+  refs.formStepper.hidden = false;
+  refs.formStepper.innerHTML = "";
+  for (let i = 0; i < steps; i++) {
+    const dot = document.createElement("span");
+    dot.className = "form-stepper-dot";
+    if (i < current) dot.classList.add("is-done");
+    if (i === current) dot.classList.add("is-active");
+    refs.formStepper.appendChild(dot);
+  }
+}
+
+function optionEntries(options: FormFieldOption[] | undefined): Array<{ value: string; label: string }> {
+  if (!options) return [];
+  return options.map((opt) =>
+    typeof opt === "string"
+      ? { value: opt, label: opt }
+      : { value: opt.value, label: opt.label ?? opt.value },
+  );
+}
+
+function buildFieldNode(
+  refs: UIRefs,
+  field: FormFieldDef,
+  value: string,
+  onChange?: () => void,
+): HTMLElement {
+  // Reassigned once the error node exists; lets `notifyChange` clear a field's
+  // inline error the moment the visitor starts fixing it.
+  let clearError = () => {};
+  const notifyChange = () => {
+    clearError();
+    if (onChange) onChange();
+  };
+  // Display blocks render their own wrapper with no input registered.
+  if (field.type === "display") {
+    const block = document.createElement("div");
+    block.className = "form-display";
+    if (field.label) {
+      const heading = document.createElement("div");
+      heading.className = "form-display-title";
+      heading.textContent = field.label;
+      block.appendChild(heading);
+    }
+    if (field.help_text) {
+      const body = document.createElement("p");
+      body.className = "form-display-body";
+      body.textContent = field.help_text;
+      block.appendChild(body);
+    }
+    return block;
+  }
+
+  const fieldName = field.name!;
+  const wrapper = document.createElement("label");
+  wrapper.className = "form-field";
+  if (field.width === "half") wrapper.classList.add("is-half");
+
+  const labelEl = document.createElement("span");
+  labelEl.className = "form-label";
+  labelEl.textContent = field.required ? `${field.label} *` : field.label;
+  wrapper.appendChild(labelEl);
+
+  // `setError` is grafted on after the error node is built below.
+  let binding: Omit<FormInputBinding, "setError">;
+
+  if (field.type === "textarea") {
+    const ta = document.createElement("textarea");
+    ta.rows = field.rows ?? 4;
+    ta.placeholder = field.placeholder ?? "";
+    ta.value = value;
+    ta.name = fieldName;
+    ta.className = "form-input form-textarea";
+    if (field.required) ta.required = true;
+    ta.addEventListener("input", notifyChange);
+    wrapper.appendChild(ta);
+    binding = {
+      read: () => ta.value.trim(),
+      setDisabled: (busy) => { ta.disabled = busy; },
+    };
+  } else if (field.type === "select") {
+    const sel = document.createElement("select");
+    sel.className = "form-input form-select";
+    sel.name = fieldName;
+    if (field.required) sel.required = true;
+    const opts = optionEntries(field.options);
+    const seen = new Set(opts.map((o) => o.value));
+    const all = !value || seen.has(value) ? opts : [...opts, { value, label: value }];
+    for (const opt of all) {
+      const o = document.createElement("option");
+      o.value = opt.value;
+      o.textContent = opt.label;
+      if (opt.value === value) o.selected = true;
+      sel.appendChild(o);
+    }
+    sel.addEventListener("change", notifyChange);
+    wrapper.appendChild(sel);
+    binding = {
+      read: () => sel.value.trim(),
+      setDisabled: (busy) => { sel.disabled = busy; },
+    };
+  } else if (field.type === "radio") {
+    wrapper.classList.add("is-choice-group");
+    const groupName = `${fieldName}-${Math.random().toString(36).slice(2, 8)}`;
+    const group = document.createElement("div");
+    group.className = "form-choice-group";
+    const inputs: HTMLInputElement[] = [];
+    for (const opt of optionEntries(field.options)) {
+      const choice = document.createElement("label");
+      choice.className = "form-choice";
+      const input = document.createElement("input");
+      input.type = "radio";
+      input.name = groupName;
+      input.value = opt.value;
+      if (opt.value === value) input.checked = true;
+      if (field.required) input.required = true;
+      input.addEventListener("change", notifyChange);
+      const text = document.createElement("span");
+      text.textContent = opt.label;
+      choice.appendChild(input);
+      choice.appendChild(text);
+      group.appendChild(choice);
+      inputs.push(input);
+    }
+    wrapper.appendChild(group);
+    binding = {
+      read: () => inputs.find((i) => i.checked)?.value.trim() ?? "",
+      setDisabled: (busy) => inputs.forEach((i) => { i.disabled = busy; }),
+    };
+  } else if (field.type === "checkbox") {
+    wrapper.classList.add("is-choice-group");
+    if (field.options && field.options.length) {
+      // Multi-checkbox group — value is comma-joined.
+      const selected = new Set(
+        value
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean),
+      );
+      const group = document.createElement("div");
+      group.className = "form-choice-group";
+      const inputs: HTMLInputElement[] = [];
+      for (const opt of optionEntries(field.options)) {
+        const choice = document.createElement("label");
+        choice.className = "form-choice";
+        const input = document.createElement("input");
+        input.type = "checkbox";
+        input.value = opt.value;
+        if (selected.has(opt.value)) input.checked = true;
+        input.addEventListener("change", notifyChange);
+        const text = document.createElement("span");
+        text.textContent = opt.label;
+        choice.appendChild(input);
+        choice.appendChild(text);
+        group.appendChild(choice);
+        inputs.push(input);
+      }
+      wrapper.appendChild(group);
+      binding = {
+        read: () =>
+          inputs
+            .filter((i) => i.checked)
+            .map((i) => i.value)
+            .join(","),
+        setDisabled: (busy) => inputs.forEach((i) => { i.disabled = busy; }),
+      };
+    } else {
+      // Single boolean checkbox.
+      const single = document.createElement("input");
+      single.type = "checkbox";
+      single.name = fieldName;
+      single.className = "form-checkbox";
+      if (value === "true" || value === "1" || value === "on") single.checked = true;
+      if (field.required) single.required = true;
+      single.addEventListener("change", notifyChange);
+      wrapper.appendChild(single);
+      // Move the label text next to the checkbox for natural "agree to terms" layout.
+      wrapper.classList.add("is-inline-bool");
+      binding = {
+        read: () => (single.checked ? "true" : ""),
+        setDisabled: (busy) => { single.disabled = busy; },
+      };
+    }
+  } else {
+    const text = document.createElement("input");
+    // text/email/tel/number/date/time map 1:1 to native input types.
+    text.type = field.type;
+    text.placeholder = field.placeholder ?? "";
+    text.value = value;
+    text.name = fieldName;
+    text.className = "form-input";
+    if (field.required) text.required = true;
+    if (field.pattern) text.pattern = field.pattern;
+    if (field.type === "number") {
+      if (field.min !== undefined) text.min = String(field.min);
+      if (field.max !== undefined) text.max = String(field.max);
+    }
+    text.addEventListener("input", notifyChange);
+    wrapper.appendChild(text);
+    binding = {
+      read: () => text.value.trim(),
+      setDisabled: (busy) => { text.disabled = busy; },
+    };
+  }
+
+  if (field.help_text) {
+    const help = document.createElement("span");
+    help.className = "form-help";
+    help.textContent = field.help_text;
+    wrapper.appendChild(help);
+  }
+
+  // Inline validation error slot, hidden until `setError` fills it.
+  const errorEl = document.createElement("span");
+  errorEl.className = "form-field-error";
+  errorEl.hidden = true;
+  wrapper.appendChild(errorEl);
+
+  const setError = (message: string) => {
+    errorEl.textContent = message;
+    errorEl.hidden = !message;
+    wrapper.classList.toggle("is-invalid", Boolean(message));
+  };
+  clearError = () => setError("");
+
+  refs.formInputs.set(fieldName, { ...binding, setError });
+  return wrapper;
+}
+
+/** Apply inline validation errors, then clear any field not in the list. */
+export function setFieldErrors(
+  refs: UIRefs,
+  errors: { name: string; message: string }[],
+) {
+  const byName = new Map(errors.map((e) => [e.name, e.message]));
+  for (const [name, binding] of refs.formInputs.entries()) {
+    binding.setError(byName.get(name) ?? "");
+  }
+}
+
+/** Clear every inline field error. */
+export function clearFieldErrors(refs: UIRefs) {
+  for (const binding of refs.formInputs.values()) binding.setError("");
+}
+
+export function readFormValues(refs: UIRefs): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, binding] of refs.formInputs.entries()) {
+    out[name] = binding.read();
+  }
+  return out;
+}
+
+export function setFormBusy(refs: UIRefs, busy: boolean) {
+  refs.formSubmitBtn.disabled = busy;
+  refs.formCancelBtn.disabled = busy;
+  refs.formBackBtn.disabled = busy;
+  refs.formStepBackBtn.disabled = busy;
+  for (const binding of refs.formInputs.values()) binding.setDisabled(busy);
+  refs.formSubmitBtn.classList.toggle("is-busy", busy);
+}
+
+export function setFormError(refs: UIRefs, message: string) {
+  refs.formError.textContent = message;
+  refs.formError.hidden = !message;
+}
+
+export function setFormSuccess(refs: UIRefs, message: string) {
+  refs.formSuccess.textContent = message;
+  refs.formSuccess.hidden = !message;
+}
+
+export function setCallStatus(refs: UIRefs, text: string) {
+  refs.callStatus.textContent = text;
+}
+
+export function setCallTimer(refs: UIRefs, remainingMs: number | null) {
+  if (remainingMs === null) {
+    refs.callTimer.hidden = true;
+    refs.callTimer.classList.remove("warning");
+    refs.callTimerText.textContent = "";
+    return;
+  }
+  refs.callTimer.hidden = false;
+  const totalSeconds = Math.max(0, Math.ceil(remainingMs / 1000));
+  refs.callTimerText.textContent = formatMmSs(totalSeconds);
+  // Flash a warning tint in the final 30 seconds.
+  refs.callTimer.classList.toggle("warning", totalSeconds <= 30);
+}
+
+function formatMmSs(totalSeconds: number): string {
+  const m = Math.floor(totalSeconds / 60);
+  const s = totalSeconds % 60;
+  return `${m}:${s.toString().padStart(2, "0")}`;
+}
+
+export type OrbState =
+  | "idle"
+  | "listening"
+  | "speaking"
+  | "connecting"
+  | "thinking";
+
+export function setOrbState(refs: UIRefs, state: OrbState) {
+  refs.orb.classList.remove("listening", "speaking", "connecting", "thinking");
+  if (state !== "idle") refs.orb.classList.add(state);
+  const labels = refs.appearance.labels;
+  refs.orbLabel.textContent =
+    state === "listening"
+      ? labels.listening
+      : state === "speaking"
+        ? labels.speaking
+        : state === "connecting"
+          ? labels.connecting
+          : state === "thinking"
+            ? labels.thinking
+            : labels.idle;
+  // The contextual status line only makes sense while thinking; any other
+  // state clears it so a stale "Searching…" can't linger over a reply.
+  if (state !== "thinking") setAgentStatusLine(refs, null);
+}
+
+/**
+ * Write the contextual processing text (e.g. "Searching the knowledge base…")
+ * under the orb, or clear it when `text` is null/empty. This is the per-tool
+ * label from a voice.agent_status event; the generic orb label still reads
+ * "Thinking…".
+ */
+export function setAgentStatusLine(refs: UIRefs, text: string | null) {
+  const trimmed = (text || "").trim();
+  if (!trimmed) {
+    refs.agentStatusLine.hidden = true;
+    refs.agentStatusLine.textContent = "";
+    return;
+  }
+  refs.agentStatusLine.textContent = trimmed;
+  refs.agentStatusLine.hidden = false;
+}
+
+export function setMuteVisual(refs: UIRefs, muted: boolean) {
+  const label = muted ? "Unmute" : "Mute";
+  const icon = muted ? ICON_MIC_OFF : ICON_MIC_ON;
+  for (const btn of [refs.muteBtn, refs.formMuteBtn]) {
+    btn.classList.toggle("is-active", muted);
+    btn.setAttribute("aria-label", label);
+    btn.innerHTML = icon;
+  }
+}
+
+export function setFormCallControlsVisible(refs: UIRefs, visible: boolean) {
+  refs.formCallControls.hidden = !visible;
+}
+
+export function setAudioDrawerOpen(refs: UIRefs, open: boolean) {
+  refs.audioDrawer.hidden = !open;
+  refs.audioDrawer.classList.toggle("is-open", open);
+  refs.settingsBtn.classList.toggle("is-active", open);
+  refs.settingsBtn.setAttribute("aria-expanded", open ? "true" : "false");
+}
+
+export function setAudioMeterLevel(refs: UIRefs, level: number) {
+  const clamped = Math.max(0, Math.min(1, level));
+  refs.audioMeterBar.style.width = `${(clamped * 100).toFixed(1)}%`;
+}
+
+export function populateAudioDeviceSelect(
+  select: HTMLSelectElement,
+  devices: MediaDeviceInfo[],
+  selectedDeviceId: string,
+  defaultLabel: string,
+) {
+  const previousValue = selectedDeviceId || "";
+  select.innerHTML = "";
+  const defaultOpt = document.createElement("option");
+  defaultOpt.value = "";
+  defaultOpt.textContent = defaultLabel;
+  select.appendChild(defaultOpt);
+  for (const device of devices) {
+    const opt = document.createElement("option");
+    opt.value = device.deviceId;
+    // Empty labels happen before mic permission is granted; show a stub.
+    opt.textContent = device.label || `Device ${device.deviceId.slice(0, 6)}`;
+    select.appendChild(opt);
+  }
+  // Re-select previous value if still present, otherwise fall back to default.
+  if (Array.from(select.options).some((o) => o.value === previousValue)) {
+    select.value = previousValue;
+  } else {
+    select.value = "";
+  }
+}
+
+const typewriterTimers = new WeakMap<HTMLDivElement, number>();
+const TYPEWRITER_CHARS_PER_TICK = 2;
+const TYPEWRITER_TICK_MS = 18;
+
+function updateOneTranscript(
+  container: HTMLDivElement,
+  segments: Map<string, HTMLDivElement>,
+  interimBubbles: Map<"user" | "agent", HTMLDivElement>,
+  role: "user" | "agent",
+  segmentId: string,
+  trimmed: string,
+  isFinal: boolean,
+) {
+  const key = `${role}:${segmentId}`;
+  let bubble = segments.get(key);
+  let isNewBubble = !bubble;
+
+  if (!bubble) {
+    const lingeringInterim = interimBubbles.get(role);
+    if (lingeringInterim) {
+      bubble = lingeringInterim;
+      segments.set(key, bubble);
+      isNewBubble = false;
+    } else {
+      bubble = document.createElement("div");
+      bubble.className = `transcript-msg ${role} interim`;
+      container.appendChild(bubble);
+      segments.set(key, bubble);
+    }
+  }
+
+  const pendingTimer = typewriterTimers.get(bubble);
+  if (pendingTimer !== undefined) {
+    window.clearInterval(pendingTimer);
+    typewriterTimers.delete(bubble);
+  }
+
+  if (isNewBubble && isFinal && trimmed.length > 3) {
+    bubble.classList.add("interim");
+    bubble.classList.remove("final");
+    bubble.textContent = "";
+    let pos = 0;
+    const tick = () => {
+      pos = Math.min(trimmed.length, pos + TYPEWRITER_CHARS_PER_TICK);
+      bubble!.textContent = trimmed.slice(0, pos);
+      container.scrollTop = container.scrollHeight;
+      if (pos >= trimmed.length) {
+        const t = typewriterTimers.get(bubble!);
+        if (t !== undefined) window.clearInterval(t);
+        typewriterTimers.delete(bubble!);
+        if (role === "agent") {
+          bubble!.innerHTML = renderMarkdown(trimmed);
+        } else {
+          bubble!.textContent = trimmed;
+        }
+        bubble!.classList.remove("interim");
+        bubble!.classList.add("final");
+      }
+    };
+    const timer = window.setInterval(tick, TYPEWRITER_TICK_MS);
+    typewriterTimers.set(bubble, timer);
+    tick();
+    interimBubbles.delete(role);
+    return;
+  }
+
+  if (role === "agent") {
+    bubble.innerHTML = renderMarkdown(trimmed);
+  } else {
+    bubble.textContent = trimmed;
+  }
+  bubble.classList.toggle("interim", !isFinal);
+  bubble.classList.toggle("final", isFinal);
+  container.scrollTop = container.scrollHeight;
+
+  if (isFinal) {
+    interimBubbles.delete(role);
+  } else {
+    interimBubbles.set(role, bubble);
+  }
+}
+
+export function appendOrUpdateTranscriptSegment(
+  refs: UIRefs,
+  role: "user" | "agent",
+  segmentId: string,
+  text: string,
+  isFinal: boolean,
+) {
+  const trimmed = (text || "").trim();
+  if (!trimmed) return;
+
+  updateOneTranscript(
+    refs.transcript,
+    refs.transcriptSegments,
+    refs.transcriptInterimBubble,
+    role,
+    segmentId,
+    trimmed,
+    isFinal,
+  );
+
+  if (!refs.formTranscript.hidden) {
+    updateOneTranscript(
+      refs.formTranscript,
+      refs.formTranscriptSegments,
+      refs.formTranscriptInterimBubble,
+      role,
+      segmentId,
+      trimmed,
+      isFinal,
+    );
+  }
+}
+
+function clearOneTranscript(
+  container: HTMLDivElement,
+  segments: Map<string, HTMLDivElement>,
+  interimBubbles: Map<"user" | "agent", HTMLDivElement>,
+) {
+  for (const bubble of segments.values()) {
+    const t = typewriterTimers.get(bubble);
+    if (t !== undefined) {
+      window.clearInterval(t);
+      typewriterTimers.delete(bubble);
+    }
+  }
+  container.innerHTML = "";
+  segments.clear();
+  interimBubbles.clear();
+}
+
+export function clearTranscript(refs: UIRefs) {
+  clearOneTranscript(refs.transcript, refs.transcriptSegments, refs.transcriptInterimBubble);
+  clearOneTranscript(refs.formTranscript, refs.formTranscriptSegments, refs.formTranscriptInterimBubble);
+}
+
+export function showAgentTransition(refs: UIRefs, agentName: string) {
+  const name = (agentName || "").trim() || "the next agent";
+  const text = `Connecting you with ${name}...`;
+  for (const container of [refs.transcript, refs.formTranscript]) {
+    if (!container) continue;
+    const bubble = document.createElement("div");
+    bubble.className = "transcript-msg system agent-transition";
+    bubble.textContent = text;
+    container.appendChild(bubble);
+    container.scrollTop = container.scrollHeight;
+  }
+  setCallStatus(refs, text);
+}
+
+export function setFormTranscriptVisible(refs: UIRefs, visible: boolean) {
+  refs.formTranscript.hidden = !visible;
+  if (visible) {
+    // Sync existing transcript messages into the form transcript
+    clearOneTranscript(refs.formTranscript, refs.formTranscriptSegments, refs.formTranscriptInterimBubble);
+    for (const [key, bubble] of refs.transcriptSegments) {
+      const clone = bubble.cloneNode(true) as HTMLDivElement;
+      refs.formTranscript.appendChild(clone);
+      refs.formTranscriptSegments.set(key, clone);
+    }
+    for (const [role, bubble] of refs.transcriptInterimBubble) {
+      for (const [key, original] of refs.transcriptSegments) {
+        if (original === bubble) {
+          const clone = refs.formTranscriptSegments.get(key);
+          if (clone) refs.formTranscriptInterimBubble.set(role, clone);
+          break;
+        }
+      }
+    }
+    refs.formTranscript.scrollTop = refs.formTranscript.scrollHeight;
+  }
+}
+
+function contrastingText(color: string): string {
+  const rgb = parseColor(color);
+  if (!rgb) return "#ffffff";
+  const [r, g, b] = rgb;
+  const toLin = (c: number) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  const lum = 0.2126 * toLin(r) + 0.7152 * toLin(g) + 0.0722 * toLin(b);
+  return lum > 0.5 ? "#111111" : "#ffffff";
+}
+
+function surfaceFromBackground(bg: string): string {
+  const rgb = parseColor(bg);
+  if (!rgb) return "#f6f7f9";
+  const [r, g, b] = rgb;
+  const lum = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+  const shift = lum > 0.5 ? -10 : 18;
+  const c = (v: number) => Math.max(0, Math.min(255, v + shift));
+  return `rgb(${c(r)}, ${c(g)}, ${c(b)})`;
+}
+
+function muteText(text: string, bg: string): string {
+  const trgb = parseColor(text);
+  const brgb = parseColor(bg);
+  if (!trgb || !brgb) return "rgba(0,0,0,0.55)";
+  const mix = (i: 0 | 1 | 2) => Math.round(trgb[i] * 0.55 + brgb[i] * 0.45);
+  return `rgb(${mix(0)}, ${mix(1)}, ${mix(2)})`;
+}
+
+function parseColor(input: string): [number, number, number] | null {
+  const s = input.trim();
+  const hex = s.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (hex) {
+    let h = hex[1];
+    if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+    return [
+      parseInt(h.slice(0, 2), 16),
+      parseInt(h.slice(2, 4), 16),
+      parseInt(h.slice(4, 6), 16),
+    ];
+  }
+  const rgb = s.match(/^rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)/i);
+  if (rgb) return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+  return null;
+}
+
+function escapeAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}