feat(ai-components): port the ai-components entry point (#3314) to v15

.github/workflows/ci.yml

@@ -55,6 +55,9 @@ jobs:
       - name: Validate ESM bundle with Node ${{ env.NODE_VERSION }}
         run: yarn validate-esm
 
+      - name: Validate main entry does not pull in ai-components
+        run: yarn validate-entry-isolation
+
       - name: Validate translations are in sync with source
         # `yarn build` above already ran build-translations, which regenerates keys.ts from the
         # t() call sites and runtimeDefaults.ts. A diff here means the author changed a call site

.prettierignore

@@ -1,6 +1,8 @@
 node_modules/
 CHANGELOG.md
 examples/**/serviceWorker.ts
+examples/*/.next/
+examples/*/next-env.d.ts
 ./dist/
 
 # Vendored agent skills (third-party content from vercel-labs/agent-skills)

AGENTS.md

@@ -36,9 +36,9 @@ Respect repo-specific rules. Do not suppress lint rules broadly; justify and sco
 ## Project layout
 
 - `src/` — library source: `components/`, `context/`, `hooks/`, `store/`, `i18n/`, `styling/`, `a11y/`, `plugins/`, `utils/`, `types/`, `constants/`, `mock-builders/`
-- `src/plugins/` — separately exported entry points: `ChannelDetail`, `Emojis`, `SlotGeometry`, `SlotLayout`, `encoders`
+- `src/plugins/` — separately exported entry points: `AIComponents`, `ChannelDetail`, `Emojis`, `SlotGeometry`, `SlotLayout`, `encoders`
 - `scripts/` — build/validation scripts
-- `examples/` — private example workspaces: `examples/tutorial` (one folder per tutorial step), `examples/vite` (complete app)
+- `examples/` — private example workspaces: `examples/tutorial` (one folder per tutorial step), `examples/vite` (complete app), `examples/ai-chatbot` (Next.js AI chatbot)
 - `ai-docs/` — integrator-facing migration guides (`ai-migration-v14-v15.md`, `i18n-v15-migration.md`, `instance-configuration.md`, …) and the hand-reviewed `i18n-v15-key-map.json`
 - `developers/` — dev notes (`BRANCHES.md`, `COMMIT.md`, `DEPRECATIONS.md`, `DEVELOPMENT.md`, `DOCUMENTATION.md`, `PR.md`, `RELEASE.md`)
 
@@ -79,10 +79,12 @@ yarn i18n:export          # write an en.json on demand (for a translator or TMS)
 # Bundle smoke tests (run in CI after build)
 yarn validate-cjs         # loads dist/cjs in Node + a browser-like context
 yarn validate-esm         # imports dist/es in Node
+yarn validate-entry-isolation # fails if the main entry's ESM graph reaches ai-components or its deps
 
 # Examples
 yarn start:tutorial       # @stream-io/stream-chat-react-tutorial dev server
 yarn start:vite           # @stream-io/stream-chat-react-vite dev server
+yarn start:ai-chatbot     # @stream-io/stream-chat-react-ai-chatbot dev server (run yarn build first)
 yarn examples:build       # build all example workspaces
 ```
 
@@ -312,13 +314,14 @@ Mock modules with `vi.mock('../../EmptyStateIndicator', () => ({ … }))`; use `
 1. **`build-translations`** — regenerates `src/i18n/keys.ts` from the `t()` call sites
 2. **`vite build`** — bundles the entry points as ESM (`dist/es/*.mjs`, one file per module) + CJS (`dist/cjs/*.js`)
 3. **`tsc -p tsconfig.lib.json`** — `.d.ts` only → `dist/types/`
-4. **`build-styling`** — Sass → `dist/css/index.css`, `emoji-replacement.css`, `emoji-picker.css`, `channel-detail.css`, plus `cp -r src/styling/assets dist/css/assets`
+4. **`build-styling`** — Sass → `dist/css/index.css`, `emoji-replacement.css`, `emoji-picker.css`, `channel-detail.css`, `ai-components.css`, plus `cp -r src/styling/assets dist/css/assets`
 
 **Entry points** (`package.json` exports ↔ `vite.config.ts` `lib.entry`):
 
 | Import path                        | Source                             |
 | ---------------------------------- | ---------------------------------- |
 | `stream-chat-react`                | `src/index.ts`                     |
+| `stream-chat-react/ai-components`  | `src/plugins/AIComponents/`        |
 | `stream-chat-react/channel-detail` | `src/plugins/ChannelDetail/`       |
 | `stream-chat-react/emojis`         | `src/plugins/Emojis/`              |
 | `stream-chat-react/mp3-encoder`    | `src/plugins/encoders/mp3.ts`      |
@@ -454,7 +457,7 @@ Follow `.github/pull_request_template.md` (Goal / Implementation details / UI Ch
 - [ ] Screenshots (before/after) for UI changes
 - [ ] Public API changes documented
 
-**CI** (`.github/workflows/ci.yml`, on every PR): lint (`yarn lint`, `yarn types`, `yarn types:scripts`) · build + `validate-cjs` + `validate-esm` + `keys.ts` drift check · `yarn coverage` → Codecov · deploy `examples/vite` to Vercel. `pr-check.yml` lints the PR title; `size.yml` reports bundle size.
+**CI** (`.github/workflows/ci.yml`, on every PR): lint (`yarn lint`, `yarn types`, `yarn types:scripts`) · build + `validate-cjs` + `validate-esm` + `validate-entry-isolation` + `keys.ts` drift check · `yarn coverage` → Codecov · deploy `examples/vite` to Vercel. `pr-check.yml` lints the PR title; `size.yml` reports bundle size.
 
 **Release:** automated via semantic-release (`.releaserc.json`) from commit messages.
 

ai-docs/ai-migration-v14-v15.md

@@ -300,7 +300,7 @@ An unrenamed key does **not** throw — it simply never matches, and the English
 instead. Do not assume the absence of an error means the app is migrated.
 
 **Renaming:** every old key maps to exactly one new key. The complete table is
-[`i18n-v15-key-map.json`](./i18n-v15-key-map.json) (603 rows, `{ "<old key>": { "key": "<new key>",
+[`i18n-v15-key-map.json`](./i18n-v15-key-map.json) (621 rows, `{ "<old key>": { "key": "<new key>",
 "prose": bool, "plural"?: bool } }`). Entries with `"prose": false` hold formatter expressions
 rather than copy. Four of them nonetheless carry English words inside their `calendarFormats`
 argument — `timestamp.DateSeparator`, `timestamp.ReminderNotification`,

ai-docs/i18n-v15-key-map.json

@@ -1,6 +1,6 @@
 {
   "$comment": "Migration table: natural-language translation key (v14) -> namespaced key (v15). Hand-reviewed; nothing regenerates it. Integrators who passed translationsForLanguage/registerTranslation dictionaries keyed on the old strings should use this to rename their keys. See ai-docs/i18n-v15-migration.md.",
-  "count": 603,
+  "count": 621,
   "keys": {
     "aria/Active": {
       "key": "a11y.accessibleLabel.active.ariaLabel",
@@ -114,6 +114,78 @@
       "key": "a11y.interactionAnnouncements.voiceRecordingAttached.ariaLabel",
       "prose": true
     },
+    "Delete attachment": {
+      "key": "aiComponents.attachmentPreview.deleteAttachment.ariaLabel",
+      "prose": true
+    },
+    "Unknown file name": {
+      "key": "aiComponents.attachmentPreview.unknownFileName.text",
+      "prose": true
+    },
+    "Loading chart...": {
+      "key": "aiComponents.chart.loading.text",
+      "prose": true
+    },
+    "Unknown chart type": {
+      "key": "aiComponents.chart.unknownType.text",
+      "prose": true
+    },
+    "aria/Start voice input": {
+      "key": "aiComponents.messageComposer.speechToText.ariaLabel",
+      "prose": true
+    },
+    "Ask a question...": {
+      "key": "aiComponents.messageComposer.textInput.placeholder",
+      "prose": true
+    },
+    "Brewing up an answer": {
+      "key": "aiComponents.stateIndicator.brewingUpAnAnswer.text",
+      "prose": true
+    },
+    "Channeling my inner Einstein": {
+      "key": "aiComponents.stateIndicator.channelingMyInnerEinstein.text",
+      "prose": true
+    },
+    "Connecting the dots": {
+      "key": "aiComponents.stateIndicator.connectingTheDots.text",
+      "prose": true
+    },
+    "Consulting the AI gods": {
+      "key": "aiComponents.stateIndicator.consultingTheAiGods.text",
+      "prose": true
+    },
+    "Cooking up something good": {
+      "key": "aiComponents.stateIndicator.cookingUpSomethingGood.text",
+      "prose": true
+    },
+    "Crunching the numbers": {
+      "key": "aiComponents.stateIndicator.crunchingTheNumbers.text",
+      "prose": true
+    },
+    "Firing up the neurons": {
+      "key": "aiComponents.stateIndicator.firingUpTheNeurons.text",
+      "prose": true
+    },
+    "Putting on my thinking cap": {
+      "key": "aiComponents.stateIndicator.puttingOnMyThinkingCap.text",
+      "prose": true
+    },
+    "Reading the digital tea leaves": {
+      "key": "aiComponents.stateIndicator.readingTheDigitalTeaLeaves.text",
+      "prose": true
+    },
+    "Summoning my inner genius": {
+      "key": "aiComponents.stateIndicator.summoningMyInnerGenius.text",
+      "prose": true
+    },
+    "Thinking really hard": {
+      "key": "aiComponents.stateIndicator.thinkingReallyHard.text",
+      "prose": true
+    },
+    "Working my magic": {
+      "key": "aiComponents.stateIndicator.workingMyMagic.text",
+      "prose": true
+    },
     "Generating...": {
       "key": "aiState.indicator.generating.label",
       "prose": true

ai-docs/i18n-v15-migration.md

@@ -30,7 +30,7 @@ imported and copied into `Streami18n` at construction, so they shipped even if y
 
 ## Renaming your keys
 
-Every old key maps to exactly one new key. The full table (603 rows) is
+Every old key maps to exactly one new key. The full table (621 rows, including the 18 `aiComponents.*` keys of `stream-chat-react/ai-components`) is
 [`i18n-v15-key-map.json`](./i18n-v15-key-map.json):
 
 ```json

eslint.config.mjs

@@ -38,6 +38,7 @@ export default tseslint.config(
       '.yarn',
       'examples/*/dist',
       'examples/*/node_modules',
+      'examples/*/.next',
       'examples/*/docs-playwright',
     ],
   },

examples/ai-chatbot/.env.example

@@ -0,0 +1,4 @@
+STREAM_API_KEY=YOUR_STREAM_KEY
+STREAM_API_SECRET=YOUR_STREAM_SECRET
+# Optional: point at your own AI agent server
+# NEXT_PUBLIC_AI_SERVER_URL=http://localhost:3000

examples/ai-chatbot/.gitignore

@@ -0,0 +1,43 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env
+.env*.local
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/ai-chatbot/README.md

@@ -0,0 +1,36 @@
+# AI chatbot example
+
+A Next.js chatbot built with `stream-chat-react` and its `stream-chat-react/ai-components` entry point
+(streaming messages, AI state indicator, AI message composer). Styles come from
+`stream-chat-react/css/ai-components.css`.
+
+## Getting started
+
+From the repository root:
+
+```bash
+yarn install
+yarn build        # the SDK must be built first: the example consumes `dist` through package `exports`
+cp examples/ai-chatbot/.env.example examples/ai-chatbot/.env.local
+# fill in STREAM_API_KEY and STREAM_API_SECRET in .env.local
+yarn start:ai-chatbot
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+## Environment variables
+
+- `STREAM_API_KEY`, `STREAM_API_SECRET` - credentials of your Stream app (server-side only, never commit them).
+- `NEXT_PUBLIC_AI_SERVER_URL` (optional) - URL of your own AI agent server; defaults to Stream's hosted demo server.
+
+The hosted demo server only answers for channels of Stream's demo app. With your own `STREAM_API_KEY` /
+`STREAM_API_SECRET` the AI agent never joins your channels, so run your own AI agent server (it must
+expose `POST /start-ai-agent` and `POST /summarize`, as called from `src/components/api.ts`) and point `NEXT_PUBLIC_AI_SERVER_URL` at it.
+
+## v15 notes
+
+- **Token signing.** The server signs the user token itself, in `src/app/createUserToken.ts` (HS256), because `stream-chat` v10 is a client-side SDK with no server-side `createToken`. For production, use one of Stream's server SDKs instead.
+- **One copy of `@stream-io/state-store`.** The example keeps `installConfig.hoistingLimits: workspaces`, so the app installs its own `stream-chat` and `@stream-io/state-store` while the linked `stream-chat-react` workspace resolves the copies at the repository root. `stream-chat`, `@stream-io/i18n` and `stream-chat-react` hand each other store instances, so exactly one copy of `@stream-io/state-store` must be loaded. The app dedupes `stream-chat` and `@stream-io/state-store` through the Turbopack `resolveAlias` in `next.config.ts` plus the matching `paths` in `tsconfig.json`.
+- **Sidebar pagination.** The sidebar uses infinite scroll: v15's `ChannelList` has no load-more button.
+
+See [implementation.md](./implementation.md) for implementation notes.