From 3173fbf10ea2e1f998b61b6472b21e61ee594b4c Mon Sep 17 00:00:00 2001
From: luke-speechify <289678208+luke-speechify@users.noreply.github.com>
Date: Fri, 21 Aug 2026 00:44:20 +0100
Subject: [PATCH 1/2] feat: add agent-events-inspector demo

A debug timeline for Voice Agent calls: replay a sample realtime event
stream, or inspect a live conversation by id via the Voice Agents API.
Hosted under /agent-events-inspector, gated with the shared Turnstile
helper. The workspace key stays server-side in one route handler.
---
 README.md                                     |   1 +
 demos/agent-events-inspector/.env.example     |   1 +
 demos/agent-events-inspector/.gitignore       |   5 +
 demos/agent-events-inspector/README.md        |  58 ++++
 .../app/api/conversation/route.ts             |  53 ++++
 demos/agent-events-inspector/app/globals.css  | 283 ++++++++++++++++++
 demos/agent-events-inspector/app/layout.tsx   |  21 ++
 .../app/lib/turnstile.ts                      |  37 +++
 demos/agent-events-inspector/app/page.tsx     | 268 +++++++++++++++++
 .../app/sample-events.ts                      |  55 ++++
 demos/agent-events-inspector/demo.json        |   6 +
 demos/agent-events-inspector/next.config.ts   |  11 +
 demos/agent-events-inspector/package.json     |  25 ++
 demos/agent-events-inspector/tsconfig.json    |  41 +++
 pnpm-lock.yaml                                |  25 ++
 pnpm-workspace.yaml                           |   1 +
 site/public/index.html                        |   4 +-
 vercel.json                                   |   8 +
 18 files changed, 901 insertions(+), 2 deletions(-)
 create mode 100644 demos/agent-events-inspector/.env.example
 create mode 100644 demos/agent-events-inspector/.gitignore
 create mode 100644 demos/agent-events-inspector/README.md
 create mode 100644 demos/agent-events-inspector/app/api/conversation/route.ts
 create mode 100644 demos/agent-events-inspector/app/globals.css
 create mode 100644 demos/agent-events-inspector/app/layout.tsx
 create mode 100644 demos/agent-events-inspector/app/lib/turnstile.ts
 create mode 100644 demos/agent-events-inspector/app/page.tsx
 create mode 100644 demos/agent-events-inspector/app/sample-events.ts
 create mode 100644 demos/agent-events-inspector/demo.json
 create mode 100644 demos/agent-events-inspector/next.config.ts
 create mode 100644 demos/agent-events-inspector/package.json
 create mode 100644 demos/agent-events-inspector/tsconfig.json

diff --git a/README.md b/README.md
index b23a0c8..e198e4e 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@ Demos with a **Live** link run in your browser at [demos.speechify.ai](https://d
 | [`demos/mastra-agent-speechify/`](./demos/mastra-agent-speechify) | TypeScript (Mastra) |  | Text-in, speech-out Mastra Agent using an OpenAI LLM for replies and Speechify's simba-3.2 model for TTS via `@mastra/voice-speechify`. |
 | [`demos/voice-agent-showcase/`](./demos/voice-agent-showcase) | Cloudflare Workers |  | One page, ten live Voice Agents API demos: calendar booking, policy-bound support, a page copilot, form intake, US outbound calls with a 5-minute cap, a voice gallery, mid-call language handoff, cross-call memory, a grounded knowledge base, and dual-control troubleshooting. |
 | [`demos/vercel-ai-sdk/`](./demos/vercel-ai-sdk) | TypeScript (Vercel AI SDK) |  | Speechify TTS through the Vercel AI SDK's unified `generateSpeech` interface via the official `@speechify/vercel` provider — one-line swap from OpenAI/ElevenLabs, plus word-level speech marks from `providerMetadata`. |
+| [`demos/agent-events-inspector/`](./demos/agent-events-inspector) | Next.js | [Open](https://demos.speechify.ai/agent-events-inspector) | A debug timeline for Voice Agent calls: replay a sample realtime event stream, or inspect a live conversation by id. The workspace key stays server-side. |
 <!-- DEMOS:END -->
 
 ## Get an API key
diff --git a/demos/agent-events-inspector/.env.example b/demos/agent-events-inspector/.env.example
new file mode 100644
index 0000000..534cec4
--- /dev/null
+++ b/demos/agent-events-inspector/.env.example
@@ -0,0 +1 @@
+SPEECHIFY_API_KEY=your_api_key_here
diff --git a/demos/agent-events-inspector/.gitignore b/demos/agent-events-inspector/.gitignore
new file mode 100644
index 0000000..95d1bcb
--- /dev/null
+++ b/demos/agent-events-inspector/.gitignore
@@ -0,0 +1,5 @@
+node_modules/
+.next/
+.env
+next-env.d.ts
+*.tsbuildinfo
diff --git a/demos/agent-events-inspector/README.md b/demos/agent-events-inspector/README.md
new file mode 100644
index 0000000..c67d1dc
--- /dev/null
+++ b/demos/agent-events-inspector/README.md
@@ -0,0 +1,58 @@
+# Voice agent events inspector
+
+A tiny debug view for a Speechify Voice Agent call. Watch a call unfold as a
+timeline of realtime events — session start, user transcripts, agent replies,
+tool calls and results, session end — either by **replaying a bundled sample
+stream** or by **inspecting one of your own conversations by id**. The workspace
+API key stays server-side.
+
+Pairs with the Speechify post *Realtime agent events: debugging a live voice
+agent call*.
+
+## What you get
+
+- A **timeline** that colour-codes events by source (session / user / agent /
+  tool) and lets you expand any event's raw JSON payload.
+- **Replay mode** — plays the sample event stream in
+  [`app/sample-events.ts`](./app/sample-events.ts) against a scrubber, at
+  0.5×–4× speed, so you can see how a call reads as a stream.
+- **Inspect mode** — enter a `conv_…` id (or leave blank to list recent calls);
+  the server proxies `GET /v1/agents/conversations/{id}` on the Voice Agents API
+  and renders what comes back.
+- **[`app/api/conversation/route.ts`](./app/api/conversation/route.ts)** — the
+  one server route that holds the key and talks to the API.
+
+## Run it yourself
+
+```bash
+cp .env.example .env      # paste your Speechify workspace API key
+pnpm install
+pnpm dev                  # http://localhost:8774/agent-events-inspector
+```
+
+Get a workspace key at [platform.speechify.ai/api-keys](https://platform.speechify.ai/api-keys).
+Replay mode needs no key; inspect mode needs a key with a Voice Agents workspace.
+
+## On the event schema
+
+The confirmed conversation record fields are `id`, `agent_id`, `status`,
+`started_at`, `ended_at`, and `duration_ms` — the same ones the
+[voice-agent-showcase](../voice-agent-showcase) reads. The per-event stream shape
+in `app/sample-events.ts` is **illustrative**: it shows how you'd render a live
+event feed, and the inspector renders whichever event/transcript array a live
+conversation returns. Confirm the exact live event field names against the
+[Voice Agents API docs](https://docs.speechify.ai) before wiring this to a
+production audit tool.
+
+## Abuse protection (hosted)
+
+The hosted build gates `/api/conversation` with Cloudflare Turnstile via the
+shared [`app/lib/turnstile.ts`](./app/lib/turnstile.ts) helper. It fail-opens
+when `TURNSTILE_SECRET_KEY` is unset, so local dev and forks work with zero
+config.
+
+## Prerequisites
+
+- Node 20+.
+- For inspect mode: a Speechify workspace with the Voice Agents API and at least
+  one conversation to look at.
diff --git a/demos/agent-events-inspector/app/api/conversation/route.ts b/demos/agent-events-inspector/app/api/conversation/route.ts
new file mode 100644
index 0000000..9e6d1dc
--- /dev/null
+++ b/demos/agent-events-inspector/app/api/conversation/route.ts
@@ -0,0 +1,53 @@
+import { NextResponse } from "next/server";
+import { verifyTurnstile } from "../../lib/turnstile";
+
+export const runtime = "nodejs";
+
+const BASE = "https://api.speechify.ai";
+
+// Proxies the Voice Agents conversations API so the workspace key never reaches
+// the browser. A single id returns that conversation; no id lists recent ones.
+export async function POST(req: Request) {
+  if (!(await verifyTurnstile(req))) {
+    return NextResponse.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  const key = process.env.SPEECHIFY_API_KEY;
+  if (!key) {
+    return NextResponse.json(
+      { error: "SPEECHIFY_API_KEY is not set on the server." },
+      { status: 503 },
+    );
+  }
+
+  const { id } = (await req.json().catch(() => ({}))) as { id?: string };
+
+  // conv_ ids only — don't proxy arbitrary paths.
+  if (id && !/^conv_[a-z0-9]+$/i.test(id)) {
+    return NextResponse.json({ error: "That doesn't look like a conversation id (conv_…)." }, { status: 400 });
+  }
+
+  const path = id ? `/v1/agents/conversations/${id}` : `/v1/agents/conversations?limit=20`;
+
+  try {
+    const upstream = await fetch(`${BASE}${path}`, {
+      headers: { Authorization: `Bearer ${key}` },
+    });
+    const text = await upstream.text();
+    let data: unknown = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      /* non-JSON upstream error */
+    }
+    if (!upstream.ok) {
+      return NextResponse.json(
+        { error: `Upstream ${upstream.status}`, detail: data ?? text.slice(0, 300) },
+        { status: upstream.status },
+      );
+    }
+    return NextResponse.json(data);
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 502 });
+  }
+}
diff --git a/demos/agent-events-inspector/app/globals.css b/demos/agent-events-inspector/app/globals.css
new file mode 100644
index 0000000..37ef027
--- /dev/null
+++ b/demos/agent-events-inspector/app/globals.css
@@ -0,0 +1,283 @@
+:root {
+  color-scheme: light dark;
+  --fg: #111;
+  --bg: #fff;
+  --muted: #666;
+  --border: #ddd;
+  --surface: #f6f6f6;
+  --session: #6b7280;
+  --user: #2563eb;
+  --agent: #059669;
+  --tool: #d97706;
+  --other: #9333ea;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --fg: #f2f2f2;
+    --bg: #0c0c0c;
+    --muted: #999;
+    --border: #2a2a2a;
+    --surface: #161616;
+    --session: #9ca3af;
+    --user: #60a5fa;
+    --agent: #34d399;
+    --tool: #fbbf24;
+    --other: #c084fc;
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  padding: 2rem 1rem;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  line-height: 1.5;
+}
+
+main {
+  max-width: 46rem;
+  margin: 0 auto;
+  display: flex;
+  flex-direction: column;
+  gap: 1.25rem;
+}
+
+h1 {
+  font-size: 1.6rem;
+  font-weight: 500;
+  margin: 0 0 0.4rem;
+}
+
+.lead {
+  color: var(--muted);
+  margin: 0;
+}
+
+code,
+.json {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+code {
+  background: var(--surface);
+  padding: 0.1em 0.4em;
+  border-radius: 4px;
+  font-size: 0.85em;
+}
+
+.tabs {
+  display: flex;
+  gap: 0.5rem;
+}
+
+.tabs button {
+  font: inherit;
+  cursor: pointer;
+  padding: 0.5rem 1rem;
+  border-radius: 999px;
+  border: 1px solid var(--border);
+  background: var(--bg);
+  color: var(--fg);
+}
+
+.tabs button.on {
+  background: var(--fg);
+  color: var(--bg);
+  border-color: var(--fg);
+}
+
+.panel {
+  border: 1px solid var(--border);
+  border-radius: 0.6rem;
+  padding: 1rem;
+  background: var(--surface);
+}
+
+.meta {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.75rem;
+  font-size: 0.85rem;
+  color: var(--muted);
+}
+
+.pill {
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  padding: 0.05rem 0.6rem;
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.controls {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-bottom: 0.75rem;
+  flex-wrap: wrap;
+}
+
+.controls button,
+.live-input button {
+  font: inherit;
+  cursor: pointer;
+  padding: 0.4rem 1rem;
+  border-radius: 6px;
+  border: none;
+  background: var(--fg);
+  color: var(--bg);
+}
+
+.controls input[type="range"] {
+  flex: 1;
+  min-width: 8rem;
+}
+
+.controls label {
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+  font-size: 0.85rem;
+  color: var(--muted);
+}
+
+.controls select,
+.live-input input {
+  font: inherit;
+  color: var(--fg);
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 0.35rem 0.5rem;
+}
+
+.live-input {
+  display: flex;
+  gap: 0.5rem;
+  margin-bottom: 0.5rem;
+}
+
+.live-input input {
+  flex: 1;
+}
+
+.timeline {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.evt {
+  display: grid;
+  grid-template-columns: 5.5rem 11rem 1fr auto;
+  gap: 0.5rem;
+  align-items: baseline;
+  padding: 0.35rem 0.5rem;
+  border-left: 3px solid var(--border);
+  border-radius: 0 5px 5px 0;
+  background: var(--bg);
+  font-size: 0.85rem;
+}
+
+.evt.active {
+  outline: 2px solid var(--agent);
+}
+
+.evt.session { border-left-color: var(--session); }
+.evt.user { border-left-color: var(--user); }
+.evt.agent { border-left-color: var(--agent); }
+.evt.tool { border-left-color: var(--tool); }
+.evt.other { border-left-color: var(--other); }
+
+.evt .t {
+  color: var(--muted);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.78rem;
+}
+
+.evt .type {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.8rem;
+}
+
+.evt.session .type { color: var(--session); }
+.evt.user .type { color: var(--user); }
+.evt.agent .type { color: var(--agent); }
+.evt.tool .type { color: var(--tool); }
+.evt.other .type { color: var(--other); }
+
+.evt .summary {
+  color: var(--muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.evt .peek {
+  font: inherit;
+  font-size: 0.75rem;
+  cursor: pointer;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  background: var(--surface);
+  color: var(--fg);
+  padding: 0 0.4rem;
+}
+
+.json {
+  grid-column: 1 / -1;
+  margin: 0.4rem 0 0;
+  padding: 0.6rem;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  font-size: 0.78rem;
+  overflow-x: auto;
+}
+
+.json.raw {
+  max-height: 30rem;
+  overflow: auto;
+}
+
+.error {
+  color: #dc2626;
+  font-size: 0.9rem;
+}
+
+.hint {
+  color: var(--muted);
+  font-size: 0.9rem;
+}
+
+@media (max-width: 640px) {
+  .evt {
+    grid-template-columns: 4.5rem 1fr auto;
+  }
+  .evt .summary {
+    grid-column: 1 / -1;
+  }
+}
+
+footer {
+  color: var(--muted);
+  font-size: 0.85rem;
+  border-top: 1px solid var(--border);
+  padding-top: 1rem;
+}
+
+footer a {
+  color: inherit;
+}
diff --git a/demos/agent-events-inspector/app/layout.tsx b/demos/agent-events-inspector/app/layout.tsx
new file mode 100644
index 0000000..4c8fea7
--- /dev/null
+++ b/demos/agent-events-inspector/app/layout.tsx
@@ -0,0 +1,21 @@
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import Script from "next/script";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Voice agent events inspector",
+  description:
+    "Replay a sample realtime event stream or inspect a live Speechify Voice Agent conversation in a debug timeline.",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Script src="/turnstile.js" strategy="beforeInteractive" />
+        {children}
+      </body>
+    </html>
+  );
+}
diff --git a/demos/agent-events-inspector/app/lib/turnstile.ts b/demos/agent-events-inspector/app/lib/turnstile.ts
new file mode 100644
index 0000000..6fee926
--- /dev/null
+++ b/demos/agent-events-inspector/app/lib/turnstile.ts
@@ -0,0 +1,37 @@
+// Verifies a Turnstile token against Cloudflare siteverify. Returns true iff
+// the caller is allowed to proceed.
+//
+// Fail-open contract: when TURNSTILE_SECRET_KEY isn't set (local dev, fork
+// deploys, anywhere the operator hasn't configured Turnstile) OR when the
+// siteverify request itself errors, returns true. The alternative is
+// breaking the demo whenever Turnstile isn't configured — a worse experience
+// than leaving the abuse gate briefly open. Real prod hardening would flip
+// this to fail-closed; this is a reference demo.
+const SITEVERIFY_URL =
+  "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+
+export async function verifyTurnstile(req: Request): Promise<boolean> {
+  const secret = process.env.TURNSTILE_SECRET_KEY;
+  if (!secret) return true;
+
+  const token = req.headers.get("x-turnstile-token");
+  if (!token) return false;
+
+  const form = new URLSearchParams();
+  form.set("secret", secret);
+  form.set("response", token);
+  const remoteip = req.headers
+    .get("x-forwarded-for")
+    ?.split(",")[0]
+    ?.trim();
+  if (remoteip) form.set("remoteip", remoteip);
+
+  try {
+    const cf = await fetch(SITEVERIFY_URL, { method: "POST", body: form });
+    if (!cf.ok) return true;
+    const result = (await cf.json()) as { success?: boolean };
+    return Boolean(result?.success);
+  } catch {
+    return true;
+  }
+}
diff --git a/demos/agent-events-inspector/app/page.tsx b/demos/agent-events-inspector/app/page.tsx
new file mode 100644
index 0000000..1537e33
--- /dev/null
+++ b/demos/agent-events-inspector/app/page.tsx
@@ -0,0 +1,268 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { SAMPLE, type AgentEvent } from "./sample-events";
+
+type TurnstileHandle = {
+  getToken: (opts?: { timeout?: number }) => Promise<string | null>;
+  reset: () => void;
+};
+
+declare global {
+  interface Window {
+    SpeechifyTurnstile?: {
+      render: (target: string | HTMLElement, options?: unknown) => Promise<TurnstileHandle>;
+    };
+  }
+}
+
+// Group event types into colour buckets for the timeline rail.
+function bucket(type: string): string {
+  if (type.startsWith("session")) return "session";
+  if (type.startsWith("user")) return "user";
+  if (type.startsWith("tool")) return "tool";
+  if (type.startsWith("agent")) return "agent";
+  return "other";
+}
+
+function fmt(ms: number): string {
+  const s = Math.floor(ms / 1000);
+  return `${String(Math.floor(s / 60)).padStart(2, "0")}:${String(s % 60).padStart(2, "0")}.${String(ms % 1000).padStart(3, "0")}`;
+}
+
+export default function Home() {
+  const [mode, setMode] = useState<"sample" | "live">("sample");
+  const turnstileRef = useRef<TurnstileHandle | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      while (!window.SpeechifyTurnstile && !cancelled) await new Promise((r) => setTimeout(r, 30));
+      if (!cancelled) turnstileRef.current = await window.SpeechifyTurnstile!.render("#turnstile-container");
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return (
+    <main>
+      <header>
+        <h1>Voice agent events inspector</h1>
+        <p className="lead">
+          A debug timeline for a voice-agent call. Replay a sample realtime event stream, or point
+          it at one of your own conversations by id. The workspace API key stays server-side.
+        </p>
+      </header>
+
+      <div className="tabs">
+        <button className={mode === "sample" ? "on" : ""} onClick={() => setMode("sample")}>
+          Replay sample stream
+        </button>
+        <button className={mode === "live" ? "on" : ""} onClick={() => setMode("live")}>
+          Inspect a conversation
+        </button>
+      </div>
+
+      {mode === "sample" ? <SampleReplay /> : <LiveInspect turnstileRef={turnstileRef} />}
+
+      <div id="turnstile-container" />
+
+      <footer>
+        <p>
+          Built on the{" "}
+          <a href="https://docs.speechify.ai">Voice Agents API</a> — conversations are read via{" "}
+          <code>GET /v1/agents/conversations/&#123;id&#125;</code>. The sample stream is
+          illustrative; confirm live event field names against the docs.
+        </p>
+      </footer>
+    </main>
+  );
+}
+
+function EventRow({ e, active }: { e: AgentEvent; active: boolean }) {
+  const [open, setOpen] = useState(false);
+  const summary =
+    (e.data?.text as string) ||
+    (e.data?.name ? `${e.data.name}(${JSON.stringify(e.data.arguments ?? {})})` : "") ||
+    (e.data?.reason as string) ||
+    "";
+  return (
+    <li className={`evt ${bucket(e.type)} ${active ? "active" : ""}`}>
+      <span className="t">{fmt(e.t)}</span>
+      <span className="type">{e.type}</span>
+      <span className="summary" title={summary}>
+        {summary}
+      </span>
+      {e.data ? (
+        <button className="peek" onClick={() => setOpen((v) => !v)}>
+          {open ? "−" : "{ }"}
+        </button>
+      ) : null}
+      {open && e.data ? <pre className="json">{JSON.stringify(e.data, null, 2)}</pre> : null}
+    </li>
+  );
+}
+
+function SampleReplay() {
+  const events = SAMPLE.events;
+  const total = SAMPLE.duration_ms;
+  const [playhead, setPlayhead] = useState(total); // start fully shown
+  const [playing, setPlaying] = useState(false);
+  const [speed, setSpeed] = useState(1);
+  const raf = useRef<number | null>(null);
+  const last = useRef<number>(0);
+
+  useEffect(() => {
+    if (!playing) return;
+    last.current = performance.now();
+    const tick = (now: number) => {
+      const dt = (now - last.current) * speed;
+      last.current = now;
+      setPlayhead((p) => {
+        const next = p + dt;
+        if (next >= total) {
+          setPlaying(false);
+          return total;
+        }
+        return next;
+      });
+      raf.current = requestAnimationFrame(tick);
+    };
+    raf.current = requestAnimationFrame(tick);
+    return () => {
+      if (raf.current) cancelAnimationFrame(raf.current);
+    };
+  }, [playing, speed, total]);
+
+  const shown = useMemo(() => events.filter((e) => e.t <= playhead), [events, playhead]);
+  const lastShown = shown[shown.length - 1];
+
+  function restart() {
+    setPlayhead(0);
+    setPlaying(true);
+  }
+
+  return (
+    <section className="panel">
+      <div className="meta">
+        <code>{SAMPLE.id}</code>
+        <span className="pill">{SAMPLE.status}</span>
+        <span>{fmt(playhead)} / {fmt(total)}</span>
+      </div>
+      <div className="controls">
+        <button onClick={() => (playhead >= total ? restart() : setPlaying((v) => !v))}>
+          {playing ? "▮▮ Pause" : playhead >= total ? "↻ Replay" : "▶ Play"}
+        </button>
+        <label>
+          speed
+          <select value={speed} onChange={(e) => setSpeed(Number(e.target.value))}>
+            <option value={0.5}>0.5×</option>
+            <option value={1}>1×</option>
+            <option value={2}>2×</option>
+            <option value={4}>4×</option>
+          </select>
+        </label>
+        <input
+          type="range"
+          min={0}
+          max={total}
+          value={Math.round(playhead)}
+          onChange={(e) => {
+            setPlaying(false);
+            setPlayhead(Number(e.target.value));
+          }}
+        />
+      </div>
+      <ul className="timeline">
+        {shown.map((e, i) => (
+          <EventRow key={i} e={e} active={e === lastShown && playing} />
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+function LiveInspect({ turnstileRef }: { turnstileRef: React.RefObject<TurnstileHandle | null> }) {
+  const [id, setId] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  const [conv, setConv] = useState<Record<string, unknown> | null>(null);
+
+  async function load() {
+    setBusy(true);
+    setError("");
+    setConv(null);
+    try {
+      const t = turnstileRef.current;
+      const token = t ? await t.getToken() : null;
+      const headers: Record<string, string> = { "content-type": "application/json" };
+      if (token) headers["x-turnstile-token"] = token;
+      const res = await fetch("/agent-events-inspector/api/conversation", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ id: id.trim() || undefined }),
+      });
+      t?.reset();
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error || `Request failed (${res.status})`);
+      setConv(data);
+    } catch (err) {
+      setError((err as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  // Defensive: the events/transcript array field name may vary — render whichever exists.
+  const conversation = (conv?.conversation as Record<string, unknown>) ?? conv ?? null;
+  const events =
+    (conversation?.events as AgentEvent[]) ||
+    (conversation?.transcript as AgentEvent[]) ||
+    (conversation?.turns as AgentEvent[]) ||
+    (conversation?.messages as AgentEvent[]) ||
+    null;
+
+  return (
+    <section className="panel">
+      <div className="live-input">
+        <input
+          value={id}
+          placeholder="conv_… (leave blank to list recent conversations)"
+          onChange={(e) => setId(e.target.value)}
+        />
+        <button onClick={load} disabled={busy}>
+          {busy ? "Loading…" : "Fetch"}
+        </button>
+      </div>
+      {error ? <p className="error">{error}</p> : null}
+      {conversation ? (
+        <>
+          <div className="meta">
+            {typeof conversation.id === "string" ? <code>{conversation.id}</code> : null}
+            {typeof conversation.status === "string" ? (
+              <span className="pill">{conversation.status}</span>
+            ) : null}
+            {typeof conversation.duration_ms === "number" ? (
+              <span>{fmt(conversation.duration_ms)}</span>
+            ) : null}
+          </div>
+          {events && Array.isArray(events) ? (
+            <ul className="timeline">
+              {events.map((e, i) => (
+                <EventRow key={i} e={{ t: e.t ?? 0, type: e.type ?? "event", data: (e as AgentEvent).data ?? (e as Record<string, unknown>) }} active={false} />
+              ))}
+            </ul>
+          ) : (
+            <pre className="json raw">{JSON.stringify(conv, null, 2)}</pre>
+          )}
+        </>
+      ) : (
+        <p className="hint">
+          Enter a conversation id from your workspace, or leave it blank to list recent
+          conversations. Nothing to inspect yet? Use the sample stream tab.
+        </p>
+      )}
+    </section>
+  );
+}
diff --git a/demos/agent-events-inspector/app/sample-events.ts b/demos/agent-events-inspector/app/sample-events.ts
new file mode 100644
index 0000000..7bc0eeb
--- /dev/null
+++ b/demos/agent-events-inspector/app/sample-events.ts
@@ -0,0 +1,55 @@
+// A sample realtime event stream for one voice-agent call, used by the inspector
+// when you don't have a live conversation to point at. It is ILLUSTRATIVE — it
+// shows the shape of events you'd consume from a live call and how the debug
+// timeline renders them. Confirm the exact live event schema against the Voice
+// Agents API docs (https://docs.speechify.ai) before depending on field names.
+
+export type AgentEvent = {
+  /** Milliseconds since the call started. */
+  t: number;
+  /** Event type, dotted namespace. */
+  type: string;
+  /** Free-form payload for that event type. */
+  data?: Record<string, unknown>;
+};
+
+export type SampleConversation = {
+  id: string;
+  agent_id: string;
+  status: "completed";
+  started_at: string;
+  ended_at: string;
+  duration_ms: number;
+  events: AgentEvent[];
+};
+
+export const SAMPLE: SampleConversation = {
+  id: "conv_sample000debugview",
+  agent_id: "agent_sample_frontdesk",
+  status: "completed",
+  started_at: "2026-09-16T14:02:11.000Z",
+  ended_at: "2026-09-16T14:02:41.320Z",
+  duration_ms: 30320,
+  events: [
+    { t: 0, type: "session.started", data: { agent_id: "agent_sample_frontdesk", voice: "geffen_32", model: "simba-3.2" } },
+    { t: 120, type: "agent.speech.started", data: { text: "Hi, this is Maya at Sunrise Dental — how can I help?" } },
+    { t: 2980, type: "agent.speech.ended", data: { duration_ms: 2860 } },
+    { t: 4110, type: "user.speech.started" },
+    { t: 6740, type: "user.transcript", data: { text: "I'd like to book a cleaning for next Tuesday.", is_final: true } },
+    { t: 6980, type: "agent.thinking", data: { note: "resolve intent → schedule" } },
+    { t: 7220, type: "tool.call", data: { name: "show_calendar", call_id: "call_a1", arguments: { week_of: "2026-09-21" } } },
+    { t: 7610, type: "tool.result", data: { call_id: "call_a1", result: { open: ["Tue 10:00", "Tue 14:30", "Wed 09:15"] } } },
+    { t: 7900, type: "agent.speech.started", data: { text: "I've got Tuesday at ten or half past two — which works?" } },
+    { t: 10420, type: "agent.speech.ended", data: { duration_ms: 2520 } },
+    { t: 12010, type: "user.transcript", data: { text: "Ten is perfect.", is_final: true } },
+    { t: 12360, type: "tool.call", data: { name: "create_booking", call_id: "call_b2", arguments: { slot: "Tue 10:00", reason: "cleaning" } } },
+    { t: 12980, type: "tool.result", data: { call_id: "call_b2", result: { booking_id: "bk_5521", confirmed: true } } },
+    { t: 13240, type: "agent.speech.started", data: { text: "Booked — Tuesday at ten. Anything else?" } },
+    { t: 15600, type: "agent.speech.ended", data: { duration_ms: 2360 } },
+    { t: 17020, type: "user.transcript", data: { text: "No, thanks!", is_final: true } },
+    { t: 17400, type: "agent.speech.started", data: { text: "Great, see you then. Bye!" } },
+    { t: 19120, type: "agent.speech.ended", data: { duration_ms: 1720 } },
+    { t: 19300, type: "tool.call", data: { name: "end_call", call_id: "call_c3", arguments: {} } },
+    { t: 30320, type: "session.ended", data: { reason: "agent_ended", duration_ms: 30320 } },
+  ],
+};
diff --git a/demos/agent-events-inspector/demo.json b/demos/agent-events-inspector/demo.json
new file mode 100644
index 0000000..4dd0e3b
--- /dev/null
+++ b/demos/agent-events-inspector/demo.json
@@ -0,0 +1,6 @@
+{
+  "order": 225,
+  "title": "Agent events inspector",
+  "stack": "Next.js",
+  "blurb": "A debug timeline for Voice Agent calls: replay a sample realtime event stream, or inspect a live conversation by id. The workspace key stays server-side."
+}
diff --git a/demos/agent-events-inspector/next.config.ts b/demos/agent-events-inspector/next.config.ts
new file mode 100644
index 0000000..0cfbf53
--- /dev/null
+++ b/demos/agent-events-inspector/next.config.ts
@@ -0,0 +1,11 @@
+import type { NextConfig } from "next";
+
+const basePath = "/agent-events-inspector";
+
+const nextConfig: NextConfig = {
+  // Mounted as a Vercel Service under this subpath on demos.speechify.ai.
+  // Standalone (`npm run dev`) also serves under this prefix.
+  basePath,
+};
+
+export default nextConfig;
diff --git a/demos/agent-events-inspector/package.json b/demos/agent-events-inspector/package.json
new file mode 100644
index 0000000..af674ff
--- /dev/null
+++ b/demos/agent-events-inspector/package.json
@@ -0,0 +1,25 @@
+{
+  "name": "agent-events-inspector",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Debug view for Speechify Voice Agent conversations and their realtime event stream",
+  "scripts": {
+    "dev": "next dev -p 8774",
+    "build": "next build",
+    "start": "next start -p 8774",
+    "lint": "next lint",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "next": "^16.2.10",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "typescript": "^5.6.0"
+  }
+}
diff --git a/demos/agent-events-inspector/tsconfig.json b/demos/agent-events-inspector/tsconfig.json
new file mode 100644
index 0000000..637ff2c
--- /dev/null
+++ b/demos/agent-events-inspector/tsconfig.json
@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "ES2022"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b4e8265..df064a4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -12,6 +12,31 @@ importers:
         specifier: ^2.3.0
         version: 2.10.5
 
+  demos/agent-events-inspector:
+    dependencies:
+      next:
+        specifier: ^16.2.10
+        version: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+      react:
+        specifier: ^19.2.0
+        version: 19.2.7
+      react-dom:
+        specifier: ^19.2.0
+        version: 19.2.7(react@19.2.7)
+    devDependencies:
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.20.1
+      '@types/react':
+        specifier: ^19.2.0
+        version: 19.2.17
+      '@types/react-dom':
+        specifier: ^19.2.0
+        version: 19.2.3(@types/react@19.2.17)
+      typescript:
+        specifier: ^5.6.0
+        version: 5.9.3
+
   demos/next-voice-cloning-app:
     dependencies:
       '@speechify/api':
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index dd085e3..0f002e4 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -8,3 +8,4 @@
 packages:
   - "site"
   - "demos/next-voice-cloning-app"
+  - "demos/agent-events-inspector"
diff --git a/site/public/index.html b/site/public/index.html
index c1ded39..6ae667f 100644
--- a/site/public/index.html
+++ b/site/public/index.html
@@ -276,7 +276,7 @@
     <!-- End PostHog -->
 
     <!-- JSONLD:START -->
-    <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://demos.speechify.ai/#org","name":"Speechify AI","url":"https://speechify.ai","logo":"https://demos.speechify.ai/apple-touch-icon.png","sameAs":["https://github.com/SpeechifyInc","https://x.com/SpeechifyAI","https://www.linkedin.com/company/speechifyinc/"]},{"@type":"WebSite","@id":"https://demos.speechify.ai/#website","url":"https://demos.speechify.ai/","name":"Speechify Demos","description":"Open-source demos built on the Speechify API — text-to-speech, voice cloning, and real-time voice agents.","publisher":{"@id":"https://demos.speechify.ai/#org"}},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"SpeechifyAI","item":"https://speechify.ai"},{"@type":"ListItem","position":2,"name":"Demos","item":"https://demos.speechify.ai/"}]},{"@type":"ItemList","name":"Speechify API demos","numberOfItems":15,"itemListElement":[{"@type":"ListItem","position":1,"item":{"@type":"SoftwareApplication","name":"Voice cloning web app","description":"Upload a sample, clone the voice, synthesize with the clone. The API key stays server-side in route handlers.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://demos.speechify.ai/next-voice-cloning-app","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":2,"item":{"@type":"SoftwareApplication","name":"Captions from speech marks","description":"Synthesizes audio and builds a WebVTT caption file from the speech marks the API returns in the same response. Karaoke-highlight HTML demo included.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/captions-speech-marks","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":3,"item":{"@type":"SoftwareApplication","name":"Voice cloning narration","description":"Clones a voice from a 10-30 sec WAV sample, synthesizes with the new voice, deletes the clone. End-to-end lifecycle.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/voice-cloning-narration","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":4,"item":{"@type":"SoftwareApplication","name":"Audiobook pipeline","description":"Chunks long-form text on sentence boundaries, synthesizes each chunk via the Speechify Python SDK, concatenates the MP3s with ffmpeg.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/audiobook-pipeline","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":5,"item":{"@type":"SoftwareApplication","name":"LiveKit agent (official plugin)","description":"Real-time voice assistant using LiveKit's official livekit-plugins-speechify package for TTS, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/livekit-agent-speechify-python","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":6,"item":{"@type":"SoftwareApplication","name":"LiveKit voice agent","description":"Legacy Speechify-owned LiveKit TTS demo, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession. Prefer the official LiveKit plugin demo for new work.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/livekit-voice-agent-python","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":7,"item":{"@type":"SoftwareApplication","name":"LiveKit voice agent","description":"Legacy Speechify-owned LiveKit TTS demo, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/livekit-voice-agent-node","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":8,"item":{"@type":"SoftwareApplication","name":"SSML emotion TTS","description":"Drives emotion, pauses, prosody, emphasis, and pronunciation with SSML in a single POST /v1/audio/speech request.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/ssml-emotion-tts","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":9,"item":{"@type":"SoftwareApplication","name":"Web audio streaming","description":"Streams Speechify PCM into the browser Web Audio API for low-latency playback, behind a zero-dep proxy that keeps the key server-side.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/web-audio-streaming","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":10,"item":{"@type":"SoftwareApplication","name":"Deepgram voice agent shim","description":"Points Deepgram Voice Agent at the tts-shims OpenAI-compatible proxy so it speaks with a Speechify voice, key held server-side.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/deepgram-voice-agent-shim","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":11,"item":{"@type":"SoftwareApplication","name":"Vapi custom voice","description":"Points Vapi custom voice at the tts-shims Vapi-compatible proxy so it speaks with Speechify raw PCM, key held server-side.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/vapi-custom-voice","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":12,"item":{"@type":"SoftwareApplication","name":"Pipecat agent","description":"Real-time voice pipeline using Pipecat with Deepgram STT, Anthropic Claude, and Speechify TTS through SpeechifyTTSService.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/pipecat-agent-speechify","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":13,"item":{"@type":"SoftwareApplication","name":"Mastra voice agent","description":"Text-in, speech-out Mastra Agent using an OpenAI LLM for replies and Speechify's simba-3.2 model for TTS via `@mastra/voice-speechify`.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/mastra-agent-speechify","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":14,"item":{"@type":"SoftwareApplication","name":"Voice agent capability showcase","description":"One page, ten live Voice Agents API demos: calendar booking, policy-bound support, a page copilot, form intake, US outbound calls with a 5-minute cap, a voice gallery, mid-call language handoff, cross-call memory, a grounded knowledge base, and dual-control troubleshooting.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/voice-agent-showcase","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":15,"item":{"@type":"SoftwareApplication","name":"Vercel AI SDK","description":"Speechify TTS through the Vercel AI SDK's unified `generateSpeech` interface via the official `@speechify/vercel` provider — one-line swap from OpenAI/ElevenLabs, plus word-level speech marks from `providerMetadata`.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/vercel-ai-sdk","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}}]},{"@type":"FAQPage","mainEntity":[{"@type":"Question","name":"What are the Speechify demos?","acceptedAnswer":{"@type":"Answer","text":"Open-source, self-contained example apps for the Speechify API — text-to-speech, voice cloning, SSML, and real-time voice agents. Each demo lives in its own folder, runs on its own, and links to its source. Hosted demos run live in the browser."}},{"@type":"Question","name":"Are the demos free and open source?","acceptedAnswer":{"@type":"Answer","text":"Yes. Every demo is MIT-licensed and published at github.com/Speechify-AI/demos. Clone a folder, add your Speechify API key, and run it."}},{"@type":"Question","name":"What do I need to run a demo?","acceptedAnswer":{"@type":"Answer","text":"A Speechify API key from platform.speechify.ai/api-keys, plus the runtime the demo uses (Node, Python, or Go). Each demo's README lists its exact prerequisites."}},{"@type":"Question","name":"Which demos can I try without installing anything?","acceptedAnswer":{"@type":"Answer","text":"Demos marked LIVE run hosted at demos.speechify.ai/<demo-name>. The rest are clone-and-run from the repo."}}]}]}</script>
+    <script type="application/ld+json">{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://demos.speechify.ai/#org","name":"Speechify AI","url":"https://speechify.ai","logo":"https://demos.speechify.ai/apple-touch-icon.png","sameAs":["https://github.com/SpeechifyInc","https://x.com/SpeechifyAI","https://www.linkedin.com/company/speechifyinc/"]},{"@type":"WebSite","@id":"https://demos.speechify.ai/#website","url":"https://demos.speechify.ai/","name":"Speechify Demos","description":"Open-source demos built on the Speechify API — text-to-speech, voice cloning, and real-time voice agents.","publisher":{"@id":"https://demos.speechify.ai/#org"}},{"@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"SpeechifyAI","item":"https://speechify.ai"},{"@type":"ListItem","position":2,"name":"Demos","item":"https://demos.speechify.ai/"}]},{"@type":"ItemList","name":"Speechify API demos","numberOfItems":16,"itemListElement":[{"@type":"ListItem","position":1,"item":{"@type":"SoftwareApplication","name":"Voice cloning web app","description":"Upload a sample, clone the voice, synthesize with the clone. The API key stays server-side in route handlers.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://demos.speechify.ai/next-voice-cloning-app","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":2,"item":{"@type":"SoftwareApplication","name":"Captions from speech marks","description":"Synthesizes audio and builds a WebVTT caption file from the speech marks the API returns in the same response. Karaoke-highlight HTML demo included.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/captions-speech-marks","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":3,"item":{"@type":"SoftwareApplication","name":"Voice cloning narration","description":"Clones a voice from a 10-30 sec WAV sample, synthesizes with the new voice, deletes the clone. End-to-end lifecycle.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/voice-cloning-narration","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":4,"item":{"@type":"SoftwareApplication","name":"Audiobook pipeline","description":"Chunks long-form text on sentence boundaries, synthesizes each chunk via the Speechify Python SDK, concatenates the MP3s with ffmpeg.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/audiobook-pipeline","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":5,"item":{"@type":"SoftwareApplication","name":"LiveKit agent (official plugin)","description":"Real-time voice assistant using LiveKit's official livekit-plugins-speechify package for TTS, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/livekit-agent-speechify-python","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":6,"item":{"@type":"SoftwareApplication","name":"LiveKit voice agent","description":"Legacy Speechify-owned LiveKit TTS demo, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession. Prefer the official LiveKit plugin demo for new work.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/livekit-voice-agent-python","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":7,"item":{"@type":"SoftwareApplication","name":"LiveKit voice agent","description":"Legacy Speechify-owned LiveKit TTS demo, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/livekit-voice-agent-node","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":8,"item":{"@type":"SoftwareApplication","name":"SSML emotion TTS","description":"Drives emotion, pauses, prosody, emphasis, and pronunciation with SSML in a single POST /v1/audio/speech request.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/ssml-emotion-tts","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":9,"item":{"@type":"SoftwareApplication","name":"Web audio streaming","description":"Streams Speechify PCM into the browser Web Audio API for low-latency playback, behind a zero-dep proxy that keeps the key server-side.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/web-audio-streaming","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":10,"item":{"@type":"SoftwareApplication","name":"Deepgram voice agent shim","description":"Points Deepgram Voice Agent at the tts-shims OpenAI-compatible proxy so it speaks with a Speechify voice, key held server-side.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/deepgram-voice-agent-shim","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":11,"item":{"@type":"SoftwareApplication","name":"Vapi custom voice","description":"Points Vapi custom voice at the tts-shims Vapi-compatible proxy so it speaks with Speechify raw PCM, key held server-side.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/vapi-custom-voice","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":12,"item":{"@type":"SoftwareApplication","name":"Pipecat agent","description":"Real-time voice pipeline using Pipecat with Deepgram STT, Anthropic Claude, and Speechify TTS through SpeechifyTTSService.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/pipecat-agent-speechify","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":13,"item":{"@type":"SoftwareApplication","name":"Mastra voice agent","description":"Text-in, speech-out Mastra Agent using an OpenAI LLM for replies and Speechify's simba-3.2 model for TTS via `@mastra/voice-speechify`.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/mastra-agent-speechify","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":14,"item":{"@type":"SoftwareApplication","name":"Voice agent capability showcase","description":"One page, ten live Voice Agents API demos: calendar booking, policy-bound support, a page copilot, form intake, US outbound calls with a 5-minute cap, a voice gallery, mid-call language handoff, cross-call memory, a grounded knowledge base, and dual-control troubleshooting.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/voice-agent-showcase","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":15,"item":{"@type":"SoftwareApplication","name":"Vercel AI SDK","description":"Speechify TTS through the Vercel AI SDK's unified `generateSpeech` interface via the official `@speechify/vercel` provider — one-line swap from OpenAI/ElevenLabs, plus word-level speech marks from `providerMetadata`.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://github.com/Speechify-AI/demos/tree/main/demos/vercel-ai-sdk","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}},{"@type":"ListItem","position":16,"item":{"@type":"SoftwareApplication","name":"Agent events inspector","description":"A debug timeline for Voice Agent calls: replay a sample realtime event stream, or inspect a live conversation by id. The workspace key stays server-side.","applicationCategory":"DeveloperApplication","operatingSystem":"Any","url":"https://demos.speechify.ai/agent-events-inspector","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"}}}]},{"@type":"FAQPage","mainEntity":[{"@type":"Question","name":"What are the Speechify demos?","acceptedAnswer":{"@type":"Answer","text":"Open-source, self-contained example apps for the Speechify API — text-to-speech, voice cloning, SSML, and real-time voice agents. Each demo lives in its own folder, runs on its own, and links to its source. Hosted demos run live in the browser."}},{"@type":"Question","name":"Are the demos free and open source?","acceptedAnswer":{"@type":"Answer","text":"Yes. Every demo is MIT-licensed and published at github.com/Speechify-AI/demos. Clone a folder, add your Speechify API key, and run it."}},{"@type":"Question","name":"What do I need to run a demo?","acceptedAnswer":{"@type":"Answer","text":"A Speechify API key from platform.speechify.ai/api-keys, plus the runtime the demo uses (Node, Python, or Go). Each demo's README lists its exact prerequisites."}},{"@type":"Question","name":"Which demos can I try without installing anything?","acceptedAnswer":{"@type":"Answer","text":"Demos marked LIVE run hosted at demos.speechify.ai/<demo-name>. The rest are clone-and-run from the repo."}}]}]}</script>
 <!-- JSONLD:END -->
   </head>
   <body>
@@ -368,7 +368,7 @@ <h2>FAQ</h2>
 
     <script>
       /* DEMOS_DATA:START */
-      window.__DEMOS__ = [{"slug":"next-voice-cloning-app","repoPath":"demos/next-voice-cloning-app","title":"Voice cloning web app","stack":"Next.js","hosted":true,"blurb":"Upload a sample, clone the voice, synthesize with the clone. The API key stays server-side in route handlers."},{"slug":"captions-speech-marks","repoPath":"demos/captions-speech-marks","title":"Captions from speech marks","stack":"TypeScript (native)","hosted":false,"blurb":"Synthesizes audio and builds a WebVTT caption file from the speech marks the API returns in the same response. Karaoke-highlight HTML demo included."},{"slug":"voice-cloning-narration","repoPath":"demos/voice-cloning-narration","title":"Voice cloning narration","stack":"TypeScript (native)","hosted":false,"blurb":"Clones a voice from a 10-30 sec WAV sample, synthesizes with the new voice, deletes the clone. End-to-end lifecycle."},{"slug":"audiobook-pipeline","repoPath":"demos/audiobook-pipeline","title":"Audiobook pipeline","stack":"Python (SDK)","hosted":false,"blurb":"Chunks long-form text on sentence boundaries, synthesizes each chunk via the Speechify Python SDK, concatenates the MP3s with ffmpeg."},{"slug":"livekit-agent-speechify-python","repoPath":"demos/livekit-agent-speechify-python","title":"LiveKit agent (official plugin)","stack":"Python (LiveKit)","hosted":false,"blurb":"Real-time voice assistant using LiveKit's official livekit-plugins-speechify package for TTS, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession."},{"slug":"livekit-voice-agent-python","repoPath":"demos/livekit-voice-agent-python","title":"LiveKit voice agent","stack":"Python (LiveKit)","hosted":false,"blurb":"Legacy Speechify-owned LiveKit TTS demo, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession. Prefer the official LiveKit plugin demo for new work."},{"slug":"livekit-voice-agent-node","repoPath":"demos/livekit-voice-agent-node","title":"LiveKit voice agent","stack":"TypeScript (LiveKit)","hosted":false,"blurb":"Legacy Speechify-owned LiveKit TTS demo, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession."},{"slug":"ssml-emotion-tts","repoPath":"demos/ssml-emotion-tts","title":"SSML emotion TTS","stack":"TypeScript (SDK)","hosted":false,"blurb":"Drives emotion, pauses, prosody, emphasis, and pronunciation with SSML in a single POST /v1/audio/speech request."},{"slug":"web-audio-streaming","repoPath":"demos/web-audio-streaming","title":"Web audio streaming","stack":"TypeScript (browser)","hosted":false,"blurb":"Streams Speechify PCM into the browser Web Audio API for low-latency playback, behind a zero-dep proxy that keeps the key server-side."},{"slug":"deepgram-voice-agent-shim","repoPath":"demos/deepgram-voice-agent-shim","title":"Deepgram voice agent shim","stack":"Go shim + Node","hosted":false,"blurb":"Points Deepgram Voice Agent at the tts-shims OpenAI-compatible proxy so it speaks with a Speechify voice, key held server-side."},{"slug":"vapi-custom-voice","repoPath":"demos/vapi-custom-voice","title":"Vapi custom voice","stack":"Go shim","hosted":false,"blurb":"Points Vapi custom voice at the tts-shims Vapi-compatible proxy so it speaks with Speechify raw PCM, key held server-side."},{"slug":"pipecat-agent-speechify","repoPath":"demos/pipecat-agent-speechify","title":"Pipecat agent","stack":"Python (Pipecat)","hosted":false,"blurb":"Real-time voice pipeline using Pipecat with Deepgram STT, Anthropic Claude, and Speechify TTS through SpeechifyTTSService."},{"slug":"mastra-agent-speechify","repoPath":"demos/mastra-agent-speechify","title":"Mastra voice agent","stack":"TypeScript (Mastra)","hosted":false,"blurb":"Text-in, speech-out Mastra Agent using an OpenAI LLM for replies and Speechify's simba-3.2 model for TTS via `@mastra/voice-speechify`."},{"slug":"voice-agent-showcase","repoPath":"demos/voice-agent-showcase","title":"Voice agent capability showcase","stack":"Cloudflare Workers","hosted":false,"blurb":"One page, ten live Voice Agents API demos: calendar booking, policy-bound support, a page copilot, form intake, US outbound calls with a 5-minute cap, a voice gallery, mid-call language handoff, cross-call memory, a grounded knowledge base, and dual-control troubleshooting."},{"slug":"vercel-ai-sdk","repoPath":"demos/vercel-ai-sdk","title":"Vercel AI SDK","stack":"TypeScript (Vercel AI SDK)","hosted":false,"blurb":"Speechify TTS through the Vercel AI SDK's unified `generateSpeech` interface via the official `@speechify/vercel` provider — one-line swap from OpenAI/ElevenLabs, plus word-level speech marks from `providerMetadata`."}];
+      window.__DEMOS__ = [{"slug":"next-voice-cloning-app","repoPath":"demos/next-voice-cloning-app","title":"Voice cloning web app","stack":"Next.js","hosted":true,"blurb":"Upload a sample, clone the voice, synthesize with the clone. The API key stays server-side in route handlers."},{"slug":"captions-speech-marks","repoPath":"demos/captions-speech-marks","title":"Captions from speech marks","stack":"TypeScript (native)","hosted":false,"blurb":"Synthesizes audio and builds a WebVTT caption file from the speech marks the API returns in the same response. Karaoke-highlight HTML demo included."},{"slug":"voice-cloning-narration","repoPath":"demos/voice-cloning-narration","title":"Voice cloning narration","stack":"TypeScript (native)","hosted":false,"blurb":"Clones a voice from a 10-30 sec WAV sample, synthesizes with the new voice, deletes the clone. End-to-end lifecycle."},{"slug":"audiobook-pipeline","repoPath":"demos/audiobook-pipeline","title":"Audiobook pipeline","stack":"Python (SDK)","hosted":false,"blurb":"Chunks long-form text on sentence boundaries, synthesizes each chunk via the Speechify Python SDK, concatenates the MP3s with ffmpeg."},{"slug":"livekit-agent-speechify-python","repoPath":"demos/livekit-agent-speechify-python","title":"LiveKit agent (official plugin)","stack":"Python (LiveKit)","hosted":false,"blurb":"Real-time voice assistant using LiveKit's official livekit-plugins-speechify package for TTS, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession."},{"slug":"livekit-voice-agent-python","repoPath":"demos/livekit-voice-agent-python","title":"LiveKit voice agent","stack":"Python (LiveKit)","hosted":false,"blurb":"Legacy Speechify-owned LiveKit TTS demo, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession. Prefer the official LiveKit plugin demo for new work."},{"slug":"livekit-voice-agent-node","repoPath":"demos/livekit-voice-agent-node","title":"LiveKit voice agent","stack":"TypeScript (LiveKit)","hosted":false,"blurb":"Legacy Speechify-owned LiveKit TTS demo, with Deepgram STT and an OpenAI LLM in a LiveKit AgentSession."},{"slug":"ssml-emotion-tts","repoPath":"demos/ssml-emotion-tts","title":"SSML emotion TTS","stack":"TypeScript (SDK)","hosted":false,"blurb":"Drives emotion, pauses, prosody, emphasis, and pronunciation with SSML in a single POST /v1/audio/speech request."},{"slug":"web-audio-streaming","repoPath":"demos/web-audio-streaming","title":"Web audio streaming","stack":"TypeScript (browser)","hosted":false,"blurb":"Streams Speechify PCM into the browser Web Audio API for low-latency playback, behind a zero-dep proxy that keeps the key server-side."},{"slug":"deepgram-voice-agent-shim","repoPath":"demos/deepgram-voice-agent-shim","title":"Deepgram voice agent shim","stack":"Go shim + Node","hosted":false,"blurb":"Points Deepgram Voice Agent at the tts-shims OpenAI-compatible proxy so it speaks with a Speechify voice, key held server-side."},{"slug":"vapi-custom-voice","repoPath":"demos/vapi-custom-voice","title":"Vapi custom voice","stack":"Go shim","hosted":false,"blurb":"Points Vapi custom voice at the tts-shims Vapi-compatible proxy so it speaks with Speechify raw PCM, key held server-side."},{"slug":"pipecat-agent-speechify","repoPath":"demos/pipecat-agent-speechify","title":"Pipecat agent","stack":"Python (Pipecat)","hosted":false,"blurb":"Real-time voice pipeline using Pipecat with Deepgram STT, Anthropic Claude, and Speechify TTS through SpeechifyTTSService."},{"slug":"mastra-agent-speechify","repoPath":"demos/mastra-agent-speechify","title":"Mastra voice agent","stack":"TypeScript (Mastra)","hosted":false,"blurb":"Text-in, speech-out Mastra Agent using an OpenAI LLM for replies and Speechify's simba-3.2 model for TTS via `@mastra/voice-speechify`."},{"slug":"voice-agent-showcase","repoPath":"demos/voice-agent-showcase","title":"Voice agent capability showcase","stack":"Cloudflare Workers","hosted":false,"blurb":"One page, ten live Voice Agents API demos: calendar booking, policy-bound support, a page copilot, form intake, US outbound calls with a 5-minute cap, a voice gallery, mid-call language handoff, cross-call memory, a grounded knowledge base, and dual-control troubleshooting."},{"slug":"vercel-ai-sdk","repoPath":"demos/vercel-ai-sdk","title":"Vercel AI SDK","stack":"TypeScript (Vercel AI SDK)","hosted":false,"blurb":"Speechify TTS through the Vercel AI SDK's unified `generateSpeech` interface via the official `@speechify/vercel` provider — one-line swap from OpenAI/ElevenLabs, plus word-level speech marks from `providerMetadata`."},{"slug":"agent-events-inspector","repoPath":"demos/agent-events-inspector","title":"Agent events inspector","stack":"Next.js","hosted":true,"blurb":"A debug timeline for Voice Agent calls: replay a sample realtime event stream, or inspect a live conversation by id. The workspace key stays server-side."}];
 /* DEMOS_DATA:END */
     </script>
     <script>
diff --git a/vercel.json b/vercel.json
index 52519fb..4903b38 100644
--- a/vercel.json
+++ b/vercel.json
@@ -9,6 +9,10 @@
     "next-voice-cloning-app": {
       "root": "demos/next-voice-cloning-app/",
       "framework": "nextjs"
+    },
+    "agent-events-inspector": {
+      "root": "demos/agent-events-inspector/",
+      "framework": "nextjs"
     }
   },
   "rewrites": [
@@ -16,6 +20,10 @@
       "source": "/next-voice-cloning-app/:path*",
       "destination": { "service": "next-voice-cloning-app" }
     },
+    {
+      "source": "/agent-events-inspector/:path*",
+      "destination": { "service": "agent-events-inspector" }
+    },
     {
       "source": "/",
       "destination": { "service": "site", "path": "/index.html" }

From 0be613f4b959dcdb0c162b3fc008a35229387698 Mon Sep 17 00:00:00 2001
From: luke-speechify <289678208+luke-speechify@users.noreply.github.com>
Date: Fri, 21 Aug 2026 01:16:02 +0100
Subject: [PATCH 2/2] feat(agent-events-inspector): apply Speechify brand
 styling and add real-API e2e

---
 demos/agent-events-inspector/.gitignore       |   4 +
 demos/agent-events-inspector/app/globals.css  | 310 ++++++++++++------
 demos/agent-events-inspector/app/page.tsx     |   9 +-
 .../e2e/agent-events-inspector.spec.ts        |  66 ++++
 demos/agent-events-inspector/package.json     |   4 +-
 .../playwright.config.ts                      |  22 ++
 pnpm-lock.yaml                                |  45 ++-
 7 files changed, 352 insertions(+), 108 deletions(-)
 create mode 100644 demos/agent-events-inspector/e2e/agent-events-inspector.spec.ts
 create mode 100644 demos/agent-events-inspector/playwright.config.ts

diff --git a/demos/agent-events-inspector/.gitignore b/demos/agent-events-inspector/.gitignore
index 95d1bcb..e838375 100644
--- a/demos/agent-events-inspector/.gitignore
+++ b/demos/agent-events-inspector/.gitignore
@@ -3,3 +3,7 @@ node_modules/
 .env
 next-env.d.ts
 *.tsbuildinfo
+test-results/
+playwright-report/
+/.playwright/
+.last-run.json
diff --git a/demos/agent-events-inspector/app/globals.css b/demos/agent-events-inspector/app/globals.css
index 37ef027..c96c327 100644
--- a/demos/agent-events-inspector/app/globals.css
+++ b/demos/agent-events-inspector/app/globals.css
@@ -1,74 +1,202 @@
-:root {
-  color-scheme: light dark;
-  --fg: #111;
-  --bg: #fff;
-  --muted: #666;
-  --border: #ddd;
-  --surface: #f6f6f6;
-  --session: #6b7280;
-  --user: #2563eb;
-  --agent: #059669;
-  --tool: #d97706;
-  --other: #9333ea;
-}
+/* Speechify brand base — mirrors demos.speechify.ai/site (speechify.ai/brand).
+ * ABC Diatype is licensed and NOT committed; it is loaded cross-origin from
+ * speechify.ai/fonts (served with Access-Control-Allow-Origin: *). Monochrome
+ * palette, thin display type, pill ink buttons, sentence-case voice.
+ * Paste this block at the TOP of the demo's app/globals.css, then make the
+ * demo-specific rules below it reference these tokens (no hardcoded colours). */
+
+@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Thin.woff2") format("woff2"); font-weight: 100; font-style: normal; font-display: swap; }
+@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Light.woff2") format("woff2"); font-weight: 300; font-style: normal; font-display: swap; }
+@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Regular.woff2") format("woff2"); font-weight: 400; font-style: normal; font-display: swap; }
+@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Medium.woff2") format("woff2"); font-weight: 500; font-style: normal; font-display: swap; }
+@font-face { font-family: "ABCDiatype"; src: url("https://speechify.ai/fonts/ABCDiatype-Bold.woff2") format("woff2"); font-weight: 700; font-style: normal; font-display: swap; }
 
+:root {
+  --font-sans: "ABCDiatype", ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, "Cascadia Code", monospace;
+
+  --surface-page: #ffffff;
+  --surface-card: #ffffff;
+  --surface-subtle: #f5f5f5;
+  --surface-raised: #fafafa;
+  --text-primary: #0a0a0a;
+  --text-secondary: #525252;
+  --text-tertiary: #666666;
+  --border-subtle: #e5e5e5;
+  --border-strong: #d1d1d4;
+  --action: #0a0a0a;
+  --action-hover: #2a2a2e;
+  --action-foreground: #fafafa;
+  --focus-ring: rgba(10, 10, 10, 0.22);
+  --success: #00c270;
+  --danger: #b42318;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  --radius-pill: 9999px;
+}
+
+/* Interactive apps: keep a monochrome dark mapping so night viewers aren't
+ * blinded. Still monochrome, still on-brand (inverted ink/paper). */
 @media (prefers-color-scheme: dark) {
   :root {
-    --fg: #f2f2f2;
-    --bg: #0c0c0c;
-    --muted: #999;
-    --border: #2a2a2a;
-    --surface: #161616;
-    --session: #9ca3af;
-    --user: #60a5fa;
-    --agent: #34d399;
-    --tool: #fbbf24;
-    --other: #c084fc;
+    --surface-page: #0a0a0a;
+    --surface-card: #101010;
+    --surface-subtle: #161616;
+    --surface-raised: #141414;
+    --text-primary: #fafafa;
+    --text-secondary: #b3b3b3;
+    --text-tertiary: #8a8a8a;
+    --border-subtle: #262626;
+    --border-strong: #3a3a3a;
+    --action: #fafafa;
+    --action-hover: #e5e5e5;
+    --action-foreground: #0a0a0a;
+    --focus-ring: rgba(250, 250, 250, 0.28);
   }
 }
 
-* {
-  box-sizing: border-box;
-}
+* { box-sizing: border-box; }
 
 body {
   margin: 0;
-  padding: 2rem 1rem;
-  background: var(--bg);
-  color: var(--fg);
-  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
-  line-height: 1.5;
+  padding: 4rem 1.5rem;
+  background: var(--surface-page);
+  color: var(--text-primary);
+  font-family: var(--font-sans);
+  font-weight: 400;
+  line-height: 1.55;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
 }
 
 main {
-  max-width: 46rem;
+  max-width: 44rem;
   margin: 0 auto;
   display: flex;
   flex-direction: column;
-  gap: 1.25rem;
+  gap: 1.75rem;
 }
 
+/* Thin display headings, tight tracking, sentence case (author copy in sentence case). */
 h1 {
-  font-size: 1.6rem;
+  font-weight: 100;
+  font-size: clamp(2.25rem, 6vw, 3.5rem);
+  line-height: 1.02;
+  letter-spacing: -0.03em;
+  margin: 0 0 0.5rem;
+}
+h2 { font-weight: 300; letter-spacing: -0.01em; margin: 0 0 0.5rem; }
+
+.eyebrow {
+  font-family: var(--font-mono);
+  font-size: 13px;
   font-weight: 500;
-  margin: 0 0 0.4rem;
+  letter-spacing: 0.02em;
+  color: var(--text-tertiary);
+  text-transform: none;
+  margin: 0 0 0.75rem;
 }
 
 .lead {
-  color: var(--muted);
+  max-width: 62ch;
+  color: var(--text-secondary);
+  font-size: 1.0625rem;
+  line-height: 1.55;
   margin: 0;
 }
 
-code,
-.json {
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-}
+a { color: var(--text-primary); text-underline-offset: 2px; }
 
+code, kbd, samp { font-family: var(--font-mono); }
 code {
-  background: var(--surface);
-  padding: 0.1em 0.4em;
-  border-radius: 4px;
-  font-size: 0.85em;
+  background: var(--surface-subtle);
+  border: 1px solid var(--border-subtle);
+  padding: 0.08em 0.38em;
+  border-radius: 5px;
+  font-size: 0.88em;
+}
+
+.card, .step {
+  background: var(--surface-subtle);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg);
+  padding: 1.25rem;
+}
+
+label { display: block; font-size: 0.9rem; color: var(--text-secondary); margin: 0 0 0.5rem; }
+
+input[type="text"], input[type="email"], textarea, select {
+  width: 100%;
+  font: inherit;
+  color: var(--text-primary);
+  background: var(--surface-card);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  padding: 0.65rem 0.8rem;
+}
+textarea { resize: vertical; }
+
+input:focus-visible, textarea:focus-visible, select:focus-visible, button:focus-visible {
+  outline: 3px solid var(--focus-ring);
+  outline-offset: 1px;
+}
+
+/* Pill buttons — medium weight only, never 600. */
+.btn, button.btn {
+  font: inherit;
+  font-weight: 500;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.4rem;
+  border-radius: var(--radius-pill);
+  padding: 0.65rem 1.5rem;
+  border: 1px solid transparent;
+  transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease;
+}
+.btn-primary { background: var(--action); color: var(--action-foreground); }
+.btn-primary:hover:not(:disabled) { background: var(--action-hover); }
+.btn-outline { background: transparent; color: var(--text-primary); border-color: var(--border-strong); }
+.btn-outline:hover:not(:disabled) { background: var(--action); color: var(--action-foreground); border-color: var(--action); }
+.btn:disabled { opacity: 0.55; cursor: default; }
+
+footer {
+  color: var(--text-tertiary);
+  font-size: 0.9rem;
+  border-top: 1px solid var(--border-subtle);
+  padding-top: 1.25rem;
+}
+footer a { color: inherit; }
+
+@media (prefers-reduced-motion: reduce) {
+  * { animation-duration: 0.001ms !important; animation-iteration-count: 1 !important; transition-duration: 0.001ms !important; }
+}
+
+/* ── Demo-specific: agent events inspector ─────────────────────────────────
+ * A dense debug timeline needs a slightly wider column than the 44rem default.
+ * Event-type rail colours are kept as semantic accents (see brand note: agent
+ * event-type colours may stay as-is); everything else references brand tokens. */
+
+main { max-width: 46rem; }
+
+/* Event-type accents for the timeline rail — semantic, kept as-is. */
+:root {
+  --session: #6b7280;
+  --user: #2563eb;
+  --agent: #059669;
+  --tool: #d97706;
+  --other: #9333ea;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --session: #9ca3af;
+    --user: #60a5fa;
+    --agent: #34d399;
+    --tool: #fbbf24;
+    --other: #c084fc;
+  }
 }
 
 .tabs {
@@ -78,25 +206,27 @@ code {
 
 .tabs button {
   font: inherit;
+  font-weight: 500;
   cursor: pointer;
-  padding: 0.5rem 1rem;
-  border-radius: 999px;
-  border: 1px solid var(--border);
-  background: var(--bg);
-  color: var(--fg);
+  padding: 0.5rem 1.1rem;
+  border-radius: var(--radius-pill);
+  border: 1px solid var(--border-strong);
+  background: transparent;
+  color: var(--text-primary);
+  transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease;
 }
 
 .tabs button.on {
-  background: var(--fg);
-  color: var(--bg);
-  border-color: var(--fg);
+  background: var(--action);
+  color: var(--action-foreground);
+  border-color: var(--action);
 }
 
 .panel {
-  border: 1px solid var(--border);
-  border-radius: 0.6rem;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-lg);
   padding: 1rem;
-  background: var(--surface);
+  background: var(--surface-subtle);
 }
 
 .meta {
@@ -106,12 +236,12 @@ code {
   flex-wrap: wrap;
   margin-bottom: 0.75rem;
   font-size: 0.85rem;
-  color: var(--muted);
+  color: var(--text-secondary);
 }
 
 .pill {
-  border: 1px solid var(--border);
-  border-radius: 999px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-pill);
   padding: 0.05rem 0.6rem;
   font-size: 0.75rem;
   text-transform: uppercase;
@@ -126,17 +256,6 @@ code {
   flex-wrap: wrap;
 }
 
-.controls button,
-.live-input button {
-  font: inherit;
-  cursor: pointer;
-  padding: 0.4rem 1rem;
-  border-radius: 6px;
-  border: none;
-  background: var(--fg);
-  color: var(--bg);
-}
-
 .controls input[type="range"] {
   flex: 1;
   min-width: 8rem;
@@ -147,17 +266,14 @@ code {
   align-items: center;
   gap: 0.35rem;
   font-size: 0.85rem;
-  color: var(--muted);
+  color: var(--text-secondary);
+  margin: 0;
 }
 
-.controls select,
-.live-input input {
-  font: inherit;
-  color: var(--fg);
-  background: var(--bg);
-  border: 1px solid var(--border);
-  border-radius: 6px;
+.controls select {
+  width: auto;
   padding: 0.35rem 0.5rem;
+  border-radius: var(--radius-md);
 }
 
 .live-input {
@@ -185,9 +301,9 @@ code {
   gap: 0.5rem;
   align-items: baseline;
   padding: 0.35rem 0.5rem;
-  border-left: 3px solid var(--border);
+  border-left: 3px solid var(--border-subtle);
   border-radius: 0 5px 5px 0;
-  background: var(--bg);
+  background: var(--surface-card);
   font-size: 0.85rem;
 }
 
@@ -202,13 +318,13 @@ code {
 .evt.other { border-left-color: var(--other); }
 
 .evt .t {
-  color: var(--muted);
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: var(--text-tertiary);
+  font-family: var(--font-mono);
   font-size: 0.78rem;
 }
 
 .evt .type {
-  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-family: var(--font-mono);
   font-size: 0.8rem;
 }
 
@@ -219,7 +335,7 @@ code {
 .evt.other .type { color: var(--other); }
 
 .evt .summary {
-  color: var(--muted);
+  color: var(--text-secondary);
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
@@ -229,10 +345,10 @@ code {
   font: inherit;
   font-size: 0.75rem;
   cursor: pointer;
-  border: 1px solid var(--border);
+  border: 1px solid var(--border-subtle);
   border-radius: 5px;
-  background: var(--surface);
-  color: var(--fg);
+  background: var(--surface-subtle);
+  color: var(--text-primary);
   padding: 0 0.4rem;
 }
 
@@ -240,9 +356,10 @@ code {
   grid-column: 1 / -1;
   margin: 0.4rem 0 0;
   padding: 0.6rem;
-  background: var(--surface);
-  border: 1px solid var(--border);
-  border-radius: 6px;
+  background: var(--surface-raised);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  font-family: var(--font-mono);
   font-size: 0.78rem;
   overflow-x: auto;
 }
@@ -253,12 +370,12 @@ code {
 }
 
 .error {
-  color: #dc2626;
+  color: var(--danger);
   font-size: 0.9rem;
 }
 
 .hint {
-  color: var(--muted);
+  color: var(--text-secondary);
   font-size: 0.9rem;
 }
 
@@ -270,14 +387,3 @@ code {
     grid-column: 1 / -1;
   }
 }
-
-footer {
-  color: var(--muted);
-  font-size: 0.85rem;
-  border-top: 1px solid var(--border);
-  padding-top: 1rem;
-}
-
-footer a {
-  color: inherit;
-}
diff --git a/demos/agent-events-inspector/app/page.tsx b/demos/agent-events-inspector/app/page.tsx
index 1537e33..034adb8 100644
--- a/demos/agent-events-inspector/app/page.tsx
+++ b/demos/agent-events-inspector/app/page.tsx
@@ -48,6 +48,7 @@ export default function Home() {
   return (
     <main>
       <header>
+        <p className="eyebrow">Speechify · Voice Agents API</p>
         <h1>Voice agent events inspector</h1>
         <p className="lead">
           A debug timeline for a voice-agent call. Replay a sample realtime event stream, or point
@@ -151,7 +152,10 @@ function SampleReplay() {
         <span>{fmt(playhead)} / {fmt(total)}</span>
       </div>
       <div className="controls">
-        <button onClick={() => (playhead >= total ? restart() : setPlaying((v) => !v))}>
+        <button
+          className="btn btn-primary"
+          onClick={() => (playhead >= total ? restart() : setPlaying((v) => !v))}
+        >
           {playing ? "▮▮ Pause" : playhead >= total ? "↻ Replay" : "▶ Play"}
         </button>
         <label>
@@ -227,11 +231,12 @@ function LiveInspect({ turnstileRef }: { turnstileRef: React.RefObject<Turnstile
     <section className="panel">
       <div className="live-input">
         <input
+          type="text"
           value={id}
           placeholder="conv_… (leave blank to list recent conversations)"
           onChange={(e) => setId(e.target.value)}
         />
-        <button onClick={load} disabled={busy}>
+        <button className="btn btn-primary" onClick={load} disabled={busy}>
           {busy ? "Loading…" : "Fetch"}
         </button>
       </div>
diff --git a/demos/agent-events-inspector/e2e/agent-events-inspector.spec.ts b/demos/agent-events-inspector/e2e/agent-events-inspector.spec.ts
new file mode 100644
index 0000000..19ef585
--- /dev/null
+++ b/demos/agent-events-inspector/e2e/agent-events-inspector.spec.ts
@@ -0,0 +1,66 @@
+import { test, expect } from "@playwright/test";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+// Real-API e2e: boots `pnpm dev` and drives the inspector against the live
+// Speechify Voice Agents API. No mocking of the API or of Turnstile behaviour.
+//
+// The demo's layout loads the shared Turnstile client from the site root
+// (`<script src="/turnstile.js">`). When hosted, demos.speechify.ai serves that
+// file for every demo; a standalone `pnpm dev` has no site root, so we serve the
+// *genuine* site asset to the browser. It's the real script — on localhost
+// Cloudflare rejects the domain, the widget fails open exactly as in production,
+// and the request goes out tokenless. The server's verifyTurnstile also fails
+// open locally (no TURNSTILE_SECRET_KEY), so the call reaches the real API.
+const dir = path.dirname(fileURLToPath(import.meta.url));
+const turnstileFile = path.resolve(dir, "../../../site/public/turnstile.js");
+
+const SLUG = "/agent-events-inspector";
+
+test.skip(!process.env.SPEECHIFY_API_KEY, "needs SPEECHIFY_API_KEY");
+
+test("replays the sample timeline and lists real conversations from the API", async ({
+  page,
+}) => {
+  await page.route("**/turnstile.js", (route) =>
+    route.fulfill({
+      path: turnstileFile,
+      contentType: "application/javascript",
+    }),
+  );
+
+  await page.goto(SLUG);
+
+  // Page shell renders.
+  await expect(
+    page.getByRole("heading", { name: /voice agent events inspector/i }),
+  ).toBeVisible();
+  await expect(page.locator("#turnstile-container")).toBeAttached();
+
+  // Default "Replay sample" tab renders a timeline with at least one event row.
+  const sampleTab = page.getByRole("button", { name: /replay sample/i });
+  await expect(sampleTab).toHaveClass(/on/);
+  await expect(page.locator(".timeline .evt").first()).toBeVisible();
+  expect(await page.locator(".timeline .evt").count()).toBeGreaterThan(0);
+
+  // Switch to the live "Inspect a conversation" tab.
+  await page.getByRole("button", { name: /inspect a conversation/i }).click();
+  const fetchBtn = page.getByRole("button", { name: /^fetch$/i });
+  await expect(fetchBtn).toBeVisible();
+
+  // Fetch with a blank id → lists recent conversations from the real API.
+  const responsePromise = page.waitForResponse(
+    (r) => r.url().includes("/api/conversation") && r.status() === 200,
+    { timeout: 60_000 },
+  );
+  await fetchBtn.click();
+  const response = await responsePromise;
+
+  // Real-API assertion: the body carries a `conversations` array. An empty
+  // array from the live Voice Agents API is a valid pass.
+  const body = (await response.json()) as { conversations?: unknown };
+  expect(Array.isArray(body.conversations)).toBe(true);
+
+  // UI leaves the loading state.
+  await expect(fetchBtn).toHaveText(/fetch/i);
+});
diff --git a/demos/agent-events-inspector/package.json b/demos/agent-events-inspector/package.json
index af674ff..2a7f2b4 100644
--- a/demos/agent-events-inspector/package.json
+++ b/demos/agent-events-inspector/package.json
@@ -9,7 +9,8 @@
     "build": "next build",
     "start": "next start -p 8774",
     "lint": "next lint",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "e2e": "playwright test"
   },
   "dependencies": {
     "next": "^16.2.10",
@@ -17,6 +18,7 @@
     "react-dom": "^19.2.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.50.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
diff --git a/demos/agent-events-inspector/playwright.config.ts b/demos/agent-events-inspector/playwright.config.ts
new file mode 100644
index 0000000..daf2521
--- /dev/null
+++ b/demos/agent-events-inspector/playwright.config.ts
@@ -0,0 +1,22 @@
+import { defineConfig } from "@playwright/test";
+
+const PORT = 8774;
+
+export default defineConfig({
+  testDir: "./e2e",
+  timeout: 90_000,
+  expect: { timeout: 30_000 },
+  reporter: "list",
+  fullyParallel: false,
+  workers: 1,
+  use: {
+    baseURL: `http://localhost:${PORT}`,
+    trace: "on-first-retry",
+  },
+  webServer: {
+    command: "pnpm dev",
+    url: `http://localhost:${PORT}/agent-events-inspector`,
+    timeout: 120_000,
+    reuseExistingServer: !process.env.CI,
+  },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index df064a4..7a9d19c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -16,7 +16,7 @@ importers:
     dependencies:
       next:
         specifier: ^16.2.10
-        version: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+        version: 16.2.10(@playwright/test@1.62.1)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       react:
         specifier: ^19.2.0
         version: 19.2.7
@@ -24,6 +24,9 @@ importers:
         specifier: ^19.2.0
         version: 19.2.7(react@19.2.7)
     devDependencies:
+      '@playwright/test':
+        specifier: ^1.50.0
+        version: 1.62.1
       '@types/node':
         specifier: ^22.0.0
         version: 22.20.1
@@ -44,7 +47,7 @@ importers:
         version: 3.0.1
       next:
         specifier: ^16.2.10
-        version: 16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
+        version: 16.2.10(@playwright/test@1.62.1)(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
       react:
         specifier: ^19.2.0
         version: 19.2.7
@@ -260,6 +263,11 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@playwright/test@1.62.1':
+    resolution: {integrity: sha512-DTcUc8qii+cpHvtOwggMtBRMjKZHXYWdw8syRYu2vtzuq4Wxphqq4NfCs5Zt44L6mA8rfDfj+PHnxFc/FeK6mQ==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   '@speechify/api@3.0.1':
     resolution: {integrity: sha512-bEqbyvwGW0A/cgq+ZsQJVP3Hm4/0Bm1sniVtPLBh7vDNG2f/YY8y8sweWojoUnhIeIAL6bHBde43+VZLA2MYpA==}
     engines: {node: '>=18.0.0'}
@@ -326,6 +334,11 @@ packages:
     resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
     engines: {node: '>=8'}
 
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
   nanoid@3.3.16:
     resolution: {integrity: sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -355,6 +368,16 @@ packages:
   picocolors@1.1.1:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
+  playwright-core@1.62.1:
+    resolution: {integrity: sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==}
+    engines: {node: '>=20'}
+    hasBin: true
+
+  playwright@1.62.1:
+    resolution: {integrity: sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   postcss@8.4.31:
     resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
     engines: {node: ^10 || ^12 || >=14}
@@ -542,6 +565,10 @@ snapshots:
   '@next/swc-win32-x64-msvc@16.2.10':
     optional: true
 
+  '@playwright/test@1.62.1':
+    dependencies:
+      playwright: 1.62.1
+
   '@speechify/api@3.0.1': {}
 
   '@swc/helpers@0.5.15':
@@ -589,9 +616,12 @@ snapshots:
   detect-libc@2.1.2:
     optional: true
 
+  fsevents@2.3.2:
+    optional: true
+
   nanoid@3.3.16: {}
 
-  next@16.2.10(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
+  next@16.2.10(@playwright/test@1.62.1)(react-dom@19.2.7(react@19.2.7))(react@19.2.7):
     dependencies:
       '@next/env': 16.2.10
       '@swc/helpers': 0.5.15
@@ -610,6 +640,7 @@ snapshots:
       '@next/swc-linux-x64-musl': 16.2.10
       '@next/swc-win32-arm64-msvc': 16.2.10
       '@next/swc-win32-x64-msvc': 16.2.10
+      '@playwright/test': 1.62.1
       sharp: 0.34.5
     transitivePeerDependencies:
       - '@babel/core'
@@ -617,6 +648,14 @@ snapshots:
 
   picocolors@1.1.1: {}
 
+  playwright-core@1.62.1: {}
+
+  playwright@1.62.1:
+    dependencies:
+      playwright-core: 1.62.1
+    optionalDependencies:
+      fsevents: 2.3.2
+
   postcss@8.4.31:
     dependencies:
       nanoid: 3.3.16