@heyramzi/marketing 2.1.0 → 3.1.0

package/README.md

@@ -26,8 +26,13 @@ The analytics module provides wrappers for Umami tracking across different envir
 ```typescript
 import { initServer, trackServer } from '@heyramzi/marketing/analytics/server';
 
-initServer({ websiteId: process.env.UMAMI_WEBSITE_ID });
-await trackServer('signup', { plan: 'pro' });
+initServer({
+  hostUrl: 'https://umami.example.com',
+  websiteId: process.env.UMAMI_WEBSITE_ID,
+  hostname: 'example.com',
+});
+// Resolves true once Umami recorded it. On a Worker, await it or pass it to waitUntil.
+await trackServer('signup', { plan: 'pro' }, { url: '/signup', id: user.id });
 ```
 
 #### Script tag and browser tracking

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/marketing",
-  "version": "2.1.0",
+  "version": "3.1.0",
   "description": "Umami analytics for client, server, and Svelte, plus a satori-based HTML-to-image pipeline.",
   "license": "MIT",
   "repository": {

package/src/analytics/server.test.ts

@@ -1,282 +1,165 @@
-import { describe, it, expect, vi, beforeEach } from "vite-plus/test";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vite-plus/test";
 
-// The server module holds module-level singletons (client, _config).
-// Each test resets them by calling vi.resetModules() + re-importing.
+// The server module holds its config at module level, so each test re-imports it.
 
 async function freshImport() {
   vi.resetModules();
   return import("#src/analytics/server.js");
 }
 
-beforeEach(() => {
-  vi.resetModules();
-});
-
-// ---- initServer ----
-
-describe("initServer", () => {
-  it("stores config so that subsequent trackServer calls succeed", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
-
-    const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("test_event");
-    await new Promise((r) => setTimeout(r, 0));
+const fetchMock = vi.fn();
 
-    expect(mockTrack).toHaveBeenCalledWith({ name: "test_event" });
-  });
+function answer(body: string, status = 200) {
+  fetchMock.mockResolvedValue(new Response(body, { status }));
+}
 
-  it("throws when trackServer is called without prior initServer", async () => {
-    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    vi.doMock("@umami/node", () => ({ Umami: class {} }));
+function sent() {
+  const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+  return {
+    url,
+    headers: init.headers as Record<string, string>,
+    body: JSON.parse(init.body as string) as { type: string; payload: Record<string, unknown> },
+  };
+}
 
-    const { trackServer } = await freshImport();
-    trackServer("orphan_event");
-    await new Promise((r) => setTimeout(r, 0));
+beforeEach(() => {
+  fetchMock.mockReset();
+  answer('{"cache":"x"}');
+  vi.stubGlobal("fetch", fetchMock);
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
 
-    expect(consoleSpy).toHaveBeenCalledWith(
-      "[analytics] Server track failed:",
-      expect.objectContaining({ message: "Call initServer() before tracking events" }),
-    );
-  });
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
 });
 
-// ---- trackServer ----
+const config = {
+  hostUrl: "https://umami.example.com",
+  websiteId: "abc-123",
+  hostname: "example.com",
+};
 
 describe("trackServer", () => {
-  it("builds a payload with only name when no data or url is given", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
-
+  it("awaits the POST to /api/send and resolves true", async () => {
     const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("signup");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(mockTrack).toHaveBeenCalledWith({ name: "signup" });
-  });
-
-  it("includes data in the payload when provided", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+    initServer(config);
 
-    const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("feature_used", { feature: "export", count: 5 });
-    await new Promise((r) => setTimeout(r, 0));
+    await expect(trackServer("signup")).resolves.toBe(true);
 
-    expect(mockTrack).toHaveBeenCalledWith({
-      name: "feature_used",
-      data: { feature: "export", count: 5 },
+    const { url, headers, body } = sent();
+    expect(url).toBe("https://umami.example.com/api/send");
+    expect(headers["User-Agent"]).toMatch(/^Mozilla\/5\.0/);
+    expect(body).toEqual({
+      type: "event",
+      payload: { website: "abc-123", hostname: "example.com", url: "/", name: "signup" },
     });
   });
 
-  it("includes url in the payload when provided", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
-
+  it("sends data, url and id", async () => {
     const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("page_view", undefined, "/pricing");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(mockTrack).toHaveBeenCalledWith({ name: "page_view", url: "/pricing" });
-  });
+    initServer(config);
 
-  it("includes both data and url when both are provided", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+    await trackServer("click", { label: "CTA" }, { url: "/home", id: "cs_123" });
 
-    const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("click", { label: "CTA" }, "/home");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(mockTrack).toHaveBeenCalledWith({
+    expect(sent().body.payload).toEqual({
+      website: "abc-123",
+      hostname: "example.com",
+      url: "/home",
       name: "click",
       data: { label: "CTA" },
-      url: "/home",
+      id: "cs_123",
     });
   });
 
-  it("logs an error and does not throw when track rejects", async () => {
-    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    const mockTrack = vi.fn().mockRejectedValue(new Error("network failure"));
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
-
+  it("still takes the url as a plain string", async () => {
     const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("risky_event");
-    await new Promise((r) => setTimeout(r, 0));
+    initServer(config);
 
-    expect(consoleSpy).toHaveBeenCalledWith("[analytics] Server track failed:", expect.any(Error));
-  });
+    await trackServer("page_view", undefined, "/pricing");
 
-  it("reuses the same Umami instance across multiple calls", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    let constructorCallCount = 0;
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        constructor() {
-          constructorCallCount++;
-        }
-        track = mockTrack;
-      },
-    }));
+    expect(sent().body.payload.url).toBe("/pricing");
+    expect(sent().body.payload).not.toHaveProperty("id");
+  });
 
+  it("strips a trailing slash from hostUrl and forwards a custom userAgent", async () => {
     const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServer("first");
-    // Wait for the first getClient() promise to resolve and set the cached client
-    await new Promise((r) => setTimeout(r, 10));
-    trackServer("second");
-    await new Promise((r) => setTimeout(r, 10));
-
-    expect(constructorCallCount).toBe(1);
-    expect(mockTrack).toHaveBeenCalledTimes(2);
-  });
-});
+    initServer({
+      ...config,
+      hostUrl: "https://umami.example.com/",
+      userAgent: "Mozilla/5.0 Seam/1.0",
+    });
 
-// ---- trackServerRevenue ----
+    await trackServer("ua_test");
 
-describe("trackServerRevenue", () => {
-  it("tracks a revenue event with revenue and currency merged into data", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+    expect(sent().url).toBe("https://umami.example.com/api/send");
+    expect(sent().headers["User-Agent"]).toBe("Mozilla/5.0 Seam/1.0");
+  });
 
-    const { initServer, trackServerRevenue } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServerRevenue("purchase", 49.99, "USD");
-    await new Promise((r) => setTimeout(r, 0));
+  // Umami rejects an event with HTTP 200 and the body `beep`.
+  it("resolves false when Umami answers beep", async () => {
+    answer("beep");
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
 
-    expect(mockTrack).toHaveBeenCalledWith({
-      name: "purchase",
-      data: { revenue: 49.99, currency: "USD" },
-    });
+    await expect(trackServer("dropped")).resolves.toBe(false);
+    expect(console.error).toHaveBeenCalled();
   });
 
-  it("merges extra EventData alongside revenue and currency", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+  it("resolves false on an HTTP error", async () => {
+    answer("nope", 500);
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
 
-    const { initServer, trackServerRevenue } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServerRevenue("subscription", 9.99, "EUR", { plan: "pro" });
-    await new Promise((r) => setTimeout(r, 0));
+    await expect(trackServer("server_error")).resolves.toBe(false);
+  });
 
-    expect(mockTrack).toHaveBeenCalledWith({
-      name: "subscription",
-      data: { plan: "pro", revenue: 9.99, currency: "EUR" },
-    });
+  it("resolves false and never throws when fetch rejects", async () => {
+    fetchMock.mockRejectedValue(new Error("network failure"));
+    const { initServer, trackServer } = await freshImport();
+    initServer(config);
+
+    await expect(trackServer("risky_event")).resolves.toBe(false);
   });
 
-  it("passes url to the underlying trackServer call", async () => {
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        track = mockTrack;
-      },
-    }));
+  it("resolves false without initServer and sends nothing", async () => {
+    const { trackServer } = await freshImport();
 
-    const { initServer, trackServerRevenue } = await freshImport();
-    initServer({ hostUrl: "https://umami.example.com", websiteId: "abc-123" });
-    trackServerRevenue("checkout", 19.99, "USD", undefined, "/checkout");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(mockTrack).toHaveBeenCalledWith({
-      name: "checkout",
-      data: { revenue: 19.99, currency: "USD" },
-      url: "/checkout",
-    });
+    await expect(trackServer("orphan_event")).resolves.toBe(false);
+    expect(fetchMock).not.toHaveBeenCalled();
   });
 });
 
-// ---- initServer config forwarding ----
-
-describe("initServer config forwarding", () => {
-  it("passes hostUrl and websiteId to the Umami constructor", async () => {
-    let capturedConfig = null;
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        constructor(cfg: unknown) {
-          capturedConfig = cfg;
-        }
-        track = mockTrack;
-      },
-    }));
-
-    const { initServer, trackServer } = await freshImport();
-    initServer({ hostUrl: "https://analytics.myapp.io", websiteId: "xyz-789" });
-    trackServer("init_test");
-    await new Promise((r) => setTimeout(r, 0));
-
-    expect(capturedConfig).toEqual({
-      hostUrl: "https://analytics.myapp.io",
-      websiteId: "xyz-789",
-      userAgent: "Server",
+describe("trackServerRevenue", () => {
+  it("merges revenue and currency into data and forwards url and id", async () => {
+    const { initServer, trackServerRevenue } = await freshImport();
+    initServer(config);
+
+    await expect(
+      trackServerRevenue(
+        "Purchase Complete",
+        9.99,
+        "EUR",
+        { plan: "pro" },
+        { url: "/buy", id: "cs_1" },
+      ),
+    ).resolves.toBe(true);
+
+    expect(sent().body.payload).toMatchObject({
+      name: "Purchase Complete",
+      url: "/buy",
+      id: "cs_1",
+      data: { plan: "pro", revenue: 9.99, currency: "EUR" },
     });
   });
 
-  it("forwards a custom userAgent to the Umami constructor", async () => {
-    let capturedConfig = null;
-    const mockTrack = vi.fn().mockResolvedValue(undefined);
-    vi.doMock("@umami/node", () => ({
-      Umami: class {
-        constructor(cfg: unknown) {
-          capturedConfig = cfg;
-        }
-        track = mockTrack;
-      },
-    }));
-
-    const { initServer, trackServer } = await freshImport();
-    initServer({
-      hostUrl: "https://umami.example.com",
-      websiteId: "abc-123",
-      userAgent: "MyBot/1.0",
-    });
-    trackServer("ua_test");
-    await new Promise((r) => setTimeout(r, 0));
+  it("resolves false when the send fails", async () => {
+    answer("beep");
+    const { initServer, trackServerRevenue } = await freshImport();
+    initServer(config);
 
-    expect(capturedConfig).toEqual({
-      hostUrl: "https://umami.example.com",
-      websiteId: "abc-123",
-      userAgent: "MyBot/1.0",
-    });
+    await expect(
+      trackServerRevenue("checkout", 19.99, "USD", undefined, "/checkout"),
+    ).resolves.toBe(false);
   });
 });

package/src/analytics/server.ts

@@ -1,32 +1,31 @@
 /**
- * Server-side Umami tracking via @umami/node.
- * Reliable for revenue and critical events — bypasses ad blockers.
- *
- * Requires `@umami/node` peer dependency.
+ * Server-side Umami tracking. A Worker cancels a fetch still in flight once the response
+ * returns, so await each tracker or hand it to `waitUntil`.
  */
 
 import type { EventData } from "#src/analytics/types.js";
-
-type UmamiNodeClient = {
-  track: (payload: Record<string, unknown>) => Promise<unknown>;
-};
-
-type UmamiNodeModule = {
-  Umami: new (config: {
-    hostUrl: string;
-    websiteId: string;
-    userAgent?: string;
-  }) => UmamiNodeClient;
-};
-
-let client: UmamiNodeClient | null = null;
+import { buildSendBody, UMAMI_ENDPOINTS } from "#src/analytics/umami/protocol.js";
 
 type ServerConfig = {
   hostUrl: string;
   websiteId: string;
+  /** Site hostname, such as `getseam.app`. Without it Umami logs the event under `localhost`. */
+  hostname?: string;
+  /** Umami answers a non-browser user agent with `beep` and drops the event. */
   userAgent?: string;
 };
 
+/** Per-event options. A string is the url, as in 3.0. */
+export type ServerEventOptions = {
+  url?: string;
+  /** Umami keys the session on it. Without one, every event shares the Worker's session. */
+  id?: string;
+};
+
+// Umami's bot filter answers `beep` to any agent containing "Server" (tested 19 Oct 2026).
+const DEFAULT_USER_AGENT = "Mozilla/5.0 Marketing/1.0";
+const TIMEOUT_MS = 3000;
+
 let _config: ServerConfig | null = null;
 
 /** Initialize the server-side Umami client. Call once at startup. */
@@ -34,30 +33,47 @@ export function initServer(config: ServerConfig): void {
   _config = config;
 }
 
-async function getClient(): Promise<UmamiNodeClient> {
-  if (client) return client;
-  if (!_config) throw new Error("Call initServer() before tracking events");
-
-  const { Umami } = (await import("@umami/node")) as UmamiNodeModule;
-  client = new Umami({
-    hostUrl: _config.hostUrl,
-    websiteId: _config.websiteId,
-    userAgent: _config.userAgent ?? "Server",
-  });
-  return client;
-}
+/**
+ * Sends one event and checks Umami recorded it. Never throws.
+ * Resolves false on a timeout, an HTTP error or a `beep` rejection.
+ */
+export async function trackServer(
+  name: string,
+  data?: EventData,
+  options?: string | ServerEventOptions,
+): Promise<boolean> {
+  const { url, id } =
+    typeof options === "string" ? { url: options, id: undefined } : (options ?? {});
+  try {
+    if (!_config) throw new Error("Call initServer() before tracking events");
 
-/** Fire-and-forget server-side event tracking. Never throws. */
-export function trackServer(name: string, data?: EventData, url?: string): void {
-  const payload: { name: string; data?: EventData; url?: string } = { name };
-  if (data) payload.data = data;
-  if (url) payload.url = url;
+    const body = buildSendBody({
+      websiteId: _config.websiteId,
+      hostname: _config.hostname,
+      name,
+      url,
+      data,
+    });
+    const payload = id ? { ...body.payload, id } : body.payload;
 
-  getClient()
-    .then((c) => c.track(payload))
-    .catch((err: unknown) => {
-      console.error("[analytics] Server track failed:", err);
+    const response = await fetch(`${_config.hostUrl.replace(/\/$/, "")}${UMAMI_ENDPOINTS.send}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": _config.userAgent ?? DEFAULT_USER_AGENT,
+      },
+      body: JSON.stringify({ ...body, payload }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
     });
+    const text = await response.text();
+    if (!response.ok || text.includes("beep")) {
+      throw new Error(`HTTP ${response.status}: ${text.slice(0, 120)}`);
+    }
+    return true;
+  } catch (err: unknown) {
+    console.error(`[analytics] Server track failed for ${name}:`, err);
+    return false;
+  }
 }
 
 /** Track a server-side revenue event. Revenue must be in dollars (not cents). */
@@ -66,7 +82,7 @@ export function trackServerRevenue(
   revenue: number,
   currency: string,
   data?: EventData,
-  url?: string,
-): void {
-  trackServer(name, { ...data, revenue, currency }, url);
+  options?: string | ServerEventOptions,
+): Promise<boolean> {
+  return trackServer(name, { ...data, revenue, currency }, options);
 }

package/src/testimonials/embed.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { getEmbedUrl } from "#src/testimonials/embed.js";
+
+describe("getEmbedUrl", () => {
+  it("turns a youtube watch link into its embed url", () => {
+    expect(getEmbedUrl("https://www.youtube.com/watch?v=abc123")).toBe(
+      "https://www.youtube.com/embed/abc123",
+    );
+  });
+
+  it("keeps a youtube embed link as it is", () => {
+    expect(getEmbedUrl("https://youtube.com/embed/abc123")).toBe("https://youtube.com/embed/abc123");
+  });
+
+  it("turns a youtu.be short link into its embed url", () => {
+    expect(getEmbedUrl("https://youtu.be/abc123")).toBe("https://www.youtube.com/embed/abc123");
+  });
+
+  it("turns a vimeo link into the player url", () => {
+    expect(getEmbedUrl("https://vimeo.com/76979871")).toBe("https://player.vimeo.com/video/76979871");
+  });
+
+  it("turns a loom share link into its embed url", () => {
+    expect(getEmbedUrl("https://www.loom.com/share/deadbeef?sid=1")).toBe(
+      "https://www.loom.com/embed/deadbeef",
+    );
+  });
+
+  it("returns null for a file url so the <video> path runs", () => {
+    expect(getEmbedUrl("https://example.com/clip.mp4")).toBeNull();
+  });
+
+  it("returns null for a youtube link with no video id", () => {
+    expect(getEmbedUrl("https://www.youtube.com/")).toBeNull();
+  });
+
+  it("returns null for text that is not a url", () => {
+    expect(getEmbedUrl("not a url")).toBeNull();
+  });
+});

package/src/testimonials/embed.ts

@@ -0,0 +1,41 @@
+/**
+ * WHY: a testimonial's `videoUrl` is a pasted link, so YouTube, Vimeo and Loom arrive as watch or share pages that refuse to load inside an iframe.
+ */
+
+/*
+ * Returns the iframe-safe url for a known host, and null for anything else, so the caller falls back to a `<video>`.
+ */
+export function getEmbedUrl(videoUrl: string): string | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(videoUrl);
+  } catch {
+    return null;
+  }
+
+  const { hostname, pathname } = parsed;
+
+  if (hostname === "www.youtube.com" || hostname === "youtube.com") {
+    if (pathname.startsWith("/embed/")) return videoUrl;
+    const videoId = parsed.searchParams.get("v");
+    return videoId ? `https://www.youtube.com/embed/${videoId}` : null;
+  }
+
+  if (hostname === "youtu.be") {
+    const videoId = pathname.slice(1);
+    return videoId ? `https://www.youtube.com/embed/${videoId}` : null;
+  }
+
+  if (hostname === "vimeo.com" || hostname === "www.vimeo.com") {
+    const videoId = pathname.slice(1);
+    return videoId ? `https://player.vimeo.com/video/${videoId}` : null;
+  }
+
+  if (hostname === "www.loom.com" || hostname === "loom.com") {
+    if (pathname.startsWith("/embed/")) return videoUrl;
+    const shareId = pathname.match(/\/share\/([^?]+)/)?.[1];
+    return shareId ? `https://www.loom.com/embed/${shareId}` : null;
+  }
+
+  return null;
+}

package/src/testimonials/svelte/TestimonialCarousel.svelte

@@ -5,7 +5,7 @@
 	import type { PublicTestimonial } from "#src/testimonials/types.js";
 	import { renderTestimonialContent } from "#src/testimonials/render-content.js";
 	import StarRating from "#src/testimonials/svelte/StarRating.svelte";
-	import VideoEmbed from "#src/testimonials/svelte/VideoEmbed.svelte";
+	import TestimonialVideoPlayer from "#src/testimonials/svelte/TestimonialVideoPlayer.svelte";
 
 	// =========================
 	// PROPS
@@ -68,7 +68,7 @@
 			>
 				{#if testimonial.videoUrl}
 					<div class="mb-4">
-						<VideoEmbed url={testimonial.videoUrl} />
+						<TestimonialVideoPlayer src={testimonial.videoUrl} nativeControls />
 					</div>
 				{/if}
 

package/src/testimonials/svelte/TestimonialGrid.svelte

@@ -75,7 +75,7 @@
 			>
 				{#if testimonial.videoUrl}
 					{@const cap = getCaption ? getCaption(testimonial.videoUrl) : null}
-					<TestimonialVideoPlayer src={testimonial.videoUrl} caption={cap} />
+					<TestimonialVideoPlayer src={testimonial.videoUrl} caption={cap} rounded={false} />
 				{/if}
 
 				<div class="p-5">
@@ -87,7 +87,7 @@
 
 					<blockquote class="mb-3 text-sm leading-relaxed text-foreground">
 						<div
-							class={`testimonial-content ${needsClamp && !isExpanded ? "is-clamped" : "is-expanded"}`}
+							class={`testimonial-content ${needsClamp ? "can-clamp" : ""} ${needsClamp && !isExpanded ? "is-clamped" : ""}`}
 						>
 							<p>"<!-- eslint-disable-next-line svelte/no-at-html-tags -->{@html rendered}"</p>
 						</div>
@@ -153,17 +153,22 @@
 <!-- STYLE -->
 <!-- =========================== -->
 <style>
+	/* WHY grid rows: 0fr to 1fr animates to the text's real height with no
+	   max-height guess, and the row never goes below the five-line floor. */
 	.testimonial-content {
 		position: relative;
+		display: grid;
+		grid-template-rows: 1fr;
+		transition: grid-template-rows 360ms cubic-bezier(0.4, 0, 0.2, 1);
+	}
+	.testimonial-content > p {
 		overflow: hidden;
-		transition: max-height 360ms cubic-bezier(0.4, 0, 0.2, 1);
-		will-change: max-height;
 	}
-	.testimonial-content.is-clamped {
-		max-height: calc(1.625em * 5);
+	.testimonial-content.can-clamp > p {
+		min-height: calc(1.625em * 5);
 	}
-	.testimonial-content.is-expanded {
-		max-height: 200vh;
+	.testimonial-content.is-clamped {
+		grid-template-rows: 0fr;
 	}
 	.testimonial-content.is-clamped::after {
 		content: "";

package/src/testimonials/svelte/TestimonialHighlight.svelte

@@ -5,7 +5,7 @@
 	import type { PublicTestimonial } from "#src/testimonials/types.js";
 	import { renderTestimonialContent } from "#src/testimonials/render-content.js";
 	import StarRating from "#src/testimonials/svelte/StarRating.svelte";
-	import VideoEmbed from "#src/testimonials/svelte/VideoEmbed.svelte";
+	import TestimonialVideoPlayer from "#src/testimonials/svelte/TestimonialVideoPlayer.svelte";
 	import quoteIcon from "#src/testimonials/svelte/quote-icon.svg?raw";
 
 	// =========================
@@ -45,7 +45,7 @@
 
 		{#if featured.videoUrl}
 			<div class="mb-6">
-				<VideoEmbed url={featured.videoUrl} />
+				<TestimonialVideoPlayer src={featured.videoUrl} nativeControls />
 			</div>
 		{/if}
 

package/src/testimonials/svelte/TestimonialVideoPlayer.svelte

@@ -5,6 +5,7 @@
 	import Play from "phosphor-svelte/lib/Play";
 	import Pause from "phosphor-svelte/lib/Pause";
 	import ClosedCaptioning from "phosphor-svelte/lib/ClosedCaptioning";
+	import { getEmbedUrl } from "#src/testimonials/embed.js";
 	import { getMuxPlaybackId, getMuxPosterUrl } from "#src/testimonials/mux.js";
 	import type { TestimonialCaption } from "#src/testimonials/svelte/types.js";
 
@@ -15,13 +16,26 @@
 		src: string;
 		caption?: TestimonialCaption | null;
 		fit?: "cover" | "contain";
+		rounded?: boolean;
+		/** Browser controls on a file video, instead of the centred play button and caption toggle. */
+		nativeControls?: boolean;
+		/** Accessible name of the YouTube, Vimeo or Loom frame. */
+		title?: string;
 		class?: string;
 	};
 
 	// =========================
 	// PROPS
 	// =========================
-	let { src, caption = null, fit = "cover", class: extraClass = "" }: Props = $props();
+	let {
+		src,
+		caption = null,
+		fit = "cover",
+		rounded = true,
+		nativeControls = false,
+		title = "Video testimonial",
+		class: extraClass = "",
+	}: Props = $props();
 
 	// =========================
 	// STATE
@@ -37,6 +51,7 @@
 	// DERIVED
 	// =========================
 	const muxPlaybackId = $derived(getMuxPlaybackId(src));
+	const embedUrl = $derived(muxPlaybackId ? null : getEmbedUrl(src));
 
 	// =========================
 	// FUNCTIONS
@@ -123,7 +138,7 @@
 <!-- MARKUP -->
 <!-- =========================== -->
 <div
-	class={`group relative w-full overflow-hidden bg-black ${extraClass}`}
+	class={`group relative w-full overflow-hidden bg-black ${rounded ? "rounded-lg" : ""} ${extraClass}`}
 	style={aspectRatio ? `aspect-ratio: ${aspectRatio};` : "aspect-ratio: 16 / 9;"}
 	onmousemove={showControls}
 	onmouseleave={() => playing && (controlsVisible = false)}
@@ -137,10 +152,13 @@
 			stream-type="on-demand"
 			class="testimonial-mux-player size-full"
 		></mux-player>
+	{:else if embedUrl}
+		<iframe src={embedUrl} class="absolute inset-0 size-full" allowfullscreen {title}></iframe>
 	{:else}
 		<video
 			bind:this={videoEl}
 			{src}
+			controls={nativeControls}
 			class={`size-full ${fit === "contain" ? "object-contain" : "object-cover"}`}
 			preload="metadata"
 			playsinline
@@ -162,31 +180,33 @@
 				<track kind="captions" src="" srclang="en" label="Captions" default />
 			{/if}
 		</video>
-		<button
-			onclick={togglePlay}
-			class={`absolute inset-0 flex cursor-pointer items-center justify-center border-none bg-transparent text-white transition-opacity duration-300 ${controlsVisible ? "opacity-100" : "opacity-0"}`}
-			aria-label={playing ? "Pause" : "Play"}
-		>
-			<span
-				class="flex size-16 items-center justify-center rounded-full bg-black/55 backdrop-blur-sm transition-colors group-hover:bg-black/75"
-			>
-				{#if playing}
-					<Pause size={28} weight="fill" />
-				{:else}
-					<Play size={28} weight="fill" />
-				{/if}
-			</span>
-		</button>
-		{#if caption}
+		{#if !nativeControls}
 			<button
-				onclick={toggleCaptions}
-				class={`absolute bottom-2.5 right-2.5 flex size-7 cursor-pointer items-center justify-center rounded text-white backdrop-blur-sm transition-opacity duration-300 ${controlsVisible ? "opacity-100" : "pointer-events-none opacity-0"} ${captionsOn ? "border border-white/70 bg-white/20" : "border border-white/20 bg-black/55 hover:bg-black/75"}`}
-				aria-label={captionsOn ? "Hide captions" : "Show captions"}
-				aria-pressed={captionsOn}
-				title={captionsOn ? "Hide captions" : "Show captions"}
+				onclick={togglePlay}
+				class={`absolute inset-0 flex cursor-pointer items-center justify-center border-none bg-transparent text-white transition-opacity duration-300 ${controlsVisible ? "opacity-100" : "opacity-0"}`}
+				aria-label={playing ? "Pause" : "Play"}
 			>
-				<ClosedCaptioning size={14} weight={captionsOn ? "fill" : "regular"} />
+				<span
+					class="flex size-16 items-center justify-center rounded-full bg-black/55 backdrop-blur-sm transition-colors group-hover:bg-black/75"
+				>
+					{#if playing}
+						<Pause size={28} weight="fill" />
+					{:else}
+						<Play size={28} weight="fill" />
+					{/if}
+				</span>
 			</button>
+			{#if caption}
+				<button
+					onclick={toggleCaptions}
+					class={`absolute bottom-2.5 right-2.5 flex size-7 cursor-pointer items-center justify-center rounded text-white backdrop-blur-sm transition-opacity duration-300 ${controlsVisible ? "opacity-100" : "pointer-events-none opacity-0"} ${captionsOn ? "border border-white/70 bg-white/20" : "border border-white/20 bg-black/55 hover:bg-black/75"}`}
+					aria-label={captionsOn ? "Hide captions" : "Show captions"}
+					aria-pressed={captionsOn}
+					title={captionsOn ? "Hide captions" : "Show captions"}
+				>
+					<ClosedCaptioning size={14} weight={captionsOn ? "fill" : "regular"} />
+				</button>
+			{/if}
 		{/if}
 	{/if}
 </div>

package/src/testimonials/svelte/index.ts

@@ -5,7 +5,6 @@ export { default as TestimonialCompact } from "#src/testimonials/svelte/Testimon
 export { default as TestimonialHighlight } from "#src/testimonials/svelte/TestimonialHighlight.svelte";
 export { default as TestimonialVideoPlayer } from "#src/testimonials/svelte/TestimonialVideoPlayer.svelte";
 export { default as StarRating } from "#src/testimonials/svelte/StarRating.svelte";
-export { default as VideoEmbed } from "#src/testimonials/svelte/VideoEmbed.svelte";
 
 export { renderTestimonialContent } from "#src/testimonials/render-content.js";
 export { getMuxPlaybackId, getMuxPosterUrl } from "#src/testimonials/mux.js";

package/src/testimonials/svelte/VideoEmbed.svelte

@@ -1,170 +0,0 @@
-<script lang="ts">
-	// =========================
-	// IMPORTS
-	// =========================
-	import pauseIcon from "#src/testimonials/svelte/pause-icon.svg?raw";
-	import playIcon from "#src/testimonials/svelte/play-icon.svg?raw";
-
-	// =========================
-	// PROPS
-	// =========================
-	let {
-		url,
-		rounded = true,
-		playOnly = false,
-	}: { url: string; rounded?: boolean; playOnly?: boolean } = $props();
-
-	// =========================
-	// STATE
-	// =========================
-	let videoEl = $state<HTMLVideoElement | null>(null);
-	let playing = $state(false);
-
-	// =========================
-	// DERIVED
-	// =========================
-	const VIDEO_EXTENSIONS = [".mp4", ".webm", ".ogg", ".mov"];
-
-	const isDirectVideo = $derived.by(() => {
-		try {
-			const { pathname } = new URL(url);
-			return VIDEO_EXTENSIONS.some((ext) => pathname.toLowerCase().endsWith(ext));
-		} catch {
-			return false;
-		}
-	});
-
-	const embedUrl = $derived.by(() => {
-		if (isDirectVideo) return null;
-		try {
-			const parsed = new URL(url);
-
-			if (parsed.hostname === "www.youtube.com" || parsed.hostname === "youtube.com") {
-				if (parsed.pathname.startsWith("/embed/")) return url;
-				const videoId = parsed.searchParams.get("v");
-				if (videoId) return `https://www.youtube.com/embed/${videoId}`;
-			}
-
-			if (parsed.hostname === "youtu.be") {
-				const videoId = parsed.pathname.slice(1);
-				if (videoId) return `https://www.youtube.com/embed/${videoId}`;
-			}
-
-			if (parsed.hostname === "vimeo.com" || parsed.hostname === "www.vimeo.com") {
-				const videoId = parsed.pathname.slice(1);
-				if (videoId) return `https://player.vimeo.com/video/${videoId}`;
-			}
-
-			if (parsed.hostname === "www.loom.com" || parsed.hostname === "loom.com") {
-				if (parsed.pathname.startsWith("/embed/")) return url;
-				const match = parsed.pathname.match(/\/share\/([^?]+)/);
-				if (match?.[1]) return `https://www.loom.com/embed/${match[1]}`;
-			}
-
-			return null;
-		} catch {
-			return null;
-		}
-	});
-
-	const roundingClass = $derived(rounded ? "rounded-lg" : "");
-
-	// =========================
-	// FUNCTIONS
-	// =========================
-	function togglePlay() {
-		if (!videoEl) return;
-		if (videoEl.paused) {
-			videoEl.play();
-			playing = true;
-		} else {
-			videoEl.pause();
-			playing = false;
-		}
-	}
-</script>
-
-<!-- =========================== -->
-<!-- MARKUP -->
-<!-- =========================== -->
-{#if isDirectVideo}
-	{#if playOnly}
-		<div class="relative aspect-video w-full overflow-hidden {roundingClass}">
-			<video
-				bind:this={videoEl}
-				src={url}
-				class="size-full object-cover"
-				preload="metadata"
-				playsinline
-				onended={() => (playing = false)}
-			></video>
-			<button onclick={togglePlay} class="play-btn" aria-label={playing ? "Pause" : "Play"}>
-				{#if playing}
-					<!-- eslint-disable-next-line svelte/no-at-html-tags -->
-					{@html pauseIcon}
-				{:else}
-					<!-- eslint-disable-next-line svelte/no-at-html-tags -->
-					{@html playIcon}
-				{/if}
-			</button>
-		</div>
-	{:else}
-		<video
-			src={url}
-			class="aspect-video w-full object-cover {roundingClass}"
-			controls
-			preload="metadata"
-			playsinline
-		></video>
-	{/if}
-{:else if embedUrl}
-	<div class="relative aspect-video w-full overflow-hidden {roundingClass}">
-		<iframe
-			src={embedUrl}
-			class="absolute inset-0 size-full"
-			allowfullscreen
-			title="Video testimonial"
-		></iframe>
-	</div>
-{/if}
-
-<!-- =========================== -->
-<!-- STYLE -->
-<!-- =========================== -->
-<style>
-	.play-btn {
-		position: absolute;
-		inset: 0;
-		display: flex;
-		align-items: center;
-		justify-content: center;
-		background: transparent;
-		border: none;
-		cursor: pointer;
-		color: white;
-	}
-
-	.play-btn::before {
-		content: "";
-		position: absolute;
-		width: 64px;
-		height: 64px;
-		border-radius: 50%;
-		background: rgba(0, 0, 0, 0.55);
-		backdrop-filter: blur(4px);
-		transition: background 0.15s ease;
-	}
-
-	.play-btn:hover::before {
-		background: rgba(0, 0, 0, 0.75);
-	}
-
-	.play-btn :global(svg) {
-		position: relative;
-		z-index: 1;
-	}
-
-	.play-btn:active {
-		transform: scale(0.97);
-	}
-</style>

package/src/testimonials/svelte/pause-icon.svg

@@ -1 +0,0 @@
-<svg viewBox="0 0 24 24" fill="currentColor" width="28" height="28" aria-hidden="true"><rect x="6" y="4" width="4" height="16" rx="1" /><rect x="14" y="4" width="4" height="16" rx="1" /></svg>

package/src/testimonials/svelte/play-icon.svg

@@ -1 +0,0 @@
-<svg viewBox="0 0 24 24" fill="currentColor" width="28" height="28" aria-hidden="true"><path d="M8 5.14v14l11-7-11-7z" /></svg>