From 276928213c667ab0c5d402a3ecf31477e6adcfe0 Mon Sep 17 00:00:00 2001
From: Marcos Medina <marcos.medina@factorial.co>
Date: Mon, 22 Jun 2026 17:09:14 +0200
Subject: [PATCH 1/2] feat(ai): welcome cards + suggestions above composer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bake the welcome-cards capability into F0AiChat as a data-driven
`welcomeScreenCards` prop (symmetric with `welcomeScreenSuggestions`),
rendered by an internal WelcomeScreenCardsRow — replacing the standalone
F0AiChatWelcomeCards component, which the consumer had to hand-wire through
the `footer` slot. Also always render the welcome suggestions row above the
composer so its popover opens upward instead of covering the input.

Combines and supersedes #4534 and #4537.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../react/src/sds/ai/F0AiChat/F0AiChat.tsx    |  2 +
 .../_mock/MockConnectedChatInput.tsx          | 10 +++
 packages/react/src/sds/ai/F0AiChat/index.ts   |  1 +
 .../src/sds/ai/F0AiChat/internal-types.ts     |  6 ++
 .../providers/AiChatStateProvider.tsx         |  8 +++
 packages/react/src/sds/ai/F0AiChat/types.ts   | 28 ++++++++
 .../ai/F0AiChatTextArea/F0AiChatTextArea.tsx  | 31 ++++++--
 .../__stories__/F0AiChatTextArea.stories.tsx  | 35 +++++++++
 .../F0AiChatTextArea.welcomeLayout.test.tsx   | 51 +++++++++++--
 .../__tests__/WelcomeScreenCardsRow.test.tsx  | 72 +++++++++++++++++++
 .../components/WelcomeScreenCardsRow.tsx      | 45 ++++++++++++
 .../WelcomeScreenSuggestionsRow.tsx           |  7 +-
 .../src/sds/ai/F0AiChatTextArea/types.ts      | 17 ++++-
 13 files changed, 296 insertions(+), 17 deletions(-)
 create mode 100644 packages/react/src/sds/ai/F0AiChatTextArea/__tests__/WelcomeScreenCardsRow.test.tsx
 create mode 100644 packages/react/src/sds/ai/F0AiChatTextArea/components/WelcomeScreenCardsRow.tsx

diff --git a/packages/react/src/sds/ai/F0AiChat/F0AiChat.tsx b/packages/react/src/sds/ai/F0AiChat/F0AiChat.tsx
index 34fdedbf29..7a13fec349 100644
--- a/packages/react/src/sds/ai/F0AiChat/F0AiChat.tsx
+++ b/packages/react/src/sds/ai/F0AiChat/F0AiChat.tsx
@@ -40,6 +40,7 @@ const F0AiChatProviderComponent = ({
   chatMessages,
   chatInput,
   welcomeScreenSuggestions,
+  welcomeScreenCards,
   disclaimer,
   resizable = false,
   defaultVisualizationMode,
@@ -72,6 +73,7 @@ const F0AiChatProviderComponent = ({
       chatMessages={chatMessages}
       chatInput={chatInput}
       welcomeScreenSuggestions={welcomeScreenSuggestions}
+      welcomeScreenCards={welcomeScreenCards}
       disclaimer={disclaimer}
       resizable={resizable}
       defaultVisualizationMode={defaultVisualizationMode}
diff --git a/packages/react/src/sds/ai/F0AiChat/__stories__/_mock/MockConnectedChatInput.tsx b/packages/react/src/sds/ai/F0AiChat/__stories__/_mock/MockConnectedChatInput.tsx
index a8f350f796..1e2bbcb46e 100644
--- a/packages/react/src/sds/ai/F0AiChat/__stories__/_mock/MockConnectedChatInput.tsx
+++ b/packages/react/src/sds/ai/F0AiChat/__stories__/_mock/MockConnectedChatInput.tsx
@@ -33,6 +33,7 @@ export const MockConnectedChatInput = () => {
     visualizationMode,
     creditWarning,
     welcomeScreenSuggestions,
+    welcomeScreenCards,
     tracking,
     openGame,
   } = useAiChat()
@@ -70,6 +71,13 @@ export const MockConnectedChatInput = () => {
     [sendMessage, tracking]
   )
 
+  const handleCardSelect = useCallback(
+    (message: string) => {
+      sendMessage(message)
+    },
+    [sendMessage]
+  )
+
   return (
     <F0AiChatTextArea
       ref={containerRef}
@@ -91,6 +99,8 @@ export const MockConnectedChatInput = () => {
       fullscreen={fullscreen}
       welcomeScreenSuggestions={welcomeScreenSuggestions}
       onSuggestionClick={handleSuggestionClick}
+      welcomeScreenCards={welcomeScreenCards}
+      onCardSelect={handleCardSelect}
     />
   )
 }
diff --git a/packages/react/src/sds/ai/F0AiChat/index.ts b/packages/react/src/sds/ai/F0AiChat/index.ts
index ad981cf8d9..cae6dcb9ec 100644
--- a/packages/react/src/sds/ai/F0AiChat/index.ts
+++ b/packages/react/src/sds/ai/F0AiChat/index.ts
@@ -24,6 +24,7 @@ export type {
   DashboardCanvasContent,
   DataDownloadCanvasContent,
   F0AIMessage,
+  F0AiChatWelcomeCard,
   F0Message,
   F0ToolCall,
   FormCanvasContent,
diff --git a/packages/react/src/sds/ai/F0AiChat/internal-types.ts b/packages/react/src/sds/ai/F0AiChat/internal-types.ts
index 2047a0ae40..1b55b8b264 100644
--- a/packages/react/src/sds/ai/F0AiChat/internal-types.ts
+++ b/packages/react/src/sds/ai/F0AiChat/internal-types.ts
@@ -17,6 +17,7 @@ import {
   type PendingQuote,
   type TranscribeFn,
   type VisualizationMode,
+  F0AiChatWelcomeCard,
   WelcomeScreenSuggestion,
 } from "./types"
 
@@ -33,6 +34,7 @@ export interface AiChatState {
   chatMessages?: React.ReactNode
   chatInput?: React.ReactNode
   welcomeScreenSuggestions?: WelcomeScreenSuggestion[]
+  welcomeScreenCards?: F0AiChatWelcomeCard[]
   disclaimer?: AiChatDisclaimer
   resizable?: boolean
   defaultVisualizationMode?: VisualizationMode
@@ -84,6 +86,10 @@ export type AiChatProviderReturnValue = {
   setWelcomeScreenSuggestions: React.Dispatch<
     React.SetStateAction<WelcomeScreenSuggestion[]>
   >
+  welcomeScreenCards: F0AiChatWelcomeCard[]
+  setWelcomeScreenCards: React.Dispatch<
+    React.SetStateAction<F0AiChatWelcomeCard[]>
+  >
   onThumbsUp?: (
     message: F0AIMessage,
     { threadId, feedback }: { threadId: string; feedback: string }
diff --git a/packages/react/src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx b/packages/react/src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx
index e9238ef4ea..296a97948e 100644
--- a/packages/react/src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx
+++ b/packages/react/src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx
@@ -22,6 +22,7 @@ import {
   type PendingContext,
   type PendingQuote,
   type VisualizationMode,
+  F0AiChatWelcomeCard,
   WelcomeScreenSuggestion,
 } from "../types"
 import { DEFAULT_CHAT_WIDTH } from "../utils/constants"
@@ -57,6 +58,7 @@ export const AiChatStateProvider: FC<PropsWithChildren<AiChatState>> = ({
   chatMessages,
   chatInput,
   welcomeScreenSuggestions: initialWelcomeScreenSuggestions = [],
+  welcomeScreenCards: initialWelcomeScreenCards = [],
   disclaimer,
   resizable = false,
   defaultVisualizationMode = "sidepanel",
@@ -114,6 +116,9 @@ export const AiChatStateProvider: FC<PropsWithChildren<AiChatState>> = ({
   const [welcomeScreenSuggestions, setWelcomeScreenSuggestions] = useState<
     WelcomeScreenSuggestion[]
   >(initialWelcomeScreenSuggestions)
+  const [welcomeScreenCards, setWelcomeScreenCards] = useState<
+    F0AiChatWelcomeCard[]
+  >(initialWelcomeScreenCards)
   const i18n = useI18n()
   const [placeholders, setPlaceholders] = useState<string[]>([
     i18n.t("ai.inputPlaceholder"),
@@ -262,6 +267,8 @@ export const AiChatStateProvider: FC<PropsWithChildren<AiChatState>> = ({
         chatInput,
         welcomeScreenSuggestions,
         setWelcomeScreenSuggestions,
+        welcomeScreenCards,
+        setWelcomeScreenCards,
         onThumbsUp,
         onThumbsDown,
         placeholders,
@@ -358,6 +365,7 @@ const REAL_VALUES: Partial<AiChatProviderReturnValue> = {
   shouldPlayEntranceAnimation: true,
   placeholders: [],
   welcomeScreenSuggestions: [],
+  welcomeScreenCards: [],
 }
 
 const NO_PROVIDER_CONTEXT = new Proxy({} as AiChatProviderReturnValue, {
diff --git a/packages/react/src/sds/ai/F0AiChat/types.ts b/packages/react/src/sds/ai/F0AiChat/types.ts
index 53f6f26423..83ad84577a 100644
--- a/packages/react/src/sds/ai/F0AiChat/types.ts
+++ b/packages/react/src/sds/ai/F0AiChat/types.ts
@@ -294,6 +294,11 @@ export type AiChatProviderProps = {
    */
   initialMessage?: string | string[]
   welcomeScreenSuggestions?: WelcomeScreenSuggestion[]
+  /**
+   * Action/prompt cards rendered below the composer on the fullscreen welcome
+   * screen. The chat owns layout and, for prompt cards, the send.
+   */
+  welcomeScreenCards?: F0AiChatWelcomeCard[]
   disclaimer?: AiChatDisclaimer
   /**
    * Enable resizable chat window
@@ -425,6 +430,29 @@ export type WelcomeScreenSuggestion = {
   items: WelcomeScreenSuggestionItem[]
 }
 
+/**
+ * A card shown below the composer on the fullscreen welcome screen, rendered
+ * as an `F0CardHorizontal`. Two kinds:
+ * - **Prompt cards** carry a `message` the chat sends when the card is clicked.
+ * - **Action cards** carry an `onClick` (e.g. open a dialog) which takes
+ *   precedence over `message`.
+ *
+ * Data-driven and runtime-agnostic — the chat owns the layout and, for prompt
+ * cards, the send.
+ */
+export type F0AiChatWelcomeCard = {
+  icon: IconType
+  title: string
+  description?: string
+  /** Prompt cards: the message the chat sends when the card is clicked. */
+  message?: string
+  /**
+   * Action cards: custom click handler (e.g. open a dialog). Takes precedence
+   * over `message` when both are present.
+   */
+  onClick?: () => void
+}
+
 /**
  * Disclaimer configuration for the chat input
  */
diff --git a/packages/react/src/sds/ai/F0AiChatTextArea/F0AiChatTextArea.tsx b/packages/react/src/sds/ai/F0AiChatTextArea/F0AiChatTextArea.tsx
index 3d9872036d..6d14d06366 100644
--- a/packages/react/src/sds/ai/F0AiChatTextArea/F0AiChatTextArea.tsx
+++ b/packages/react/src/sds/ai/F0AiChatTextArea/F0AiChatTextArea.tsx
@@ -16,6 +16,7 @@ import { CreditWarningWrapper } from "./components/CreditWarningWrapper"
 import { MentionPopover } from "./components/MentionPopover"
 import { PendingQuoteChip } from "./components/PendingQuoteChip"
 import { TextareaField } from "./components/TextareaField"
+import { WelcomeScreenCardsRow } from "./components/WelcomeScreenCardsRow"
 import { WelcomeScreenSuggestionsRow } from "./components/WelcomeScreenSuggestionsRow"
 import type {
   WelcomeScreenSuggestion,
@@ -81,6 +82,8 @@ export const F0AiChatTextArea = ({
   fullscreen = false,
   welcomeScreenSuggestions,
   onSuggestionClick,
+  welcomeScreenCards,
+  onCardSelect,
   ref,
 }: F0AiChatTextAreaProps) => {
   const translation = useI18n()
@@ -326,9 +329,9 @@ export const F0AiChatTextArea = ({
   const hasOverlay =
     mentions.mentions.length > 0 || mentions.inlineCompletion !== null
 
-  // Welcome suggestions row. On the welcome screen it sits above the textarea
-  // in sidepanel and below it in fullscreen (so the popover can open downward
-  // without covering the composer).
+  // Welcome suggestions row. On the welcome screen it always sits above the
+  // textarea (both sidepanel and fullscreen); the popover opens upward so it
+  // doesn't cover the composer.
   const showSuggestions =
     isWelcomeScreen &&
     !!welcomeScreenSuggestions &&
@@ -340,10 +343,19 @@ export const F0AiChatTextArea = ({
       suggestions={welcomeScreenSuggestions}
       onItemClick={handleSuggestionClick}
       onItemHover={setHoveredSuggestion}
-      side={fullscreen ? "bottom" : "top"}
+      side="top"
     />
   ) : null
 
+  // Welcome cards sit below the composer on the fullscreen welcome screen
+  // (same gate the footer slot uses). Prompt cards send their message through
+  // `onCardSelect`; action cards run their own `onClick`.
+  const showWelcomeCards =
+    isWelcomeScreen &&
+    fullscreen &&
+    !!welcomeScreenCards &&
+    welcomeScreenCards.length > 0
+
   const isFullscreenWelcome = fullscreen && isWelcomeScreen
 
   // Reveal the composer when the welcome screen gives way to the conversation
@@ -368,7 +380,7 @@ export const F0AiChatTextArea = ({
       {...(fullscreen ? composerReveal : {})}
     >
       <div className="flex w-full max-w-content flex-col gap-2">
-        {suggestionsRow && !fullscreen && <div>{suggestionsRow}</div>}
+        {suggestionsRow && <div>{suggestionsRow}</div>}
         <CreditWarningWrapper creditWarning={creditWarning}>
           <motion.form
             aria-busy={inProgress}
@@ -550,8 +562,13 @@ export const F0AiChatTextArea = ({
         </CreditWarningWrapper>
       </div>
 
-      {suggestionsRow && fullscreen && (
-        <div className="w-full max-w-content">{suggestionsRow}</div>
+      {showWelcomeCards && (
+        <div className="w-full max-w-content pt-2">
+          <WelcomeScreenCardsRow
+            cards={welcomeScreenCards}
+            onCardSelect={onCardSelect}
+          />
+        </div>
       )}
 
       {footer && isWelcomeScreen && fullscreen && (
diff --git a/packages/react/src/sds/ai/F0AiChatTextArea/__stories__/F0AiChatTextArea.stories.tsx b/packages/react/src/sds/ai/F0AiChatTextArea/__stories__/F0AiChatTextArea.stories.tsx
index dbed13cc9e..7c8130e318 100644
--- a/packages/react/src/sds/ai/F0AiChatTextArea/__stories__/F0AiChatTextArea.stories.tsx
+++ b/packages/react/src/sds/ai/F0AiChatTextArea/__stories__/F0AiChatTextArea.stories.tsx
@@ -4,6 +4,7 @@ import { useRef, useState } from "react"
 import { F0AiChatTextArea } from "../F0AiChatTextArea"
 import type { F0AiChatTextAreaSubmitPayload } from "../types"
 
+import { File, Marketplace } from "@/icons/app"
 import { mockTranscribe } from "@/lib/storybook-utils/ai-mocks"
 
 import { F0ClarifyingPanel } from "../../F0ClarifyingPanel"
@@ -12,6 +13,7 @@ import type {
   AiChatCreditWarning,
   AiChatDisclaimer,
   AiChatFileAttachmentConfig,
+  F0AiChatWelcomeCard,
   PendingContext,
   PendingQuote,
   PersonProfile,
@@ -91,6 +93,21 @@ const CREDIT_WARNING: AiChatCreditWarning = {
   onDismiss: () => console.log("dismiss clicked"),
 }
 
+const WELCOME_CARDS: F0AiChatWelcomeCard[] = [
+  {
+    icon: File,
+    title: "Empty survey",
+    description: "Start from scratch",
+    message: "Create an empty survey.",
+  },
+  {
+    icon: Marketplace,
+    title: "Templates",
+    description: "Browse pre-made surveys",
+    onClick: () => console.log("open templates"),
+  },
+]
+
 const noop = () => {}
 
 const buildClarifyingState = (
@@ -135,6 +152,7 @@ type WrapperProps = {
   creditWarning?: AiChatCreditWarning
   disclaimer?: AiChatDisclaimer
   footer?: React.ReactNode
+  welcomeScreenCards?: F0AiChatWelcomeCard[]
   isWelcomeScreen?: boolean
   fullscreen?: boolean
   inProgress?: boolean
@@ -151,6 +169,7 @@ const Wrapper = ({
   creditWarning,
   disclaimer,
   footer,
+  welcomeScreenCards,
   isWelcomeScreen,
   fullscreen,
   inProgress,
@@ -194,6 +213,13 @@ const Wrapper = ({
         searchPersons={searchPersons}
         disclaimer={disclaimer}
         footer={footer}
+        welcomeScreenCards={welcomeScreenCards}
+        onCardSelect={(message) =>
+          setSubmissions((prev) => [
+            ...prev,
+            { text: message, files: [], context: null, quote: null },
+          ])
+        }
         isWelcomeScreen={isWelcomeScreen}
         fullscreen={fullscreen}
       />
@@ -311,6 +337,15 @@ export const FullscreenWelcome: Story = {
   },
 }
 
+export const WithWelcomeCards: Story = {
+  args: {
+    isWelcomeScreen: true,
+    fullscreen: true,
+    welcomeScreenCards: WELCOME_CARDS,
+    disclaimer: DISCLAIMER,
+  },
+}
+
 export const InProgress: Story = {
   args: {
     inProgress: true,
diff --git a/packages/react/src/sds/ai/F0AiChatTextArea/__tests__/F0AiChatTextArea.welcomeLayout.test.tsx b/packages/react/src/sds/ai/F0AiChatTextArea/__tests__/F0AiChatTextArea.welcomeLayout.test.tsx
index af42ef5f68..dc78845ee1 100644
--- a/packages/react/src/sds/ai/F0AiChatTextArea/__tests__/F0AiChatTextArea.welcomeLayout.test.tsx
+++ b/packages/react/src/sds/ai/F0AiChatTextArea/__tests__/F0AiChatTextArea.welcomeLayout.test.tsx
@@ -1,9 +1,12 @@
 import { describe, expect, it, vi } from "vitest"
 
-import { ChartVerticalBars } from "@/icons/app"
+import { ChartVerticalBars, File } from "@/icons/app"
 import { zeroRender as render, screen } from "@/testing/test-utils"
 
-import { type WelcomeScreenSuggestion } from "../../F0AiChat/types"
+import {
+  type F0AiChatWelcomeCard,
+  type WelcomeScreenSuggestion,
+} from "../../F0AiChat/types"
 
 vi.mock("../components/TextareaField", () => ({
   TextareaField: () => <textarea aria-label="Message" readOnly />,
@@ -39,7 +42,7 @@ describe("F0AiChatTextArea welcome suggestions placement", () => {
     ).toBeTruthy()
   })
 
-  it("renders the suggestions below the textarea in fullscreen mode", () => {
+  it("renders the suggestions above the textarea in fullscreen mode", () => {
     render(
       <F0AiChatTextArea
         onSubmit={() => {}}
@@ -52,13 +55,51 @@ describe("F0AiChatTextArea welcome suggestions placement", () => {
 
     const trigger = screen.getByRole("button", { name: /analyze/i })
     const textarea = screen.getByRole("textbox", { name: "Message" })
-    // trigger follows the textarea in document order → suggestions are below.
+    // textarea follows the trigger in document order → suggestions are above.
     expect(
-      textarea.compareDocumentPosition(trigger) &
+      trigger.compareDocumentPosition(textarea) &
         Node.DOCUMENT_POSITION_FOLLOWING
     ).toBeTruthy()
   })
 
+  it("renders welcome cards below the textarea on the fullscreen welcome screen", () => {
+    const cards: F0AiChatWelcomeCard[] = [
+      { icon: File, title: "Empty survey", message: "Create an empty survey." },
+    ]
+    render(
+      <F0AiChatTextArea
+        onSubmit={() => {}}
+        fullscreen
+        isWelcomeScreen
+        welcomeScreenCards={cards}
+        onCardSelect={() => {}}
+      />
+    )
+
+    const textarea = screen.getByRole("textbox", { name: "Message" })
+    const card = screen.getByText("Empty survey")
+    // card follows the textarea in document order → cards are below.
+    expect(
+      textarea.compareDocumentPosition(card) & Node.DOCUMENT_POSITION_FOLLOWING
+    ).toBeTruthy()
+  })
+
+  it("does not render welcome cards on the sidepanel welcome screen", () => {
+    const cards: F0AiChatWelcomeCard[] = [
+      { icon: File, title: "Empty survey", message: "Create an empty survey." },
+    ]
+    render(
+      <F0AiChatTextArea
+        onSubmit={() => {}}
+        isWelcomeScreen
+        welcomeScreenCards={cards}
+        onCardSelect={() => {}}
+      />
+    )
+
+    expect(screen.queryByText("Empty survey")).not.toBeInTheDocument()
+  })
+
   it("hides the footer on the sidepanel welcome screen", () => {
     render(
       <F0AiChatTextArea
diff --git a/packages/react/src/sds/ai/F0AiChatTextArea/__tests__/WelcomeScreenCardsRow.test.tsx b/packages/react/src/sds/ai/F0AiChatTextArea/__tests__/WelcomeScreenCardsRow.test.tsx
new file mode 100644
index 0000000000..557b467c5f
--- /dev/null
+++ b/packages/react/src/sds/ai/F0AiChatTextArea/__tests__/WelcomeScreenCardsRow.test.tsx
@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "vitest"
+import "@testing-library/jest-dom/vitest"
+import { zeroRender as render, screen, userEvent } from "@/testing/test-utils"
+
+import { File, Marketplace } from "@/icons/app"
+
+import { type F0AiChatWelcomeCard } from "../../F0AiChat/types"
+import { WelcomeScreenCardsRow } from "../components/WelcomeScreenCardsRow"
+
+const clickCard = async (title: string) => {
+  const card = screen.getByText(title).closest('[data-testid="card"]')
+  expect(card).not.toBeNull()
+  await userEvent.click(card as HTMLElement)
+}
+
+describe("WelcomeScreenCardsRow", () => {
+  it("renders every card's title and description", () => {
+    const cards: F0AiChatWelcomeCard[] = [
+      {
+        icon: File,
+        title: "Empty survey",
+        description: "Start from scratch",
+        message: "Create an empty survey.",
+      },
+      {
+        icon: Marketplace,
+        title: "Templates",
+        description: "Browse pre-made surveys",
+        message: "Show me the survey templates.",
+      },
+    ]
+
+    render(<WelcomeScreenCardsRow cards={cards} onCardSelect={vi.fn()} />)
+
+    expect(screen.getByText("Empty survey")).toBeInTheDocument()
+    expect(screen.getByText("Start from scratch")).toBeInTheDocument()
+    expect(screen.getByText("Templates")).toBeInTheDocument()
+    expect(screen.getByText("Browse pre-made surveys")).toBeInTheDocument()
+  })
+
+  it("calls onCardSelect with the message when a prompt card is clicked", async () => {
+    const onCardSelect = vi.fn()
+    const cards: F0AiChatWelcomeCard[] = [
+      { icon: File, title: "Empty survey", message: "Create an empty survey." },
+    ]
+
+    render(<WelcomeScreenCardsRow cards={cards} onCardSelect={onCardSelect} />)
+    await clickCard("Empty survey")
+
+    expect(onCardSelect).toHaveBeenCalledTimes(1)
+    expect(onCardSelect).toHaveBeenCalledWith("Create an empty survey.")
+  })
+
+  it("calls onClick (not onCardSelect) when an action card is clicked", async () => {
+    const onCardSelect = vi.fn()
+    const onClick = vi.fn()
+    const cards: F0AiChatWelcomeCard[] = [
+      {
+        icon: Marketplace,
+        title: "Templates",
+        message: "ignored when onClick is present",
+        onClick,
+      },
+    ]
+
+    render(<WelcomeScreenCardsRow cards={cards} onCardSelect={onCardSelect} />)
+    await clickCard("Templates")
+
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(onCardSelect).not.toHaveBeenCalled()
+  })
+})
diff --git a/packages/react/src/sds/ai/F0AiChatTextArea/components/WelcomeScreenCardsRow.tsx b/packages/react/src/sds/ai/F0AiChatTextArea/components/WelcomeScreenCardsRow.tsx
new file mode 100644
index 0000000000..5cc9e34eea
--- /dev/null
+++ b/packages/react/src/sds/ai/F0AiChatTextArea/components/WelcomeScreenCardsRow.tsx
@@ -0,0 +1,45 @@
+import { F0CardHorizontal } from "@/experimental/F0CardHorizontal"
+
+import type { F0AiChatWelcomeCard } from "../../F0AiChat/types"
+
+export type WelcomeScreenCardsRowProps = {
+  cards: F0AiChatWelcomeCard[]
+  /**
+   * Fired with a prompt card's `message` when it's clicked. Action cards (with
+   * their own `onClick`) bypass this — `onClick` takes precedence.
+   */
+  onCardSelect?: (message: string) => void
+}
+
+/**
+ * Grid of action/prompt cards shown below the composer on the fullscreen
+ * welcome screen, rendered with `F0CardHorizontal`. Prompt cards (with a
+ * `message`) call `onCardSelect`; action cards run their own `onClick`, which
+ * takes precedence when both are present.
+ */
+export const WelcomeScreenCardsRow = ({
+  cards,
+  onCardSelect,
+}: WelcomeScreenCardsRowProps) => {
+  if (cards.length === 0) return null
+
+  return (
+    <div className="grid w-full grid-cols-2 gap-3">
+      {cards.map((card) => (
+        <F0CardHorizontal
+          key={card.title}
+          avatar={{ type: "icon", icon: card.icon }}
+          title={card.title}
+          description={card.description}
+          onClick={() => {
+            if (card.onClick) {
+              card.onClick()
+            } else if (card.message) {
+              onCardSelect?.(card.message)
+            }
+          }}
+        />
+      ))}
+    </div>
+  )
+}
diff --git a/packages/react/src/sds/ai/F0AiChatTextArea/components/WelcomeScreenSuggestionsRow.tsx b/packages/react/src/sds/ai/F0AiChatTextArea/components/WelcomeScreenSuggestionsRow.tsx
index 46f867b8cb..e495464965 100644
--- a/packages/react/src/sds/ai/F0AiChatTextArea/components/WelcomeScreenSuggestionsRow.tsx
+++ b/packages/react/src/sds/ai/F0AiChatTextArea/components/WelcomeScreenSuggestionsRow.tsx
@@ -45,9 +45,10 @@ export type WelcomeScreenSuggestionsRowProps = {
    */
   onItemHover?: (item: WelcomeScreenSuggestionItem | null) => void
   /**
-   * Side the popover opens towards. Defaults to "top" (sidepanel, row sits
-   * above the textarea). Fullscreen passes "bottom" so the popover opens into
-   * the empty space below the textarea instead of covering it.
+   * Side the popover opens towards. Defaults to "top" — the row sits above the
+   * textarea, so the popover opens upward into the empty space rather than
+   * covering the composer. "bottom" remains available for layouts that place
+   * the row below the textarea.
    */
   side?: "top" | "bottom"
 }
diff --git a/packages/react/src/sds/ai/F0AiChatTextArea/types.ts b/packages/react/src/sds/ai/F0AiChatTextArea/types.ts
index f6e103638a..32a6e9e6e5 100644
--- a/packages/react/src/sds/ai/F0AiChatTextArea/types.ts
+++ b/packages/react/src/sds/ai/F0AiChatTextArea/types.ts
@@ -9,6 +9,7 @@ import type {
   PersonProfile,
   TranscribeFn,
   UploadedFile,
+  F0AiChatWelcomeCard,
   WelcomeScreenSuggestion,
   WelcomeScreenSuggestionItem,
 } from "../F0AiChat/types"
@@ -135,11 +136,23 @@ export type F0AiChatTextAreaProps = {
     group: WelcomeScreenSuggestion
   ) => void
 
+  /**
+   * Action/prompt cards rendered as a grid below the composer on the
+   * fullscreen welcome screen. Prompt cards (with a `message`) call
+   * `onCardSelect`; action cards (with an `onClick`) run their own handler.
+   */
+  welcomeScreenCards?: F0AiChatWelcomeCard[]
+  /**
+   * Called with a prompt card's `message` when it's clicked. Wire this to the
+   * chat's send. Action cards bypass it via their own `onClick`.
+   */
+  onCardSelect?: (message: string) => void
+
   /**
    * When true on the welcome screen, the composer adopts the fullscreen
    * layout: the input slot grows to claim the bottom half (so the textarea
-   * rises toward the vertical center), and the welcome suggestions render
-   * below the textarea with their popover opening downward (instead of above).
+   * rises toward the vertical center) and the welcome cards render below it.
+   * The welcome suggestions row sits above the composer in both layouts.
    */
   fullscreen?: boolean
 }

From c71b2d5ec642f2a4376bf2484c68605f1886fa17 Mon Sep 17 00:00:00 2001
From: Marcos Medina <marcos.medina@factorial.co>
Date: Mon, 22 Jun 2026 17:42:19 +0200
Subject: [PATCH 2/2] refactor(ai): use type-only imports in F0AiChat state
 provider

Mark F0AiChatWelcomeCard / WelcomeScreenSuggestion (and the internal-types
import) as type-only so they're consistent with their sibling type imports.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/react/src/sds/ai/F0AiChat/internal-types.ts        | 4 ++--
 .../src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx   | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/react/src/sds/ai/F0AiChat/internal-types.ts b/packages/react/src/sds/ai/F0AiChat/internal-types.ts
index 1b55b8b264..cff1365131 100644
--- a/packages/react/src/sds/ai/F0AiChat/internal-types.ts
+++ b/packages/react/src/sds/ai/F0AiChat/internal-types.ts
@@ -17,8 +17,8 @@ import {
   type PendingQuote,
   type TranscribeFn,
   type VisualizationMode,
-  F0AiChatWelcomeCard,
-  WelcomeScreenSuggestion,
+  type F0AiChatWelcomeCard,
+  type WelcomeScreenSuggestion,
 } from "./types"
 
 /**
diff --git a/packages/react/src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx b/packages/react/src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx
index 296a97948e..da0d8c6d29 100644
--- a/packages/react/src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx
+++ b/packages/react/src/sds/ai/F0AiChat/providers/AiChatStateProvider.tsx
@@ -15,15 +15,15 @@ import {
 
 import { useI18n } from "@/lib/providers/i18n"
 
-import { AiChatProviderReturnValue, AiChatState } from "../internal-types"
+import type { AiChatProviderReturnValue, AiChatState } from "../internal-types"
 import {
   type AiChatMode,
   type CanvasContent,
   type PendingContext,
   type PendingQuote,
   type VisualizationMode,
-  F0AiChatWelcomeCard,
-  WelcomeScreenSuggestion,
+  type F0AiChatWelcomeCard,
+  type WelcomeScreenSuggestion,
 } from "../types"
 import { DEFAULT_CHAT_WIDTH } from "../utils/constants"