@dbx-tools/ui-teams 0.3.39

package/README.md

@@ -0,0 +1,101 @@
+# @dbx-tools/ui-teams
+
+React surface for the Teams add-on: render Microsoft Teams Adaptive Cards in the
+browser with the [`adaptivecards`](https://www.npmjs.com/package/adaptivecards)
+JavaScript renderer.
+
+Import this package when a UI needs to display the Adaptive Card documents that
+[`@dbx-tools/teams`](../../node/teams) builds. It consumes the browser-safe card
+contract from [`@dbx-tools/shared-teams`](../../shared/teams) and renders through
+[`@dbx-tools/ui-appkit`](../appkit)'s UI kit.
+
+**Key features:**
+
+- `TeamsChat` - a Teams conversation surface: each turn posts a Bot Framework
+  activity to the server's `POST /api/teams/messages` endpoint - the SAME route a
+  real Teams channel calls, so this is a faithful preview rather than a parallel
+  implementation - and the agent's reply renders as Adaptive Card attachments,
+  the way a Teams channel shows a bot's cards. (That route only answers in the
+  HTTP response when the server enables its `allowUnauthenticated` development
+  bypass; against a real bot registration replies go out over the Connector API,
+  so point `endpoint` at `/api/teams/activity` instead.)
+  Mints one conversation id per mount (which threads the server's
+  agent memory), echoes the user's turn optimistically, cancels an in-flight turn
+  on unmount, and offers tap-to-send starters while the transcript is empty.
+- `AdaptiveCardView` - a thin React wrapper over the imperative `adaptivecards`
+  renderer: feed it a compiled Adaptive Card document and it mounts the rendered
+  node, re-rendering on change and wiring `Action.OpenUrl` clicks (open in a new
+  tab by default, or intercept with `onOpenUrl`).
+- `AdaptiveCardGallery` - a self-contained dev tool: edit a `CardSpec` (or pick a
+  sample), compile it through the server's `POST /api/teams/card` route, and see
+  the card render live. This is the drop-in "display them" surface for a dev
+  preview page.
+- Built-in `CARD_SAMPLES` covering the different parts of a card (facts, link
+  actions, plain notes) so the preview shows something before you edit.
+- Markdown in a `TextBlock` actually renders. A `TextBlock` is markdown per the
+  Adaptive Cards spec, but `adaptivecards` ships no parser - it leaves the
+  implementation (and its sanitization) to the host, so `**bold**` renders
+  literally until one is installed. Importing this package registers `marked`
+  as the renderer's `onProcessMarkdown` processor, degrading to plain text if a
+  string fails to parse, and the stylesheet re-applies list markers / paragraph
+  spacing that Tailwind's preflight resets away.
+
+## Simulate A Teams Chat
+
+```tsx
+import { TeamsChat } from "@dbx-tools/ui-teams/react";
+
+const Chat = () => <TeamsChat className="h-full" />;
+```
+
+Point `endpoint` elsewhere if the plugin is mounted under a different name, and
+pass `agentId` to converse with a specific agent instead of the server's default.
+`starters` replaces the built-in `DEFAULT_STARTERS` prompts.
+
+## Render A Card
+
+```tsx
+import { AdaptiveCardView } from "@dbx-tools/ui-teams/react";
+
+const Preview = ({ card }: { card: AdaptiveCard }) => (
+  <AdaptiveCardView card={card} className="ac-container" />
+);
+```
+
+`AdaptiveCardView` renders any compiled Adaptive Card document - one returned by
+the `create_teams_card` tool, the plugin's `buildCard` export, or the
+`/api/teams/card` route. Card text is treated as markdown, matching how Teams
+itself renders a `TextBlock`.
+
+## Live Preview Page
+
+```tsx
+import { AdaptiveCardGallery } from "@dbx-tools/ui-teams/react";
+
+const Cards = () => <AdaptiveCardGallery />;
+export default Cards;
+```
+
+Drop `<AdaptiveCardGallery/>` on a route. It posts the edited `CardSpec` to the
+`@dbx-tools/teams` plugin's `/api/teams/card` route and renders the compiled
+card, so you exercise the real server builder end to end. Point it at a
+different mount with `buildEndpoint`.
+
+## Styling
+
+Import the stylesheet once from the host app's Tailwind entry, after Tailwind and
+your AppKit-UI theme:
+
+```css
+@import "tailwindcss";
+@import "@databricks/appkit-ui/styles.css";
+@import "@dbx-tools/ui-teams/styles.css";
+```
+
+## Modules
+
+- `./react` - `TeamsChat`, `DEFAULT_STARTERS`, `AdaptiveCardView`,
+  `AdaptiveCardGallery`, `CARD_SAMPLES`, and the
+  re-exported `AdaptiveCard` / `CardResult` / `CardSpec` types.
+- `./styles.css` - the AppKit-token-based styling for the gallery plus a minimal
+  Adaptive Card container skin.

package/index.ts

@@ -0,0 +1,12 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as reactAdaptiveCard from "./src/react/adaptive-card";
+export * as reactAdaptiveCardGallery from "./src/react/adaptive-card-gallery";
+export * as reactSamples from "./src/react/samples";
+export * as reactTeamsChat from "./src/react/teams-chat";
+export type { AdaptiveCardViewProps } from "./src/react/adaptive-card";
+export type { AdaptiveCardGalleryProps } from "./src/react/adaptive-card-gallery";
+export type { CardSample } from "./src/react/samples";
+export type { TeamsChatProps } from "./src/react/teams-chat";

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@dbx-tools/ui-teams",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reggie-db/dbx-tools.git",
+    "directory": "workspaces/ui/teams"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "adaptivecards": "^3.0.5",
+    "marked": "^18.0.5",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "@dbx-tools/ui-appkit": "0.3.39",
+    "@dbx-tools/shared-teams": "0.3.39",
+    "@dbx-tools/shared-core": "0.3.39"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.39",
+  "type": "module",
+  "exports": {
+    "./react": "./src/react/index.ts",
+    "./styles.css": "./src/styles.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "dbxToolsConfig": {
+    "tags": [
+      "ui"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/react/adaptive-card-gallery.tsx

@@ -0,0 +1,175 @@
+// A self-contained dev tool for the Teams add-on: pick or paste a `CardSpec`,
+// send it to the server's `POST /api/teams/card` route to compile it into an
+// Adaptive Card, and render the result with the `adaptivecards` renderer. This
+// is the "have this display them" surface - drop `<AdaptiveCardGallery/>` on a
+// page and you get a live card preview backed by the real server builder.
+
+import { json } from "@dbx-tools/shared-core";
+import { card, type CardResult, type CardSpec } from "@dbx-tools/shared-teams";
+import {
+  Button,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Label,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Textarea,
+  cn,
+} from "@dbx-tools/ui-appkit/react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { AdaptiveCardView } from "./adaptive-card";
+import { CARD_SAMPLES } from "./samples";
+
+/** Props for {@link AdaptiveCardGallery}. */
+export interface AdaptiveCardGalleryProps {
+  /**
+   * The server route that compiles a `CardSpec` into an Adaptive Card. Defaults
+   * to the `@dbx-tools/teams` plugin's mount (`/api/teams/card`).
+   */
+  buildEndpoint?: string;
+  /** Extra classes merged onto the root container. */
+  className?: string;
+}
+
+/** Pretty-print a spec for the editable textarea. */
+const format = (spec: CardSpec): string => JSON.stringify(spec, null, 2);
+
+/**
+ * Live Adaptive Card preview. Edits to the JSON are debounced and posted to the
+ * server builder; the returned card is rendered with the `adaptivecards`
+ * package. Falls back to a local build only for the initial paint so the panel
+ * is never empty while the first request is in flight.
+ */
+export const AdaptiveCardGallery = ({
+  buildEndpoint = "/api/teams/card",
+  className,
+}: AdaptiveCardGalleryProps) => {
+  const [sampleIndex, setSampleIndex] = useState(0);
+  const [source, setSource] = useState(() => format(CARD_SAMPLES[0]!.spec));
+  const [result, setResult] = useState<CardResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const spec = useMemo(() => {
+    const parsed = card.cardSpecSchema.safeParse(json.parse(source, undefined));
+    return parsed.success ? parsed.data : null;
+  }, [source]);
+
+  const build = useCallback(
+    async (draft: CardSpec, signal: AbortSignal) => {
+      try {
+        const response = await fetch(buildEndpoint, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(draft),
+          signal,
+        });
+        const payload = await response.json();
+        if (!response.ok) {
+          setError(payload?.error ?? `Build failed (${response.status})`);
+          return;
+        }
+        const parsed = card.cardResultSchema.safeParse(payload);
+        if (!parsed.success) {
+          setError("Server returned an unexpected card shape.");
+          return;
+        }
+        setResult(parsed.data);
+        setError(null);
+      } catch (err) {
+        if ((err as Error).name === "AbortError") return;
+        setError((err as Error).message);
+      }
+    },
+    [buildEndpoint],
+  );
+
+  useEffect(() => {
+    if (!spec) {
+      setError("The card JSON is not a valid CardSpec.");
+      return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => void build(spec, controller.signal), 250);
+    return () => {
+      controller.abort();
+      clearTimeout(timer);
+    };
+  }, [spec, build]);
+
+  const chooseSample = (value: string) => {
+    const index = Number(value);
+    setSampleIndex(index);
+    setSource(format(CARD_SAMPLES[index]!.spec));
+  };
+
+  return (
+    <div className={cn("grid gap-4 md:grid-cols-2", className)}>
+      <Card className="min-h-0">
+        <CardHeader>
+          <CardTitle>Card spec</CardTitle>
+          <CardDescription>
+            Edit the description a model would produce, or pick a sample. It is compiled by the
+            server's <code>/api/teams/card</code> route.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="flex flex-col gap-3">
+          <div className="flex flex-col gap-1.5">
+            <Label htmlFor="teams-sample">Sample</Label>
+            <Select value={String(sampleIndex)} onValueChange={chooseSample}>
+              <SelectTrigger id="teams-sample" className="w-full">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {CARD_SAMPLES.map((sample, index) => (
+                  <SelectItem key={sample.label} value={String(index)}>
+                    {sample.label}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          <Textarea
+            aria-label="Card spec JSON"
+            className="min-h-72 font-mono text-xs"
+            spellCheck={false}
+            value={source}
+            onChange={(event) => setSource(event.target.value)}
+          />
+          <div className="flex items-center gap-2">
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={() => setSource(format(CARD_SAMPLES[sampleIndex]!.spec))}
+            >
+              Reset
+            </Button>
+            {error ? <span className="text-xs text-destructive">{error}</span> : null}
+          </div>
+        </CardContent>
+      </Card>
+
+      <Card className="min-h-0">
+        <CardHeader>
+          <CardTitle>Adaptive Card preview</CardTitle>
+          <CardDescription>
+            Rendered with the <code>adaptivecards</code> JavaScript renderer, the same one Teams
+            preview tools embed.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          {result ? (
+            <AdaptiveCardView card={result.card} className="ac-container" />
+          ) : (
+            <p className="text-sm text-muted-foreground">No card yet.</p>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+};

package/src/react/adaptive-card.tsx

@@ -0,0 +1,90 @@
+// React wrapper over the Adaptive Cards JavaScript renderer (the
+// `adaptivecards` npm package). The renderer is imperative - you feed it card
+// JSON and it returns a rendered `HTMLElement` - so this component parses the
+// document and mounts the rendered node into a ref on every change, and wires
+// `Action.OpenUrl` clicks to an optional handler (defaulting to opening the URL
+// in a new tab). This is the same renderer many internal Teams preview tools
+// embed to show cards outside Teams.
+//
+// The renderer deliberately ships NO markdown parser: a `TextBlock` is markdown
+// per the Adaptive Cards spec, but `adaptivecards` leaves the implementation to
+// the host so each host can pick its own (and its own sanitization). Without a
+// host processor Teams' own `**bold**` renders literally, so this module
+// installs `marked` as the processor once at import - see
+// {@link installMarkdownProcessor}.
+
+import type { AdaptiveCard as AdaptiveCardDocument } from "@dbx-tools/shared-teams";
+import * as AdaptiveCards from "adaptivecards";
+import { marked } from "marked";
+import { useEffect, useRef } from "react";
+
+/**
+ * Teach the renderer to process `TextBlock` markdown with `marked`.
+ *
+ * `onProcessMarkdown` is a STATIC hook on `AdaptiveCard`, so this runs once per
+ * module load rather than per component. `didProcess` must be set to `true` or
+ * the renderer discards the HTML and falls back to the raw text.
+ *
+ * `marked` is called in a try/catch and falls back to leaving the text alone:
+ * card text can come from a model, and a markdown edge case should degrade to
+ * plain text rather than blanking the card.
+ */
+const installMarkdownProcessor = () => {
+  AdaptiveCards.AdaptiveCard.onProcessMarkdown = (text, result) => {
+    try {
+      result.outputHtml = marked.parse(text, { async: false, breaks: true }) as string;
+      result.didProcess = true;
+    } catch {
+      result.didProcess = false;
+    }
+  };
+};
+
+installMarkdownProcessor();
+
+/** Props for {@link AdaptiveCardView}. */
+export interface AdaptiveCardViewProps {
+  /** The compiled Adaptive Card document to render. */
+  card: AdaptiveCardDocument;
+  /**
+   * Called when an `Action.OpenUrl` button is tapped. Defaults to opening the
+   * URL in a new tab. Pass a handler to intercept (e.g. to post back instead).
+   */
+  onOpenUrl?: (url: string) => void;
+  /** Extra classes merged onto the mount container. */
+  className?: string;
+}
+
+/**
+ * Render a single Adaptive Card document with the `adaptivecards` renderer.
+ * Re-renders whenever the card JSON changes.
+ */
+export const AdaptiveCardView = ({ card, onOpenUrl, className }: AdaptiveCardViewProps) => {
+  const hostRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+    const rendered = new AdaptiveCards.AdaptiveCard();
+    rendered.onExecuteAction = (action) => {
+      if (action instanceof AdaptiveCards.OpenUrlAction && action.url) {
+        if (onOpenUrl) onOpenUrl(action.url);
+        else window.open(action.url, "_blank", "noopener,noreferrer");
+      }
+    };
+    try {
+      rendered.parse(card as unknown as Record<string, unknown>);
+      const element = rendered.render();
+      host.replaceChildren(...(element ? [element] : []));
+    } catch (err) {
+      host.replaceChildren(
+        Object.assign(document.createElement("pre"), {
+          textContent: `Failed to render card: ${(err as Error).message}`,
+        }),
+      );
+    }
+    return () => host.replaceChildren();
+  }, [card, onOpenUrl]);
+
+  return <div ref={hostRef} className={className} data-testid="adaptive-card" />;
+};

package/src/react/index.ts

@@ -0,0 +1,13 @@
+// React surface for `@dbx-tools/ui-teams`: a `TeamsChat` that talks to the
+// conversation endpoint and renders each reply's Adaptive Card attachments like
+// a Teams channel, an `AdaptiveCardView` that renders a compiled Adaptive Card
+// document with the `adaptivecards` JavaScript renderer, and a self-contained
+// `AdaptiveCardGallery` dev tool that edits a `CardSpec`, compiles it through
+// the server's `/api/teams/card` route, and previews the result live. Styled
+// with AppKit tokens.
+
+export type { Activity, AdaptiveCard, CardResult, CardSpec } from "@dbx-tools/shared-teams";
+export { TeamsChat, DEFAULT_STARTERS, type TeamsChatProps } from "./teams-chat";
+export { AdaptiveCardView, type AdaptiveCardViewProps } from "./adaptive-card";
+export { AdaptiveCardGallery, type AdaptiveCardGalleryProps } from "./adaptive-card-gallery";
+export { CARD_SAMPLES, type CardSample } from "./samples";

package/src/react/samples.ts

@@ -0,0 +1,57 @@
+// A few ready-made `CardSpec` samples the dev gallery starts from, so the
+// preview shows something interesting before you edit anything. Each exercises
+// a different combination of the spec's optional parts (subtitle, text, facts,
+// actions).
+
+import type { CardSpec } from "@dbx-tools/shared-teams";
+
+/** A named sample card spec shown in the gallery picker. */
+export interface CardSample {
+  /** Label shown in the picker. */
+  label: string;
+  /** The spec to build/render. */
+  spec: CardSpec;
+}
+
+/** The built-in sample specs. */
+export const CARD_SAMPLES: CardSample[] = [
+  {
+    label: "Deployment",
+    spec: {
+      title: "Deployment succeeded",
+      subtitle: "prod • 2 minutes ago",
+      text: "The **api** service rolled out cleanly across all regions.",
+      facts: [
+        { title: "Version", value: "1.4.2" },
+        { title: "Owner", value: "alice" },
+        { title: "Duration", value: "3m 12s" },
+      ],
+      actions: [
+        { title: "View run", url: "https://example.com/runs/42" },
+        { title: "Rollback", url: "https://example.com/runs/42/rollback" },
+      ],
+    },
+  },
+  {
+    label: "Incident",
+    spec: {
+      title: "PagerDuty: high latency",
+      subtitle: "SEV-2 • checkout-service",
+      text: "p95 latency exceeded 800ms for 5 minutes. Auto-scaling triggered.",
+      facts: [
+        { title: "Status", value: "Investigating" },
+        { title: "On-call", value: "bob" },
+        { title: "Started", value: "14:02 UTC" },
+      ],
+      actions: [{ title: "Open incident", url: "https://example.com/incidents/7" }],
+    },
+  },
+  {
+    label: "Simple note",
+    spec: {
+      title: "Weekly report is ready",
+      text: "Numbers look healthy this week. See the dashboard for the breakdown.",
+      actions: [{ title: "Open dashboard", url: "https://example.com/dashboard" }],
+    },
+  },
+];

package/src/react/teams-chat.tsx

@@ -0,0 +1,252 @@
+// A Teams-like chat surface for the `@dbx-tools/teams` conversation endpoint.
+// Each turn POSTs a Bot Framework activity to `POST /api/teams/activity` and
+// appends the activities the bot answers with; a reply's Adaptive Card
+// attachments render through the `adaptivecards` renderer, so the transcript
+// looks like a Teams channel where the agent always answers in cards.
+
+import { hash, json, string } from "@dbx-tools/shared-core";
+import { activity as activityContract, type Activity } from "@dbx-tools/shared-teams";
+import { Avatar, AvatarFallback, Button, Input, Spinner, cn } from "@dbx-tools/ui-appkit/react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { AdaptiveCardView } from "./adaptive-card";
+
+/** Props for {@link TeamsChat}. */
+export interface TeamsChatProps {
+  /**
+   * Conversation endpoint. Defaults to the Bot Framework messaging endpoint
+   * (`/api/teams/messages`) - the SAME route a real Teams channel calls, which
+   * is why this surface is a faithful preview rather than a parallel
+   * implementation.
+   *
+   * That route only answers in the HTTP response when the server enables its
+   * development bypass (`allowUnauthenticated`); against a real bot
+   * registration it validates a Bot Service JWT and delivers replies through
+   * the Connector API, so this component cannot drive it. Point at
+   * `/api/teams/activity` for a server that keeps `/messages` locked down.
+   */
+  endpoint?: string;
+  /** Mastra agent to answer with. Defaults to the server's default agent. */
+  agentId?: string;
+  /** Display name of the local user, shown on their messages. */
+  userName?: string;
+  /** Prompts offered as one-tap starters while the transcript is empty. */
+  starters?: string[];
+  /** Extra classes merged onto the root container. */
+  className?: string;
+}
+
+/**
+ * Default starters. Deliberately generic - they exercise the different parts of
+ * a card (facts, bullets, actions) without assuming what the agent is wired to.
+ */
+export const DEFAULT_STARTERS = [
+  "Summarize today's deployment status",
+  "What should I know about this workspace?",
+  "Draft a release note for version 1.4.2",
+];
+
+/** The local user's identity on outbound activities. */
+const localUser = (name: string) => ({ id: "local-user", name });
+
+/** Whether an activity was authored by the local user rather than the bot. */
+const isFromUser = (item: Activity): boolean => item.from?.id === "local-user";
+
+/**
+ * A Teams-style conversation with an agent that answers in Adaptive Cards.
+ *
+ * The transcript is a list of Bot Framework activities - the same objects the
+ * endpoint exchanges - so what renders here is exactly what a real channel
+ * would receive. A conversation id is minted once per mount and sent on every
+ * turn, which is what threads the server's agent memory.
+ */
+export const TeamsChat = ({
+  endpoint = "/api/teams/messages",
+  agentId,
+  userName = "You",
+  starters = DEFAULT_STARTERS,
+  className,
+}: TeamsChatProps) => {
+  const [transcript, setTranscript] = useState<Activity[]>([]);
+  const [draft, setDraft] = useState("");
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // One conversation id for the lifetime of the mount: the server maps it onto
+  // an agent memory thread, so reusing it is what makes the chat continuous.
+  const conversationRef = useRef(`conv-${hash.id()}`);
+  const scrollRef = useRef<HTMLDivElement>(null);
+  // Tracks the in-flight turn so unmounting (or a rapid second send) cancels it
+  // instead of resolving into a dead component.
+  const abortRef = useRef<AbortController | null>(null);
+
+  useEffect(() => () => abortRef.current?.abort(), []);
+
+  // Keep the newest activity in view as the transcript grows.
+  useEffect(() => {
+    const node = scrollRef.current;
+    if (node) node.scrollTop = node.scrollHeight;
+  }, [transcript, pending]);
+
+  const send = useCallback(
+    async (text: string) => {
+      const prompt = string.trimToNull(text);
+      if (!prompt || pending) return;
+
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      const outbound: Activity = {
+        type: "message",
+        id: hash.id(),
+        timestamp: new Date().toISOString(),
+        text: prompt,
+        from: localUser(userName),
+        conversation: { id: conversationRef.current },
+      };
+      // Echo the user's turn immediately; the reply is appended when it lands.
+      setTranscript((current) => [...current, outbound]);
+      setDraft("");
+      setError(null);
+      setPending(true);
+
+      try {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ activity: outbound, ...(agentId ? { agentId } : {}) }),
+          signal: controller.signal,
+        });
+        const body = json.parseRecord(await response.text());
+        if (!response.ok) {
+          throw new Error(
+            string.trimToNull(String(body?.error ?? "")) ?? `Request failed (${response.status})`,
+          );
+        }
+        const parsed = activityContract.activityResponseSchema.safeParse(body);
+        if (!parsed.success) throw new Error("The server returned an unexpected reply.");
+        setTranscript((current) => [...current, ...parsed.data.activities]);
+      } catch (err) {
+        // An aborted turn is a deliberate cancel, not a failure to report.
+        if ((err as Error)?.name === "AbortError") return;
+        setError((err as Error).message);
+      } finally {
+        setPending(false);
+      }
+    },
+    [agentId, endpoint, pending, userName],
+  );
+
+  return (
+    <div className={cn("flex h-full flex-col overflow-hidden rounded-lg border", className)}>
+      <div className="flex items-center gap-2 border-b px-4 py-3">
+        <span className="text-sm font-semibold">Teams conversation</span>
+        <span className="text-muted-foreground text-xs">
+          answers arrive as Adaptive Cards from <code>{endpoint}</code>
+        </span>
+      </div>
+
+      <div ref={scrollRef} className="flex-1 space-y-4 overflow-y-auto p-4">
+        {transcript.length === 0 && (
+          <div className="space-y-3 py-6 text-center">
+            <p className="text-muted-foreground text-sm">
+              Ask the agent something. It replies with an Adaptive Card, the way a Teams bot does.
+            </p>
+            <div className="flex flex-wrap justify-center gap-2">
+              {starters.map((starter) => (
+                <Button
+                  key={starter}
+                  variant="outline"
+                  size="sm"
+                  onClick={() => void send(starter)}
+                >
+                  {starter}
+                </Button>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {transcript.map((item, index) => (
+          <ActivityBubble key={item.id ?? index} activity={item} userName={userName} />
+        ))}
+
+        {pending && (
+          <div className="text-muted-foreground flex items-center gap-2 text-sm">
+            <Spinner className="size-4" />
+            <span>The agent is composing a card…</span>
+          </div>
+        )}
+
+        {error && (
+          <p className="text-destructive text-sm" role="alert">
+            {error}
+          </p>
+        )}
+      </div>
+
+      <form
+        className="flex items-center gap-2 border-t p-3"
+        onSubmit={(event) => {
+          event.preventDefault();
+          void send(draft);
+        }}
+      >
+        <Input
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+          placeholder="Message the agent…"
+          aria-label="Message the agent"
+          disabled={pending}
+        />
+        <Button type="submit" disabled={pending || string.trimToNull(draft) === null}>
+          Send
+        </Button>
+      </form>
+    </div>
+  );
+};
+
+/**
+ * One activity in the transcript: the user's text on the right, the bot's reply
+ * on the left with each Adaptive Card attachment rendered.
+ */
+const ActivityBubble = ({ activity, userName }: { activity: Activity; userName: string }) => {
+  const fromUser = isFromUser(activity);
+  const cards = activityContract.cardsOf(activity);
+  const label = fromUser ? userName : (activity.from?.name ?? "Agent");
+
+  return (
+    <div className={cn("flex gap-3", fromUser && "flex-row-reverse")}>
+      <Avatar className="size-8 shrink-0">
+        <AvatarFallback className="text-xs">{initials(label)}</AvatarFallback>
+      </Avatar>
+      <div className={cn("min-w-0 max-w-[85%] space-y-2", fromUser && "items-end text-right")}>
+        <span className="text-muted-foreground text-xs">{label}</span>
+        {activity.text && (
+          <div
+            className={cn(
+              "rounded-lg px-3 py-2 text-sm",
+              fromUser ? "bg-primary text-primary-foreground" : "bg-muted",
+            )}
+          >
+            {activity.text}
+          </div>
+        )}
+        {cards.map((document, index) => (
+          <div key={index} className="bg-card rounded-lg border p-3 text-left shadow-sm">
+            <AdaptiveCardView card={document} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+/** Up-to-two-letter initials for an avatar fallback. */
+const initials = (name: string): string =>
+  name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase() ?? "")
+    .join("") || "?";

package/src/styles.css

@@ -0,0 +1,92 @@
+/*
+ * @dbx-tools/ui-teams stylesheet.
+ *
+ * Import once from the host app's Tailwind entry, after Tailwind and
+ * your AppKit-UI theme:
+ *
+ *   @import "tailwindcss";
+ *   @import "@databricks/appkit-ui/styles.css";
+ *   @import "@dbx-tools/ui-teams/styles.css";
+ *
+ * The gallery UI styles exclusively with AppKit semantic tokens and
+ * inherits the host app's theme. The rendered Adaptive Card itself is
+ * styled by the `adaptivecards` renderer's own host config; the small
+ * rules below only give the mount container sane spacing and let the
+ * card's own colors show through on both light and dark themes.
+ *
+ * Pulls shared styling from `@dbx-tools/ui-appkit` and registers this
+ * package's React components with Tailwind via `@source`.
+ */
+
+@import "@dbx-tools/ui-appkit/styles.css";
+
+@source "./react";
+
+.ac-container {
+  --ac-font-family: inherit;
+}
+
+.ac-container .ac-adaptiveCard {
+  border-radius: var(--radius, 0.5rem);
+  background: var(--card, #fff);
+  color: var(--card-foreground, inherit);
+  padding: 0.75rem 1rem;
+}
+
+/*
+ * Restore markdown block styling inside a rendered card.
+ *
+ * A `TextBlock` is markdown, and the host markdown processor (`marked`, wired
+ * up in `adaptive-card.tsx`) emits real `<ul>` / `<ol>` / `<p>` elements. But
+ * Tailwind's preflight resets list-style and margins globally, so a bulleted
+ * list in a card renders as unmarked, unindented lines. These rules re-apply
+ * list markers and paragraph spacing to card-rendered markdown ONLY, scoped
+ * under `.ac-textBlock` so nothing outside a card is affected.
+ */
+.ac-textBlock ul,
+.ac-textBlock ol {
+  margin: 0.25rem 0;
+  padding-inline-start: 1.25rem;
+}
+
+.ac-textBlock ul {
+  list-style: disc outside;
+}
+
+.ac-textBlock ol {
+  list-style: decimal outside;
+}
+
+.ac-textBlock li {
+  display: list-item;
+}
+
+.ac-textBlock p {
+  margin: 0.25rem 0;
+}
+
+/*
+ * The renderer sets `line-height` INLINE on the `TextBlock` container to the
+ * value the card's host config asked for, but the host app's base typography
+ * sets a taller `line-height` on `p` itself, which wins over the inherited
+ * container value. That double-spaces every card paragraph and makes a wrapped
+ * `FactSet` title look like two separate rows. Inheriting puts the renderer's
+ * own metrics back in charge.
+ */
+.ac-textBlock p,
+.ac-textBlock li {
+  line-height: inherit;
+}
+
+.ac-textBlock p:first-child {
+  margin-top: 0;
+}
+
+.ac-textBlock p:last-child {
+  margin-bottom: 0;
+}
+
+.ac-textBlock a {
+  color: var(--primary, #0b6bcb);
+  text-decoration: underline;
+}