From e4294fe89645049664f091d833453e438213e18a Mon Sep 17 00:00:00 2001
From: jules <cloudtech@juleslive.net>
Date: Sun, 7 Jun 2026 20:15:40 +1000
Subject: [PATCH] =?UTF-8?q?feat:=20starter=5Fsuggestions=20on=20AgentRef?=
 =?UTF-8?q?=20=E2=86=92=20"Try=20saying=E2=80=A6"=20empty=20state?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lets the host app feed a small list of click-to-send prompts that the
dock shows above the empty composer on first chat. Solves the
"users don't know what to ask it" problem without baking the curation
into the lib — the app picks what to suggest (e.g. derived from the
agent's focus areas).

Changes:
- AgentRef gains optional starter_suggestions?: string[].
- Empty-bubbles render: when present, shows a "Try saying" header +
  bulleted list of clickable rows (capped at 4 — more makes the
  panel feel heavy). Click sends the prompt verbatim via the same
  sendMessage path as the composer.
- Falls back to the existing "Ask anything." line when none provided.
- Subtle hint "Click any to send — or write your own." nudges
  toward custom prompts.

Suggestions disappear naturally after the first message — the panel
only renders when bubbles is empty.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/index.tsx | 56 ++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/src/index.tsx b/src/index.tsx
index 8270e63..14a72db 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -20,7 +20,18 @@ import { MessageBody } from "@crema/agent-ui"
 /*  Public types                                                       */
 /* ------------------------------------------------------------------ */
 
-export type AgentRef = { id: string; name: string }
+export type AgentRef = {
+  id: string
+  name: string
+  /** Optional "try saying…" prompts shown to the user above the empty
+   *  composer on first chat. Click sends the prompt verbatim. The dock
+   *  doesn't curate or persist these — the host app decides what to
+   *  suggest (e.g. derived from the agent's focus areas).
+   *
+   *  Limit ~4 to keep the panel light; the dock won't truncate but
+   *  more rows make the chat feel cluttered. */
+  starter_suggestions?: string[]
+}
 
 /** Structured page-awareness signal. Travels to the platform as its own
  *  field — never concatenated into the user message — so page content
@@ -314,12 +325,43 @@ export function AgentDock({
             {/* Messages */}
             <div ref={scrollRef} className="flex-1 space-y-4 overflow-y-auto p-4">
               {bubbles.length === 0 ? (
-                <div className="pt-8 text-center text-sm text-[var(--foreground)]/80">
-                  {agentId
-                    ? "Ask anything. I can see what page you're on."
-                    : agents && agents.length === 0
-                      ? "No agents available yet."
-                      : "Loading…"}
+                <div className="space-y-4 pt-6">
+                  <p className="text-center text-sm text-[var(--foreground)]/80">
+                    {agentId
+                      ? "Ask anything. I can see what page you're on."
+                      : agents && agents.length === 0
+                        ? "No agents available yet."
+                        : "Loading…"}
+                  </p>
+                  {agentId &&
+                  currentAgent?.starter_suggestions &&
+                  currentAgent.starter_suggestions.length > 0 ? (
+                    <div className="space-y-2">
+                      <p className="px-1 text-xs font-medium uppercase tracking-wide text-[var(--foreground)]/60">
+                        Try saying
+                      </p>
+                      <ul className="space-y-1.5">
+                        {currentAgent.starter_suggestions
+                          .slice(0, 4)
+                          .map((s) => (
+                            <li key={s}>
+                              <button
+                                type="button"
+                                onClick={() => void sendMessage(s)}
+                                disabled={sending}
+                                className="w-full rounded-lg border border-[var(--border)] bg-[var(--chat-assistant-bg)] px-3 py-2 text-left text-sm leading-snug text-[var(--chat-assistant-fg)] transition-colors hover:border-[var(--primary)] disabled:opacity-60"
+                                data-action="assistant-dock-starter"
+                              >
+                                {s}
+                              </button>
+                            </li>
+                          ))}
+                      </ul>
+                      <p className="px-1 text-[11px] text-[var(--foreground)]/50">
+                        Click any to send — or write your own.
+                      </p>
+                    </div>
+                  ) : null}
                 </div>
               ) : (
                 bubbles.map((b, i) =>