diff --git a/README.md b/README.md
index 9471520..73fa0f4 100644
--- a/README.md
+++ b/README.md
@@ -144,6 +144,19 @@ Output: `dist/claudius.iife.js` and `dist/claudius.css`
 
 Host these files on your site or a CDN, then add the embed snippet to your HTML.
 
+## Testing
+
+```bash
+cd widget
+pnpm test                # Unit + integration (Vitest)
+pnpm test:coverage       # Coverage report (target: 80%+)
+pnpm e2e:install         # One-time: download Chromium for Playwright
+pnpm e2e                 # End-to-end (Playwright, against `pnpm dev`)
+pnpm e2e:ui              # Playwright UI mode
+```
+
+The E2E suite mocks `**/api/chat` via `page.route()` so the worker doesn't need to be running, and builds the embed bundle once in `globalSetup` to exercise it via `<script src>` and `<claudius-chat>` web component.
+
 ## Tech Stack
 
 - **Widget:** React 18, TypeScript, Tailwind CSS, Vite
diff --git a/widget/e2e/chat.spec.ts b/widget/e2e/chat.spec.ts
new file mode 100644
index 0000000..523d504
--- /dev/null
+++ b/widget/e2e/chat.spec.ts
@@ -0,0 +1,91 @@
+import { test, expect } from "@playwright/test";
+import { mockChatApi } from "./helpers";
+
+test.describe("desktop chat flow", () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto("/");
+  });
+
+  test("toggle button opens and closes the chat window", async ({ page }) => {
+    const toggle = page.getByRole("button", { name: /open chat/i });
+    await expect(toggle).toBeVisible();
+    await expect(page.getByRole("dialog")).toHaveCount(0);
+
+    await toggle.click();
+    const dialog = page.getByRole("dialog");
+    await expect(dialog).toBeVisible();
+
+    // Header close button (first in DOM order).
+    await dialog.getByRole("button", { name: /close chat/i }).click();
+    await expect(page.getByRole("dialog")).toHaveCount(0);
+    await expect(toggle).toBeFocused();
+  });
+
+  test("send a message and render the assistant reply", async ({ page }) => {
+    const api = await mockChatApi(page);
+    api.enqueueReply("Plans start at $1,000/month.");
+
+    await page.getByRole("button", { name: /open chat/i }).click();
+
+    const input = page.getByLabel(/type your message/i);
+    await input.fill("What are your prices?");
+    await input.press("Enter");
+
+    const log = page.getByRole("log");
+    await expect(log.getByText("What are your prices?")).toBeVisible();
+    await expect(log.getByText(/Plans start at \$1,000/)).toBeVisible();
+    expect(api.callCount()).toBe(1);
+
+    // Typing indicator must clear after the reply lands.
+    await expect(
+      page.getByRole("status", { name: /assistant is typing/i }),
+    ).toHaveCount(0);
+  });
+
+  test("Escape closes the chat and returns focus to the toggle", async ({ page }) => {
+    const toggle = page.getByRole("button", { name: /open chat/i });
+    await toggle.click();
+    await expect(page.getByRole("dialog")).toBeVisible();
+
+    await page.keyboard.press("Escape");
+    await expect(page.getByRole("dialog")).toHaveCount(0);
+    await expect(toggle).toBeFocused();
+  });
+
+  test("focus traps inside the dialog when tabbing", async ({ page }) => {
+    await page.getByRole("button", { name: /open chat/i }).click();
+
+    // After several Tab presses the active element must remain inside the dialog.
+    for (let i = 0; i < 8; i++) {
+      await page.keyboard.press("Tab");
+    }
+
+    const dialogContainsActive = await page.evaluate(() => {
+      const dlg = document.querySelector('[role="dialog"]');
+      return !!dlg && dlg.contains(document.activeElement);
+    });
+    expect(dialogContainsActive).toBe(true);
+  });
+
+  test("Retry button recovers from a network failure", async ({ page }) => {
+    const api = await mockChatApi(page);
+    api.enqueueError(500, { error: "Server error", code: "SERVICE_ERROR" });
+
+    await page.getByRole("button", { name: /open chat/i }).click();
+    await page.getByLabel(/type your message/i).fill("Hello");
+    await page.getByLabel(/type your message/i).press("Enter");
+
+    const alert = page.getByRole("alert");
+    await expect(alert).toBeVisible();
+    const retryBtn = page.getByRole("button", { name: /retry/i });
+    await expect(retryBtn).toBeVisible();
+
+    api.enqueueReply("Welcome back!");
+    await retryBtn.click();
+
+    const log = page.getByRole("log");
+    await expect(log.getByText("Welcome back!")).toBeVisible();
+    await expect(page.getByRole("alert")).toHaveCount(0);
+    expect(api.callCount()).toBe(2);
+  });
+});
diff --git a/widget/e2e/embed.spec.ts b/widget/e2e/embed.spec.ts
new file mode 100644
index 0000000..64256e1
--- /dev/null
+++ b/widget/e2e/embed.spec.ts
@@ -0,0 +1,94 @@
+import { test, expect } from "@playwright/test";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mockChatApi } from "./helpers";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const IIFE_PATH = resolve(__dirname, "..", "dist", "claudius-embed.iife.js");
+const CSS_PATH = resolve(__dirname, "..", "dist", "claudius-embed.css");
+
+const FAKE_API = "https://test.example/api";
+
+async function loadEmbed(
+  page: import("@playwright/test").Page,
+  init: () => void,
+): Promise<void> {
+  // Use the dev origin so cross-origin fetch + route() works cleanly. The
+  // dev app mounts its own widget at #root — strip it so only the embed
+  // bundle's widget exists for assertions.
+  await page.goto("/");
+  await page.evaluate(() => {
+    document.getElementById("root")?.remove();
+  });
+  await page.evaluate(init);
+  await page.addStyleTag({ path: CSS_PATH });
+  await page.addScriptTag({ path: IIFE_PATH });
+}
+
+test.describe("embed script (IIFE bundle)", () => {
+  test("auto-initialises from window.ClaudiusConfig", async ({ page }) => {
+    const api = await mockChatApi(page);
+    api.enqueueReply("Hello from the embed bundle!");
+
+    await loadEmbed(page, () => {
+      (window as unknown as { ClaudiusConfig: unknown }).ClaudiusConfig = {
+        apiUrl: "https://test.example",
+        title: "Embed Test",
+      };
+    });
+
+    // The auto-init path appends a #claudius-chat-widget container with the toggle.
+    await expect(page.locator("#claudius-chat-widget")).toBeAttached();
+    await expect(
+      page.getByRole("button", { name: /open chat/i }),
+    ).toBeVisible();
+
+    // End-to-end: open, send, receive — all driven by the bundled code.
+    await page.getByRole("button", { name: /open chat/i }).click();
+    await expect(page.getByRole("dialog")).toBeVisible();
+    await expect(page.getByText("Embed Test")).toBeVisible();
+
+    const input = page.getByLabel(/type your message/i);
+    await input.fill("Ping");
+    await input.press("Enter");
+
+    await expect(
+      page.getByRole("log").getByText("Hello from the embed bundle!"),
+    ).toBeVisible();
+    expect(api.callCount()).toBe(1);
+  });
+
+  test("registers <claudius-chat> as a working web component", async ({ page }) => {
+    const api = await mockChatApi(page);
+    api.enqueueReply("Web component reply");
+
+    await loadEmbed(page, () => {
+      // No ClaudiusConfig — auto-init runs but logs an error and exits.
+      // The web-component path should still work.
+    });
+
+    // Inject the custom element after the script registers it.
+    await page.evaluate((apiUrl) => {
+      const el = document.createElement("claudius-chat");
+      el.setAttribute("api-url", apiUrl);
+      el.setAttribute("title", "WC Test");
+      document.body.appendChild(el);
+    }, FAKE_API.replace(/\/api$/, ""));
+
+    await expect(
+      page.getByRole("button", { name: /open chat/i }),
+    ).toBeVisible();
+
+    await page.getByRole("button", { name: /open chat/i }).click();
+    await expect(page.getByText("WC Test")).toBeVisible();
+
+    const input = page.getByLabel(/type your message/i);
+    await input.fill("Hi WC");
+    await input.press("Enter");
+
+    await expect(
+      page.getByRole("log").getByText("Web component reply"),
+    ).toBeVisible();
+    expect(api.callCount()).toBe(1);
+  });
+});
diff --git a/widget/e2e/global-setup.ts b/widget/e2e/global-setup.ts
new file mode 100644
index 0000000..407cf12
--- /dev/null
+++ b/widget/e2e/global-setup.ts
@@ -0,0 +1,32 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Build the IIFE embed bundle once before any test runs. The embed.spec.ts
+ * suite injects this file via `page.addScriptTag({ path })`, so it must
+ * exist on disk before tests start.
+ */
+export default async function globalSetup(): Promise<void> {
+  const iifePath = resolve(__dirname, "..", "dist", "claudius-embed.iife.js");
+
+  if (process.env.E2E_SKIP_BUILD === "1" && existsSync(iifePath)) {
+    return;
+  }
+
+  // eslint-disable-next-line no-console
+  console.log("[e2e] Building embed bundle (pnpm build:embed)...");
+  execSync("pnpm build:embed", {
+    cwd: resolve(__dirname, ".."),
+    stdio: "inherit",
+  });
+
+  if (!existsSync(iifePath)) {
+    throw new Error(
+      `[e2e] Build completed but ${iifePath} is missing — check vite.config.embed.ts.`,
+    );
+  }
+}
diff --git a/widget/e2e/helpers.ts b/widget/e2e/helpers.ts
new file mode 100644
index 0000000..7f9a257
--- /dev/null
+++ b/widget/e2e/helpers.ts
@@ -0,0 +1,68 @@
+import type { Page, Route } from "@playwright/test";
+
+/**
+ * Intercept POST /api/chat with a queue of replies. The dev app points the
+ * widget at http://localhost:8787, so we route any URL ending in /api/chat
+ * regardless of host. Each call consumes the next response in the queue.
+ *
+ * Because requests are cross-origin (page on :5173, widget points at :8787)
+ * the mock includes CORS headers and answers the OPTIONS preflight.
+ */
+export interface ApiMockHandle {
+  enqueueReply: (reply: string, sources?: unknown) => void;
+  enqueueError: (status: number, body: { error: string; code?: string }) => void;
+  callCount: () => number;
+}
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type, Retry-After",
+  "Access-Control-Expose-Headers": "Retry-After",
+};
+
+export async function mockChatApi(page: Page): Promise<ApiMockHandle> {
+  const queue: Array<(route: Route) => Promise<void>> = [];
+  let calls = 0;
+
+  await page.route("**/api/chat", async (route) => {
+    if (route.request().method() === "OPTIONS") {
+      await route.fulfill({ status: 204, headers: CORS_HEADERS });
+      return;
+    }
+
+    calls += 1;
+    const handler = queue.shift();
+    if (!handler) {
+      await route.fulfill({
+        status: 500,
+        headers: { ...CORS_HEADERS, "Content-Type": "application/json" },
+        body: JSON.stringify({ error: "no mock queued", code: "TEST_ERROR" }),
+      });
+      return;
+    }
+    await handler(route);
+  });
+
+  return {
+    enqueueReply(reply, sources) {
+      queue.push(async (route) => {
+        await route.fulfill({
+          status: 200,
+          headers: { ...CORS_HEADERS, "Content-Type": "application/json" },
+          body: JSON.stringify({ reply, sources }),
+        });
+      });
+    },
+    enqueueError(status, body) {
+      queue.push(async (route) => {
+        await route.fulfill({
+          status,
+          headers: { ...CORS_HEADERS, "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+        });
+      });
+    },
+    callCount: () => calls,
+  };
+}
diff --git a/widget/e2e/mobile.spec.ts b/widget/e2e/mobile.spec.ts
new file mode 100644
index 0000000..36e6c2a
--- /dev/null
+++ b/widget/e2e/mobile.spec.ts
@@ -0,0 +1,48 @@
+import { test, expect } from "@playwright/test";
+import { mockChatApi } from "./helpers";
+
+test.describe("mobile responsive layout", () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto("/");
+  });
+
+  test("opens as a bottom sheet with a scrim and a drag handle", async ({ page }) => {
+    await page.getByRole("button", { name: /open chat/i }).click();
+
+    const dialog = page.getByRole("dialog");
+    await expect(dialog).toHaveClass(/claudius-bottom-sheet/);
+    await expect(dialog).toHaveAttribute("aria-modal", "true");
+
+    // Drag handle: the small rounded bar inside the aria-hidden wrapper.
+    const dragHandle = dialog.locator('[aria-hidden="true"] .rounded-full').first();
+    await expect(dragHandle).toBeVisible();
+
+    // Scrim is rendered as a sibling of the dialog with the dedicated class.
+    await expect(page.locator(".claudius-scrim")).toBeVisible();
+  });
+
+  test("tapping the scrim closes the bottom sheet", async ({ page }) => {
+    await page.getByRole("button", { name: /open chat/i }).click();
+    const scrim = page.locator(".claudius-scrim");
+    await expect(scrim).toBeVisible();
+
+    // The bottom sheet occupies the lower 90vh — click the scrim near the top
+    // so the click doesn't land on the dialog underneath.
+    await scrim.click({ position: { x: 50, y: 20 } });
+    await expect(page.getByRole("dialog")).toHaveCount(0);
+  });
+
+  test("send a message and receive a reply on mobile", async ({ page }) => {
+    const api = await mockChatApi(page);
+    api.enqueueReply("Hello from mobile!");
+
+    await page.getByRole("button", { name: /open chat/i }).click();
+    const input = page.getByLabel(/type your message/i);
+    await input.fill("Hi");
+    await input.press("Enter");
+
+    const log = page.getByRole("log");
+    await expect(log.getByText("Hi")).toBeVisible();
+    await expect(log.getByText("Hello from mobile!")).toBeVisible();
+  });
+});
diff --git a/widget/package.json b/widget/package.json
index 1f21ffe..1be0d10 100644
--- a/widget/package.json
+++ b/widget/package.json
@@ -25,6 +25,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "e2e": "playwright test",
+    "e2e:ui": "playwright test --ui",
+    "e2e:install": "playwright install chromium",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "format": "prettier --write \"src/**/*.{ts,tsx,css}\"",
@@ -41,6 +44,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.24.0",
+    "@playwright/test": "^1.59.1",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.0",
diff --git a/widget/playwright.config.ts b/widget/playwright.config.ts
new file mode 100644
index 0000000..f307340
--- /dev/null
+++ b/widget/playwright.config.ts
@@ -0,0 +1,45 @@
+import { defineConfig, devices } from "@playwright/test";
+
+const PORT = 5173;
+const BASE_URL = `http://localhost:${PORT}`;
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: process.env.CI ? "github" : "list",
+
+  // Build the IIFE bundle once before running embed.spec.ts.
+  globalSetup: "./e2e/global-setup.ts",
+
+  use: {
+    baseURL: BASE_URL,
+    trace: "on-first-retry",
+    actionTimeout: 5_000,
+    navigationTimeout: 15_000,
+  },
+
+  projects: [
+    {
+      name: "chromium-desktop",
+      use: { ...devices["Desktop Chrome"], viewport: { width: 1280, height: 800 } },
+      testIgnore: ["**/mobile.spec.ts"],
+    },
+    {
+      name: "chromium-mobile",
+      use: { ...devices["iPhone 13"] },
+      testMatch: ["**/mobile.spec.ts"],
+    },
+  ],
+
+  webServer: {
+    command: "pnpm dev",
+    url: BASE_URL,
+    reuseExistingServer: !process.env.CI,
+    stdout: "ignore",
+    stderr: "pipe",
+    timeout: 60_000,
+  },
+});
diff --git a/widget/pnpm-lock.yaml b/widget/pnpm-lock.yaml
index af3f53c..ece1b63 100644
--- a/widget/pnpm-lock.yaml
+++ b/widget/pnpm-lock.yaml
@@ -18,6 +18,9 @@ importers:
       '@eslint/js':
         specifier: ^9.24.0
         version: 9.39.4
+      '@playwright/test':
+        specifier: ^1.59.1
+        version: 1.59.1
       '@testing-library/jest-dom':
         specifier: ^6.6.0
         version: 6.9.1
@@ -451,6 +454,11 @@ packages:
     resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
     engines: {node: '>= 8'}
 
+  '@playwright/test@1.59.1':
+    resolution: {integrity: sha512-PG6q63nQg5c9rIi4/Z5lR5IVF7yU5MqmKaPOe0HSc0O2cX1fPi96sUQu5j7eo4gKCkB2AnNGoWt7y4/Xx3Kcqg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   '@rolldown/pluginutils@1.0.0-beta.27':
     resolution: {integrity: sha512-+d0F4MKMCbeVUJwG96uQ4SgAznZNSq93I3V+9NHA4OpvqG8mRCpGdKmK8l/dl02h2CCDHwW2FqilnTyDcAnqjA==}
 
@@ -1219,6 +1227,11 @@ packages:
   fraction.js@5.3.4:
     resolution: {integrity: sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ==}
 
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
   fsevents@2.3.3:
     resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -1701,6 +1714,16 @@ packages:
     resolution: {integrity: sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==}
     engines: {node: '>= 6'}
 
+  playwright-core@1.59.1:
+    resolution: {integrity: sha512-HBV/RJg81z5BiiZ9yPzIiClYV/QMsDCKUyogwH9p3MCP6IYjUFu/MActgYAvK0oWyV9NlwM3GLBjADyWgydVyg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.59.1:
+    resolution: {integrity: sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
   possible-typed-array-names@1.1.0:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
@@ -2526,6 +2549,10 @@ snapshots:
       '@nodelib/fs.scandir': 2.1.5
       fastq: 1.20.1
 
+  '@playwright/test@1.59.1':
+    dependencies:
+      playwright: 1.59.1
+
   '@rolldown/pluginutils@1.0.0-beta.27': {}
 
   '@rollup/rollup-android-arm-eabi@4.59.0':
@@ -3400,6 +3427,9 @@ snapshots:
 
   fraction.js@5.3.4: {}
 
+  fsevents@2.3.2:
+    optional: true
+
   fsevents@2.3.3:
     optional: true
 
@@ -3881,6 +3911,14 @@ snapshots:
 
   pirates@4.0.7: {}
 
+  playwright-core@1.59.1: {}
+
+  playwright@1.59.1:
+    dependencies:
+      playwright-core: 1.59.1
+    optionalDependencies:
+      fsevents: 2.3.2
+
   possible-typed-array-names@1.1.0: {}
 
   postcss-import@15.1.0(postcss@8.5.8):
diff --git a/widget/vite.config.embed.ts b/widget/vite.config.embed.ts
index 827da3d..f9823c0 100644
--- a/widget/vite.config.embed.ts
+++ b/widget/vite.config.embed.ts
@@ -4,6 +4,12 @@ import { resolve } from "path";
 
 export default defineConfig({
   plugins: [react()],
+  // The IIFE is loaded directly by browsers via <script src>, so any
+  // `process.env.NODE_ENV` reference left in the bundle (React uses it to
+  // gate dev warnings) blows up at runtime. Replace it at build time.
+  define: {
+    "process.env.NODE_ENV": JSON.stringify("production"),
+  },
   build: {
     lib: {
       entry: resolve(__dirname, "src/embed.tsx"),
diff --git a/widget/vite.config.ts b/widget/vite.config.ts
index f1b6fe0..aab8a4b 100644
--- a/widget/vite.config.ts
+++ b/widget/vite.config.ts
@@ -36,6 +36,7 @@ export default defineConfig({
     environment: "jsdom",
     setupFiles: ["./src/test-setup.ts"],
     globals: true,
+    exclude: ["**/node_modules/**", "**/dist/**", "**/e2e/**"],
     coverage: {
       provider: "v8",
       reporter: ["text", "html", "lcov"],