chore: import upstream snapshot with attribution

showcase/tests/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+test-results/
+playwright-report/

showcase/tests/docker-compose.integrations.yml

@@ -0,0 +1,39 @@
+# Aimock sidecar for per-package e2e testing in CI.
+#
+# Boots aimock with the depth-organized fixture directories so per-package
+# Playwright tests get deterministic LLM responses.
+#
+# Usage:
+#   docker compose -f docker-compose.integrations.yml up -d aimock
+#   OPENAI_BASE_URL=http://localhost:4010/v1 OPENAI_API_KEY=test-key \
+#     cd ../integrations/<slug> && pnpm dev &
+#   npx playwright test
+#
+# Or in CI, reference this as a service container alongside the test runner.
+services:
+  aimock:
+    image: ghcr.io/copilotkit/aimock:latest
+    volumes:
+      - ../aimock/shared:/fixtures/shared:ro
+      - ../aimock/d4:/fixtures/d4:ro
+      - ../aimock/d6:/fixtures/d6:ro
+    command:
+      [
+        "--fixtures",
+        "/fixtures/shared",
+        "--fixtures",
+        "/fixtures/d4",
+        "--fixtures",
+        "/fixtures/d6",
+        "--host",
+        "0.0.0.0",
+        "--validate-on-load",
+      ]
+    ports:
+      - "4010:4010"
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:4010/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 5s

showcase/tests/e2e/helpers.ts

@@ -0,0 +1,281 @@
+/**
+ * Shared test helpers for E2E smoke tests.
+ *
+ * Used by both integration-smoke.spec.ts (showcase backends on Railway)
+ * and starter-smoke.spec.ts (Docker-built starters with aimock).
+ */
+
+import type { APIRequestContext, Page } from "@playwright/test";
+
+// ---------------------------------------------------------------------------
+// Result types
+// ---------------------------------------------------------------------------
+
+export interface HealthCheckResult {
+  ok: boolean;
+  status: number;
+  path: string;
+  body: string;
+}
+
+export interface AgentCheckResult {
+  ok: boolean;
+  status: number;
+  body: string;
+}
+
+export interface ChatResult {
+  gotResponse: boolean;
+  responseText: string;
+}
+
+// ---------------------------------------------------------------------------
+// Health check
+// ---------------------------------------------------------------------------
+
+/**
+ * Probe the health endpoint(s) and return the first 200 response.
+ *
+ * Defaults to `/api/health` only — the standard Next.js convention used by
+ * all deployed showcase backends and starters. Historically this helper also
+ * fell back to `/health`, but every starter now mounts `/api/health` and the
+ * fallback masked legitimate 5xx responses (a 503 "agent degraded" on
+ * `/api/health` would be hidden behind the subsequent 404 from the non-
+ * existent `/health`, reporting the misleading `path=/health` in failures).
+ *
+ * Callers that need to probe a different path (e.g. local Docker starters
+ * with a custom health route) can pass an explicit `paths` array.
+ *
+ * Supports retries with delay for cold-start scenarios (e.g. Railway starters).
+ */
+export async function checkHealth(
+  request: APIRequestContext,
+  baseUrl: string,
+  paths: string[] = ["/api/health"],
+  retries: number = 0,
+  retryDelayMs: number = 15_000,
+): Promise<HealthCheckResult> {
+  let lastResult: HealthCheckResult = {
+    ok: false,
+    status: 0,
+    path: paths[0],
+    body: "no attempts made",
+  };
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    for (const path of paths) {
+      try {
+        const res = await request.get(`${baseUrl}${path}`, {
+          timeout: 15_000,
+        });
+        if (res.ok()) {
+          return {
+            ok: true,
+            status: res.status(),
+            path,
+            body: await res.text(),
+          };
+        }
+        lastResult = {
+          ok: false,
+          status: res.status(),
+          path,
+          body: await res.text(),
+        };
+      } catch (e: unknown) {
+        const msg = e instanceof Error ? e.message : String(e);
+        lastResult = { ok: false, status: 0, path, body: msg };
+      }
+    }
+
+    // If we have retries left, wait before the next attempt
+    if (attempt < retries) {
+      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    }
+  }
+
+  return lastResult;
+}
+
+// ---------------------------------------------------------------------------
+// Agent endpoint check
+// ---------------------------------------------------------------------------
+
+/**
+ * Check the CopilotKit runtime endpoint is reachable.
+ * Tries GET on /info first, then falls back to POST on the base path.
+ * Considers the endpoint OK when the response is 2xx-4xx (not 5xx or network error).
+ */
+export async function checkAgentEndpoint(
+  request: APIRequestContext,
+  baseUrl: string,
+  agentPath: string = "/api/copilotkit",
+): Promise<AgentCheckResult> {
+  // Try GET /info first (CopilotKit runtime info endpoint — returns runtime
+  // metadata on starters that support it). Then fall back to POST on the base
+  // path. The key check is that we get ANY response from the CopilotKit runtime
+  // (even a 404 from its internal Hono router) rather than a Next.js 404 page.
+  const infoPaths = [`${agentPath}/info`, agentPath];
+
+  for (const path of infoPaths) {
+    try {
+      const res = await request.get(`${baseUrl}${path}`, { timeout: 15_000 });
+      const body = await res.text();
+      // Accept 2xx as definitive success
+      if (res.status() >= 200 && res.status() < 300) {
+        return { ok: true, status: res.status(), body };
+      }
+      // A 405 "Method not allowed" proves the route exists (just wrong method)
+      if (res.status() === 405) {
+        return { ok: true, status: res.status(), body };
+      }
+    } catch {
+      // try next path
+    }
+  }
+
+  // Fall back to POST — the CopilotKit Hono router may return its own 404
+  // for a bare POST (expects sub-path), but that still proves the runtime
+  // is mounted. Distinguish from a Next.js 404 by checking for JSON body.
+  try {
+    const res = await request.post(`${baseUrl}${agentPath}`, {
+      headers: { "Content-Type": "application/json" },
+      data: { messages: [], tools: [], agentId: "agentic_chat" },
+      timeout: 15_000,
+    });
+    const body = await res.text();
+    const isRuntimeResponse = body.includes('"error"') || res.status() !== 404;
+    return {
+      ok: isRuntimeResponse,
+      status: res.status(),
+      body,
+    };
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, status: 0, body: msg };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Chat interaction
+// ---------------------------------------------------------------------------
+
+/**
+ * Navigate to a page and interact with the chat.
+ */
+export async function sendChatMessage(
+  page: Page,
+  baseUrl: string,
+  message: string,
+  path: string = "/",
+): Promise<ChatResult> {
+  const url = `${baseUrl}${path}`;
+  await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+
+  // Wait for the chat UI to be ready — CopilotKit renders a textarea
+  const textarea = page.locator("textarea").first();
+  await textarea.waitFor({ state: "visible", timeout: 15_000 });
+
+  // Count existing messages before sending
+  const messagesBefore = await page
+    .locator('[data-testid="copilot-assistant-message"]')
+    .count();
+
+  // Type and send
+  await textarea.fill(message);
+  await textarea.press("Enter");
+
+  // Wait for a new assistant message to appear
+  try {
+    await page.waitForFunction(
+      ({ selector, countBefore }) => {
+        const msgs = document.querySelectorAll(selector);
+        return msgs.length > countBefore;
+      },
+      {
+        selector: '[data-testid="copilot-assistant-message"]',
+        countBefore: messagesBefore,
+      },
+      { timeout: 60_000 },
+    );
+  } catch {
+    // Fallback: look for any new content that appeared after our message
+    // This handles cases where the selector doesn't match
+    await page.waitForTimeout(5_000);
+  }
+
+  // Extract the latest assistant message text, waiting for content to stream in
+  const assistantMessages = page.locator(
+    '[data-testid="copilot-assistant-message"]',
+  );
+  const count = await assistantMessages.count();
+  if (count > messagesBefore) {
+    const latest = assistantMessages.nth(count - 1);
+    // Wait for the message to have non-empty text (streaming may still be in progress)
+    try {
+      await page.waitForFunction(
+        (el) => (el?.textContent?.trim().length ?? 0) > 0,
+        await latest.elementHandle(),
+        { timeout: 60_000 },
+      );
+    } catch {
+      // Streaming may be slow; continue with whatever we have
+    }
+    const text = (await latest.textContent()) ?? "";
+    return { gotResponse: true, responseText: text.trim() };
+  }
+
+  // Fallback: CopilotSidebar may not use data-testid="copilot-assistant-message".
+  // Detect response by looking for new text content that appeared after our message.
+  // The "Regenerate response" button appears next to assistant messages in the sidebar.
+  const pageText = await page.locator("body").textContent();
+  const userMsgIndex = pageText?.lastIndexOf(message) ?? -1;
+  if (userMsgIndex >= 0) {
+    const afterUserMsg = (pageText ?? "")
+      .slice(userMsgIndex + message.length)
+      .trim();
+    // Filter out UI chrome text (buttons, labels) — look for substantial text
+    const stripped = afterUserMsg
+      .replace(/Regenerate response/g, "")
+      .replace(/Copy to clipboard/g, "")
+      .replace(/Thumbs (up|down)/g, "")
+      .replace(/Powered by CopilotKit/g, "")
+      .replace(/Type a message\.\.\./g, "")
+      .replace(/\bSend\b/g, "")
+      .trim();
+    if (stripped.length > 20) {
+      return {
+        gotResponse: true,
+        responseText: stripped.split("\n")[0].trim(),
+      };
+    }
+  }
+
+  return { gotResponse: false, responseText: "" };
+}
+
+// ---------------------------------------------------------------------------
+// Console error collector
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach listeners for console errors and page errors.
+ * Returns an accessor to retrieve collected errors.
+ */
+export function setupConsoleErrorCollector(page: Page): {
+  getErrors: () => string[];
+} {
+  const errors: string[] = [];
+
+  page.on("console", (msg) => {
+    if (msg.type() === "error") {
+      errors.push(`[console.error] ${msg.text()}`);
+    }
+  });
+
+  page.on("pageerror", (err) => {
+    errors.push(`[pageerror] ${err.message}`);
+  });
+
+  return { getErrors: () => [...errors] };
+}

showcase/tests/e2e/integration-smoke.spec.ts

@@ -0,0 +1,229 @@
+/**
+ * E2E Smoke Test Suite for Showcase Integrations
+ *
+ * Tests the full path: Railway backend -> AG-UI protocol -> CopilotKit runtime -> frontend response
+ *
+ * Levels:
+ *   1. @health  - Backend health endpoint returns 200
+ *   2. @agent   - Agent endpoint is reachable (not 404)
+ *   3. @chat    - Round-trip chat: send message, get assistant response
+ *   4. @tools   - Tool rendering: trigger a tool, verify UI result
+ *
+ * Run all:     npx playwright test
+ * Run level:   npx playwright test --grep @health
+ * Run one:     npx playwright test --grep "langgraph-python"
+ */
+
+import { test, expect } from "@playwright/test";
+import { checkHealth, checkAgentEndpoint, sendChatMessage } from "./helpers";
+// Generated by showcase/scripts/generate-registry.ts — must run `npm run build`
+// in showcase/shell (or run the generator directly) before this test can import the file.
+import registry from "../../shell/src/data/registry.json";
+import localPorts from "../../shared/local-ports.json";
+
+// LOCAL_PORTS=1 rewrites Railway backend URLs to http://localhost:<port>
+// using showcase/shared/local-ports.json. Lets smoke run against the
+// docker-compose.local.yml stack instead of Railway. Starters are skipped
+// because they're not represented in local-ports.json (local dev only
+// targets the 17 integration backends).
+const USE_LOCAL_PORTS = process.env.LOCAL_PORTS === "1";
+
+// SHOWCASE_BACKEND_HOST_PATTERN lets a single deployed test image be
+// re-pointed at a different backend environment (e.g. staging) without
+// regenerating registry.json. `{slug}` is the only placeholder. If unset,
+// each integration's baked-in backend_url is used as-is (current behavior).
+// LOCAL_PORTS=1 takes precedence so docker-compose flows are unaffected.
+const HOST_PATTERN_OVERRIDE = process.env.SHOWCASE_BACKEND_HOST_PATTERN || "";
+const applyHostPattern = (slug: string, defaultUrl: string): string => {
+  if (!HOST_PATTERN_OVERRIDE) return defaultUrl;
+  return `https://${HOST_PATTERN_OVERRIDE.replace("{slug}", slug)}`;
+};
+
+const rewriteBackendUrl = (slug: string, railwayUrl: string): string => {
+  if (USE_LOCAL_PORTS) {
+    const port = (localPorts as Record<string, number>)[slug];
+    if (!port) throw new Error(`LOCAL_PORTS=1 but no port for slug '${slug}'`);
+    return `http://localhost:${port}`;
+  }
+  return applyHostPattern(slug, railwayUrl);
+};
+
+// ---------------------------------------------------------------------------
+// Integration registry — derived from showcase/shell/src/data/registry.json
+// ---------------------------------------------------------------------------
+
+const INTEGRATIONS = registry.integrations.map((i) => ({
+  slug: i.slug,
+  name: i.name,
+  backendUrl: i.backend_url,
+  deployed: i.deployed,
+  hasToolRendering: i.features.includes("tool-rendering"),
+  demos: i.demos.map((d: { id: string }) => d.id),
+}));
+
+// Only test deployed integrations unless SMOKE_ALL=true
+const SMOKE_ALL = process.env.SMOKE_ALL === "true";
+const activeIntegrations = (
+  SMOKE_ALL ? INTEGRATIONS : INTEGRATIONS.filter((i) => i.deployed)
+).map((i) => ({ ...i, backendUrl: rewriteBackendUrl(i.slug, i.backendUrl) }));
+
+// ---------------------------------------------------------------------------
+// Level 1: Health checks (@health) — fast, API-only
+// ---------------------------------------------------------------------------
+
+test.describe("Level 1: Backend Health @health", () => {
+  for (const integration of activeIntegrations) {
+    test(`[L1: health] ${integration.slug} backend is healthy @health`, async ({
+      request,
+    }) => {
+      const result = await checkHealth(request, integration.backendUrl);
+      expect(
+        result.ok,
+        `${integration.slug} health check failed: status=${result.status} path=${result.path} body=${result.body.slice(0, 500)}`,
+      ).toBe(true);
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Level 2: Agent endpoint reachability (@agent)
+// ---------------------------------------------------------------------------
+
+test.describe("Level 2: Agent Endpoint @agent", () => {
+  for (const integration of activeIntegrations) {
+    test(`[L2: agent] ${integration.slug} agent endpoint responds (not 404) @agent`, async ({
+      request,
+    }) => {
+      const result = await checkAgentEndpoint(request, integration.backendUrl);
+      expect(
+        result.status,
+        `${integration.slug} agent endpoint returned 404 — likely using wrong agent type (LangGraphAgent vs HttpAgent). Status=${result.status} body=${result.body.slice(0, 500)}`,
+      ).not.toBe(404);
+      expect(
+        result.ok,
+        `${integration.slug} agent endpoint is unreachable: status=${result.status} body=${result.body.slice(0, 500)}`,
+      ).toBe(true);
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Level 3: Round-trip chat (@chat) — browser-based
+// ---------------------------------------------------------------------------
+
+test.describe("Level 3: Round-trip Chat @chat", () => {
+  for (const integration of activeIntegrations) {
+    test(`[L3: chat] ${integration.slug} responds to a message @chat`, async ({
+      page,
+    }) => {
+      test.slow(); // Allow extra time for cold starts
+
+      const result = await sendChatMessage(
+        page,
+        integration.backendUrl,
+        "Hello, please respond with a brief greeting.",
+        "/demos/agentic-chat",
+      );
+
+      expect(
+        result.gotResponse,
+        `${integration.slug} did not produce an assistant response. The agent may be down, misconfigured, or using the wrong agent type.`,
+      ).toBe(true);
+      expect(
+        result.responseText.length,
+        `${integration.slug} assistant response was empty`,
+      ).toBeGreaterThan(0);
+    });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Level 4: Tool rendering (@tools) — browser-based, subset
+// ---------------------------------------------------------------------------
+
+test.describe("Level 4: Tool Rendering @tools", () => {
+  // Future-proofing: `demos.includes("tool-rendering")` is what actually matters —
+  // if a new integration lands without the tool-rendering demo, it's correctly
+  // skipped here. The previous `hasToolRendering` boolean was redundant with
+  // this check (always `true` alongside the demo entry) and has been removed.
+  const toolIntegrations = activeIntegrations.filter((i) =>
+    i.demos.includes("tool-rendering"),
+  );
+
+  for (const integration of toolIntegrations) {
+    test(`[L4: tools] ${integration.slug} renders tool results @tools`, async ({
+      page,
+    }) => {
+      test.slow();
+
+      const result = await sendChatMessage(
+        page,
+        integration.backendUrl,
+        "What's the weather in San Francisco?",
+        "/demos/tool-rendering",
+      );
+
+      // Tool rendering should produce an assistant response
+      expect(
+        result.gotResponse,
+        `${integration.slug} did not render a tool result`,
+      ).toBe(true);
+
+      // The response should contain weather-related content. Avoid a bare
+      // `/\d+/` fallback — any digit anywhere makes the assertion vacuous
+      // (timestamps, UI chrome, model names all contain digits). Match only
+      // on weather-specific vocabulary.
+      const responseLC = result.responseText.toLowerCase();
+      const hasWeatherContent =
+        responseLC.includes("san francisco") ||
+        responseLC.includes("weather") ||
+        responseLC.includes("temperature") ||
+        responseLC.includes("degrees") ||
+        responseLC.includes("sunny") ||
+        responseLC.includes("cloudy") ||
+        responseLC.includes("rain") ||
+        responseLC.includes("humidity") ||
+        responseLC.includes("wind");
+
+      expect(
+        hasWeatherContent,
+        `${integration.slug} response doesn't contain weather info: "${result.responseText}"`,
+      ).toBe(true);
+
+      // Check for rendered components (not just text) — catches the query_data
+      // loop bug where the agent returns text but never renders a chart/card.
+      //
+      // isVisible() resolves false for missing/detached elements rather than
+      // throwing, so the previous .catch(() => false) was masking nothing on
+      // the happy path — but it ALSO masked real errors (e.g. evaluation
+      // errors in the locator) as "not visible", which is the concrete bug
+      // the original TODO in this file flagged. Drop the swallowing catches
+      // and let genuine errors surface as test failures; a missing optional
+      // renderer still just yields `false`.
+      const responseArea = page
+        .locator('[data-testid="copilot-assistant-message"]')
+        .last();
+      const checks = await Promise.all([
+        responseArea.locator(".recharts-wrapper").first().isVisible(),
+        responseArea
+          .locator("svg circle[stroke-dasharray]")
+          .first()
+          .isVisible(),
+        responseArea
+          .locator('[data-testid="weather-card"]')
+          .first()
+          .isVisible(),
+        responseArea.locator("canvas").first().isVisible(),
+      ]);
+      const hasRenderedComponent = checks.some(Boolean);
+
+      // Warning for now — upgrade to hard failure after data-testid convention
+      // is established across all integrations
+      if (!hasRenderedComponent) {
+        console.warn(
+          `\u26a0\ufe0f ${integration.slug}: Tool response contains text but no rendered chart/weather component. This would have missed the query_data loop bug.`,
+        );
+      }
+    });
+  }
+});

showcase/tests/e2e/starter-smoke.spec.ts

@@ -0,0 +1,159 @@
+/**
+ * E2E smoke tests for Docker-built starter templates.
+ *
+ * Test levels: @health, @agent, @chat, @interaction
+ * Targets a running starter container at STARTER_URL (default localhost:3000).
+ * The starter is selected by the STARTER env var (default "langgraph-python").
+ *
+ * All starters share the same CopilotKit UI shell, so interaction selectors
+ * are universal — only the agent backend differs per starter.
+ */
+
+import { test, expect } from "@playwright/test";
+import {
+  checkHealth,
+  checkAgentEndpoint,
+  sendChatMessage,
+  setupConsoleErrorCollector,
+} from "./helpers";
+
+// ---------------------------------------------------------------------------
+// Starter registry
+// ---------------------------------------------------------------------------
+
+interface Starter {
+  slug: string;
+  path: string;
+  healthPaths: string[];
+  agentPath: string;
+  chatMessage: string;
+  /** Whether the starter has Chat/App mode toggle */
+  hasAppMode: boolean;
+}
+
+const DEFAULT_STARTER: Omit<Starter, "slug"> = {
+  path: "",
+  healthPaths: ["/api/health", "/health", "/"],
+  agentPath: "/api/copilotkit",
+  chatMessage: "Hello",
+  hasAppMode: false,
+};
+
+const STARTERS: Starter[] = [
+  { ...DEFAULT_STARTER, slug: "langgraph-python", hasAppMode: true },
+  { ...DEFAULT_STARTER, slug: "mastra" },
+  { ...DEFAULT_STARTER, slug: "langgraph-js", hasAppMode: true },
+  { ...DEFAULT_STARTER, slug: "crewai-crews" },
+  { ...DEFAULT_STARTER, slug: "pydantic-ai" },
+  { ...DEFAULT_STARTER, slug: "adk" },
+  { ...DEFAULT_STARTER, slug: "agno" },
+  { ...DEFAULT_STARTER, slug: "llamaindex" },
+  { ...DEFAULT_STARTER, slug: "langgraph-fastapi", hasAppMode: true },
+  { ...DEFAULT_STARTER, slug: "strands-python", hasAppMode: true },
+  { ...DEFAULT_STARTER, slug: "ms-agent-framework-python" },
+  { ...DEFAULT_STARTER, slug: "ms-agent-framework-dotnet" },
+];
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+const STARTER_SLUG = process.env.STARTER ?? "langgraph-python";
+const STARTER_URL = process.env.STARTER_URL ?? "http://localhost:3000";
+const activeStarter = STARTERS.find((s) => s.slug === STARTER_SLUG);
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+test.describe(`starter-smoke: ${STARTER_SLUG}`, () => {
+  test.skip(!activeStarter, `Unknown starter slug: ${STARTER_SLUG}`);
+  const starter = activeStarter!;
+
+  test(`@health ${STARTER_SLUG} — health endpoint responds`, async ({
+    request,
+  }) => {
+    const result = await checkHealth(request, STARTER_URL, starter.healthPaths);
+    expect(result.ok, `Health check failed: ${result.body}`).toBe(true);
+  });
+
+  test(`@agent ${STARTER_SLUG} — agent endpoint is reachable`, async ({
+    request,
+  }) => {
+    const result = await checkAgentEndpoint(
+      request,
+      STARTER_URL,
+      starter.agentPath,
+    );
+    expect(result.status, "Agent endpoint returned 404").not.toBe(404);
+    expect(result.ok, `Agent check failed: ${result.body}`).toBe(true);
+  });
+
+  test(`@chat ${STARTER_SLUG} — chat round-trip via aimock`, async ({
+    page,
+  }) => {
+    test.slow();
+    const result = await sendChatMessage(
+      page,
+      STARTER_URL,
+      starter.chatMessage,
+    );
+    expect(result.gotResponse, "No assistant response received").toBe(true);
+    expect(result.responseText.length).toBeGreaterThan(0);
+  });
+
+  test(`@interaction ${STARTER_SLUG} — UI interactions work`, async ({
+    page,
+  }) => {
+    test.slow();
+    const { getErrors } = setupConsoleErrorCollector(page);
+
+    await page.goto(STARTER_URL, {
+      waitUntil: "networkidle",
+      timeout: 30_000,
+    });
+
+    // Remove CopilotKit web inspector overlay (blocks pointer events in dev)
+    await page.evaluate(() => {
+      document
+        .querySelectorAll("cpk-web-inspector")
+        .forEach((el) => el.remove());
+    });
+
+    if (starter.hasAppMode !== false) {
+      // Starters with Chat/App mode toggle (showcase shell)
+      const appBtn = page.locator('button:text-is("App")');
+      await appBtn.waitFor({ state: "visible", timeout: 10_000 });
+      await appBtn.click({ force: true });
+      await page.waitForTimeout(1_000);
+      await expect(page.locator("text=No todos yet").first()).toBeVisible({
+        timeout: 10_000,
+      });
+
+      // Switch back to Chat mode — verify textarea reappears
+      const chatBtn = page.locator('button:text-is("Chat")');
+      await chatBtn.click({ force: true });
+      await page.waitForTimeout(1_000);
+      await expect(page.locator("textarea").first()).toBeVisible({
+        timeout: 10_000,
+      });
+    } else {
+      // Starters with CopilotSidebar (no Chat/App toggle)
+      // Verify the sidebar chat UI is present and interactive
+      const textarea = page.locator("textarea").first();
+      await textarea.waitFor({ state: "visible", timeout: 10_000 });
+
+      // Verify the sidebar rendered with its title
+      await expect(page.locator("text=Popup Assistant").first()).toBeVisible({
+        timeout: 10_000,
+      });
+    }
+
+    // Verify no JS errors throughout
+    const errors = getErrors().filter(
+      (e) =>
+        !e.includes("favicon.ico") && !e.includes("net::ERR_BLOCKED_BY_CLIENT"),
+    );
+    expect(errors, `JS console errors:\n${errors.join("\n")}`).toHaveLength(0);
+  });
+});

showcase/tests/env-routing.spec.ts

@@ -0,0 +1,186 @@
+import { test, expect } from "@playwright/test";
+import type { Route } from "@playwright/test";
+
+/**
+ * Env-routing test (B14): for each shell × env combination, assert that
+ *   (a) the inlined `window.__SHOWCASE_CONFIG__` matches the env's
+ *       expected URL set, and
+ *   (b) every backend fetch host matches a tight per-env allowlist.
+ *
+ * Runs against live deployments after B15 wires the per-env Railway env
+ * vars. Failures indicate either a runtime-config wiring regression
+ * (the artifact serves stale URLs) or an unsanctioned third-party host
+ * appearing in a page load (silent dep introducing a tracker, etc.).
+ *
+ * Allowlists below are derived from the plan-B host inventory (real
+ * page-load captures across the four shells). Treat the inventory as a
+ * floor — extend it when a captured load surfaces a new legitimate
+ * host, never contract it. An over-broad allowlist masks env-leak bugs.
+ *
+ * This file is intentionally scoped narrowly to env-routing assertions
+ * and uses its own Playwright config at
+ * `showcase/playwright.env-routing.config.ts` (the existing
+ * `showcase/tests/playwright.config.ts` is the integrations smoke
+ * harness with `testDir: ./e2e`).
+ */
+
+// Tell ts-prune / unused-import linters that Route is intentionally
+// imported for future use (per-request interception in follow-on
+// suites that will inspect specific URLs rather than only hosts).
+type _Route = Route;
+
+interface EnvSet {
+  name: "staging" | "prod";
+  expected: {
+    baseUrl?: string;
+    shellUrl?: string;
+    pocketbaseUrl?: string;
+    opsBaseUrl?: string;
+  };
+  /** Hosts (regex) that backend fetches MAY hit. Anything else fails. */
+  backendAllowlist: RegExp[];
+}
+
+// Third-party hosts shared by both envs (analytics, fonts, CDN, HubSpot,
+// REB2B, Reo). Same keys/hosts in staging and prod — these are NOT
+// env-routing signals. Pinned tightly to the EXACT hosts captured in
+// real page loads (see plan-B B14 host-inventory step); broader
+// patterns would let env leaks slip through.
+const SHARED_THIRDPARTY_ALLOWLIST: RegExp[] = [
+  // Analytics + product telemetry
+  /^eu\.i\.posthog\.com$/,
+  /^eu-assets\.i\.posthog\.com$/,
+  /^static\.scarf\.sh$/,
+  /^www\.google-analytics\.com$/,
+  /^region1\.google-analytics\.com$/,
+  // Fonts (next/font/google preconnects to both)
+  /^fonts\.googleapis\.com$/,
+  /^fonts\.gstatic\.com$/,
+  // Marketing + visitor identification (shell-docs)
+  /^js\.hs-scripts\.com$/,
+  /^static\.reo\.dev$/,
+  /^b2bjsstore\.s3\.us-west-2\.amazonaws\.com$/,
+  // Shared image/video CDN (cdn.copilotkit.ai, next.config.ts)
+  /^cdn\.copilotkit\.ai$/,
+];
+
+const STAGING: EnvSet = {
+  name: "staging",
+  expected: {
+    baseUrl: "https://docs.staging.copilotkit.ai",
+    shellUrl: "https://showcase.staging.copilotkit.ai",
+    pocketbaseUrl: "https://pocketbase-staging-eec0.up.railway.app",
+    opsBaseUrl: "https://harness-staging-2ee4.up.railway.app",
+  },
+  backendAllowlist: [
+    // Staging ingress: ONLY *.staging.copilotkit.ai (e.g.
+    // docs.staging.copilotkit.ai, showcase.staging.copilotkit.ai,
+    // dashboard.showcase.staging.copilotkit.ai). Anchored at both
+    // ends so `something.docs.staging.copilotkit.ai` does NOT slip
+    // through.
+    /^(docs|showcase|dashboard\.showcase)\.staging\.copilotkit\.ai$/,
+    // Railway public domains for the staging deploys this
+    // workstream wires. Pinned to the EXACT host suffixes that
+    // appear in the B15 env-var list — not a wildcard
+    // `-staging-[a-z0-9]+` pattern that would also match other
+    // unrelated staging services in the workspace.
+    /^pocketbase-staging-eec0\.up\.railway\.app$/,
+    /^harness-staging-2ee4\.up\.railway\.app$/,
+    ...SHARED_THIRDPARTY_ALLOWLIST,
+  ],
+};
+
+const PROD: EnvSet = {
+  name: "prod",
+  expected: {
+    baseUrl: "https://docs.copilotkit.ai",
+    shellUrl: "https://showcase.copilotkit.ai",
+    pocketbaseUrl: "https://showcase-pocketbase-production.up.railway.app",
+    opsBaseUrl: "https://showcase-harness-production.up.railway.app",
+  },
+  backendAllowlist: [
+    // Prod ingress: bare-domain marketing + docs + showcase +
+    // dashboard hosts. ONLY these — anchored at both ends so
+    // `something.docs.copilotkit.ai` doesn't slip through.
+    /^(www|docs|showcase|dashboard\.showcase)\.copilotkit\.ai$/,
+    // Railway public domains used by prod (exact suffix match per
+    // the build-args at showcase_build.yml:197-198).
+    /^showcase-pocketbase-production\.up\.railway\.app$/,
+    /^showcase-harness-production\.up\.railway\.app$/,
+    ...SHARED_THIRDPARTY_ALLOWLIST,
+  ],
+};
+
+interface ShellTarget {
+  shell: "shell" | "shell-docs" | "shell-dashboard" | "shell-dojo";
+  urlFor: (env: EnvSet) => string;
+  expectedFields: Array<keyof EnvSet["expected"]>;
+}
+
+const TARGETS: ShellTarget[] = [
+  {
+    shell: "shell",
+    urlFor: (e) =>
+      e.name === "staging"
+        ? "https://showcase.staging.copilotkit.ai/"
+        : "https://showcase.copilotkit.ai/",
+    expectedFields: ["baseUrl"],
+  },
+  {
+    shell: "shell-docs",
+    urlFor: (e) =>
+      e.name === "staging"
+        ? "https://docs.staging.copilotkit.ai/"
+        : "https://docs.copilotkit.ai/",
+    expectedFields: ["baseUrl", "shellUrl"],
+  },
+  {
+    shell: "shell-dashboard",
+    urlFor: (e) =>
+      e.name === "staging"
+        ? "https://dashboard.showcase.staging.copilotkit.ai/"
+        : "https://dashboard.showcase.copilotkit.ai/",
+    expectedFields: ["pocketbaseUrl", "shellUrl", "opsBaseUrl"],
+  },
+  // shell-dojo — uncomment when a public env-routed host is wired
+  // (no public ingress today per the B15 service inventory).
+];
+
+for (const env of [STAGING, PROD]) {
+  for (const target of TARGETS) {
+    test(`${target.shell} on ${env.name}: runtime config + backend allowlist`, async ({
+      page,
+    }) => {
+      const offenders: string[] = [];
+      page.on("request", (req) => {
+        const url = new URL(req.url());
+        // Same-origin requests don't cross env lines.
+        if (url.origin === new URL(target.urlFor(env)).origin) return;
+        // Data: and blob: aren't network hosts.
+        if (url.protocol === "data:" || url.protocol === "blob:") return;
+        const allowed = env.backendAllowlist.some((re) => re.test(url.host));
+        if (!allowed) offenders.push(req.url());
+      });
+
+      await page.goto(target.urlFor(env), { waitUntil: "networkidle" });
+
+      // Assert __SHOWCASE_CONFIG__ matches the expected env.
+      const cfg = await page.evaluate(
+        () =>
+          (window as Window & { __SHOWCASE_CONFIG__?: unknown })
+            .__SHOWCASE_CONFIG__,
+      );
+      expect(cfg).toBeDefined();
+      for (const field of target.expectedFields) {
+        expect((cfg as Record<string, string>)[field]).toBe(
+          env.expected[field],
+        );
+      }
+
+      expect(
+        offenders,
+        `${target.shell} on ${env.name} hit non-allowlisted hosts:\n${offenders.join("\n")}`,
+      ).toEqual([]);
+    });
+  }
+}

showcase/tests/package-lock.json

@@ -0,0 +1,76 @@
+{
+  "name": "@showcase/e2e-smoke",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@showcase/e2e-smoke",
+      "devDependencies": {
+        "@playwright/test": "1.52.0"
+      }
+    },
+    "node_modules/@playwright/test": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.52.0.tgz",
+      "integrity": "sha512-uh6W7sb55hl7D6vsAeA+V2p5JnlAqzhqFyF0VcJkKZXkgnFcVG9PziERRHQfPLfNGx1C292a4JqbWzhR8L4R1g==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.52.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.52.0.tgz",
+      "integrity": "sha512-JAwMNMBlxJ2oD1kce4KPtMkDeKGHQstdpFPcPH3maElAXon/QZeTvtsfXmTMRyO9TslfoYOXkSsvao2nE1ilTw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.52.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.52.0.tgz",
+      "integrity": "sha512-l2osTgLXSMeuLZOML9qYODUQoPPnUsKsb5/P6LJ2e6uPKXUdPK5WYhN4z03G+YNbWmGDY4YENauNu4ZKczreHg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}

showcase/tests/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@showcase/e2e-smoke",
+  "private": true,
+  "scripts": {
+    "test": "playwright test",
+    "test:health": "playwright test --grep @health",
+    "test:agent": "playwright test --grep @agent",
+    "test:chat": "playwright test --grep @chat",
+    "test:tools": "playwright test --grep @tools",
+    "test:list": "playwright test --list",
+    "test:starter": "playwright test starter-smoke",
+    "smoke:local": "../scripts/smoke-local.sh",
+    "smoke:local:L1": "../scripts/smoke-local.sh --level=L1",
+    "smoke:local:keep": "../scripts/smoke-local.sh --keep",
+    "smoke:local:nobuild": "../scripts/smoke-local.sh --no-build"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.52.0"
+  }
+}

showcase/tests/playwright.config.ts

@@ -0,0 +1,34 @@
+import { defineConfig, devices } from "@playwright/test";
+
+/**
+ * E2E smoke test config for showcase integrations.
+ *
+ * By default runs a single "chromium" project with all tests.
+ * Use --grep to filter by level: --grep @health, --grep @agent, etc.
+ *
+ * Usage:
+ *   npx playwright test                    # all levels
+ *   npx playwright test --grep @health     # health checks only
+ *   npx playwright test --grep @agent      # agent endpoint only
+ *   npx playwright test --grep @chat       # round-trip chat only
+ *   npx playwright test --grep @tools      # tool rendering only
+ *   npx playwright test -g "langgraph-python"  # single integration
+ */
+export default defineConfig({
+  testDir: "./e2e",
+  timeout: 120_000,
+  expect: {
+    timeout: 30_000,
+  },
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: 1,
+  workers: process.env.CI ? 2 : 4,
+  reporter: process.env.CI ? "github" : "list",
+  outputDir: "test-results",
+  use: {
+    ...devices["Desktop Chrome"],
+    trace: "retain-on-failure",
+    screenshot: "only-on-failure",
+  },
+});