feat(sdk): rich empty state with avatar, headline, suggestion chips (v0.11.0)

Replaces the lone "Start a conversation" placeholder with an
onboarding panel — agent avatar, headline, sub-line, and clickable
suggestion chips. Click a chip and it sends as a normal user message
(equivalent to typing the same text and pressing Send). The whole
block hides the moment the conversation begins, including while the
agent is mid-stream — chips don't flash next to a typing indicator.

API: four independent options on init() and as `data-*` attributes,
all optional, all backwards-compatible (none set → legacy single-line
copy stays):

  - emptyAvatar    / data-empty-avatar
  - emptyTitle     / data-empty-title
  - emptySubtitle  / data-empty-subtitle
  - suggestions    / data-suggestions  (pipe-split string OR JSON array)

Programmatic form accepts `string[]`; the data-* form accepts either a
JSON array string or a `|`-separated string, which is easier to write
in HTML without escaping. Same parser on both sides.

Docs:
- script-tag.md — 4 rows in the attribute table, full "Empty state"
  section with snippet, behavior, and when-not-to-use guidance.
- New 06 · Empty state cookbook page with live <BridleEmbed> demo,
  combine-with-greeting-and-prompt recipe, and tips (chip length,
  3–5 chip ceiling, avatar size).
- 01 · Basic optional-knobs table picks up the four new attrs.
- BridleEmbed accepts all four props so future pages can demo them.
- Sidebar adds 06.

HTML embed example: basic snippet shows all four data-* with
comments; the live floating widget mounts with chips + greeting so a
visitor sees the new onboarding flow on page load.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dmitriyzhuk

docs/docs/.vitepress/config.ts

@@ -78,6 +78,7 @@ export default defineConfig({
             { text: '03 · Styles', link: '/examples/styles' },
             { text: '04 · Authenticator', link: '/examples/authenticator' },
             { text: '05 · Welcome message', link: '/examples/welcome' },
+            { text: '06 · Empty state', link: '/examples/empty-state' },
           ],
         },
       ],

docs/docs/.vitepress/theme/components/BridleEmbed.vue

@@ -20,6 +20,10 @@ const props = withDefaults(
     greeting?: string
     greetingDelay?: number
     fabIcon?: string
+    emptyAvatar?: string
+    emptyTitle?: string
+    emptySubtitle?: string
+    suggestions?: string[]
   }>(),
   {
     apiUrl: DEFAULT_API_URL,
@@ -58,6 +62,10 @@ onMounted(async () => {
       greeting: props.greeting,
       greetingDelay: props.greetingDelay,
       fabIcon: props.fabIcon,
+      emptyAvatar: props.emptyAvatar,
+      emptyTitle: props.emptyTitle,
+      emptySubtitle: props.emptySubtitle,
+      suggestions: props.suggestions,
       onError: (err: Error) => {
         error.value = err.message || String(err)
       },

docs/docs/embed/script-tag.md

@@ -32,6 +32,10 @@ When the script loads, it auto-registers a `<bridle-chat>` Custom Element and mo
 | `data-prompt` | optional | Free-form context string sent at handshake and forwarded to the agent on every message — page URL, user plan, locale, A/B cohort, etc. See [Page Context](/embed/context) |
 | `data-greeting` | optional | Welcome message shown on the first open of an empty chat, after a typing-indicator delay. Markdown supported. See [Welcome message](#welcome-message) |
 | `data-greeting-delay` | `3000` | Milliseconds of typing indicator before `data-greeting` appears. Set `0` to skip the delay |
+| `data-empty-avatar` | optional | URL of an avatar shown on the empty-state screen. See [Empty state](#empty-state) |
+| `data-empty-title` | optional | Headline shown on the empty-state screen, e.g. "What can I help with?" |
+| `data-empty-subtitle` | optional | Sub-line shown under `data-empty-title` |
+| `data-suggestions` | optional | Suggestion chips rendered on the empty state. Pipe-separated (`Q1|Q2|Q3`) or a JSON array string. Clicking a chip sends it as a user message |
 
 ## Choosing where to load the script from
 
@@ -79,6 +83,47 @@ Mount the chat inside a specific container instead of floating:
 
 In inline mode, the chat fills its container. Set the height/width on the parent via CSS.
 
+## Empty state
+
+The default empty chat shows a single muted "Start a conversation" line. Pass any of `emptyAvatar` / `emptyTitle` / `emptySubtitle` / `suggestions` and you get a richer onboarding panel — agent avatar, headline, sub-line, and pill-shaped suggestion chips. Click a chip and it sends that question as a regular user message; the empty state then disappears.
+
+```html
+<script
+  src="https://bridle.cleanslice.org/sdk/latest.js"
+  data-agent-id="agent-abc-123"
+  data-token="<jwt>"
+  data-empty-avatar="/avatars/support-agent.png"
+  data-empty-title="How can I help?"
+  data-empty-subtitle="I can compare plans, schedule a demo, or open a ticket."
+  data-suggestions="Compare plans|Book a demo|Open a support ticket"
+></script>
+```
+
+Programmatic:
+
+```ts
+init({
+  apiUrl, agentId, token,
+  emptyAvatar: '/avatars/support-agent.png',
+  emptyTitle: 'How can I help?',
+  emptySubtitle: 'I can compare plans, schedule a demo, or open a ticket.',
+  suggestions: ['Compare plans', 'Book a demo', 'Open a support ticket'],
+})
+```
+
+### Behavior
+
+- Hidden as soon as `messages.length > 0` **or** the agent starts replying (`isTyping`). Suggestion chips do not flash next to a streaming reply.
+- Clicking a chip is **equivalent to typing the same text and pressing Send** — `onMessage` fires for the user turn, the runtime sees it as any other message.
+- Chips are disabled while the WebSocket isn't open, so visitors don't fire questions into a closed connection.
+- All four fields are independent — pass only the ones you want. Provide nothing and the legacy "Start a conversation" line stays.
+
+### When NOT to use it
+
+- **Long replies as chips** — chip text becomes the entire user message. Keep them short prompts ("Pricing?"), not full sentences the visitor wouldn't have typed.
+- **A FAQ list** — chips are for *opening* the conversation, not a static knowledge base. After the first user turn they're gone.
+- **Forms / structured input** — chips send free text. For "pick a plan: Basic / Pro / Team" structured selection, the runtime should emit assistant messages with parts of type the renderer understands (not a feature of the SDK today).
+
 ## Welcome message
 
 When the visitor opens the chat for the first time and there's no prior transcript, you can pre-seed an assistant bubble — typing dots appear for a moment, then the message fades in like the agent typed it.

docs/docs/examples/basic.md

@@ -21,6 +21,8 @@ Everything below works on the script tag with **zero extra integration code** 
 |-----------|--------------|-----------|
 | `data-greeting` | Pre-seeds the first assistant bubble after a typing-indicator delay on an empty chat | [Welcome message](/examples/welcome) |
 | `data-greeting-delay` | Milliseconds before the greeting appears (default `3000`) | — |
+| `data-empty-avatar` / `data-empty-title` / `data-empty-subtitle` | Avatar + headline + sub-line shown on the empty-state screen | [Empty state](/examples/empty-state) |
+| `data-suggestions` | Pipe-separated suggestion chips on the empty state — click to send | — |
 | `data-prompt` | Free-form context forwarded to the agent on every message — page URL, plan, locale, A/B cohort | [Page Context](/embed/context) |
 | `data-fab-icon` | URL of an image to replace the FAB's built-in glyph | [Theming › Custom FAB icon](/embed/theming#custom-fab-icon) |
 | `data-custom-css` | Inline CSS injected into the shadow root to restyle internal classes | [Theming › Overriding internal classes](/embed/theming#overriding-internal-classes) |

docs/docs/examples/empty-state.md

@@ -0,0 +1,93 @@
+# 06 · Empty state with suggestions
+
+Replace the default "Start a conversation" placeholder with an onboarding panel — agent avatar, headline, sub-line, and clickable suggestion chips. Click a chip and it sends as a normal user message; the whole block disappears the moment the conversation begins.
+
+## Snippet
+
+```html
+<script
+  src="https://bridle.cleanslice.org/sdk/latest.js"
+  data-agent-id="agent-abc-123"
+  data-token="<jwt>"
+  data-empty-avatar="/avatars/support-agent.png"
+  data-empty-title="How can I help?"
+  data-empty-subtitle="I can compare plans, schedule a demo, or open a ticket."
+  data-suggestions="Compare plans|Book a demo|Open a support ticket"
+></script>
+```
+
+Programmatic form:
+
+```ts
+Bridle.init({
+  apiUrl, agentId, token,
+  emptyAvatar: '/avatars/support-agent.png',
+  emptyTitle: 'How can I help?',
+  emptySubtitle: 'I can compare plans, schedule a demo, or open a ticket.',
+  suggestions: ['Compare plans', 'Book a demo', 'Open a support ticket'],
+})
+```
+
+## Live demo
+
+<BridleEmbed
+  title="Welcome desk"
+  empty-avatar="https://bridle.cleanslice.org/logo.svg"
+  empty-title="How can I help?"
+  empty-subtitle="Ask me anything about Bridle, or pick one of the prompts below."
+  :suggestions="['How do I embed Bridle?', 'How does theming work?', 'What does data-prompt do?']"
+/>
+
+Click a chip — it sends as a user message, the panel switches to the live conversation, and the empty state stays out of the way.
+
+## Behavior
+
+| Condition | Result |
+|-----------|--------|
+| `messages.length === 0` and not typing | Empty state visible |
+| Agent starts replying (`isTyping`) | Empty state hidden (chips don't flash next to a streaming reply) |
+| User sends anything — text, image, or a chip | Empty state hidden — conversation begins |
+| WebSocket not open | Chips disabled — visitors don't fire into a closed connection |
+| All four fields unset | Legacy single-line "Start a conversation" copy |
+
+## Combine with `greeting` and `prompt`
+
+| Field | Job |
+|-------|-----|
+| `emptyAvatar` / `emptyTitle` / `emptySubtitle` / `suggestions` | What the **visitor** sees in an empty chat. Static content. |
+| `greeting` / `greetingDelay` | What the **agent** "says" once typing dots clear. Static, one-shot per session. |
+| `prompt` | What the **agent runtime** receives at handshake. Hidden from the visitor. Drives the agent's reasoning. |
+
+Used together, they tell a coherent story to both sides:
+
+```ts
+Bridle.init({
+  apiUrl, agentId, token,
+
+  // Visitor sees:
+  emptyAvatar: '/avatars/support-agent.png',
+  emptyTitle: 'How can I help?',
+  emptySubtitle: 'Ask anything about your subscription.',
+  suggestions: ['Upgrade my plan', 'See past invoices', 'Cancel my account'],
+
+  // Then the agent "introduces itself" once they open the panel:
+  greeting: "Hi! I'm here for your subscription questions. Heads-up: cancellations are processed at the end of the billing cycle.",
+  greetingDelay: 2000,
+
+  // Background context for the runtime (not shown to visitor):
+  prompt: 'Section: account/billing · Plan: pro · Renews: 2026-07-12',
+})
+```
+
+## Tips
+
+- **Keep chip text short** — chip text becomes the entire user message. "Pricing?" not "Could you walk me through your pricing model?". Long chips become long user turns in the transcript.
+- **3–5 chips max** — more than that and the empty state grows tall enough to push the input below the fold on mobile.
+- **Avatar at ≥56px** — the panel renders it as a 56×56 circle. Smaller sources scale up and look fuzzy.
+- **Style the chip itself** via [`customCss`](/embed/theming#overriding-internal-classes) targeting `.bridle__suggestion` — see the recipe in [03 · Styles](/examples/styles#styling-image-attachments) (same approach).
+
+## Related
+
+- [Welcome message](/examples/welcome) — what the agent says.
+- [Page Context](/embed/context) — what the agent runtime knows.
+- [Script Tag → Empty state](/embed/script-tag#empty-state) — full reference.

example/index.html

@@ -26,6 +26,7 @@ <h1 class="mt-2 text-4xl font-bold tracking-tight">Bridle integration examples</
         </p>
         <p class="mx-auto mt-3 max-w-xl text-xs text-slate-500">
           Latest:
+          empty-state suggestions (v0.11.0) ·
           <code>data-greeting</code> (v0.10.0) ·
           image attachments — drag / paste / paperclip (v0.9.0) ·
           <code>data-fab-icon</code> (v0.8.2) ·
@@ -51,6 +52,12 @@ <h2 class="mt-1 text-2xl font-semibold">Basic — one <code>&lt;script&gt;</code
   data-agent-id="agent-31a6fbd1-…"
   data-token="&lt;jwt&gt;"
 
+  &lt;!-- v0.11.0: rich empty state with avatar, headline, suggestion chips --&gt;
+  data-empty-avatar="/avatars/agent.png"
+  data-empty-title="How can I help?"
+  data-empty-subtitle="Ask anything, or pick a prompt below."
+  data-suggestions="Compare plans|Book a demo|Open a support ticket"
+
   &lt;!-- v0.10.0: pre-seed the first bubble on an empty chat --&gt;
   data-greeting="Hi! Drop a screenshot or ask me anything."
   data-greeting-delay="2500"
@@ -198,6 +205,12 @@ <h2 class="mt-1 text-2xl font-semibold">Authenticator — token as a function</h
           sdk.dataset.agentId = basic.agentId;
           sdk.dataset.token = basic.token;
           sdk.dataset.title = 'Chat';
+          // v0.11.0 — rich empty state: visitor sees suggestion chips
+          // before they type. Clicking a chip fires the prompt for them.
+          sdk.dataset.emptyTitle = 'How can I help?';
+          sdk.dataset.emptySubtitle = 'Ask anything, or pick a prompt below.';
+          sdk.dataset.suggestions =
+            'Compare plans|Book a demo|How does theming work?';
           // v0.10.0 — typing dots for 2.5s, then this message lands as the
           // first assistant bubble. Cancels if the user types first.
           sdk.dataset.greeting =

sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleanslice/bridle",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Embeddable web chat for Bridle — drop-in <script> or programmatic init.",
   "type": "module",
   "main": "./dist/bridle.mjs",