From 0b8a310a7c2dbee33184296a11fe815bfdc4557f Mon Sep 17 00:00:00 2001
From: Devon-White <devon.white@signalwire.com>
Date: Mon, 8 Jun 2026 12:08:30 -0400
Subject: [PATCH 1/7] New TTS widget

---
 fern/components/skeleton.css                  |  25 ++
 fern/components/skeleton.tsx                  |  50 +++
 fern/components/types.ts                      |  51 +++
 fern/components/voice-widget.css              |  47 +++
 fern/components/voice-widget.tsx              | 357 ++++++++++++++++++
 fern/docs.yml                                 |   5 +
 .../pages/calling/voice/TTS/index.mdx         |   9 +
 fern/voice-widget-overrides.css               |  71 ++++
 8 files changed, 615 insertions(+)
 create mode 100644 fern/components/skeleton.css
 create mode 100644 fern/components/skeleton.tsx
 create mode 100644 fern/components/types.ts
 create mode 100644 fern/components/voice-widget.css
 create mode 100644 fern/components/voice-widget.tsx
 create mode 100644 fern/voice-widget-overrides.css

diff --git a/fern/components/skeleton.css b/fern/components/skeleton.css
new file mode 100644
index 0000000000..3b18147218
--- /dev/null
+++ b/fern/components/skeleton.css
@@ -0,0 +1,25 @@
+/* Reusable loading-skeleton (shimmer) for custom MDX components, ported from the SignalWire
+   components design reference. The original drove it with --skeleton-base / --skeleton-shimmer
+   design tokens; here those map onto Fern's theme-aware grayscale vars so it follows light/dark.
+   Loaded globally via docs.yml `css:`. Markup comes from components/skeleton.tsx (`.sw-skeleton`). */
+.sw-skeleton {
+  background: var(--grayscale-a3);
+  border-radius: 8px;
+  position: relative;
+  overflow: hidden;
+  flex: none; /* keep its size in flex layouts */
+}
+.sw-skeleton::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(90deg, transparent, var(--grayscale-a4), transparent);
+  animation: sw-shimmer 1.5s infinite;
+}
+@keyframes sw-shimmer {
+  0% { transform: translateX(-100%); }
+  100% { transform: translateX(100%); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .sw-skeleton::after { animation: none; }
+}
diff --git a/fern/components/skeleton.tsx b/fern/components/skeleton.tsx
new file mode 100644
index 0000000000..1326788011
--- /dev/null
+++ b/fern/components/skeleton.tsx
@@ -0,0 +1,50 @@
+import type { CSSProperties } from "react";
+
+// Reusable loading-skeleton primitive for custom MDX components that fetch data at runtime.
+// Compose a few of these to mimic the shape of the content that's loading. Pairs with
+// skeleton.css (loaded via docs.yml `css:` — Fern's component bundler doesn't process CSS imports).
+// Theme-aware (light/dark) through Fern's grayscale vars.
+//
+//   import { Skeleton, SkeletonText } from "@/components/skeleton";
+//   if (!data) return <Skeleton width="60%" height={20} />;
+
+export interface SkeletonProps {
+  /** CSS width — number (px) or any CSS length (e.g. "60%"). */
+  width?: string | number;
+  /** CSS height — number (px) or any CSS length. Default: 14. */
+  height?: string | number;
+  /** Border radius override — number (px) or any CSS length (e.g. "50%" for a circle). */
+  radius?: string | number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Skeleton({ width, height = 14, radius, className, style }: SkeletonProps) {
+  return (
+    <div
+      className={`sw-skeleton${className ? ` ${className}` : ""}`}
+      aria-hidden="true"
+      style={{ width, height, ...(radius != null ? { borderRadius: radius } : null), ...style }}
+    />
+  );
+}
+
+export interface SkeletonTextProps {
+  /** Number of lines. Default: 3. */
+  lines?: number;
+  /** Gap between lines in px. Default: 8. */
+  gap?: number;
+  /** Per-line widths; defaults to full width with a shorter last line. */
+  widths?: (string | number)[];
+}
+
+/** A stack of text-line skeletons — for paragraph/description placeholders. */
+export function SkeletonText({ lines = 3, gap = 8, widths }: SkeletonTextProps) {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap }} aria-hidden="true">
+      {Array.from({ length: lines }).map((_, i) => (
+        <Skeleton key={i} height={12} width={widths?.[i] ?? (i === lines - 1 ? "60%" : "100%")} />
+      ))}
+    </div>
+  );
+}
diff --git a/fern/components/types.ts b/fern/components/types.ts
new file mode 100644
index 0000000000..85b0f336c8
--- /dev/null
+++ b/fern/components/types.ts
@@ -0,0 +1,51 @@
+// Shapes of the assets produced by the Python pipeline (tools/voice_widget). These two files +
+// the audio/ tree are the entire contract handed to devex — keep this in sync with
+// catalog_schema.json and synth_examples.py.
+
+export type Gender = "male" | "female" | "neutral" | "unknown";
+
+export interface CatalogVoice {
+  key: string;              // "<engine>/<voice_id>" — unique
+  engine: string;           // mod_openai engine id (elevenlabs, cartesia, ...)
+  provider: string;         // human-facing label
+  voice_id: string;         // value passed to the provider to synthesize
+  display_name: string;     // mod_openai `voice` field / UI label
+  languages: string[];
+  primary_language: string;
+  gender: Gender;
+  model: string | null;
+  tags: string[];
+  description: string;
+  provider_preview_url: string | null;
+  source: "api" | "static" | "docs";
+  fetched_at: string;
+}
+
+export interface Catalog {
+  generated_at: string;
+  voices: CatalogVoice[];
+}
+
+export interface Clip {
+  language: string;
+  sample_text: string;
+  audio: string;            // path relative to the audio base (e.g. "audio/elevenlabs/Brian.mp3")
+  format: string;
+  bytes: number;
+  duration_sec: number | null;
+  synth_model: string | null;
+  fingerprint: string | null;
+  synthesized_at: string;
+  status: "ok" | "error";
+  error: string | null;
+}
+
+export interface Manifest {
+  generated_at: string;
+  clips: Record<string, Clip>; // keyed by CatalogVoice.key
+}
+
+// A catalog voice joined with its synthesized clip (if any).
+export interface VoiceRow extends CatalogVoice {
+  clip?: Clip;
+}
diff --git a/fern/components/voice-widget.css b/fern/components/voice-widget.css
new file mode 100644
index 0000000000..e8bf99c785
--- /dev/null
+++ b/fern/components/voice-widget.css
@@ -0,0 +1,47 @@
+/* Scoped under .vw so the widget can be dropped into the docs without clobbering host styles. */
+.vw {
+  --vw-bg: #0e1116; --vw-card: #171b22; --vw-line: #262c36; --vw-fg: #e6e9ef;
+  --vw-muted: #8b95a5; --vw-accent: #3a86ff; --vw-radius: 10px;
+  color: var(--vw-fg); font: 14px/1.45 system-ui, sans-serif;
+}
+.vw-loading, .vw-error { padding: 2rem; color: var(--vw-muted); }
+.vw-error { color: #ff6b6b; }
+
+.vw-head { display: flex; align-items: center; gap: 1rem; margin-bottom: .75rem; }
+.vw-title { font-size: 1.15rem; font-weight: 700; }
+.vw-count { color: var(--vw-muted); font-weight: 400; margin-left: .35rem; }
+.vw-search { margin-left: auto; padding: .5rem .75rem; min-width: 220px;
+  background: var(--vw-card); border: 1px solid var(--vw-line); border-radius: var(--vw-radius); color: inherit; }
+
+.vw-filters { display: flex; flex-wrap: wrap; gap: .75rem; align-items: end; margin-bottom: 1rem;
+  position: sticky; top: 0; background: var(--vw-bg); padding: .5rem 0; z-index: 2; }
+.vw-select { display: flex; flex-direction: column; gap: .2rem; font-size: .8rem; color: var(--vw-muted); }
+.vw-select select { padding: .4rem .5rem; background: var(--vw-card); color: var(--vw-fg);
+  border: 1px solid var(--vw-line); border-radius: 8px; }
+.vw-group { display: flex; gap: .25rem; margin-left: auto; }
+.vw-group button { padding: .4rem .6rem; background: var(--vw-card); color: var(--vw-muted);
+  border: 1px solid var(--vw-line); border-radius: 8px; cursor: pointer; }
+.vw-group button.on { color: #fff; border-color: var(--vw-accent); }
+
+.vw-section { margin-bottom: 1.5rem; }
+.vw-section-title { font-size: .95rem; margin: .5rem 0; text-transform: capitalize; }
+.vw-section-title span { color: var(--vw-muted); font-weight: 400; margin-left: .35rem; }
+
+.vw-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: .75rem; }
+.vw-card { background: var(--vw-card); border: 1px solid var(--vw-line); border-radius: var(--vw-radius);
+  padding: .75rem; display: flex; flex-direction: column; gap: .5rem; }
+.vw-card.vw-disabled { opacity: .55; }
+.vw-card-top { display: flex; align-items: center; gap: .5rem; }
+.vw-play { width: 32px; height: 32px; flex: 0 0 auto; border-radius: 50%; cursor: pointer;
+  background: var(--vw-accent); color: #fff; border: none; font-size: .8rem; }
+.vw-play:disabled { background: var(--vw-line); cursor: not-allowed; }
+.vw-name { font-weight: 600; flex: 1 1 auto; }
+.vw-badge { font-size: .68rem; padding: .15rem .4rem; border: 1px solid var(--vw-line);
+  border-radius: 999px; color: var(--vw-muted); white-space: nowrap; }
+.vw-meta { display: flex; flex-wrap: wrap; gap: .35rem; font-size: .7rem; color: var(--vw-muted); }
+.vw-meta span { padding: .12rem .4rem; background: #0d1014; border-radius: 6px; }
+.vw-gender.vw-male { color: #6db3ff; } .vw-gender.vw-female { color: #ff9eec; }
+.vw-sample { margin: 0; font-size: .82rem; color: #cfd6e2; font-style: italic; }
+.vw-note { margin: 0; font-size: .72rem; color: #ff9b6b; }
+.vw-copy { align-self: flex-start; font-size: .72rem; background: transparent; color: var(--vw-accent);
+  border: 1px solid var(--vw-line); border-radius: 6px; padding: .25rem .5rem; cursor: pointer; }
diff --git a/fern/components/voice-widget.tsx b/fern/components/voice-widget.tsx
new file mode 100644
index 0000000000..b0828a6ae3
--- /dev/null
+++ b/fern/components/voice-widget.tsx
@@ -0,0 +1,357 @@
+import { memo, useCallback, useDeferredValue, useEffect, useMemo, useRef, useState } from "react";
+import type { CSSProperties } from "react";
+import type { Catalog, Manifest, VoiceRow } from "./types";
+import { Skeleton } from "./skeleton";
+
+// Ported from @signalwire/tts-voice-widget for embedding as a Fern MDX component.
+// Pure data consumer: fetches catalog.json + manifest.json produced by the TTS pipeline and plays
+// the pre-synthesized sample clips. Styles live in voice-widget.css + voice-widget-overrides.css,
+// loaded via docs.yml `css:` (Fern's component bundler does not process CSS imports).
+
+// Single source of truth for where the asset bundle (catalog.json + manifest.json + audio/) is
+// hosted. The bundle cannot live in fern/assets — Fern only serves assets it statically discovers
+// in MDX/CSS and rewrites to content-hashed URLs, so a runtime fetch() has no resolvable path.
+// It must be served from an external origin with CORS enabled on the JSON. Flip this one string
+// to move between hosts; the three URLs (catalog/manifest/audio) all derive from it.
+//
+// Cloudflare quick tunnel to the local CDN (`http-server temp/voice_widget/dist -p 8080 --cors -g`),
+// so a tunnelled docs preview can be shared and fetch assets over HTTPS from a host every viewer
+// can resolve. Ephemeral: quick-tunnel URLs change on every cloudflared restart — update this and
+// restart the docs dev server to re-bundle. For local-only dev set to "http://localhost:8080".
+// Swap to the production CDN base URL when one is available.
+const ASSET_BASE = "https://trainers-babies-ctrl-thrown.trycloudflare.com";
+
+const ALL = "__all__";
+const DEFAULT_PAGE_SIZE = 60;
+const MOBILE_PAGE_SIZE = 12;
+const MOBILE_QUERY = "(max-width: 640px)";
+
+// Tracks whether the viewport is in the mobile breakpoint (matches the CSS media query below).
+function useIsMobile() {
+  const [mobile, setMobile] = useState(false);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia(MOBILE_QUERY);
+    const update = () => setMobile(mq.matches);
+    update();
+    mq.addEventListener("change", update);
+    return () => mq.removeEventListener("change", update);
+  }, []);
+  return mobile;
+}
+
+export interface VoiceWidgetProps {
+  /** Base URL of the hosted bundle (serves catalog.json, manifest.json, audio/). Default: ASSET_BASE. */
+  assetBaseUrl?: string;
+  /** Override the catalog.json URL. Default: `${assetBaseUrl}/catalog.json`. */
+  catalogUrl?: string;
+  /** Override the manifest.json URL. Default: `${assetBaseUrl}/manifest.json`. */
+  manifestUrl?: string;
+  /** Override the base the clip `audio` paths resolve against. Default: assetBaseUrl. */
+  audioBaseUrl?: string;
+  /** Initial grouping. Default: "provider". */
+  groupBy?: "provider" | "language";
+  /** Cards rendered per page (page-size limit). Default: 60. Keeps the DOM small and the catalog fast. */
+  pageSize?: number;
+  /**
+   * Fixed number of grid columns. When unset, the grid auto-fills responsively (≈240px min per
+   * card). When set, it renders exactly this many columns.
+   */
+  columns?: number;
+  /**
+   * Lock the widget to a single provider. Matches the provider label or engine id,
+   * case-insensitive (e.g. "ElevenLabs" or "elevenlabs"). When set, only that provider's voices
+   * are shown and the provider filter is hidden — for embedding on a provider-specific page.
+   */
+  provider?: string;
+}
+
+export function VoiceWidget({
+  assetBaseUrl = ASSET_BASE,
+  catalogUrl = `${assetBaseUrl}/catalog.json`,
+  manifestUrl = `${assetBaseUrl}/manifest.json`,
+  audioBaseUrl = assetBaseUrl,
+  groupBy: initialGroup = "provider",
+  pageSize = DEFAULT_PAGE_SIZE,
+  columns,
+  provider: lockedProvider,
+}: VoiceWidgetProps) {
+  // Normalized single-provider lock (null when the widget shows all providers).
+  const lock = lockedProvider?.trim().toLowerCase() || null;
+  // Fixed column count overrides the responsive auto-fill grid when provided. Set as CSS custom
+  // properties (consumed by .vw-grid in the stylesheet) rather than grid-template-columns directly,
+  // so the mobile media query can still collapse the grid to one column regardless of this prop.
+  const gridStyle = (columns && columns > 0
+    ? { "--vw-cols": Math.floor(columns), "--vw-col-min": "0px" }
+    : undefined) as CSSProperties | undefined;
+  const [rows, setRows] = useState<VoiceRow[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [q, setQ] = useState("");
+  const [provider, setProvider] = useState(ALL);
+  const [language, setLanguage] = useState(ALL);
+  const [gender, setGender] = useState(ALL);
+  const [group, setGroup] = useState<"provider" | "language">(initialGroup);
+  const [page, setPage] = useState(0);
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const [playingKey, setPlayingKey] = useState<string | null>(null);
+
+  // Defer the search term so typing stays responsive while the (cheap) filter recomputes.
+  const deferredQ = useDeferredValue(q);
+
+  // On small screens the grid collapses to one column (CSS), so cap the page size too — a 60-card
+  // single column is an excessive scroll on a phone.
+  const isMobile = useIsMobile();
+  const effectivePageSize = isMobile ? Math.min(pageSize, MOBILE_PAGE_SIZE) : pageSize;
+
+  useEffect(() => {
+    let alive = true;
+    (async () => {
+      try {
+        const [cat, man] = await Promise.all([
+          fetch(catalogUrl).then((r) => r.json() as Promise<Catalog>),
+          fetch(manifestUrl).then((r) => r.json() as Promise<Manifest>).catch(() => ({ clips: {} } as Manifest)),
+        ]);
+        if (!alive) return;
+        setRows(cat.voices.map((v) => ({ ...v, clip: man.clips?.[v.key] })));
+      } catch (e) {
+        if (alive) setError(String(e));
+      }
+    })();
+    return () => { alive = false; };
+  }, [catalogUrl, manifestUrl]);
+
+  const providers = useMemo(() => uniq(rows?.map((r) => r.provider)), [rows]);
+  const languages = useMemo(() => uniq(rows?.flatMap((r) => r.languages)), [rows]);
+
+  const filtered = useMemo(() => {
+    if (!rows) return [];
+    const needle = deferredQ.trim().toLowerCase();
+    return rows.filter((r) =>
+      (!lock || r.provider.toLowerCase() === lock || r.engine.toLowerCase() === lock) &&
+      (provider === ALL || r.provider === provider) &&
+      (language === ALL || r.languages.includes(language)) &&
+      (gender === ALL || r.gender === gender) &&
+      (!needle ||
+        r.display_name.toLowerCase().includes(needle) ||
+        r.provider.toLowerCase().includes(needle) ||
+        r.description.toLowerCase().includes(needle) ||
+        r.tags.join(" ").toLowerCase().includes(needle)));
+  }, [rows, lock, deferredQ, provider, language, gender]);
+
+  // Flatten into grouped order once, and remember each group's full size for the section headers.
+  const { ordered, groupTotals } = useMemo(() => {
+    const m = new Map<string, VoiceRow[]>();
+    for (const r of filtered) {
+      const k = group === "provider" ? r.provider : r.primary_language;
+      (m.get(k) ?? m.set(k, []).get(k)!).push(r);
+    }
+    const entries = [...m.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    const ordered: VoiceRow[] = [];
+    const groupTotals = new Map<string, number>();
+    for (const [name, items] of entries) {
+      groupTotals.set(name, items.length);
+      for (const it of items) ordered.push(it);
+    }
+    return { ordered, groupTotals };
+  }, [filtered, group]);
+
+  // Reset to the first page whenever the result set changes — done during render (not in an
+  // effect) so there's no one-frame flash of the old page number. Canonical "adjust state on
+  // change" pattern: the setState below re-renders synchronously before commit.
+  const filterSig = `${lock}|${deferredQ}|${provider}|${language}|${gender}|${group}`;
+  const [lastSig, setLastSig] = useState(filterSig);
+  if (filterSig !== lastSig) {
+    setLastSig(filterSig);
+    if (page !== 0) setPage(0);
+  }
+
+  // Pagination math. Clamp the page so it stays valid even mid-transition.
+  const pageCount = Math.max(1, Math.ceil(ordered.length / effectivePageSize));
+  const safePage = Math.min(page, pageCount - 1);
+  const start = safePage * effectivePageSize;
+  const end = Math.min(start + effectivePageSize, ordered.length);
+
+  // Split the current page's slice into contiguous group sections (reuses the section/grid DOM).
+  const pageSections = useMemo(() => {
+    const secs: { name: string; items: VoiceRow[] }[] = [];
+    for (const r of ordered.slice(start, end)) {
+      const k = group === "provider" ? r.provider : r.primary_language;
+      const last = secs[secs.length - 1];
+      if (last && last.name === k) last.items.push(r);
+      else secs.push({ name: k, items: [r] });
+    }
+    return secs;
+  }, [ordered, start, end, group]);
+
+  // Keep the latest playing key in a ref so play() can stay referentially stable (memoized cards).
+  const playingKeyRef = useRef<string | null>(null);
+  useEffect(() => { playingKeyRef.current = playingKey; }, [playingKey]);
+
+  const play = useCallback((r: VoiceRow) => {
+    if (!r.clip || r.clip.status !== "ok") return;
+    const url = audioBaseUrl ? `${audioBaseUrl.replace(/\/$/, "")}/${r.clip.audio}` : r.clip.audio;
+    const a = audioRef.current!;
+    if (playingKeyRef.current === r.key && !a.paused) { a.pause(); setPlayingKey(null); return; }
+    a.src = url;
+    a.play().then(() => setPlayingKey(r.key)).catch(() => setPlayingKey(null));
+  }, [audioBaseUrl]);
+
+  const copyConfig = useCallback(async (r: VoiceRow) => {
+    const cfg: Record<string, unknown> = { engine: r.engine, voice: r.display_name };
+    if (r.model) cfg.params = { model: r.model };
+    try {
+      await navigator.clipboard.writeText(JSON.stringify(cfg));
+      return true;
+    } catch {
+      return false;
+    }
+  }, []);
+
+  if (error) return <div className="vw vw-error">Failed to load voices: {error}</div>;
+  if (!rows) return <VoiceWidgetSkeleton gridStyle={gridStyle} />;
+
+  const pager = pageCount > 1 ? (
+    <nav className="vw-pager" aria-label="Voice pages">
+      <button className="vw-pager-btn" onClick={() => setPage((p) => Math.max(0, p - 1))} disabled={safePage <= 0}>
+        ‹ Prev
+      </button>
+      <span className="vw-pager-info">
+        {ordered.length ? `${start + 1}–${end} of ${ordered.length}` : "0 of 0"}
+        <span className="vw-pager-page"> · page {safePage + 1}/{pageCount}</span>
+      </span>
+      <button className="vw-pager-btn" onClick={() => setPage((p) => Math.min(pageCount - 1, p + 1))} disabled={safePage >= pageCount - 1}>
+        Next ›
+      </button>
+    </nav>
+  ) : null;
+
+  return (
+    <div className="vw">
+      <audio ref={audioRef} onEnded={() => setPlayingKey(null)} preload="none" />
+      <header className="vw-head">
+        <div className="vw-title">TTS Voices <span className="vw-count">{filtered.length}</span></div>
+        <input className="vw-search" placeholder="Search voices…" value={q}
+               onChange={(e) => setQ(e.target.value)} />
+      </header>
+
+      <div className="vw-filters">
+        {!lock && <Select label="Provider" value={provider} onChange={setProvider} opts={providers} />}
+        <Select label="Language" value={language} onChange={setLanguage} opts={languages} />
+        <Select label="Gender" value={gender} onChange={setGender}
+                opts={["male", "female", "neutral", "unknown"]} />
+        <div className="vw-group">
+          <button className={group === "provider" ? "on" : ""} onClick={() => setGroup("provider")}>by provider</button>
+          <button className={group === "language" ? "on" : ""} onClick={() => setGroup("language")}>by language</button>
+        </div>
+      </div>
+
+      {pager}
+
+      {pageSections.length === 0 ? (
+        <p className="vw-empty">No voices match your filters.</p>
+      ) : (
+        pageSections.map((sec, i) => (
+          <section key={`${sec.name}-${i}`} className="vw-section">
+            <h3 className="vw-section-title">{sec.name} <span>{groupTotals.get(sec.name)}</span></h3>
+            <div className="vw-grid" style={gridStyle}>
+              {sec.items.map((r) => (
+                <Card key={r.key} r={r} playing={playingKey === r.key} onPlay={play} onCopy={copyConfig} />
+              ))}
+            </div>
+          </section>
+        ))
+      )}
+
+      {pager}
+    </div>
+  );
+}
+
+// Memoized so that playing/pausing a voice (which re-renders the widget) only re-renders the two
+// cards whose `playing` flag actually changed — not all ~60 cards on the page.
+const Card = memo(function Card({ r, playing, onPlay, onCopy }: {
+  r: VoiceRow; playing: boolean; onPlay: (r: VoiceRow) => void; onCopy: (r: VoiceRow) => Promise<boolean> | void;
+}) {
+  const disabled = !r.clip || r.clip.status !== "ok";
+  const [copied, setCopied] = useState(false);
+  const copyTimer = useRef<ReturnType<typeof setTimeout>>();
+  useEffect(() => () => clearTimeout(copyTimer.current), []);
+
+  const handleCopy = () => {
+    Promise.resolve(onCopy(r)).then((ok) => {
+      if (ok === false) return; // clipboard unavailable — leave the button unchanged
+      setCopied(true);
+      clearTimeout(copyTimer.current);
+      copyTimer.current = setTimeout(() => setCopied(false), 1500);
+    });
+  };
+
+  return (
+    <article className={`vw-card${r.clip?.status === "error" || !r.clip ? " vw-disabled" : ""}`}>
+      <div className="vw-card-top">
+        <button className="vw-play" disabled={disabled} onClick={() => onPlay(r)}
+                aria-label={`Play ${r.display_name}`}>{playing ? "❚❚" : "▶"}</button>
+        <div className="vw-name">{r.display_name}</div>
+        <span className="vw-badge">{r.provider}</span>
+      </div>
+      <div className="vw-meta">
+        <span className="vw-lang">{r.primary_language}</span>
+        <span className={`vw-gender vw-${r.gender}`}>{r.gender}</span>
+        {r.model && <span className="vw-model">{r.model}</span>}
+      </div>
+      {r.clip?.sample_text && <p className="vw-sample">“{r.clip.sample_text}”</p>}
+      {(!r.clip || r.clip.status === "error") &&
+        <p className="vw-note">{r.clip?.error ?? "no sample (provider key missing)"}</p>}
+      <button className={`vw-copy${copied ? " vw-copied" : ""}`} onClick={handleCopy} aria-live="polite">
+        {copied ? "copied ✓" : "copy config"}
+      </button>
+    </article>
+  );
+});
+
+// Loading state: skeleton placeholders that mirror the real header + card grid, so the layout
+// doesn't jump when the data arrives. Built from the shared <Skeleton> primitive.
+function VoiceWidgetSkeleton({ gridStyle }: { gridStyle?: CSSProperties }) {
+  return (
+    <div className="vw" aria-busy="true" aria-label="Loading voices">
+      <header className="vw-head">
+        <Skeleton width={150} height={22} />
+        <Skeleton width={220} height={36} radius={10} style={{ marginLeft: "auto" }} />
+      </header>
+      <div className="vw-grid" style={gridStyle}>
+        {Array.from({ length: 8 }).map((_, i) => (
+          <article key={i} className="vw-card">
+            <div className="vw-card-top">
+              <Skeleton width={32} height={32} radius="50%" />
+              <Skeleton width="55%" height={14} />
+            </div>
+            <div className="vw-meta">
+              <Skeleton width={48} height={16} radius={6} />
+              <Skeleton width={42} height={16} radius={6} />
+            </div>
+            <Skeleton width="90%" height={11} />
+            <Skeleton width="70%" height={11} />
+            <Skeleton width={84} height={26} radius={6} />
+          </article>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function Select({ label, value, onChange, opts }:
+  { label: string; value: string; onChange: (v: string) => void; opts: string[] }) {
+  return (
+    <label className="vw-select">
+      <span>{label}</span>
+      <select value={value} onChange={(e) => onChange(e.target.value)}>
+        <option value={ALL}>all</option>
+        {opts.map((o) => <option key={o} value={o}>{o}</option>)}
+      </select>
+    </label>
+  );
+}
+
+function uniq(xs?: string[]): string[] {
+  return [...new Set((xs ?? []).filter(Boolean))].sort();
+}
diff --git a/fern/docs.yml b/fern/docs.yml
index f18bcbd0da..242d2b25cc 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -30,6 +30,8 @@ agents:
 
 experimental:
   ai-examples: false
+  mdx-components:
+    - ./components
 
 products:
   - display-name: Home
@@ -173,6 +175,9 @@ css:
   - brand-tokens.css
   - brand-overrides.css
   - styles.css
+  - components/skeleton.css
+  - components/voice-widget.css
+  - voice-widget-overrides.css
 
 redirects:
   - source: /docs/agents-sdk
diff --git a/fern/products/platform/pages/calling/voice/TTS/index.mdx b/fern/products/platform/pages/calling/voice/TTS/index.mdx
index 41a6549e98..7ba36c8d96 100644
--- a/fern/products/platform/pages/calling/voice/TTS/index.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/index.mdx
@@ -29,6 +29,15 @@ SignalWire integrates natively with leading third-party text-to-speech (TTS) pro
 This guide describes supported engines, voices, and languages.
 Refer to each provider's documentation for up-to-date model details and service information.
 
+## Browse and audition voices
+
+import { VoiceWidget } from "@/components/voice-widget";
+
+Search and filter every supported voice by provider, language, and gender, and play a sample clip
+for each. Use **copy config** to grab the engine and voice values to drop into your SWML or SDK code.
+
+<VoiceWidget columns={4} />
+
 ## Compare providers and models
 
 SignalWire's TTS providers offer a wide range of voice engines optimized for various applications.
diff --git a/fern/voice-widget-overrides.css b/fern/voice-widget-overrides.css
new file mode 100644
index 0000000000..dca3e28c4c
--- /dev/null
+++ b/fern/voice-widget-overrides.css
@@ -0,0 +1,71 @@
+/* Voice widget — docs theme overrides.
+   The bundled widget stylesheet (fern/components/voice-widget.css) ships a fixed dark palette.
+   This layer, loaded AFTER it in docs.yml `css`, remaps the widget's scoped --vw-* variables onto
+   the docs' theme-aware brand tokens so the widget follows light/dark mode. Kept separate from the
+   widget's own CSS so widget updates aren't clobbered by local edits. */
+.vw {
+  --vw-bg: var(--bg-page);
+  --vw-card: var(--bg-surface-raised);
+  --vw-line: var(--border-default);
+  --vw-fg: var(--fg-default);
+  --vw-muted: var(--fg-muted);
+  --vw-accent: var(--accent);
+}
+
+/* Hardcoded colors in the widget that don't flow through the --vw-* variables: */
+.vw-play { color: var(--accent-contrast); }                                /* was #fff */
+.vw-play:disabled { color: var(--fg-muted); }
+.vw-group button.on { color: var(--accent); background: var(--accent-a3); } /* was #fff on transparent */
+.vw-meta span { background: var(--grayscale-a3); }                         /* was #0d1014 */
+.vw-sample { color: var(--fg-secondary); }                                 /* was #cfd6e2 */
+.vw-note { color: var(--warning-text); }                                   /* was #ff9b6b */
+.vw-error { color: var(--error-text); }                                    /* was #ff6b6b */
+.vw-gender.vw-male { color: #3b82f6; }                                     /* readable on both themes */
+.vw-gender.vw-female { color: #d6409f; }
+
+/* Pagination controls + empty state (added with the component's pagination feature). */
+.vw-pager { display: flex; align-items: center; justify-content: center; gap: .75rem;
+  margin: 1rem 0; flex-wrap: wrap; }
+.vw-pager-btn { padding: .4rem .8rem; background: var(--grayscale-2); color: var(--fg-default);
+  border: 1px solid var(--border-default); border-radius: 8px; cursor: pointer; font-size: .82rem; }
+.vw-pager-btn:hover:not(:disabled) { border-color: var(--accent); color: var(--accent); }
+.vw-pager-btn:disabled { opacity: .45; cursor: not-allowed; }
+.vw-pager-info { font-size: .8rem; color: var(--fg-muted); }
+.vw-pager-page { color: var(--fg-muted); }
+.vw-empty { padding: 2rem 0; color: var(--fg-muted); font-size: .9rem; }
+
+/* "copy config" → copied feedback state. */
+.vw-copy.vw-copied { color: var(--accent); border-color: var(--accent); background: var(--accent-a3); }
+
+/* --- Responsive grid ---
+   Column count is driven by --vw-cols (set inline by the `columns` prop; falls back to responsive
+   auto-fill). Defining the template here (rather than inline) lets the mobile media query below
+   override it regardless of the prop. */
+.vw-grid {
+  grid-template-columns: repeat(var(--vw-cols, auto-fill), minmax(var(--vw-col-min, 240px), 1fr));
+}
+
+/* On phones, collapse to a single column no matter what `columns` was set to. */
+@media (max-width: 640px) {
+  .vw-grid { grid-template-columns: 1fr; }
+  .vw-filters { gap: .5rem; }
+  .vw-search { min-width: 0; }
+}
+
+/* --- Card header: keep the name + provider badge inside the card, never overlapping ---
+   The name is the flex item that must be allowed to shrink (min-width:0) and truncate; the badge
+   keeps its size and won't be pushed out. */
+.vw-card { overflow: hidden; }
+.vw-card-top { min-width: 0; }
+.vw-name {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.vw-badge {
+  flex: 0 0 auto;
+  max-width: 50%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}

From b84cc6794790e5a0823865b81c33c65571e4218c Mon Sep 17 00:00:00 2001
From: Devon-White <devon.white@signalwire.com>
Date: Mon, 8 Jun 2026 15:55:25 -0400
Subject: [PATCH 2/7] Updates

---
 fern/components/index.tsx                     |   8 +
 .../{skeleton.tsx => skeleton/index.tsx}      |   0
 .../{skeleton.css => skeleton/styles.css}     |   0
 fern/components/voice-widget.css              |  47 ------
 .../index.tsx}                                | 138 ++++++++++++++----
 fern/components/voice-widget/styles.css       |  82 +++++++++++
 fern/components/{ => voice-widget}/types.ts   |   0
 fern/voice-widget-overrides.css               |  71 ---------
 8 files changed, 196 insertions(+), 150 deletions(-)
 create mode 100644 fern/components/index.tsx
 rename fern/components/{skeleton.tsx => skeleton/index.tsx} (100%)
 rename fern/components/{skeleton.css => skeleton/styles.css} (100%)
 delete mode 100644 fern/components/voice-widget.css
 rename fern/components/{voice-widget.tsx => voice-widget/index.tsx} (69%)
 create mode 100644 fern/components/voice-widget/styles.css
 rename fern/components/{ => voice-widget}/types.ts (100%)
 delete mode 100644 fern/voice-widget-overrides.css

diff --git a/fern/components/index.tsx b/fern/components/index.tsx
new file mode 100644
index 0000000000..289efdaf69
--- /dev/null
+++ b/fern/components/index.tsx
@@ -0,0 +1,8 @@
+// Barrel for docs MDX components. Each component lives in its own subdirectory as an index.tsx
+// for organization. MDX pages import this barrel as a file path —
+// `import { VoiceWidget } from "@/components/index"` — because Fern's resolver only resolves file
+// paths, not directories (and not directory→index). For the same reason the re-exports below use
+// explicit `/index` file paths rather than bare directory paths. `export *` pulls in each
+// component's public surface (components + types) without enumerating them.
+export * from "./voice-widget/index";
+export * from "./skeleton/index";
diff --git a/fern/components/skeleton.tsx b/fern/components/skeleton/index.tsx
similarity index 100%
rename from fern/components/skeleton.tsx
rename to fern/components/skeleton/index.tsx
diff --git a/fern/components/skeleton.css b/fern/components/skeleton/styles.css
similarity index 100%
rename from fern/components/skeleton.css
rename to fern/components/skeleton/styles.css
diff --git a/fern/components/voice-widget.css b/fern/components/voice-widget.css
deleted file mode 100644
index e8bf99c785..0000000000
--- a/fern/components/voice-widget.css
+++ /dev/null
@@ -1,47 +0,0 @@
-/* Scoped under .vw so the widget can be dropped into the docs without clobbering host styles. */
-.vw {
-  --vw-bg: #0e1116; --vw-card: #171b22; --vw-line: #262c36; --vw-fg: #e6e9ef;
-  --vw-muted: #8b95a5; --vw-accent: #3a86ff; --vw-radius: 10px;
-  color: var(--vw-fg); font: 14px/1.45 system-ui, sans-serif;
-}
-.vw-loading, .vw-error { padding: 2rem; color: var(--vw-muted); }
-.vw-error { color: #ff6b6b; }
-
-.vw-head { display: flex; align-items: center; gap: 1rem; margin-bottom: .75rem; }
-.vw-title { font-size: 1.15rem; font-weight: 700; }
-.vw-count { color: var(--vw-muted); font-weight: 400; margin-left: .35rem; }
-.vw-search { margin-left: auto; padding: .5rem .75rem; min-width: 220px;
-  background: var(--vw-card); border: 1px solid var(--vw-line); border-radius: var(--vw-radius); color: inherit; }
-
-.vw-filters { display: flex; flex-wrap: wrap; gap: .75rem; align-items: end; margin-bottom: 1rem;
-  position: sticky; top: 0; background: var(--vw-bg); padding: .5rem 0; z-index: 2; }
-.vw-select { display: flex; flex-direction: column; gap: .2rem; font-size: .8rem; color: var(--vw-muted); }
-.vw-select select { padding: .4rem .5rem; background: var(--vw-card); color: var(--vw-fg);
-  border: 1px solid var(--vw-line); border-radius: 8px; }
-.vw-group { display: flex; gap: .25rem; margin-left: auto; }
-.vw-group button { padding: .4rem .6rem; background: var(--vw-card); color: var(--vw-muted);
-  border: 1px solid var(--vw-line); border-radius: 8px; cursor: pointer; }
-.vw-group button.on { color: #fff; border-color: var(--vw-accent); }
-
-.vw-section { margin-bottom: 1.5rem; }
-.vw-section-title { font-size: .95rem; margin: .5rem 0; text-transform: capitalize; }
-.vw-section-title span { color: var(--vw-muted); font-weight: 400; margin-left: .35rem; }
-
-.vw-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: .75rem; }
-.vw-card { background: var(--vw-card); border: 1px solid var(--vw-line); border-radius: var(--vw-radius);
-  padding: .75rem; display: flex; flex-direction: column; gap: .5rem; }
-.vw-card.vw-disabled { opacity: .55; }
-.vw-card-top { display: flex; align-items: center; gap: .5rem; }
-.vw-play { width: 32px; height: 32px; flex: 0 0 auto; border-radius: 50%; cursor: pointer;
-  background: var(--vw-accent); color: #fff; border: none; font-size: .8rem; }
-.vw-play:disabled { background: var(--vw-line); cursor: not-allowed; }
-.vw-name { font-weight: 600; flex: 1 1 auto; }
-.vw-badge { font-size: .68rem; padding: .15rem .4rem; border: 1px solid var(--vw-line);
-  border-radius: 999px; color: var(--vw-muted); white-space: nowrap; }
-.vw-meta { display: flex; flex-wrap: wrap; gap: .35rem; font-size: .7rem; color: var(--vw-muted); }
-.vw-meta span { padding: .12rem .4rem; background: #0d1014; border-radius: 6px; }
-.vw-gender.vw-male { color: #6db3ff; } .vw-gender.vw-female { color: #ff9eec; }
-.vw-sample { margin: 0; font-size: .82rem; color: #cfd6e2; font-style: italic; }
-.vw-note { margin: 0; font-size: .72rem; color: #ff9b6b; }
-.vw-copy { align-self: flex-start; font-size: .72rem; background: transparent; color: var(--vw-accent);
-  border: 1px solid var(--vw-line); border-radius: 6px; padding: .25rem .5rem; cursor: pointer; }
diff --git a/fern/components/voice-widget.tsx b/fern/components/voice-widget/index.tsx
similarity index 69%
rename from fern/components/voice-widget.tsx
rename to fern/components/voice-widget/index.tsx
index b0828a6ae3..dc2e59fa16 100644
--- a/fern/components/voice-widget.tsx
+++ b/fern/components/voice-widget/index.tsx
@@ -1,7 +1,7 @@
 import { memo, useCallback, useDeferredValue, useEffect, useMemo, useRef, useState } from "react";
 import type { CSSProperties } from "react";
 import type { Catalog, Manifest, VoiceRow } from "./types";
-import { Skeleton } from "./skeleton";
+import { Skeleton } from "../skeleton/index";
 
 // Ported from @signalwire/tts-voice-widget for embedding as a Fern MDX component.
 // Pure data consumer: fetches catalog.json + manifest.json produced by the TTS pipeline and plays
@@ -19,12 +19,16 @@ import { Skeleton } from "./skeleton";
 // can resolve. Ephemeral: quick-tunnel URLs change on every cloudflared restart — update this and
 // restart the docs dev server to re-bundle. For local-only dev set to "http://localhost:8080".
 // Swap to the production CDN base URL when one is available.
-const ASSET_BASE = "https://trainers-babies-ctrl-thrown.trycloudflare.com";
+const ASSET_BASE = "https://warming-watched-physics-assistance.trycloudflare.com";
 
 const ALL = "__all__";
-const DEFAULT_PAGE_SIZE = 60;
+const DEFAULT_PAGE_SIZE = 48;
 const MOBILE_PAGE_SIZE = 12;
 const MOBILE_QUERY = "(max-width: 640px)";
+// Multiples of the max column count (4) so every page fills complete rows; 4 = a single row.
+const PAGE_SIZE_OPTIONS = [4, 8, 12, 24, 48, 96];
+
+type FilterKey = "search" | "provider" | "language" | "gender" | "group" | "pageSize";
 
 // Tracks whether the viewport is in the mobile breakpoint (matches the CSS media query below).
 function useIsMobile() {
@@ -49,13 +53,13 @@ export interface VoiceWidgetProps {
   manifestUrl?: string;
   /** Override the base the clip `audio` paths resolve against. Default: assetBaseUrl. */
   audioBaseUrl?: string;
-  /** Initial grouping. Default: "provider". */
-  groupBy?: "provider" | "language";
-  /** Cards rendered per page (page-size limit). Default: 60. Keeps the DOM small and the catalog fast. */
+  /** Initial grouping. "none" renders a flat grid with no section headers or group toggle. Default: "provider". */
+  groupBy?: "provider" | "language" | "none";
+  /** Cards rendered per page (page-size limit). Default: 48. Keeps the DOM small and the catalog fast. */
   pageSize?: number;
   /**
-   * Fixed number of grid columns. When unset, the grid auto-fills responsively (≈240px min per
-   * card). When set, it renders exactly this many columns.
+   * Fixed number of grid columns. Default: 3. Collapses to 1 column on phones regardless. Pass 0
+   * for a responsive auto-fill grid (≈240px min per card) instead of a fixed count.
    */
   columns?: number;
   /**
@@ -64,6 +68,20 @@ export interface VoiceWidgetProps {
    * are shown and the provider filter is hidden — for embedding on a provider-specific page.
    */
   provider?: string;
+  /**
+   * Show only these specific voices (an allowlist). Each entry matches a voice's `voice_id`, its
+   * `<engine>/<voice_id>` key, its `<engine>/<voice_id>:<model>` key (to disambiguate a voice that
+   * exists under multiple models), or its display name — case-insensitive. When unset, all voices
+   * show. Use to curate a small demo set, e.g. one representative voice per provider.
+   */
+  voiceIds?: string[];
+  /**
+   * Toggle the filter/search controls. `true` or unset shows all; `false` hides all (just the
+   * title + grid). An object toggles individual controls — `search`, `provider`, `language`,
+   * `gender`, `group`, `pageSize` — each defaulting on unless set `false`. The provider control is
+   * always hidden when the `provider` lock prop is set.
+   */
+  filters?: boolean | Partial<Record<FilterKey, boolean>>;
 }
 
 export function VoiceWidget({
@@ -73,11 +91,22 @@ export function VoiceWidget({
   audioBaseUrl = assetBaseUrl,
   groupBy: initialGroup = "provider",
   pageSize = DEFAULT_PAGE_SIZE,
-  columns,
+  columns = 3,
   provider: lockedProvider,
+  voiceIds,
+  filters,
 }: VoiceWidgetProps) {
   // Normalized single-provider lock (null when the widget shows all providers).
   const lock = lockedProvider?.trim().toLowerCase() || null;
+  // Normalized voice-id allowlist (null when showing all voices). Sorted+joined into a stable key
+  // so the memoized Set below — and the filter that depends on it — don't churn each render.
+  const voiceIdsKey = voiceIds && voiceIds.length
+    ? voiceIds.map((s) => s.trim().toLowerCase()).filter(Boolean).sort().join("|")
+    : "";
+  const idAllowlist = useMemo(
+    () => (voiceIdsKey ? new Set(voiceIdsKey.split("|")) : null),
+    [voiceIdsKey]
+  );
   // Fixed column count overrides the responsive auto-fill grid when provided. Set as CSS custom
   // properties (consumed by .vw-grid in the stylesheet) rather than grid-template-columns directly,
   // so the mobile media query can still collapse the grid to one column regardless of this prop.
@@ -90,8 +119,9 @@ export function VoiceWidget({
   const [provider, setProvider] = useState(ALL);
   const [language, setLanguage] = useState(ALL);
   const [gender, setGender] = useState(ALL);
-  const [group, setGroup] = useState<"provider" | "language">(initialGroup);
+  const [group, setGroup] = useState<"provider" | "language" | "none">(initialGroup);
   const [page, setPage] = useState(0);
+  const [pageSizeChoice, setPageSizeChoice] = useState(pageSize);
   const audioRef = useRef<HTMLAudioElement | null>(null);
   const [playingKey, setPlayingKey] = useState<string | null>(null);
 
@@ -101,7 +131,17 @@ export function VoiceWidget({
   // On small screens the grid collapses to one column (CSS), so cap the page size too — a 60-card
   // single column is an excessive scroll on a phone.
   const isMobile = useIsMobile();
-  const effectivePageSize = isMobile ? Math.min(pageSize, MOBILE_PAGE_SIZE) : pageSize;
+  const effectivePageSize = isMobile ? Math.min(pageSizeChoice, MOBILE_PAGE_SIZE) : pageSizeChoice;
+  const pageSizeOpts = [...new Set([...PAGE_SIZE_OPTIONS, pageSize])].sort((a, b) => a - b);
+
+  // Resolve which filter/search controls are visible. `filters` is a boolean (all on/off) or a
+  // per-control object; each control defaults on unless explicitly false.
+  const showFilter = (key: FilterKey) =>
+    filters === false ? false
+    : filters && typeof filters === "object" ? filters[key] !== false
+    : true;
+  const showProvider = !lock && showFilter("provider");
+  const showGroup = group !== "none" && showFilter("group");
 
   useEffect(() => {
     let alive = true;
@@ -127,6 +167,11 @@ export function VoiceWidget({
     if (!rows) return [];
     const needle = deferredQ.trim().toLowerCase();
     return rows.filter((r) =>
+      (!idAllowlist ||
+        idAllowlist.has(r.voice_id.toLowerCase()) ||
+        idAllowlist.has(r.key.toLowerCase()) ||
+        idAllowlist.has(uidOf(r).toLowerCase()) ||
+        idAllowlist.has(r.display_name.toLowerCase())) &&
       (!lock || r.provider.toLowerCase() === lock || r.engine.toLowerCase() === lock) &&
       (provider === ALL || r.provider === provider) &&
       (language === ALL || r.languages.includes(language)) &&
@@ -136,10 +181,12 @@ export function VoiceWidget({
         r.provider.toLowerCase().includes(needle) ||
         r.description.toLowerCase().includes(needle) ||
         r.tags.join(" ").toLowerCase().includes(needle)));
-  }, [rows, lock, deferredQ, provider, language, gender]);
+  }, [rows, idAllowlist, lock, deferredQ, provider, language, gender]);
 
   // Flatten into grouped order once, and remember each group's full size for the section headers.
+  // group === "none" keeps the filtered order as-is, with no sections.
   const { ordered, groupTotals } = useMemo(() => {
+    if (group === "none") return { ordered: filtered, groupTotals: new Map<string, number>() };
     const m = new Map<string, VoiceRow[]>();
     for (const r of filtered) {
       const k = group === "provider" ? r.provider : r.primary_language;
@@ -158,7 +205,7 @@ export function VoiceWidget({
   // Reset to the first page whenever the result set changes — done during render (not in an
   // effect) so there's no one-frame flash of the old page number. Canonical "adjust state on
   // change" pattern: the setState below re-renders synchronously before commit.
-  const filterSig = `${lock}|${deferredQ}|${provider}|${language}|${gender}|${group}`;
+  const filterSig = `${voiceIdsKey}|${lock}|${deferredQ}|${provider}|${language}|${gender}|${group}|${pageSizeChoice}`;
   const [lastSig, setLastSig] = useState(filterSig);
   if (filterSig !== lastSig) {
     setLastSig(filterSig);
@@ -172,9 +219,12 @@ export function VoiceWidget({
   const end = Math.min(start + effectivePageSize, ordered.length);
 
   // Split the current page's slice into contiguous group sections (reuses the section/grid DOM).
+  // group === "none" → a single unlabeled section (flat grid).
   const pageSections = useMemo(() => {
+    const slice = ordered.slice(start, end);
+    if (group === "none") return slice.length ? [{ name: "", items: slice }] : [];
     const secs: { name: string; items: VoiceRow[] }[] = [];
-    for (const r of ordered.slice(start, end)) {
+    for (const r of slice) {
       const k = group === "provider" ? r.provider : r.primary_language;
       const last = secs[secs.length - 1];
       if (last && last.name === k) last.items.push(r);
@@ -189,11 +239,12 @@ export function VoiceWidget({
 
   const play = useCallback((r: VoiceRow) => {
     if (!r.clip || r.clip.status !== "ok") return;
+    const uid = uidOf(r);
     const url = audioBaseUrl ? `${audioBaseUrl.replace(/\/$/, "")}/${r.clip.audio}` : r.clip.audio;
     const a = audioRef.current!;
-    if (playingKeyRef.current === r.key && !a.paused) { a.pause(); setPlayingKey(null); return; }
+    if (playingKeyRef.current === uid && !a.paused) { a.pause(); setPlayingKey(null); return; }
     a.src = url;
-    a.play().then(() => setPlayingKey(r.key)).catch(() => setPlayingKey(null));
+    a.play().then(() => setPlayingKey(uid)).catch(() => setPlayingKey(null));
   }, [audioBaseUrl]);
 
   const copyConfig = useCallback(async (r: VoiceRow) => {
@@ -230,20 +281,36 @@ export function VoiceWidget({
       <audio ref={audioRef} onEnded={() => setPlayingKey(null)} preload="none" />
       <header className="vw-head">
         <div className="vw-title">TTS Voices <span className="vw-count">{filtered.length}</span></div>
-        <input className="vw-search" placeholder="Search voices…" value={q}
-               onChange={(e) => setQ(e.target.value)} />
+        {showFilter("search") && (
+          <input className="vw-search" placeholder="Search voices…" value={q}
+                 onChange={(e) => setQ(e.target.value)} />
+        )}
       </header>
 
-      <div className="vw-filters">
-        {!lock && <Select label="Provider" value={provider} onChange={setProvider} opts={providers} />}
-        <Select label="Language" value={language} onChange={setLanguage} opts={languages} />
-        <Select label="Gender" value={gender} onChange={setGender}
-                opts={["male", "female", "neutral", "unknown"]} />
-        <div className="vw-group">
-          <button className={group === "provider" ? "on" : ""} onClick={() => setGroup("provider")}>by provider</button>
-          <button className={group === "language" ? "on" : ""} onClick={() => setGroup("language")}>by language</button>
+      {(showProvider || showFilter("language") || showFilter("gender") || showFilter("pageSize") || showGroup) && (
+        <div className="vw-filters">
+          {showProvider && <Select label="Provider" value={provider} onChange={setProvider} opts={providers} />}
+          {showFilter("language") && <Select label="Language" value={language} onChange={setLanguage} opts={languages} />}
+          {showFilter("gender") && (
+            <Select label="Gender" value={gender} onChange={setGender}
+                    opts={["male", "female", "neutral", "unknown"]} />
+          )}
+          {showFilter("pageSize") && (
+            <label className="vw-select">
+              <span>Per page</span>
+              <select value={pageSizeChoice} onChange={(e) => setPageSizeChoice(Number(e.target.value))}>
+                {pageSizeOpts.map((n) => <option key={n} value={n}>{n}</option>)}
+              </select>
+            </label>
+          )}
+          {showGroup && (
+            <div className="vw-group">
+              <button className={group === "provider" ? "on" : ""} onClick={() => setGroup("provider")}>by provider</button>
+              <button className={group === "language" ? "on" : ""} onClick={() => setGroup("language")}>by language</button>
+            </div>
+          )}
         </div>
-      </div>
+      )}
 
       {pager}
 
@@ -252,10 +319,10 @@ export function VoiceWidget({
       ) : (
         pageSections.map((sec, i) => (
           <section key={`${sec.name}-${i}`} className="vw-section">
-            <h3 className="vw-section-title">{sec.name} <span>{groupTotals.get(sec.name)}</span></h3>
+            {sec.name && <h3 className="vw-section-title">{sec.name} <span>{groupTotals.get(sec.name)}</span></h3>}
             <div className="vw-grid" style={gridStyle}>
-              {sec.items.map((r) => (
-                <Card key={r.key} r={r} playing={playingKey === r.key} onPlay={play} onCopy={copyConfig} />
+              {sec.items.map((r, idx) => (
+                <Card key={`${uidOf(r)}#${idx}`} r={r} playing={playingKey === uidOf(r)} onPlay={play} onCopy={copyConfig} />
               ))}
             </div>
           </section>
@@ -288,11 +355,11 @@ const Card = memo(function Card({ r, playing, onPlay, onCopy }: {
 
   return (
     <article className={`vw-card${r.clip?.status === "error" || !r.clip ? " vw-disabled" : ""}`}>
+      <span className="vw-badge">{r.provider}</span>
       <div className="vw-card-top">
         <button className="vw-play" disabled={disabled} onClick={() => onPlay(r)}
                 aria-label={`Play ${r.display_name}`}>{playing ? "❚❚" : "▶"}</button>
-        <div className="vw-name">{r.display_name}</div>
-        <span className="vw-badge">{r.provider}</span>
+        <div className="vw-name" title={r.display_name}>{r.display_name}</div>
       </div>
       <div className="vw-meta">
         <span className="vw-lang">{r.primary_language}</span>
@@ -355,3 +422,10 @@ function Select({ label, value, onChange, opts }:
 function uniq(xs?: string[]): string[] {
   return [...new Set((xs ?? []).filter(Boolean))].sort();
 }
+
+// Stable per-voice identity. The catalog `key` (<engine>/<voice_id>) is NOT unique — a voice with
+// multiple models repeats it (e.g. rime/abbie under "mist" and "mistv2") — so append the model for
+// React keys, play-state, and allowlist disambiguation.
+function uidOf(r: VoiceRow): string {
+  return r.model ? `${r.key}:${r.model}` : r.key;
+}
diff --git a/fern/components/voice-widget/styles.css b/fern/components/voice-widget/styles.css
new file mode 100644
index 0000000000..04405094a9
--- /dev/null
+++ b/fern/components/voice-widget/styles.css
@@ -0,0 +1,82 @@
+/* Voice widget styles, scoped under .vw so it can be dropped into the docs without clobbering host
+   styles. The palette maps onto the docs' theme-aware brand tokens so the widget follows light/dark
+   mode automatically. */
+.vw {
+  --vw-bg: var(--bg-page);
+  --vw-card: var(--bg-surface-raised);
+  --vw-line: var(--border-default);
+  --vw-fg: var(--fg-default);
+  --vw-muted: var(--fg-muted);
+  --vw-accent: var(--accent);
+  --vw-radius: 10px;
+  color: var(--vw-fg); font: 14px/1.45 system-ui, sans-serif;
+}
+.vw-loading, .vw-error { padding: 2rem; color: var(--vw-muted); }
+.vw-error { color: var(--error-text); }
+
+.vw-head { display: flex; align-items: center; gap: 1rem; margin-bottom: .75rem; }
+.vw-title { font-size: 1.15rem; font-weight: 700; }
+.vw-count { color: var(--vw-muted); font-weight: 400; margin-left: .35rem; }
+.vw-search { margin-left: auto; padding: .5rem .75rem; min-width: 220px;
+  background: var(--vw-card); border: 1px solid var(--vw-line); border-radius: var(--vw-radius); color: inherit; }
+
+.vw-filters { display: flex; flex-wrap: wrap; gap: .75rem; align-items: end; margin-bottom: 1rem;
+  position: sticky; top: 0; background: var(--vw-bg); padding: .5rem 0; z-index: 2; }
+.vw-select { display: flex; flex-direction: column; gap: .2rem; font-size: .8rem; color: var(--vw-muted); }
+.vw-select select { padding: .4rem .5rem; background: var(--vw-card); color: var(--vw-fg);
+  border: 1px solid var(--vw-line); border-radius: 8px; }
+.vw-group { display: flex; gap: .25rem; margin-left: auto; }
+.vw-group button { padding: .4rem .6rem; background: var(--vw-card); color: var(--vw-muted);
+  border: 1px solid var(--vw-line); border-radius: 8px; cursor: pointer; }
+.vw-group button.on { color: var(--accent); border-color: var(--accent); background: var(--accent-a3); }
+
+.vw-section { margin-bottom: 1.5rem; }
+.vw-section-title { font-size: .95rem; margin: .5rem 0; text-transform: capitalize; }
+.vw-section-title span { color: var(--vw-muted); font-weight: 400; margin-left: .35rem; }
+
+/* Column count is driven by --vw-cols (set inline by the `columns` prop; falls back to responsive
+   auto-fill). Defining the template here lets the mobile media query override it regardless. */
+.vw-grid { display: grid; gap: .75rem;
+  grid-template-columns: repeat(var(--vw-cols, auto-fill), minmax(var(--vw-col-min, 240px), 1fr)); }
+.vw-card { background: var(--vw-card); border: 1px solid var(--vw-line); border-radius: var(--vw-radius);
+  padding: .75rem; display: flex; flex-direction: column; gap: .5rem; overflow: hidden; }
+.vw-card.vw-disabled { opacity: .55; }
+.vw-card-top { display: flex; align-items: center; gap: .5rem; min-width: 0; }
+.vw-play { width: 32px; height: 32px; flex: 0 0 auto; border-radius: 50%; cursor: pointer;
+  background: var(--vw-accent); color: var(--accent-contrast); border: none; font-size: .8rem; }
+.vw-play:disabled { background: var(--grayscale-a4); color: var(--vw-muted); cursor: not-allowed; }
+.vw-name { font-weight: 600; flex: 1 1 auto;
+  min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+/* Provider badge sits in the card's top-right corner, on its own line above the title, tucked into
+   the corner so it can't overlap the title or meta chips and adds no tall empty strip. */
+.vw-badge { font-size: .68rem; padding: .15rem .4rem; border: 1px solid var(--vw-line);
+  border-radius: 999px; color: var(--vw-muted); white-space: nowrap;
+  align-self: flex-end; width: fit-content; max-width: 100%;
+  overflow: hidden; text-overflow: ellipsis; margin: -0.15rem -0.15rem -0.7rem 0; }
+.vw-meta { display: flex; flex-wrap: wrap; gap: .35rem; font-size: .7rem; color: var(--vw-muted); }
+.vw-meta span { padding: .12rem .4rem; background: var(--grayscale-a3); border-radius: 6px; }
+.vw-gender.vw-male { color: #3b82f6; } .vw-gender.vw-female { color: #d6409f; }
+.vw-sample { margin: 0; font-size: .82rem; color: var(--fg-secondary); font-style: italic; }
+.vw-note { margin: 0; font-size: .72rem; color: var(--warning-text); }
+/* margin-top:auto pins copy to the bottom so it aligns across a row regardless of sample length. */
+.vw-copy { align-self: flex-start; margin-top: auto; font-size: .72rem; background: transparent;
+  color: var(--vw-accent); border: 1px solid var(--vw-line); border-radius: 6px; padding: .25rem .5rem; cursor: pointer; }
+.vw-copy.vw-copied { color: var(--accent); border-color: var(--accent); background: var(--accent-a3); }
+
+/* Pagination controls + empty state. */
+.vw-pager { display: flex; align-items: center; justify-content: center; gap: .75rem;
+  margin: 1rem 0; flex-wrap: wrap; }
+.vw-pager-btn { padding: .4rem .8rem; background: var(--grayscale-2); color: var(--fg-default);
+  border: 1px solid var(--border-default); border-radius: 8px; cursor: pointer; font-size: .82rem; }
+.vw-pager-btn:hover:not(:disabled) { border-color: var(--accent); color: var(--accent); }
+.vw-pager-btn:disabled { opacity: .45; cursor: not-allowed; }
+.vw-pager-info { font-size: .8rem; color: var(--fg-muted); }
+.vw-pager-page { color: var(--fg-muted); }
+.vw-empty { padding: 2rem 0; color: var(--fg-muted); font-size: .9rem; }
+
+/* On phones, collapse to a single column no matter what `columns` was set to. */
+@media (max-width: 640px) {
+  .vw-grid { grid-template-columns: 1fr; }
+  .vw-filters { gap: .5rem; }
+  .vw-search { min-width: 0; }
+}
diff --git a/fern/components/types.ts b/fern/components/voice-widget/types.ts
similarity index 100%
rename from fern/components/types.ts
rename to fern/components/voice-widget/types.ts
diff --git a/fern/voice-widget-overrides.css b/fern/voice-widget-overrides.css
deleted file mode 100644
index dca3e28c4c..0000000000
--- a/fern/voice-widget-overrides.css
+++ /dev/null
@@ -1,71 +0,0 @@
-/* Voice widget — docs theme overrides.
-   The bundled widget stylesheet (fern/components/voice-widget.css) ships a fixed dark palette.
-   This layer, loaded AFTER it in docs.yml `css`, remaps the widget's scoped --vw-* variables onto
-   the docs' theme-aware brand tokens so the widget follows light/dark mode. Kept separate from the
-   widget's own CSS so widget updates aren't clobbered by local edits. */
-.vw {
-  --vw-bg: var(--bg-page);
-  --vw-card: var(--bg-surface-raised);
-  --vw-line: var(--border-default);
-  --vw-fg: var(--fg-default);
-  --vw-muted: var(--fg-muted);
-  --vw-accent: var(--accent);
-}
-
-/* Hardcoded colors in the widget that don't flow through the --vw-* variables: */
-.vw-play { color: var(--accent-contrast); }                                /* was #fff */
-.vw-play:disabled { color: var(--fg-muted); }
-.vw-group button.on { color: var(--accent); background: var(--accent-a3); } /* was #fff on transparent */
-.vw-meta span { background: var(--grayscale-a3); }                         /* was #0d1014 */
-.vw-sample { color: var(--fg-secondary); }                                 /* was #cfd6e2 */
-.vw-note { color: var(--warning-text); }                                   /* was #ff9b6b */
-.vw-error { color: var(--error-text); }                                    /* was #ff6b6b */
-.vw-gender.vw-male { color: #3b82f6; }                                     /* readable on both themes */
-.vw-gender.vw-female { color: #d6409f; }
-
-/* Pagination controls + empty state (added with the component's pagination feature). */
-.vw-pager { display: flex; align-items: center; justify-content: center; gap: .75rem;
-  margin: 1rem 0; flex-wrap: wrap; }
-.vw-pager-btn { padding: .4rem .8rem; background: var(--grayscale-2); color: var(--fg-default);
-  border: 1px solid var(--border-default); border-radius: 8px; cursor: pointer; font-size: .82rem; }
-.vw-pager-btn:hover:not(:disabled) { border-color: var(--accent); color: var(--accent); }
-.vw-pager-btn:disabled { opacity: .45; cursor: not-allowed; }
-.vw-pager-info { font-size: .8rem; color: var(--fg-muted); }
-.vw-pager-page { color: var(--fg-muted); }
-.vw-empty { padding: 2rem 0; color: var(--fg-muted); font-size: .9rem; }
-
-/* "copy config" → copied feedback state. */
-.vw-copy.vw-copied { color: var(--accent); border-color: var(--accent); background: var(--accent-a3); }
-
-/* --- Responsive grid ---
-   Column count is driven by --vw-cols (set inline by the `columns` prop; falls back to responsive
-   auto-fill). Defining the template here (rather than inline) lets the mobile media query below
-   override it regardless of the prop. */
-.vw-grid {
-  grid-template-columns: repeat(var(--vw-cols, auto-fill), minmax(var(--vw-col-min, 240px), 1fr));
-}
-
-/* On phones, collapse to a single column no matter what `columns` was set to. */
-@media (max-width: 640px) {
-  .vw-grid { grid-template-columns: 1fr; }
-  .vw-filters { gap: .5rem; }
-  .vw-search { min-width: 0; }
-}
-
-/* --- Card header: keep the name + provider badge inside the card, never overlapping ---
-   The name is the flex item that must be allowed to shrink (min-width:0) and truncate; the badge
-   keeps its size and won't be pushed out. */
-.vw-card { overflow: hidden; }
-.vw-card-top { min-width: 0; }
-.vw-name {
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-.vw-badge {
-  flex: 0 0 auto;
-  max-width: 50%;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}

From 3660b1662473fae5b0ced0609258cb115964ae4f Mon Sep 17 00:00:00 2001
From: Devon-White <devon.white@signalwire.com>
Date: Mon, 8 Jun 2026 15:55:35 -0400
Subject: [PATCH 3/7] Updates

---
 fern/components/skeleton/index.tsx            |  6 ++--
 fern/components/skeleton/styles.css           |  2 +-
 fern/components/voice-widget/index.tsx        |  9 ++++--
 fern/components/voice-widget/styles.css       | 14 +++++++--
 fern/docs.yml                                 |  5 ++--
 .../pages/calling/voice/TTS/azure.mdx         |  6 ++++
 .../pages/calling/voice/TTS/cartesia.mdx      |  6 ++++
 .../pages/calling/voice/TTS/deepgram.mdx      |  6 ++++
 .../pages/calling/voice/TTS/elevenlabs.mdx    |  6 ++++
 .../pages/calling/voice/TTS/google.mdx        |  8 +++++
 .../pages/calling/voice/TTS/index.mdx         | 29 +++++++++++++++----
 .../pages/calling/voice/TTS/openai.mdx        |  6 ++++
 .../pages/calling/voice/TTS/polly.mdx         |  8 +++++
 .../platform/pages/calling/voice/TTS/rime.mdx |  6 ++++
 14 files changed, 98 insertions(+), 19 deletions(-)

diff --git a/fern/components/skeleton/index.tsx b/fern/components/skeleton/index.tsx
index 1326788011..c59f770bdc 100644
--- a/fern/components/skeleton/index.tsx
+++ b/fern/components/skeleton/index.tsx
@@ -1,11 +1,11 @@
 import type { CSSProperties } from "react";
 
 // Reusable loading-skeleton primitive for custom MDX components that fetch data at runtime.
-// Compose a few of these to mimic the shape of the content that's loading. Pairs with
-// skeleton.css (loaded via docs.yml `css:` — Fern's component bundler doesn't process CSS imports).
+// Compose a few of these to mimic the shape of the content that's loading. Pairs with this folder's
+// styles.css (loaded via docs.yml `css:` — Fern's component bundler doesn't process CSS imports).
 // Theme-aware (light/dark) through Fern's grayscale vars.
 //
-//   import { Skeleton, SkeletonText } from "@/components/skeleton";
+//   import { Skeleton, SkeletonText } from "@/components/index";
 //   if (!data) return <Skeleton width="60%" height={20} />;
 
 export interface SkeletonProps {
diff --git a/fern/components/skeleton/styles.css b/fern/components/skeleton/styles.css
index 3b18147218..0f50a8d170 100644
--- a/fern/components/skeleton/styles.css
+++ b/fern/components/skeleton/styles.css
@@ -1,7 +1,7 @@
 /* Reusable loading-skeleton (shimmer) for custom MDX components, ported from the SignalWire
    components design reference. The original drove it with --skeleton-base / --skeleton-shimmer
    design tokens; here those map onto Fern's theme-aware grayscale vars so it follows light/dark.
-   Loaded globally via docs.yml `css:`. Markup comes from components/skeleton.tsx (`.sw-skeleton`). */
+   Loaded globally via docs.yml `css:`. Markup comes from this folder's index.tsx (`.sw-skeleton`). */
 .sw-skeleton {
   background: var(--grayscale-a3);
   border-radius: 8px;
diff --git a/fern/components/voice-widget/index.tsx b/fern/components/voice-widget/index.tsx
index dc2e59fa16..f389b6ce0e 100644
--- a/fern/components/voice-widget/index.tsx
+++ b/fern/components/voice-widget/index.tsx
@@ -5,8 +5,8 @@ import { Skeleton } from "../skeleton/index";
 
 // Ported from @signalwire/tts-voice-widget for embedding as a Fern MDX component.
 // Pure data consumer: fetches catalog.json + manifest.json produced by the TTS pipeline and plays
-// the pre-synthesized sample clips. Styles live in voice-widget.css + voice-widget-overrides.css,
-// loaded via docs.yml `css:` (Fern's component bundler does not process CSS imports).
+// the pre-synthesized sample clips. Styles live in this folder's styles.css, loaded via docs.yml
+// `css:` (Fern's component bundler does not process CSS imports).
 
 // Single source of truth for where the asset bundle (catalog.json + manifest.json + audio/) is
 // hosted. The bundle cannot live in fern/assets — Fern only serves assets it statically discovers
@@ -369,8 +369,11 @@ const Card = memo(function Card({ r, playing, onPlay, onCopy }: {
       {r.clip?.sample_text && <p className="vw-sample">“{r.clip.sample_text}”</p>}
       {(!r.clip || r.clip.status === "error") &&
         <p className="vw-note">{r.clip?.error ?? "no sample (provider key missing)"}</p>}
+      {/* Both labels are always in the DOM and grid-stacked (see CSS) so the button keeps the width
+          of the wider one — no layout shift when it swaps to the copied state. */}
       <button className={`vw-copy${copied ? " vw-copied" : ""}`} onClick={handleCopy} aria-live="polite">
-        {copied ? "copied ✓" : "copy config"}
+        <span className="vw-copy-default">copy config</span>
+        <span className="vw-copy-done">✓ copied</span>
       </button>
     </article>
   );
diff --git a/fern/components/voice-widget/styles.css b/fern/components/voice-widget/styles.css
index 04405094a9..0e811f975e 100644
--- a/fern/components/voice-widget/styles.css
+++ b/fern/components/voice-widget/styles.css
@@ -58,10 +58,18 @@
 .vw-gender.vw-male { color: #3b82f6; } .vw-gender.vw-female { color: #d6409f; }
 .vw-sample { margin: 0; font-size: .82rem; color: var(--fg-secondary); font-style: italic; }
 .vw-note { margin: 0; font-size: .72rem; color: var(--warning-text); }
-/* margin-top:auto pins copy to the bottom so it aligns across a row regardless of sample length. */
+/* margin-top:auto pins copy to the bottom so it aligns across a row regardless of sample length.
+   The two labels are grid-stacked in one cell so the button always sizes to the wider label
+   ("copy config") — swapping to the copied state causes no width change / layout shift. */
 .vw-copy { align-self: flex-start; margin-top: auto; font-size: .72rem; background: transparent;
-  color: var(--vw-accent); border: 1px solid var(--vw-line); border-radius: 6px; padding: .25rem .5rem; cursor: pointer; }
-.vw-copy.vw-copied { color: var(--accent); border-color: var(--accent); background: var(--accent-a3); }
+  color: var(--vw-accent); border: 1px solid var(--vw-line); border-radius: 6px; padding: .25rem .5rem;
+  cursor: pointer; display: inline-grid; text-align: center; transition: border-color .15s ease; }
+.vw-copy:hover:not(.vw-copied) { border-color: var(--accent); }
+.vw-copy > span { grid-area: 1 / 1; }
+.vw-copy .vw-copy-done { visibility: hidden; }            /* reserves space but hidden until copied */
+.vw-copy.vw-copied .vw-copy-default { visibility: hidden; }
+.vw-copy.vw-copied .vw-copy-done { visibility: visible; }
+.vw-copy.vw-copied { color: #16a34a; border-color: #16a34a; }  /* green check, readable on light + dark */
 
 /* Pagination controls + empty state. */
 .vw-pager { display: flex; align-items: center; justify-content: center; gap: .75rem;
diff --git a/fern/docs.yml b/fern/docs.yml
index 242d2b25cc..b84a7e6a2e 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -175,9 +175,8 @@ css:
   - brand-tokens.css
   - brand-overrides.css
   - styles.css
-  - components/skeleton.css
-  - components/voice-widget.css
-  - voice-widget-overrides.css
+  - components/skeleton/styles.css
+  - components/voice-widget/styles.css
 
 redirects:
   - source: /docs/agents-sdk
diff --git a/fern/products/platform/pages/calling/voice/TTS/azure.mdx b/fern/products/platform/pages/calling/voice/TTS/azure.mdx
index 6ad66c81db..107039ac2c 100644
--- a/fern/products/platform/pages/calling/voice/TTS/azure.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/azure.mdx
@@ -5,10 +5,16 @@ description: Learn how to use Azure TTS voices on the SignalWire platform.
 slug: /voice/tts/azure
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 Microsoft's Azure platform offers an impressive array of high-quality, multilingual voices in its Neural model.
 
 ## Voices
 
+Press play to audition any Azure voice, then **copy config** to grab the value for SWML or your SDK.
+
+<VoiceWidget provider="azure" />
+
 <CardGroup cols={2}>
   <Card title="Voices" href="https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support?tabs=tts">
     Browse the complete list of Azure Neural voices in Microsoft's official documentation.
diff --git a/fern/products/platform/pages/calling/voice/TTS/cartesia.mdx b/fern/products/platform/pages/calling/voice/TTS/cartesia.mdx
index 78502a2484..b204a000ce 100644
--- a/fern/products/platform/pages/calling/voice/TTS/cartesia.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/cartesia.mdx
@@ -5,6 +5,8 @@ description: Learn how to use Cartesia TTS voices on the SignalWire platform.
 slug: /voice/tts/cartesia
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 
 Cartesia offers a wide selection of fully multilingual voices with very low latency.
 [Create a Cartesia account](https://play.cartesia.ai) to browse and test voices in the Cartesia Playground.
@@ -34,6 +36,10 @@ All Cartesia voices can be used with any model.
 
 ## Voices
 
+Press play to audition any Cartesia voice, then **copy config** to grab the value for SWML or your SDK.
+
+<VoiceWidget provider="cartesia" />
+
 Copy the voice ID from the table below:
 
 
diff --git a/fern/products/platform/pages/calling/voice/TTS/deepgram.mdx b/fern/products/platform/pages/calling/voice/TTS/deepgram.mdx
index 39d162445a..597f25497d 100644
--- a/fern/products/platform/pages/calling/voice/TTS/deepgram.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/deepgram.mdx
@@ -5,6 +5,8 @@ description: Learn how to use Deepgram TTS voices on the SignalWire platform.
 slug: /voice/tts/deepgram
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 Deepgram's Aura model offers a wide range of voices for its text-to-speech API, 
 each designed to produce natural-sounding speech output in an array of different accents and speaking styles.
 
@@ -25,6 +27,10 @@ Deepgram's Aura model provides ultra-low latency text-to-speech optimized for co
 
 ## Voices
 
+Press play to audition any Deepgram voice, then **copy config** to grab the value for SWML or your SDK.
+
+<VoiceWidget provider="deepgram" />
+
 Deepgram Aura voices are designed for natural-sounding English speech. Each voice follows the pattern `aura-<name>-en`.
 
 Popular voices include:
diff --git a/fern/products/platform/pages/calling/voice/TTS/elevenlabs.mdx b/fern/products/platform/pages/calling/voice/TTS/elevenlabs.mdx
index d0c4a493d7..29a936f608 100644
--- a/fern/products/platform/pages/calling/voice/TTS/elevenlabs.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/elevenlabs.mdx
@@ -5,6 +5,8 @@ description: Learn how to use ElevenLabs TTS voices on the SignalWire platform.
 slug: /voice/tts/elevenlabs
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 ElevenLabs voices offer expressive, human-like pronunciation and an extensive list of supported languages.
 Every ElevenLabs [voice](#voices) can be used with all of the ElevenLabs [models](#models).
 
@@ -20,6 +22,10 @@ Consult ElevenLabs' documentation for an up-to-date list of available models and
 
 ## Voices
 
+Press play to audition any ElevenLabs voice, then **copy config** to grab the value for SWML or your SDK.
+
+<VoiceWidget provider="elevenlabs" />
+
 You can use the **Name** and **ID** values for each voice in the below table interchangeably.
 
 | Name | ID |
diff --git a/fern/products/platform/pages/calling/voice/TTS/google.mdx b/fern/products/platform/pages/calling/voice/TTS/google.mdx
index 88e51b8ac8..dcc080a888 100644
--- a/fern/products/platform/pages/calling/voice/TTS/google.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/google.mdx
@@ -5,6 +5,8 @@ description: Learn how to use Google Cloud TTS voices on the SignalWire platform
 slug: /voice/tts/gcloud
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 Google Cloud offers a number of robust text-to-speech
 [voice models](https://cloud.google.com/text-to-speech/docs/voice-types).
 SignalWire supports all Google Cloud voices in both General Availability and Preview 
@@ -36,6 +38,12 @@ and prioritizes natural and human-like pronunciation and intonation.
 voices have variants in multiple languages. For example, at time of writing,
 the `polyglot-1` voice has variants for English (Australia), English (US), French, German, Spanish (Spain), and Spanish (US).
 
+## Voices
+
+Press play to audition any Google Cloud voice, then **copy config** to grab the value for SWML or your SDK.
+
+<VoiceWidget provider="gcloud" />
+
 ## Billing
 
 Google Cloud TTS usage on SignalWire is billed according to the following SKU codes:
diff --git a/fern/products/platform/pages/calling/voice/TTS/index.mdx b/fern/products/platform/pages/calling/voice/TTS/index.mdx
index 7ba36c8d96..20feff604e 100644
--- a/fern/products/platform/pages/calling/voice/TTS/index.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/index.mdx
@@ -11,6 +11,8 @@ x-custom:
 description: Detailed list of all the TTS providers and voices SignalWire supports.
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 
 [polly]: /docs/platform/voice/tts/amazon-polly
 [azure]: /docs/platform/voice/tts/azure
@@ -31,12 +33,27 @@ Refer to each provider's documentation for up-to-date model details and service
 
 ## Browse and audition voices
 
-import { VoiceWidget } from "@/components/voice-widget";
-
-Search and filter every supported voice by provider, language, and gender, and play a sample clip
-for each. Use **copy config** to grab the engine and voice values to drop into your SWML or SDK code.
-
-<VoiceWidget columns={4} />
+Press play to audition one sample voice from each supported provider, and use **copy config** to
+grab the engine and voice values for your SWML or SDK code. Each provider's complete voice list
+lives on its reference page, linked in the table below.
+
+<VoiceWidget
+  groupBy="none"
+  voiceIds={[
+    "polly/Nicole",
+    "azure/en-AU-AnnetteNeural",
+    "cartesia/3264ada2-4a79-4666-badc-49e2267be692",
+    "deepgram/aura-2-amalthea-en",
+    "elevenlabs/NNl6r8mD7vthiJatiJt1",
+    "gcloud/en-AU-News-E",
+    "openai/alloy",
+    "rime/abbie:mist",
+    "inworld/Abby",
+    "minimax/Spanish_Arnold",
+    "playai-turbo/austin",
+    "grok/ara",
+  ]}
+/>
 
 ## Compare providers and models
 
diff --git a/fern/products/platform/pages/calling/voice/TTS/openai.mdx b/fern/products/platform/pages/calling/voice/TTS/openai.mdx
index a3f8c80264..c8b0b65bd6 100644
--- a/fern/products/platform/pages/calling/voice/TTS/openai.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/openai.mdx
@@ -5,6 +5,8 @@ description: Learn how to use OpenAI TTS voices on the SignalWire platform.
 slug: /voice/tts/openai
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 OpenAI offers versatile multilingual voices balancing low latency and good quality.
 While voices are optimized for English, they perform well across all 
 [supported languages][languages].
@@ -24,6 +26,10 @@ OpenAI offers two TTS models with different quality and latency characteristics:
 
 ## Voices
 
+Press play to audition any OpenAI voice, then **copy config** to grab the value for SWML or your SDK.
+
+<VoiceWidget provider="openai" />
+
 OpenAI provides 6 fully multilingual voices optimized for natural-sounding speech:
 
 | Voice | Description |
diff --git a/fern/products/platform/pages/calling/voice/TTS/polly.mdx b/fern/products/platform/pages/calling/voice/TTS/polly.mdx
index a499fda515..87901575a6 100644
--- a/fern/products/platform/pages/calling/voice/TTS/polly.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/polly.mdx
@@ -5,6 +5,8 @@ description: Learn how to use Polly TTS voices on the SignalWire platform.
 slug: /voice/tts/amazon-polly
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 Amazon Web Services' Polly TTS engine includes several models to accommodate different use cases.
 
 ## Models
@@ -33,6 +35,12 @@ SignalWire supports the following three Amazon models.
 
 </CardGroup>
 
+## Voices
+
+Press play to audition any Amazon Polly voice, then **copy config** to grab the value for SWML or your SDK.
+
+<VoiceWidget provider="polly" />
+
 ## Languages
 
 Consult AWS documentation for a comprehensive and up-to-date list of supported voices,
diff --git a/fern/products/platform/pages/calling/voice/TTS/rime.mdx b/fern/products/platform/pages/calling/voice/TTS/rime.mdx
index 064486efc1..3d8cdfc46d 100644
--- a/fern/products/platform/pages/calling/voice/TTS/rime.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/rime.mdx
@@ -6,6 +6,8 @@ slug: /voice/tts/rime
 description: Learn how to use Rime's Arcana and Mist v2 TTS models with SignalWire AI Voice applications.
 ---
 
+import { VoiceWidget } from "@/components/index";
+
 
 Rime offers uniquely realistic voices with a focus on natural expressiveness.
 
@@ -33,6 +35,10 @@ Rime offers uniquely realistic voices with a focus on natural expressiveness.
 
 ## Voices
 
+Press play to audition any Rime voice, then **copy config** to grab the value for SWML or your SDK.
+
+<VoiceWidget provider="rime" />
+
 Mist v2 is the default Rime model on the SignalWire platform.
 To use this model, simply set the voice ID.
 

From 6cf823fc2a7cd6cf803eccf27fa9d3ec51d12374 Mon Sep 17 00:00:00 2001
From: Devon-White <devon.white@signalwire.com>
Date: Mon, 8 Jun 2026 16:29:36 -0400
Subject: [PATCH 4/7] Disable filters on TTS overview

---
 fern/products/platform/pages/calling/voice/TTS/index.mdx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/fern/products/platform/pages/calling/voice/TTS/index.mdx b/fern/products/platform/pages/calling/voice/TTS/index.mdx
index 20feff604e..27243370c4 100644
--- a/fern/products/platform/pages/calling/voice/TTS/index.mdx
+++ b/fern/products/platform/pages/calling/voice/TTS/index.mdx
@@ -53,6 +53,7 @@ lives on its reference page, linked in the table below.
     "playai-turbo/austin",
     "grok/ara",
   ]}
+  filters={false}
 />
 
 ## Compare providers and models

From 0988a9d6fea5ae81fe6bbf0cd9f406dbb755df5e Mon Sep 17 00:00:00 2001
From: Devon-White <devon.white@signalwire.com>
Date: Tue, 9 Jun 2026 12:39:26 -0400
Subject: [PATCH 5/7] update to CDN

---
 fern/components/voice-widget/index.tsx | 113 ++++++++++++++++---------
 1 file changed, 72 insertions(+), 41 deletions(-)

diff --git a/fern/components/voice-widget/index.tsx b/fern/components/voice-widget/index.tsx
index f389b6ce0e..a8e85617e7 100644
--- a/fern/components/voice-widget/index.tsx
+++ b/fern/components/voice-widget/index.tsx
@@ -8,18 +8,18 @@ import { Skeleton } from "../skeleton/index";
 // the pre-synthesized sample clips. Styles live in this folder's styles.css, loaded via docs.yml
 // `css:` (Fern's component bundler does not process CSS imports).
 
-// Single source of truth for where the asset bundle (catalog.json + manifest.json + audio/) is
-// hosted. The bundle cannot live in fern/assets — Fern only serves assets it statically discovers
-// in MDX/CSS and rewrites to content-hashed URLs, so a runtime fetch() has no resolvable path.
-// It must be served from an external origin with CORS enabled on the JSON. Flip this one string
-// to move between hosts; the three URLs (catalog/manifest/audio) all derive from it.
+// Where the hosted asset bundle lives. The bundle cannot live in fern/assets — Fern only serves
+// assets it statically discovers in MDX/CSS and rewrites to content-hashed URLs, so a runtime
+// fetch() has no resolvable path. It must be served from an external origin with CORS enabled.
 //
-// Cloudflare quick tunnel to the local CDN (`http-server temp/voice_widget/dist -p 8080 --cors -g`),
-// so a tunnelled docs preview can be shared and fetch assets over HTTPS from a host every viewer
-// can resolve. Ephemeral: quick-tunnel URLs change on every cloudflared restart — update this and
-// restart the docs dev server to re-bundle. For local-only dev set to "http://localhost:8080".
-// Swap to the production CDN base URL when one is available.
-const ASSET_BASE = "https://warming-watched-physics-assistance.trycloudflare.com";
+// On the production CDN the JSON and the audio/ tree sit under different prefixes: catalog.json +
+// manifest.json are served from /voice_widget/dist/, while the audio is served from the domain root
+// (/audio/<engine>/<voice_id>.mp3). The manifest stores each clip's `audio` as a path relative to
+// AUDIO_BASE (e.g. "audio/rime/zion.mp3"), so the two bases are independent — keep each in sync with
+// the CDN layout. For local dev against `http-server temp/voice_widget/dist -p 8080 --cors`, set
+// both to "http://localhost:8080".
+const ASSET_BASE = "https://mcdn.signalwire.com/voice_widget/dist"; // catalog.json + manifest.json
+const AUDIO_BASE = "https://mcdn.signalwire.com";                   // /audio/<engine>/<voice_id>.mp3
 
 const ALL = "__all__";
 const DEFAULT_PAGE_SIZE = 48;
@@ -30,6 +30,38 @@ const PAGE_SIZE_OPTIONS = [4, 8, 12, 24, 48, 96];
 
 type FilterKey = "search" | "provider" | "language" | "gender" | "group" | "pageSize";
 
+// Client-side row: a catalog voice joined with its clip, plus a precomputed lowercased search blob
+// so the per-keystroke filter runs one substring test per row instead of re-lowercasing 4–5 fields.
+type Row = VoiceRow & { _search: string };
+
+// The asset bundle (catalog.json + manifest.json) is one large artifact (~5 MB, ~4.9k voices)
+// shared by every TTS page that embeds the widget. Cache the parsed+joined rows per URL pair so
+// navigating across the index and the provider pages fetches and parses it once per session, not
+// once per mount. Each embed then narrows this shared set down to the voices it shows (see baseRows).
+const bundleCache = new Map<string, Promise<Row[]>>();
+
+function loadBundle(catalogUrl: string, manifestUrl: string): Promise<Row[]> {
+  const cacheKey = `${catalogUrl}\n${manifestUrl}`;
+  let cached = bundleCache.get(cacheKey);
+  if (!cached) {
+    cached = Promise.all([
+      fetch(catalogUrl).then((r) => r.json() as Promise<Catalog>),
+      fetch(manifestUrl).then((r) => r.json() as Promise<Manifest>).catch(() => ({ clips: {} } as Manifest)),
+    ]).then(([cat, man]) =>
+      cat.voices.map((v) => ({
+        ...v,
+        clip: man.clips?.[v.key],
+        // Mirrors the fields the search filter below tests against (name, provider, description, tags).
+        _search: `${v.display_name} ${v.provider} ${v.description} ${v.tags.join(" ")}`.toLowerCase(),
+      }))
+    );
+    // Never cache a rejected fetch — evict so a later mount can retry instead of replaying the error.
+    cached.catch(() => bundleCache.delete(cacheKey));
+    bundleCache.set(cacheKey, cached);
+  }
+  return cached;
+}
+
 // Tracks whether the viewport is in the mobile breakpoint (matches the CSS media query below).
 function useIsMobile() {
   const [mobile, setMobile] = useState(false);
@@ -51,7 +83,7 @@ export interface VoiceWidgetProps {
   catalogUrl?: string;
   /** Override the manifest.json URL. Default: `${assetBaseUrl}/manifest.json`. */
   manifestUrl?: string;
-  /** Override the base the clip `audio` paths resolve against. Default: assetBaseUrl. */
+  /** Override the base the clip `audio` paths resolve against. Default: AUDIO_BASE. */
   audioBaseUrl?: string;
   /** Initial grouping. "none" renders a flat grid with no section headers or group toggle. Default: "provider". */
   groupBy?: "provider" | "language" | "none";
@@ -88,7 +120,7 @@ export function VoiceWidget({
   assetBaseUrl = ASSET_BASE,
   catalogUrl = `${assetBaseUrl}/catalog.json`,
   manifestUrl = `${assetBaseUrl}/manifest.json`,
-  audioBaseUrl = assetBaseUrl,
+  audioBaseUrl = AUDIO_BASE,
   groupBy: initialGroup = "provider",
   pageSize = DEFAULT_PAGE_SIZE,
   columns = 3,
@@ -113,7 +145,7 @@ export function VoiceWidget({
   const gridStyle = (columns && columns > 0
     ? { "--vw-cols": Math.floor(columns), "--vw-col-min": "0px" }
     : undefined) as CSSProperties | undefined;
-  const [rows, setRows] = useState<VoiceRow[] | null>(null);
+  const [allRows, setAllRows] = useState<Row[] | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [q, setQ] = useState("");
   const [provider, setProvider] = useState(ALL);
@@ -145,43 +177,42 @@ export function VoiceWidget({
 
   useEffect(() => {
     let alive = true;
-    (async () => {
-      try {
-        const [cat, man] = await Promise.all([
-          fetch(catalogUrl).then((r) => r.json() as Promise<Catalog>),
-          fetch(manifestUrl).then((r) => r.json() as Promise<Manifest>).catch(() => ({ clips: {} } as Manifest)),
-        ]);
-        if (!alive) return;
-        setRows(cat.voices.map((v) => ({ ...v, clip: man.clips?.[v.key] })));
-      } catch (e) {
-        if (alive) setError(String(e));
-      }
-    })();
+    loadBundle(catalogUrl, manifestUrl)
+      .then((loaded) => { if (alive) setAllRows(loaded); })
+      .catch((e) => { if (alive) setError(String(e)); });
     return () => { alive = false; };
   }, [catalogUrl, manifestUrl]);
 
-  const providers = useMemo(() => uniq(rows?.map((r) => r.provider)), [rows]);
-  const languages = useMemo(() => uniq(rows?.flatMap((r) => r.languages)), [rows]);
-
-  const filtered = useMemo(() => {
-    if (!rows) return [];
-    const needle = deferredQ.trim().toLowerCase();
-    return rows.filter((r) =>
+  // Static narrowing: the allowlist (voiceIds) and provider lock can't change at runtime, so apply
+  // them once here instead of re-checking the full catalog inside the per-keystroke filter below.
+  // Everything downstream — dropdown options, search, grouping, pagination — then works over only
+  // the voices this embed can ever show (12 on the index, one provider's voices on a provider page).
+  const baseRows = useMemo(() => {
+    if (!allRows) return null;
+    if (!idAllowlist && !lock) return allRows;
+    return allRows.filter((r) =>
       (!idAllowlist ||
         idAllowlist.has(r.voice_id.toLowerCase()) ||
         idAllowlist.has(r.key.toLowerCase()) ||
         idAllowlist.has(uidOf(r).toLowerCase()) ||
         idAllowlist.has(r.display_name.toLowerCase())) &&
-      (!lock || r.provider.toLowerCase() === lock || r.engine.toLowerCase() === lock) &&
+      (!lock || r.provider.toLowerCase() === lock || r.engine.toLowerCase() === lock));
+  }, [allRows, idAllowlist, lock]);
+
+  // Dropdown options derive from the narrowed set, so a provider-locked page lists only that
+  // provider's languages, not all ~180 in the catalog.
+  const providers = useMemo(() => uniq(baseRows?.map((r) => r.provider)), [baseRows]);
+  const languages = useMemo(() => uniq(baseRows?.flatMap((r) => r.languages)), [baseRows]);
+
+  const filtered = useMemo(() => {
+    if (!baseRows) return [];
+    const needle = deferredQ.trim().toLowerCase();
+    return baseRows.filter((r) =>
       (provider === ALL || r.provider === provider) &&
       (language === ALL || r.languages.includes(language)) &&
       (gender === ALL || r.gender === gender) &&
-      (!needle ||
-        r.display_name.toLowerCase().includes(needle) ||
-        r.provider.toLowerCase().includes(needle) ||
-        r.description.toLowerCase().includes(needle) ||
-        r.tags.join(" ").toLowerCase().includes(needle)));
-  }, [rows, idAllowlist, lock, deferredQ, provider, language, gender]);
+      (!needle || r._search.includes(needle)));
+  }, [baseRows, deferredQ, provider, language, gender]);
 
   // Flatten into grouped order once, and remember each group's full size for the section headers.
   // group === "none" keeps the filtered order as-is, with no sections.
@@ -259,7 +290,7 @@ export function VoiceWidget({
   }, []);
 
   if (error) return <div className="vw vw-error">Failed to load voices: {error}</div>;
-  if (!rows) return <VoiceWidgetSkeleton gridStyle={gridStyle} />;
+  if (!baseRows) return <VoiceWidgetSkeleton gridStyle={gridStyle} />;
 
   const pager = pageCount > 1 ? (
     <nav className="vw-pager" aria-label="Voice pages">

From 5188ec06320a4f522349f9fdde32d9454cbba768 Mon Sep 17 00:00:00 2001
From: Devon-White <devon.white@signalwire.com>
Date: Tue, 9 Jun 2026 12:53:17 -0400
Subject: [PATCH 6/7] add tsconfig to resolve TS errors. Add react devDeps

---
 fern/components/tsconfig.json | 19 +++++++++++++++++++
 package.json                  |  4 +++-
 yarn.lock                     | 34 +++++++++++++++++++++++++++++++++-
 3 files changed, 55 insertions(+), 2 deletions(-)
 create mode 100644 fern/components/tsconfig.json

diff --git a/fern/components/tsconfig.json b/fern/components/tsconfig.json
new file mode 100644
index 0000000000..83fe9db633
--- /dev/null
+++ b/fern/components/tsconfig.json
@@ -0,0 +1,19 @@
+{
+  // Local tooling only (editor + LSP type-checking of the custom MDX components). Fern owns the
+  // production build and provides React at build time, so React lives in the root package.json's
+  // devDependencies — these settings just teach tsserver how to resolve the JSX runtime and types.
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "types": ["react"]
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}
diff --git a/package.json b/package.json
index 2186dd0702..98df3ec79c 100644
--- a/package.json
+++ b/package.json
@@ -23,9 +23,11 @@
     "postman:publish": "node scripts/postman/build-collection.mjs publish"
   },
   "devDependencies": {
+    "@types/react": "^18.3.12",
     "fern-api": "5.44.4",
     "js-yaml": "^4.1.0",
-    "openapi-to-postmanv2": "6.0.1"
+    "openapi-to-postmanv2": "6.0.1",
+    "react": "^18.3.1"
   },
   "engines": {
     "node": ">=22"
diff --git a/yarn.lock b/yarn.lock
index d32742fa28..8dcf1b4c3d 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -310,6 +310,19 @@
   resolved "https://registry.yarnpkg.com/@sindresorhus/merge-streams/-/merge-streams-4.0.0.tgz#abb11d99aeb6d27f1b563c38147a72d50058e339"
   integrity sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==
 
+"@types/prop-types@*":
+  version "15.7.15"
+  resolved "https://registry.yarnpkg.com/@types/prop-types/-/prop-types-15.7.15.tgz#e6e5a86d602beaca71ce5163fadf5f95d70931c7"
+  integrity sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==
+
+"@types/react@^18.3.12":
+  version "18.3.31"
+  resolved "https://registry.yarnpkg.com/@types/react/-/react-18.3.31.tgz#b5e95e28ffcceab8d982f33f2eb076e17653c2a4"
+  integrity sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==
+  dependencies:
+    "@types/prop-types" "*"
+    csstype "^3.2.2"
+
 "@typespec/asset-emitter@^0.79.1":
   version "0.79.1"
   resolved "https://registry.yarnpkg.com/@typespec/asset-emitter/-/asset-emitter-0.79.1.tgz#bacb659f18ffa0ec8fb3b5a47f8e304bca8a226a"
@@ -544,6 +557,11 @@ compute-lcm@^1.1.2:
     validate.io-function "^1.0.2"
     validate.io-integer-array "^1.0.0"
 
+csstype@^3.2.2:
+  version "3.2.3"
+  resolved "https://registry.yarnpkg.com/csstype/-/csstype-3.2.3.tgz#ec48c0f3e993e50648c86da559e2610995cf989a"
+  integrity sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==
+
 emoji-regex@^10.3.0:
   version "10.6.0"
   resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-10.6.0.tgz#bf3d6e8f7f8fd22a65d9703475bc0147357a6b0d"
@@ -749,7 +767,7 @@ is-unicode-supported@^2.1.0:
   resolved "https://registry.yarnpkg.com/is-unicode-supported/-/is-unicode-supported-2.1.0.tgz#09f0ab0de6d3744d48d265ebb98f65d11f2a9b3a"
   integrity sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==
 
-js-tokens@^4.0.0:
+"js-tokens@^3.0.0 || ^4.0.0", js-tokens@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499"
   integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==
@@ -826,6 +844,13 @@ lodash@^4.17.15, lodash@^4.17.20, lodash@^4.17.4:
   resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.18.1.tgz#ff2b66c1f6326d59513de2407bf881439812771c"
   integrity sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==
 
+loose-envify@^1.1.0:
+  version "1.4.0"
+  resolved "https://registry.yarnpkg.com/loose-envify/-/loose-envify-1.4.0.tgz#71ee51fa7be4caec1a63839f7e682d8132d30caf"
+  integrity sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==
+  dependencies:
+    js-tokens "^3.0.0 || ^4.0.0"
+
 merge2@^1.3.0:
   version "1.4.1"
   resolved "https://registry.yarnpkg.com/merge2/-/merge2-1.4.1.tgz#4368892f885e907455a6fd7dc55c0c9d404990ae"
@@ -1050,6 +1075,13 @@ queue-microtask@^1.2.2:
   resolved "https://registry.yarnpkg.com/queue-microtask/-/queue-microtask-1.2.3.tgz#4929228bbc724dfac43e0efb058caf7b6cfb6243"
   integrity sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==
 
+react@^18.3.1:
+  version "18.3.1"
+  resolved "https://registry.yarnpkg.com/react/-/react-18.3.1.tgz#49ab892009c53933625bd16b2533fc754cab2891"
+  integrity sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==
+  dependencies:
+    loose-envify "^1.1.0"
+
 reftools@^1.1.9:
   version "1.1.9"
   resolved "https://registry.yarnpkg.com/reftools/-/reftools-1.1.9.tgz#e16e19f662ccd4648605312c06d34e5da3a2b77e"

From ac5987d6a68871e15bf2e0eb1a007096968a20af Mon Sep 17 00:00:00 2001
From: Devon-White <devon.white@signalwire.com>
Date: Tue, 9 Jun 2026 18:27:29 -0400
Subject: [PATCH 7/7] updates

---
 fern/components/voice-widget/index.tsx | 102 +++++++++++++++++--------
 1 file changed, 70 insertions(+), 32 deletions(-)

diff --git a/fern/components/voice-widget/index.tsx b/fern/components/voice-widget/index.tsx
index a8e85617e7..fef88d3c57 100644
--- a/fern/components/voice-widget/index.tsx
+++ b/fern/components/voice-widget/index.tsx
@@ -30,9 +30,11 @@ const PAGE_SIZE_OPTIONS = [4, 8, 12, 24, 48, 96];
 
 type FilterKey = "search" | "provider" | "language" | "gender" | "group" | "pageSize";
 
-// Client-side row: a catalog voice joined with its clip, plus a precomputed lowercased search blob
-// so the per-keystroke filter runs one substring test per row instead of re-lowercasing 4–5 fields.
-type Row = VoiceRow & { _search: string };
+// Client-side row: a catalog voice joined with its clip, plus two precomputed fields — `_search`,
+// a lowercased blob so the per-keystroke filter runs one substring test per row instead of
+// re-lowercasing 4–5 fields, and `_uid`, a collision-free identity for React keys and play state
+// (assigned in loadBundle; the catalog's key+model is not unique on its own).
+type Row = VoiceRow & { _search: string; _uid: string };
 
 // The asset bundle (catalog.json + manifest.json) is one large artifact (~5 MB, ~4.9k voices)
 // shared by every TTS page that embeds the widget. Cache the parsed+joined rows per URL pair so
@@ -45,16 +47,33 @@ function loadBundle(catalogUrl: string, manifestUrl: string): Promise<Row[]> {
   let cached = bundleCache.get(cacheKey);
   if (!cached) {
     cached = Promise.all([
-      fetch(catalogUrl).then((r) => r.json() as Promise<Catalog>),
+      // Check r.ok before parsing: a 404/500 from the CDN is an HTML page, and r.json() on it
+      // surfaces as `SyntaxError: Unexpected token '<'` in the error UI instead of the real cause.
+      fetch(catalogUrl).then((r) => {
+        if (!r.ok) throw new Error(`HTTP ${r.status} fetching catalog.json`);
+        return r.json() as Promise<Catalog>;
+      }),
       fetch(manifestUrl).then((r) => r.json() as Promise<Manifest>).catch(() => ({ clips: {} } as Manifest)),
-    ]).then(([cat, man]) =>
-      cat.voices.map((v) => ({
-        ...v,
-        clip: man.clips?.[v.key],
-        // Mirrors the fields the search filter below tests against (name, provider, description, tags).
-        _search: `${v.display_name} ${v.provider} ${v.description} ${v.tags.join(" ")}`.toLowerCase(),
-      }))
-    );
+    ]).then(([cat, man]) => {
+      // Row identity: key+model is *almost* unique, but the production catalog repeats it for a
+      // handful of rows (rime voices listed once per language, plus two literal duplicate rows),
+      // so suffix a counter on collision. Assigned once here so it's stable for the session:
+      // using `_uid` as the React key lets a card survive filter/page changes (the memoized Card
+      // skips re-rendering), and play state highlights exactly one card even for collisions.
+      const seen = new Map<string, number>();
+      return cat.voices.map((v) => {
+        const base = modelKeyOf(v);
+        const n = seen.get(base) ?? 0;
+        seen.set(base, n + 1);
+        return {
+          ...v,
+          clip: man.clips?.[v.key],
+          _uid: n ? `${base}#${n}` : base,
+          // Mirrors the fields the search filter below tests against (name, provider, description, tags).
+          _search: `${v.display_name} ${v.provider} ${v.description} ${v.tags.join(" ")}`.toLowerCase(),
+        };
+      });
+    });
     // Never cache a rejected fetch — evict so a later mount can retry instead of replaying the error.
     cached.catch(() => bundleCache.delete(cacheKey));
     bundleCache.set(cacheKey, cached);
@@ -194,7 +213,7 @@ export function VoiceWidget({
       (!idAllowlist ||
         idAllowlist.has(r.voice_id.toLowerCase()) ||
         idAllowlist.has(r.key.toLowerCase()) ||
-        idAllowlist.has(uidOf(r).toLowerCase()) ||
+        idAllowlist.has(modelKeyOf(r).toLowerCase()) ||
         idAllowlist.has(r.display_name.toLowerCase())) &&
       (!lock || r.provider.toLowerCase() === lock || r.engine.toLowerCase() === lock));
   }, [allRows, idAllowlist, lock]);
@@ -218,13 +237,13 @@ export function VoiceWidget({
   // group === "none" keeps the filtered order as-is, with no sections.
   const { ordered, groupTotals } = useMemo(() => {
     if (group === "none") return { ordered: filtered, groupTotals: new Map<string, number>() };
-    const m = new Map<string, VoiceRow[]>();
+    const m = new Map<string, Row[]>();
     for (const r of filtered) {
       const k = group === "provider" ? r.provider : r.primary_language;
       (m.get(k) ?? m.set(k, []).get(k)!).push(r);
     }
     const entries = [...m.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-    const ordered: VoiceRow[] = [];
+    const ordered: Row[] = [];
     const groupTotals = new Map<string, number>();
     for (const [name, items] of entries) {
       groupTotals.set(name, items.length);
@@ -254,7 +273,7 @@ export function VoiceWidget({
   const pageSections = useMemo(() => {
     const slice = ordered.slice(start, end);
     if (group === "none") return slice.length ? [{ name: "", items: slice }] : [];
-    const secs: { name: string; items: VoiceRow[] }[] = [];
+    const secs: { name: string; items: Row[] }[] = [];
     for (const r of slice) {
       const k = group === "provider" ? r.provider : r.primary_language;
       const last = secs[secs.length - 1];
@@ -268,14 +287,29 @@ export function VoiceWidget({
   const playingKeyRef = useRef<string | null>(null);
   useEffect(() => { playingKeyRef.current = playingKey; }, [playingKey]);
 
-  const play = useCallback((r: VoiceRow) => {
+  const play = useCallback((r: Row) => {
     if (!r.clip || r.clip.status !== "ok") return;
-    const uid = uidOf(r);
-    const url = audioBaseUrl ? `${audioBaseUrl.replace(/\/$/, "")}/${r.clip.audio}` : r.clip.audio;
     const a = audioRef.current!;
-    if (playingKeyRef.current === uid && !a.paused) { a.pause(); setPlayingKey(null); return; }
-    a.src = url;
-    a.play().then(() => setPlayingKey(uid)).catch(() => setPlayingKey(null));
+    if (playingKeyRef.current === r._uid && !a.paused) {
+      a.pause();
+      playingKeyRef.current = null;
+      setPlayingKey(null);
+      return;
+    }
+    a.src = audioBaseUrl ? `${audioBaseUrl.replace(/\/$/, "")}/${r.clip.audio}` : r.clip.audio;
+    // Mark playing immediately (and synchronously in the ref), not when play() resolves: with
+    // preload="none" the clip has to download first, and during that window a second click must
+    // read this card as already playing so it pauses — otherwise it falls through to `a.src = url`,
+    // which re-runs the load algorithm and restarts the download instead of stopping it. The eager
+    // icon flip also gives the click immediate feedback while the clip loads.
+    playingKeyRef.current = r._uid;
+    setPlayingKey(r._uid);
+    a.play().catch(() => {
+      // Rejected (autoplay policy) or aborted by a newer click — only unwind if still current.
+      if (playingKeyRef.current !== r._uid) return;
+      playingKeyRef.current = null;
+      setPlayingKey(null);
+    });
   }, [audioBaseUrl]);
 
   const copyConfig = useCallback(async (r: VoiceRow) => {
@@ -292,16 +326,19 @@ export function VoiceWidget({
   if (error) return <div className="vw vw-error">Failed to load voices: {error}</div>;
   if (!baseRows) return <VoiceWidgetSkeleton gridStyle={gridStyle} />;
 
+  // Step from safePage, not the raw page state: `page` can be stale-high after effectivePageSize
+  // grows (a mobile→desktop resize isn't in filterSig), and stepping from it makes Prev appear
+  // dead until the raw value catches back up with the clamped one.
   const pager = pageCount > 1 ? (
     <nav className="vw-pager" aria-label="Voice pages">
-      <button className="vw-pager-btn" onClick={() => setPage((p) => Math.max(0, p - 1))} disabled={safePage <= 0}>
+      <button className="vw-pager-btn" onClick={() => setPage(Math.max(0, safePage - 1))} disabled={safePage <= 0}>
         ‹ Prev
       </button>
       <span className="vw-pager-info">
         {ordered.length ? `${start + 1}–${end} of ${ordered.length}` : "0 of 0"}
         <span className="vw-pager-page"> · page {safePage + 1}/{pageCount}</span>
       </span>
-      <button className="vw-pager-btn" onClick={() => setPage((p) => Math.min(pageCount - 1, p + 1))} disabled={safePage >= pageCount - 1}>
+      <button className="vw-pager-btn" onClick={() => setPage(Math.min(pageCount - 1, safePage + 1))} disabled={safePage >= pageCount - 1}>
         Next ›
       </button>
     </nav>
@@ -352,8 +389,8 @@ export function VoiceWidget({
           <section key={`${sec.name}-${i}`} className="vw-section">
             {sec.name && <h3 className="vw-section-title">{sec.name} <span>{groupTotals.get(sec.name)}</span></h3>}
             <div className="vw-grid" style={gridStyle}>
-              {sec.items.map((r, idx) => (
-                <Card key={`${uidOf(r)}#${idx}`} r={r} playing={playingKey === uidOf(r)} onPlay={play} onCopy={copyConfig} />
+              {sec.items.map((r) => (
+                <Card key={r._uid} r={r} playing={playingKey === r._uid} onPlay={play} onCopy={copyConfig} />
               ))}
             </div>
           </section>
@@ -368,7 +405,7 @@ export function VoiceWidget({
 // Memoized so that playing/pausing a voice (which re-renders the widget) only re-renders the two
 // cards whose `playing` flag actually changed — not all ~60 cards on the page.
 const Card = memo(function Card({ r, playing, onPlay, onCopy }: {
-  r: VoiceRow; playing: boolean; onPlay: (r: VoiceRow) => void; onCopy: (r: VoiceRow) => Promise<boolean> | void;
+  r: Row; playing: boolean; onPlay: (r: Row) => void; onCopy: (r: VoiceRow) => Promise<boolean> | void;
 }) {
   const disabled = !r.clip || r.clip.status !== "ok";
   const [copied, setCopied] = useState(false);
@@ -457,9 +494,10 @@ function uniq(xs?: string[]): string[] {
   return [...new Set((xs ?? []).filter(Boolean))].sort();
 }
 
-// Stable per-voice identity. The catalog `key` (<engine>/<voice_id>) is NOT unique — a voice with
-// multiple models repeats it (e.g. rime/abbie under "mist" and "mistv2") — so append the model for
-// React keys, play-state, and allowlist disambiguation.
-function uidOf(r: VoiceRow): string {
-  return r.model ? `${r.key}:${r.model}` : r.key;
+// Model-qualified catalog key (<engine>/<voice_id>[:<model>]) — the documented matching form for
+// the voiceIds allowlist. NOT unique in the wild: a few rime voices repeat key+model (once per
+// language, plus literal duplicate rows), so row identity uses Row._uid — this plus a collision
+// counter, assigned in loadBundle.
+function modelKeyOf(v: { key: string; model: string | null }): string {
+  return v.model ? `${v.key}:${v.model}` : v.key;
 }