From 45779a980eff848a480a668a8b28a83b5bc25d8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Mon, 25 Aug 2025 09:36:33 +0200
Subject: [PATCH 01/11] Improve it for all

---
 .../gitbook/src/components/AIChat/AIChat.tsx  | 48 ++++++----
 .../Embeddable/EmbeddableAIChat.tsx           | 25 ++++-
 .../Embeddable/EmbeddableDocsPage.tsx         | 42 +++++++--
 .../components/Embeddable/EmbeddableFrame.tsx | 94 +++++++++++++------
 .../Embeddable/EmbeddableIframeAPI.tsx        | 10 ++
 .../Embeddable/EmbeddableRootLayout.tsx       | 32 +++----
 6 files changed, 174 insertions(+), 77 deletions(-)

diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
index b1b00c449b..2d7bfde8c3 100644
--- a/packages/gitbook/src/components/AIChat/AIChat.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -11,7 +11,15 @@ import {
     useAIChatController,
     useAIChatState,
 } from '../AI';
-import { EmbeddableFrame } from '../Embeddable/EmbeddableFrame';
+import {
+    EmbeddableFrame,
+    EmbeddableFrameBody,
+    EmbeddableFrameButtons,
+    EmbeddableFrameHeader,
+    EmbeddableFrameHeaderMain,
+    EmbeddableFrameSubtitle,
+    EmbeddableFrameTitle,
+} from '../Embeddable/EmbeddableFrame';
 import { useNow } from '../hooks';
 import { Button } from '../primitives';
 import { DropdownMenu, DropdownMenuItem } from '../primitives';
@@ -66,19 +74,22 @@ export function AIChat(props: { trademark: boolean }) {
             data-testid="ai-chat"
             className="ai-chat inset-y-0 right-0 z-40 mx-auto flex max-w-3xl animate-present scroll-mt-36 px-4 py-4 transition-all duration-300 sm:px-6 lg:fixed lg:w-80 lg:animate-enter-from-right lg:pr-4 lg:pl-0 xl:w-96"
         >
-            <EmbeddableFrame
-                className="relative circular-corners:rounded-3xl rounded-corners:rounded-md depth-subtle:shadow-lg shadow-tint ring-1 ring-tint-subtle"
-                icon={<AIChatDynamicIcon trademark={trademark} />}
-                title={getAIChatName(language, trademark)}
-                subtitle={
-                    chat.loading
-                        ? chat.messages[chat.messages.length - 1].content
-                            ? tString(language, 'ai_chat_working')
-                            : tString(language, 'ai_chat_thinking')
-                        : ''
-                }
-                buttons={
-                    <>
+            <EmbeddableFrame className="relative circular-corners:rounded-3xl rounded-corners:rounded-md depth-subtle:shadow-lg shadow-tint ring-1 ring-tint-subtle">
+                <EmbeddableFrameHeader>
+                    <AIChatDynamicIcon trademark={trademark} />
+                    <EmbeddableFrameHeaderMain>
+                        <EmbeddableFrameTitle>
+                            {getAIChatName(language, trademark)}
+                        </EmbeddableFrameTitle>
+                        <EmbeddableFrameSubtitle
+                            className={chat.loading ? 'h-3 opacity-11' : 'h-0 opacity-0'}
+                        >
+                            {chat.messages[chat.messages.length - 1].content
+                                ? tString(language, 'ai_chat_working')
+                                : tString(language, 'ai_chat_thinking')}
+                        </EmbeddableFrameSubtitle>
+                    </EmbeddableFrameHeaderMain>
+                    <EmbeddableFrameButtons>
                         {chat.messages.length > 0 ? (
                             <DropdownMenu
                                 button={
@@ -113,10 +124,11 @@ export function AIChat(props: { trademark: boolean }) {
                             variant="blank"
                             size="default"
                         />
-                    </>
-                }
-            >
-                <AIChatBody chatController={chatController} chat={chat} trademark={trademark} />
+                    </EmbeddableFrameButtons>
+                </EmbeddableFrameHeader>
+                <EmbeddableFrameBody>
+                    <AIChatBody chatController={chatController} chat={chat} trademark={trademark} />
+                </EmbeddableFrameBody>
             </EmbeddableFrame>
         </div>
     );
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
index f050a0b640..83b415b895 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
@@ -1,7 +1,15 @@
 'use client';
 
 import { useAIChatController, useAIChatState } from '@/components/AI';
-import { AIChatBody } from '@/components/AIChat';
+import { AIChatBody, AIChatDynamicIcon } from '@/components/AIChat';
+import {
+    EmbeddableFrame,
+    EmbeddableFrameBody,
+    EmbeddableFrameHeader,
+    EmbeddableFrameHeaderMain,
+    EmbeddableFrameTitle,
+} from './EmbeddableFrame';
+import { EmbeddableIframeButtons } from './EmbeddableIframeAPI';
 
 /**
  * Embeddable AI chat window in an iframe.
@@ -13,5 +21,18 @@ export function EmbeddableAIChat(props: {
     const chat = useAIChatState();
     const chatController = useAIChatController();
 
-    return <AIChatBody trademark={trademark} chatController={chatController} chat={chat} />;
+    return (
+        <EmbeddableFrame>
+            <EmbeddableFrameHeader>
+                <AIChatDynamicIcon trademark={trademark} />
+                <EmbeddableFrameHeaderMain>
+                    <EmbeddableFrameTitle>Chat with us</EmbeddableFrameTitle>
+                </EmbeddableFrameHeaderMain>
+                <EmbeddableIframeButtons />
+            </EmbeddableFrameHeader>
+            <EmbeddableFrameBody>
+                <AIChatBody trademark={trademark} chatController={chatController} chat={chat} />
+            </EmbeddableFrameBody>
+        </EmbeddableFrame>
+    );
 }
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
index c481363e02..fa9cec3cc5 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
@@ -3,6 +3,14 @@ import { type PagePathParams, getSitePageData } from '@/components/SitePage';
 import { PageBody } from '@/components/PageBody';
 import type { GitBookSiteContext } from '@/lib/context';
 import type { Metadata } from 'next';
+import { Button } from '../primitives';
+import {
+    EmbeddableFrame,
+    EmbeddableFrameBody,
+    EmbeddableFrameHeader,
+    EmbeddableFrameHeaderMain,
+} from './EmbeddableFrame';
+import { EmbeddableIframeButtons } from './EmbeddableIframeAPI';
 
 export const dynamic = 'force-static';
 
@@ -22,15 +30,31 @@ export async function EmbeddableDocsPage(props: EmbeddableDocsPageProps) {
     });
 
     return (
-        <div className="flex-1 overflow-auto p-6">
-            <PageBody
-                context={context}
-                page={page}
-                ancestors={ancestors}
-                document={document}
-                withPageFeedback={withPageFeedback}
-            />
-        </div>
+        <EmbeddableFrame>
+            <EmbeddableFrameHeader>
+                <EmbeddableFrameHeaderMain>
+                    <Button
+                        href={context.linker.toPathInSite('~gitbook/embed/assistant')}
+                        size="medium"
+                        variant="blank"
+                        icon="arrow-left"
+                        label="Back"
+                    />
+                </EmbeddableFrameHeaderMain>
+                <EmbeddableIframeButtons />
+            </EmbeddableFrameHeader>
+            <EmbeddableFrameBody>
+                <div className="flex-1 overflow-auto p-6">
+                    <PageBody
+                        context={context}
+                        page={page}
+                        ancestors={ancestors}
+                        document={document}
+                        withPageFeedback={withPageFeedback}
+                    />
+                </div>
+            </EmbeddableFrameBody>
+        </EmbeddableFrame>
     );
 }
 
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
index a558fb2ba7..9b233da756 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableFrame.tsx
@@ -1,27 +1,17 @@
 import { tcls } from '@/lib/tailwind';
 import React from 'react';
 
-export type EmbeddableFrameHeaderProps = {
-    icon: React.ReactNode;
-
-    title: string;
-    subtitle?: string;
-
-    buttons?: React.ReactNode;
+export type EmbeddableFrameProps = React.ComponentProps<'div'> & {
+    children: React.ReactNode;
 };
 
-export type EmbeddableFrameProps = EmbeddableFrameHeaderProps &
-    React.ComponentProps<'div'> & {
-        children: React.ReactNode;
-    };
-
 /**
  * Presentation component to display an embeddable frame.
  * It is used for the AI chat window in the docs, but also when embedded in another website.
  */
 export const EmbeddableFrame = React.forwardRef<HTMLDivElement, EmbeddableFrameProps>(
     (props, ref) => {
-        const { icon, title, subtitle, buttons, children, ...divProps } = props;
+        const { children, ...divProps } = props;
 
         return (
             <div
@@ -32,22 +22,70 @@ export const EmbeddableFrame = React.forwardRef<HTMLDivElement, EmbeddableFrameP
                 )}
                 ref={ref}
             >
-                <div className="flex select-none items-center gap-2 border-tint-subtle border-b bg-tint-subtle px-4 py-2 text-tint-strong">
-                    {icon}
-                    <div className="flex flex-col">
-                        <div className="font-bold">{title}</div>
-                        <div
-                            className={`text-tint text-xs leading-none transition-all duration-500 ${
-                                subtitle ? 'h-3 opacity-11' : 'h-0 opacity-0'
-                            }`}
-                        >
-                            {subtitle}
-                        </div>
-                    </div>
-                    <div className="ml-auto flex gap-2">{buttons}</div>
-                </div>
-                <div className="flex flex-1 flex-col overflow-hidden">{children}</div>
+                {children}
             </div>
         );
     }
 );
+
+export function EmbeddableFrameHeader(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return (
+        <div className="flex select-none items-center gap-2 border-tint-subtle border-b bg-tint-subtle px-4 py-2 text-tint-strong">
+            {children}
+        </div>
+    );
+}
+
+export function EmbeddableFrameHeaderMain(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return <div className="flex flex-1 flex-col">{children}</div>;
+}
+
+export function EmbeddableFrameBody(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return <div className="flex flex-1 flex-col overflow-hidden">{children}</div>;
+}
+
+export function EmbeddableFrameTitle(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return <div className="font-bold">{children}</div>;
+}
+
+export function EmbeddableFrameSubtitle(props: {
+    children: React.ReactNode;
+    className?: string;
+}) {
+    const { children, className } = props;
+
+    return (
+        <div
+            className={tcls(
+                'text-tint text-xs leading-none transition-all duration-500',
+                className
+            )}
+        >
+            {children}
+        </div>
+    );
+}
+
+export function EmbeddableFrameButtons(props: {
+    children: React.ReactNode;
+}) {
+    const { children } = props;
+
+    return <div className="ml-auto flex gap-2">{children}</div>;
+}
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index 85abe0cfbf..504427d17f 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -5,6 +5,8 @@ import { createChannel } from 'bidc';
 import React from 'react';
 
 import { useAIChatController } from '@/components/AI';
+import { Button } from '../primitives';
+import { EmbeddableFrameButtons } from './EmbeddableFrame';
 
 /**
  * Expose the API to communicate with the parent window.
@@ -42,3 +44,11 @@ export function EmbeddableIframeAPI() {
 
     return null;
 }
+
+export function EmbeddableIframeButtons() {
+    return (
+        <EmbeddableFrameButtons>
+            <Button size="medium" variant="blank" icon="close" label="Close" iconOnly />
+        </EmbeddableFrameButtons>
+    );
+}
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
index 9267e4e8ad..e46e3dede1 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
@@ -1,6 +1,4 @@
 import { AIChatProvider, AIContextProvider } from '@/components/AI';
-import { AIChatDynamicIcon } from '@/components/AIChat';
-import { EmbeddableFrame } from '@/components/Embeddable';
 import { CustomizationRootLayout } from '@/components/RootLayout';
 import {
     SiteLayoutClientContexts,
@@ -29,26 +27,20 @@ export async function EmbeddableRootLayout({
                 externalLinksTarget={context.customization.externalLinks.target}
                 contextId={context.contextId}
             >
-                <EmbeddableFrame
-                    icon={<AIChatDynamicIcon trademark={context.customization.trademark.enabled} />}
-                    title="Test"
-                    className="fixed inset-0"
+                <AIContextProvider
+                    aiMode={CustomizationAIMode.Assistant}
+                    trademark={context.customization.trademark.enabled}
                 >
-                    <AIContextProvider
-                        aiMode={CustomizationAIMode.Assistant}
-                        trademark={context.customization.trademark.enabled}
+                    <AIChatProvider
+                        renderMessageOptions={{
+                            withLinkPreviews: false,
+                            asEmbeddable: true,
+                        }}
                     >
-                        <AIChatProvider
-                            renderMessageOptions={{
-                                withLinkPreviews: false,
-                                asEmbeddable: true,
-                            }}
-                        >
-                            {children}
-                            <EmbeddableIframeAPI />
-                        </AIChatProvider>
-                    </AIContextProvider>
-                </EmbeddableFrame>
+                        <div className="fixed inset-0 flex flex-col">{children}</div>
+                        <EmbeddableIframeAPI />
+                    </AIChatProvider>
+                </AIContextProvider>
             </SiteLayoutClientContexts>
         </CustomizationRootLayout>
     );

From c5b6a79e1ec7cb78e7d0a0617e59097d54fef41c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Mon, 25 Aug 2025 09:38:26 +0200
Subject: [PATCH 02/11] Improve button size

---
 .../gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx    | 2 +-
 .../gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx   | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
index fa9cec3cc5..55657b25fe 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
@@ -35,7 +35,7 @@ export async function EmbeddableDocsPage(props: EmbeddableDocsPageProps) {
                 <EmbeddableFrameHeaderMain>
                     <Button
                         href={context.linker.toPathInSite('~gitbook/embed/assistant')}
-                        size="medium"
+                        size="default"
                         variant="blank"
                         icon="arrow-left"
                         label="Back"
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index 504427d17f..d1bc71b01c 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -48,7 +48,7 @@ export function EmbeddableIframeAPI() {
 export function EmbeddableIframeButtons() {
     return (
         <EmbeddableFrameButtons>
-            <Button size="medium" variant="blank" icon="close" label="Close" iconOnly />
+            <Button size="default" variant="blank" icon="close" label="Close" iconOnly />
         </EmbeddableFrameButtons>
     );
 }

From e915c1c0fb4ca7cde7732562e00bd44811437b20 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Mon, 25 Aug 2025 11:56:33 +0200
Subject: [PATCH 03/11] Start state

---
 .../embed/src/client/createGitBookFrame.ts    | 23 +++++----
 packages/embed/src/client/protocol.ts         | 42 ++++++++++++-----
 packages/embed/src/standalone/index.ts        | 16 ++-----
 .../gitbook/src/components/AIChat/AIChat.tsx  | 29 +-----------
 .../components/AIChat/AIChatControlButton.tsx | 40 ++++++++++++++++
 .../gitbook/src/components/AIChat/index.ts    |  1 +
 .../Embeddable/EmbeddableAIChat.tsx           |  8 +++-
 .../Embeddable/EmbeddableDocsPage.tsx         |  5 +-
 .../Embeddable/EmbeddableIframeAPI.tsx        | 47 ++++++++++++++++---
 9 files changed, 143 insertions(+), 68 deletions(-)
 create mode 100644 packages/gitbook/src/components/AIChat/AIChatControlButton.tsx

diff --git a/packages/embed/src/client/createGitBookFrame.ts b/packages/embed/src/client/createGitBookFrame.ts
index 031b0c4359..0836059d7a 100644
--- a/packages/embed/src/client/createGitBookFrame.ts
+++ b/packages/embed/src/client/createGitBookFrame.ts
@@ -1,8 +1,7 @@
 import { createChannel } from 'bidc';
 import type {
     FrameToParentMessage,
-    GitBookPlaceholderSettings,
-    GitBookToolDefinition,
+    GitBookEmbeddableConfiguration,
     ParentToFrameMessage,
 } from './protocol';
 
@@ -22,11 +21,6 @@ export type GitBookFrameClient = {
      */
     postUserMessage: (message: string) => void;
 
-    /**
-     * Register a custom tool.
-     */
-    registerTool: (tool: GitBookToolDefinition) => void;
-
     /**
      * Clear the chat.
      */
@@ -35,7 +29,7 @@ export type GitBookFrameClient = {
     /**
      * Set the placeholder settings.
      */
-    setPlaceholder: (placeholder: GitBookPlaceholderSettings) => void;
+    configure: (settings: Partial<GitBookEmbeddableConfiguration>) => void;
 
     /**
      * Register an event listener.
@@ -67,6 +61,13 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
 
     const events = new Map<string, Array<(...args: any[]) => void>>();
 
+    const configuration: GitBookEmbeddableConfiguration = {
+        buttons: [],
+        welcomeMessage: '',
+        suggestions: [],
+        tools: [],
+    };
+
     return {
         navigateToPage: (pagePath) => {
             sendToFrame({ type: 'navigateToPage', pagePath });
@@ -75,9 +76,11 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
             sendToFrame({ type: 'navigateToAssistant' });
         },
         postUserMessage: (message) => sendToFrame({ type: 'postUserMessage', message }),
-        registerTool: (tool) => sendToFrame({ type: 'registerTool', tool }),
+        configure: (settings) => {
+            Object.assign(configuration, settings);
+            sendToFrame({ type: 'configure', settings: configuration });
+        },
         clearChat: () => sendToFrame({ type: 'clearChat' }),
-        setPlaceholder: (settings) => sendToFrame({ type: 'setPlaceholder', settings }),
         on: (event, listener) => {
             const listeners = events.get(event) || [];
             listeners.push(listener);
diff --git a/packages/embed/src/client/protocol.ts b/packages/embed/src/client/protocol.ts
index 1356768998..f19b400e37 100644
--- a/packages/embed/src/client/protocol.ts
+++ b/packages/embed/src/client/protocol.ts
@@ -21,18 +21,42 @@ export type GitBookToolDefinition = AIToolDefinition & {
 };
 
 /**
- * Placeholder settings.
+ * Custom button definition to be passed to the embeddable GitBook.
  */
-export type GitBookPlaceholderSettings = {
+export type GitBookEmbeddableButtonDefinition = {
     /**
-     * Welcome message to be displayed in the placeholder.
+     * Icon to be displayed in the button.
      */
-    welcomeMessage: string;
+    icon: IconName;
+
+    /**
+     * Label to be displayed in the button.
+     */
+    label: string;
+
+    /**
+     * Callback when the button is clicked.
+     */
+    onClick: () => void | Promise<void>;
+};
 
+/**
+ * Overall configuration for the layout of the embeddable GitBook.
+ */
+export type GitBookEmbeddableConfiguration = {
     /**
-     * Suggestions to be displayed in the placeholder.
+     * Buttons to be displayed in the header of the embeddable GitBook.
      */
+    buttons: GitBookEmbeddableButtonDefinition[];
+
+    /** Message to be displayed in the welcome page. */
+    welcomeMessage: string;
+
+    /** Suggestions of questions to be displayed in the welcome page. */
     suggestions: string[];
+
+    /** Tools to be provided to the assistant. */
+    tools: GitBookToolDefinition[];
 };
 
 /**
@@ -43,16 +67,12 @@ export type ParentToFrameMessage =
           type: 'postUserMessage';
           message: string;
       }
-    | {
-          type: 'registerTool';
-          tool: GitBookToolDefinition;
-      }
     | {
           type: 'clearChat';
       }
     | {
-          type: 'setPlaceholder';
-          settings: GitBookPlaceholderSettings;
+          type: 'configure';
+          settings: GitBookEmbeddableConfiguration;
       }
     | {
           type: 'navigateToPage';
diff --git a/packages/embed/src/standalone/index.ts b/packages/embed/src/standalone/index.ts
index a2543c8ba2..5d7929d60a 100644
--- a/packages/embed/src/standalone/index.ts
+++ b/packages/embed/src/standalone/index.ts
@@ -4,9 +4,8 @@ import {
     type CreateGitBookOptions,
     type GetFrameURLOptions,
     type GitBookClient,
+    type GitBookEmbeddableConfiguration,
     type GitBookFrameClient,
-    type GitBookPlaceholderSettings,
-    type GitBookToolDefinition,
     createGitBook,
 } from '../client';
 
@@ -29,12 +28,10 @@ type StandaloneCalls =
     | ['toggle']
     // Post a user message
     | ['postUserMessage', string]
-    // Register a tool
-    | ['registerTool', GitBookToolDefinition]
     // Clear the chat
     | ['clearChat']
-    // Configure the placeholder
-    | ['setPlaceholder', GitBookPlaceholderSettings]
+    // Configure the embed
+    | ['configure', Partial<GitBookEmbeddableConfiguration>]
     // Navigate to a page
     | ['navigateToPage', string]
     // Navigate to the assistant
@@ -132,15 +129,12 @@ const GitBook = (...args: StandaloneCalls) => {
         case 'postUserMessage':
             getIframe().frame.postUserMessage(args[1]);
             break;
-        case 'registerTool':
-            getIframe().frame.registerTool(args[1]);
+        case 'configure':
+            getIframe().frame.configure(args[1]);
             break;
         case 'clearChat':
             getIframe().frame.clearChat();
             break;
-        case 'setPlaceholder':
-            getIframe().frame.setPlaceholder(args[1]);
-            break;
         case 'navigateToPage':
             getIframe().frame.navigateToPage(args[1]);
             break;
diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
index 2d7bfde8c3..83d151ca50 100644
--- a/packages/gitbook/src/components/AIChat/AIChat.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -22,7 +22,7 @@ import {
 } from '../Embeddable/EmbeddableFrame';
 import { useNow } from '../hooks';
 import { Button } from '../primitives';
-import { DropdownMenu, DropdownMenuItem } from '../primitives';
+import { AIChatControlButton } from './AIChatControlButton';
 import { AIChatIcon } from './AIChatIcon';
 import { AIChatInput } from './AIChatInput';
 import { AIChatMessages } from './AIChatMessages';
@@ -90,32 +90,7 @@ export function AIChat(props: { trademark: boolean }) {
                         </EmbeddableFrameSubtitle>
                     </EmbeddableFrameHeaderMain>
                     <EmbeddableFrameButtons>
-                        {chat.messages.length > 0 ? (
-                            <DropdownMenu
-                                button={
-                                    <Button
-                                        onClick={() => {}}
-                                        iconOnly
-                                        icon="ellipsis"
-                                        label={tString(language, 'actions')}
-                                        variant="blank"
-                                        size="default"
-                                    />
-                                }
-                            >
-                                <DropdownMenuItem
-                                    onClick={() => {
-                                        chatController.clear();
-                                    }}
-                                >
-                                    <Icon
-                                        icon="broom-wide"
-                                        className="size-3 shrink-0 text-tint-subtle"
-                                    />
-                                    {t(language, 'ai_chat_clear_conversation')}
-                                </DropdownMenuItem>
-                            </DropdownMenu>
-                        ) : null}
+                        <AIChatControlButton />
                         <Button
                             onClick={() => chatController.close()}
                             iconOnly
diff --git a/packages/gitbook/src/components/AIChat/AIChatControlButton.tsx b/packages/gitbook/src/components/AIChat/AIChatControlButton.tsx
new file mode 100644
index 0000000000..f909b62ab9
--- /dev/null
+++ b/packages/gitbook/src/components/AIChat/AIChatControlButton.tsx
@@ -0,0 +1,40 @@
+'use client';
+
+import { useLanguage } from '@/intl/client';
+import { t, tString } from '@/intl/translate';
+import { Icon } from '@gitbook/icons';
+import { useAIChatController, useAIChatState } from '../AI';
+import { Button, DropdownMenu, DropdownMenuItem } from '../primitives';
+
+/**
+ * Button to control the chat (clear, etc.)
+ */
+export function AIChatControlButton() {
+    const language = useLanguage();
+    const chat = useAIChatState();
+    const chatController = useAIChatController();
+
+    return chat.messages.length > 0 ? (
+        <DropdownMenu
+            button={
+                <Button
+                    onClick={() => {}}
+                    iconOnly
+                    icon="ellipsis"
+                    label={tString(language, 'actions')}
+                    variant="blank"
+                    size="default"
+                />
+            }
+        >
+            <DropdownMenuItem
+                onClick={() => {
+                    chatController.clear();
+                }}
+            >
+                <Icon icon="broom-wide" className="size-3 shrink-0 text-tint-subtle" />
+                {t(language, 'ai_chat_clear_conversation')}
+            </DropdownMenuItem>
+        </DropdownMenu>
+    ) : null;
+}
diff --git a/packages/gitbook/src/components/AIChat/index.ts b/packages/gitbook/src/components/AIChat/index.ts
index 0c0dbd0933..12eaa899e5 100644
--- a/packages/gitbook/src/components/AIChat/index.ts
+++ b/packages/gitbook/src/components/AIChat/index.ts
@@ -2,3 +2,4 @@ export * from './AIChat';
 export * from './AIChatButton';
 export * from './AIChatIcon';
 export * from './AIResponseFeedback';
+export * from './AIChatControlButton';
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
index 83b415b895..e072cbcb6d 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
@@ -1,10 +1,11 @@
 'use client';
 
 import { useAIChatController, useAIChatState } from '@/components/AI';
-import { AIChatBody, AIChatDynamicIcon } from '@/components/AIChat';
+import { AIChatBody, AIChatControlButton, AIChatDynamicIcon } from '@/components/AIChat';
 import {
     EmbeddableFrame,
     EmbeddableFrameBody,
+    EmbeddableFrameButtons,
     EmbeddableFrameHeader,
     EmbeddableFrameHeaderMain,
     EmbeddableFrameTitle,
@@ -28,7 +29,10 @@ export function EmbeddableAIChat(props: {
                 <EmbeddableFrameHeaderMain>
                     <EmbeddableFrameTitle>Chat with us</EmbeddableFrameTitle>
                 </EmbeddableFrameHeaderMain>
-                <EmbeddableIframeButtons />
+                <EmbeddableFrameButtons>
+                    <AIChatControlButton />
+                    <EmbeddableIframeButtons />
+                </EmbeddableFrameButtons>
             </EmbeddableFrameHeader>
             <EmbeddableFrameBody>
                 <AIChatBody trademark={trademark} chatController={chatController} chat={chat} />
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
index 55657b25fe..685190629d 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableDocsPage.tsx
@@ -7,6 +7,7 @@ import { Button } from '../primitives';
 import {
     EmbeddableFrame,
     EmbeddableFrameBody,
+    EmbeddableFrameButtons,
     EmbeddableFrameHeader,
     EmbeddableFrameHeaderMain,
 } from './EmbeddableFrame';
@@ -41,7 +42,9 @@ export async function EmbeddableDocsPage(props: EmbeddableDocsPageProps) {
                         label="Back"
                     />
                 </EmbeddableFrameHeaderMain>
-                <EmbeddableIframeButtons />
+                <EmbeddableFrameButtons>
+                    <EmbeddableIframeButtons />
+                </EmbeddableFrameButtons>
             </EmbeddableFrameHeader>
             <EmbeddableFrameBody>
                 <div className="flex-1 overflow-auto p-6">
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index d1bc71b01c..829f9354ef 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -1,12 +1,19 @@
 'use client';
 
-import type { ParentToFrameMessage } from '@gitbook/embed';
+import type { GitBookEmbeddableConfiguration, ParentToFrameMessage } from '@gitbook/embed';
 import { createChannel } from 'bidc';
 import React from 'react';
 
 import { useAIChatController } from '@/components/AI';
+import { createStore, useStore } from 'zustand';
 import { Button } from '../primitives';
-import { EmbeddableFrameButtons } from './EmbeddableFrame';
+
+const embeddableConfiguration = createStore<GitBookEmbeddableConfiguration>(() => ({
+    buttons: [],
+    welcomeMessage: '',
+    suggestions: [],
+    tools: [],
+}));
 
 /**
  * Expose the API to communicate with the parent window.
@@ -35,7 +42,18 @@ export function EmbeddableIframeAPI() {
                     });
                     break;
                 }
-                // TODO: Handle other messages
+                case 'configure': {
+                    embeddableConfiguration.setState(message.settings);
+                    break;
+                }
+                case 'navigateToPage': {
+                    throw new Error('Not implemented');
+                    break;
+                }
+                case 'navigateToAssistant': {
+                    throw new Error('Not implemented');
+                    break;
+                }
             }
         });
 
@@ -45,10 +63,27 @@ export function EmbeddableIframeAPI() {
     return null;
 }
 
+/**
+ * Display the buttons defined by the parent window.
+ */
 export function EmbeddableIframeButtons() {
+    const buttons = useStore(embeddableConfiguration, (state) => state.buttons);
+
     return (
-        <EmbeddableFrameButtons>
-            <Button size="default" variant="blank" icon="close" label="Close" iconOnly />
-        </EmbeddableFrameButtons>
+        <>
+            {buttons.map((button) => (
+                <Button
+                    key={button.label}
+                    size="default"
+                    variant="blank"
+                    icon={button.icon}
+                    label={button.label}
+                    iconOnly
+                    onClick={() => {
+                        button.onClick();
+                    }}
+                />
+            ))}
+        </>
     );
 }

From e7d671fd7b43ec0d052aa1bec45406cd95e1cef8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 08:16:06 +0200
Subject: [PATCH 04/11] Improve

---
 .../embed/src/client/createGitBookFrame.ts    |  2 ++
 .../gitbook/src/components/AIChat/AIChat.tsx  |  9 ++++++--
 .../AIChat/AIChatSuggestedQuestions.tsx       | 22 +++++++++++--------
 .../Embeddable/EmbeddableAIChat.tsx           | 10 +++++++--
 .../Embeddable/EmbeddableIframeAPI.tsx        | 20 +++++++++++++++--
 5 files changed, 48 insertions(+), 15 deletions(-)

diff --git a/packages/embed/src/client/createGitBookFrame.ts b/packages/embed/src/client/createGitBookFrame.ts
index 0836059d7a..baaabf647c 100644
--- a/packages/embed/src/client/createGitBookFrame.ts
+++ b/packages/embed/src/client/createGitBookFrame.ts
@@ -47,6 +47,7 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
     const channel = createChannel(iframe.contentWindow);
 
     channel.receive((message: FrameToParentMessage) => {
+        console.log('[gitbook:embed] received message', message);
         if (message.type === 'close') {
             const listeners = events.get('close') || [];
             if (listeners) {
@@ -56,6 +57,7 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
     });
 
     const sendToFrame = (message: ParentToFrameMessage) => {
+        console.log('[gitbook:embed] send message', message);
         channel.send(message);
     };
 
diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
index 83d151ca50..0c52ee68ef 100644
--- a/packages/gitbook/src/components/AIChat/AIChat.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -146,8 +146,10 @@ export function AIChatBody(props: {
     chatController: AIChatController;
     chat: AIChatState;
     trademark: boolean;
+    welcomeMessage?: string;
+    suggestions?: string[];
 }) {
-    const { chatController, chat, trademark } = props;
+    const { chatController, chat, trademark, welcomeMessage, suggestions } = props;
 
     const [input, setInput] = React.useState('');
 
@@ -233,7 +235,10 @@ export function AIChatBody(props: {
                             </p>
                         </div>
                         {!chat.error ? (
-                            <AIChatSuggestedQuestions chatController={chatController} />
+                            <AIChatSuggestedQuestions
+                                chatController={chatController}
+                                suggestions={suggestions}
+                            />
                         ) : null}
                     </div>
                 ) : (
diff --git a/packages/gitbook/src/components/AIChat/AIChatSuggestedQuestions.tsx b/packages/gitbook/src/components/AIChat/AIChatSuggestedQuestions.tsx
index 5f0089ebdf..f3951698eb 100644
--- a/packages/gitbook/src/components/AIChat/AIChatSuggestedQuestions.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChatSuggestedQuestions.tsx
@@ -2,19 +2,23 @@ import { tString, useLanguage } from '@/intl/client';
 import type { AIChatController } from '../AI';
 import { Button } from '../primitives';
 
-export default function AIChatSuggestedQuestions(props: { chatController: AIChatController }) {
-    const { chatController } = props;
+export default function AIChatSuggestedQuestions(props: {
+    chatController: AIChatController;
+    suggestions?: string[];
+}) {
     const language = useLanguage();
-
-    const DEFAULT_SUGGESTED_QUESTIONS = [
-        tString(language, 'ai_chat_suggested_questions_about_this_page'),
-        tString(language, 'ai_chat_suggested_questions_read_next'),
-        tString(language, 'ai_chat_suggested_questions_example'),
-    ];
+    const {
+        chatController,
+        suggestions = [
+            tString(language, 'ai_chat_suggested_questions_about_this_page'),
+            tString(language, 'ai_chat_suggested_questions_read_next'),
+            tString(language, 'ai_chat_suggested_questions_example'),
+        ],
+    } = props;
 
     return (
         <div className="flex flex-col items-center gap-2">
-            {DEFAULT_SUGGESTED_QUESTIONS.map((question, index) => (
+            {suggestions.map((question, index) => (
                 <Button
                     key={question}
                     variant="secondary"
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
index e072cbcb6d..9c099f46f3 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
@@ -10,7 +10,7 @@ import {
     EmbeddableFrameHeaderMain,
     EmbeddableFrameTitle,
 } from './EmbeddableFrame';
-import { EmbeddableIframeButtons } from './EmbeddableIframeAPI';
+import { EmbeddableIframeButtons, useEmbeddableConfiguration } from './EmbeddableIframeAPI';
 
 /**
  * Embeddable AI chat window in an iframe.
@@ -21,6 +21,7 @@ export function EmbeddableAIChat(props: {
     const { trademark } = props;
     const chat = useAIChatState();
     const chatController = useAIChatController();
+    const configuration = useEmbeddableConfiguration();
 
     return (
         <EmbeddableFrame>
@@ -35,7 +36,12 @@ export function EmbeddableAIChat(props: {
                 </EmbeddableFrameButtons>
             </EmbeddableFrameHeader>
             <EmbeddableFrameBody>
-                <AIChatBody trademark={trademark} chatController={chatController} chat={chat} />
+                <AIChatBody
+                    trademark={trademark}
+                    chatController={chatController}
+                    chat={chat}
+                    suggestions={configuration.suggestions}
+                />
             </EmbeddableFrameBody>
         </EmbeddableFrame>
     );
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index 829f9354ef..aba9db3aa6 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -26,11 +26,14 @@ export function EmbeddableIframeAPI() {
             return;
         }
 
+        console.log('[gitbook] create channel with parent window');
         const channel = createChannel();
 
         channel.receive((payload) => {
             const message = payload as ParentToFrameMessage;
 
+            console.log('[gitbook] received message', message);
+
             switch (message.type) {
                 case 'clearChat': {
                     chatController.clear();
@@ -57,17 +60,30 @@ export function EmbeddableIframeAPI() {
             }
         });
 
-        return channel.cleanup();
+        return () => {
+            console.log('[gitbook] cleanup');
+            channel.cleanup();
+        };
     }, [chatController]);
 
     return null;
 }
 
+/**
+ * Hook to get the configuration from the parent window.
+ */
+export function useEmbeddableConfiguration<T = GitBookEmbeddableConfiguration>(
+    // @ts-expect-error - This is a workaround to allow the function to be optional.
+    fn: (state: GitBookEmbeddableConfiguration) => T = (state) => state
+) {
+    return useStore(embeddableConfiguration, fn);
+}
+
 /**
  * Display the buttons defined by the parent window.
  */
 export function EmbeddableIframeButtons() {
-    const buttons = useStore(embeddableConfiguration, (state) => state.buttons);
+    const buttons = useEmbeddableConfiguration((state) => state.buttons);
 
     return (
         <>

From 9d4b4c47c065f1b550663bf36bfbd0d97b345ba7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 09:04:54 +0200
Subject: [PATCH 05/11] Always include a close button

---
 packages/embed/src/standalone/index.ts | 28 +++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/packages/embed/src/standalone/index.ts b/packages/embed/src/standalone/index.ts
index 5d7929d60a..e9c7135b54 100644
--- a/packages/embed/src/standalone/index.ts
+++ b/packages/embed/src/standalone/index.ts
@@ -62,6 +62,12 @@ let widgetIframe: HTMLIFrameElement | undefined;
 let _client: GitBookClient | undefined;
 let _frame: GitBookFrameClient | undefined;
 let frameOptions: GetFrameURLOptions | undefined;
+let frameConfiguration: GitBookEmbeddableConfiguration = {
+    buttons: [],
+    welcomeMessage: '',
+    suggestions: [],
+    tools: [],
+};
 
 function getClient() {
     if (!_client) {
@@ -130,7 +136,25 @@ const GitBook = (...args: StandaloneCalls) => {
             getIframe().frame.postUserMessage(args[1]);
             break;
         case 'configure':
-            getIframe().frame.configure(args[1]);
+            frameConfiguration = {
+                ...frameConfiguration,
+                ...args[1],
+            };
+            getIframe().frame.configure({
+                ...frameConfiguration,
+                buttons: [
+                    ...frameConfiguration.buttons,
+
+                    // Always include a close button
+                    {
+                        icon: 'close',
+                        label: 'Close',
+                        onClick: () => {
+                            GitBook('close');
+                        },
+                    },
+                ],
+            });
             break;
         case 'clearChat':
             getIframe().frame.clearChat();
@@ -150,3 +174,5 @@ const precalls = (window.GitBook as GitBookStandalone | undefined)?.q ?? [];
 // @ts-expect-error - GitBook is not defined in the global scope
 window.GitBook = GitBook;
 precalls.forEach((call) => GitBook(...call));
+
+GitBook('configure', {});

From 2088e0e8be21975e549113073c69196707c82e39 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 09:10:44 +0200
Subject: [PATCH 06/11] Show subtitle

---
 .../gitbook/src/components/AIChat/AIChat.tsx  | 30 +++++++++++++------
 .../Embeddable/EmbeddableAIChat.tsx           | 10 +++++--
 2 files changed, 29 insertions(+), 11 deletions(-)

diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
index 0c52ee68ef..3192636f6c 100644
--- a/packages/gitbook/src/components/AIChat/AIChat.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -81,13 +81,7 @@ export function AIChat(props: { trademark: boolean }) {
                         <EmbeddableFrameTitle>
                             {getAIChatName(language, trademark)}
                         </EmbeddableFrameTitle>
-                        <EmbeddableFrameSubtitle
-                            className={chat.loading ? 'h-3 opacity-11' : 'h-0 opacity-0'}
-                        >
-                            {chat.messages[chat.messages.length - 1].content
-                                ? tString(language, 'ai_chat_working')
-                                : tString(language, 'ai_chat_thinking')}
-                        </EmbeddableFrameSubtitle>
+                        <AIChatSubtitle chat={chat} />
                     </EmbeddableFrameHeaderMain>
                     <EmbeddableFrameButtons>
                         <AIChatControlButton />
@@ -126,7 +120,7 @@ export function AIChatDynamicIcon(props: {
                 chat.error
                     ? 'error'
                     : chat.loading
-                      ? chat.messages[chat.messages.length - 1].content
+                      ? chat.messages[chat.messages.length - 1]?.content
                           ? 'working'
                           : 'thinking'
                       : chat.messages.length > 0
@@ -139,6 +133,24 @@ export function AIChatDynamicIcon(props: {
     );
 }
 
+/**
+ * Subtitle of the AI chat window.
+ */
+export function AIChatSubtitle(props: {
+    chat: AIChatState;
+}) {
+    const { chat } = props;
+    const language = useLanguage();
+
+    return (
+        <EmbeddableFrameSubtitle className={chat.loading ? 'h-3 opacity-11' : 'h-0 opacity-0'}>
+            {chat.messages[chat.messages.length - 1]?.content
+                ? tString(language, 'ai_chat_working')
+                : tString(language, 'ai_chat_thinking')}
+        </EmbeddableFrameSubtitle>
+    );
+}
+
 /**
  * Body of the AI chat window.
  */
@@ -149,7 +161,7 @@ export function AIChatBody(props: {
     welcomeMessage?: string;
     suggestions?: string[];
 }) {
-    const { chatController, chat, trademark, welcomeMessage, suggestions } = props;
+    const { chatController, chat, trademark, suggestions } = props;
 
     const [input, setInput] = React.useState('');
 
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
index 9c099f46f3..ad30975466 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
@@ -1,7 +1,12 @@
 'use client';
 
 import { useAIChatController, useAIChatState } from '@/components/AI';
-import { AIChatBody, AIChatControlButton, AIChatDynamicIcon } from '@/components/AIChat';
+import {
+    AIChatBody,
+    AIChatControlButton,
+    AIChatDynamicIcon,
+    AIChatSubtitle,
+} from '@/components/AIChat';
 import {
     EmbeddableFrame,
     EmbeddableFrameBody,
@@ -28,7 +33,8 @@ export function EmbeddableAIChat(props: {
             <EmbeddableFrameHeader>
                 <AIChatDynamicIcon trademark={trademark} />
                 <EmbeddableFrameHeaderMain>
-                    <EmbeddableFrameTitle>Chat with us</EmbeddableFrameTitle>
+                    <EmbeddableFrameTitle>GitBook Assistant</EmbeddableFrameTitle>
+                    <AIChatSubtitle chat={chat} />
                 </EmbeddableFrameHeaderMain>
                 <EmbeddableFrameButtons>
                     <AIChatControlButton />

From faa3a4c3b80a5a4cbd10db9eb6f9c994af755254 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 09:20:44 +0200
Subject: [PATCH 07/11] Improve react components

---
 .../embed/src/react/GitBookAssistantFrame.tsx | 38 --------------
 packages/embed/src/react/GitBookFrame.tsx     | 51 +++++++++++++++++++
 packages/embed/src/react/index.ts             |  1 +
 3 files changed, 52 insertions(+), 38 deletions(-)
 delete mode 100644 packages/embed/src/react/GitBookAssistantFrame.tsx
 create mode 100644 packages/embed/src/react/GitBookFrame.tsx

diff --git a/packages/embed/src/react/GitBookAssistantFrame.tsx b/packages/embed/src/react/GitBookAssistantFrame.tsx
deleted file mode 100644
index a6e4980f07..0000000000
--- a/packages/embed/src/react/GitBookAssistantFrame.tsx
+++ /dev/null
@@ -1,38 +0,0 @@
-import React from 'react';
-import type { GetFrameURLOptions, GitBookFrameClient } from '../client';
-import { useGitBook } from './GitBookProvider';
-
-export type GitBookAssistantFrameProps = {
-    title?: string;
-    className?: string;
-} & GetFrameURLOptions;
-
-/**
- * Render a frame with the GitBook Assistant in it.
- */
-export function GitBookAssistantFrame(props: GitBookAssistantFrameProps) {
-    const { title, className, ...frameOptions } = props;
-
-    const frameRef = React.useRef<HTMLIFrameElement>(null);
-    const gitbookFrameRef = React.useRef<GitBookFrameClient | null>(null);
-    const gitbook = useGitBook();
-    const frameURL = gitbook.getFrameURL(frameOptions);
-
-    React.useEffect(() => {
-        if (frameRef.current) {
-            gitbookFrameRef.current = gitbook.createFrame(frameRef.current);
-        }
-    }, [gitbook]);
-
-    return (
-        <div className={className}>
-            <iframe
-                title={title ?? 'GitBook Assistant'}
-                ref={frameRef}
-                src={frameURL}
-                width="100%"
-                height="100%"
-            />
-        </div>
-    );
-}
diff --git a/packages/embed/src/react/GitBookFrame.tsx b/packages/embed/src/react/GitBookFrame.tsx
new file mode 100644
index 0000000000..010d87dd47
--- /dev/null
+++ b/packages/embed/src/react/GitBookFrame.tsx
@@ -0,0 +1,51 @@
+import React from 'react';
+import type {
+    GetFrameURLOptions,
+    GitBookEmbeddableConfiguration,
+    GitBookFrameClient,
+} from '../client';
+import { useGitBook } from './GitBookProvider';
+
+export type GitBookFrameProps = {
+    className?: string;
+} & GetFrameURLOptions &
+    GitBookEmbeddableConfiguration;
+
+/**
+ * Render a frame with the GitBook Assistant in it.
+ */
+export function GitBookFrame(props: GitBookFrameProps) {
+    const { className, visitor, buttons, welcomeMessage, suggestions, tools } = props;
+
+    const frameRef = React.useRef<HTMLIFrameElement>(null);
+    const gitbook = useGitBook();
+    const [gitbookFrame, setGitbookFrame] = React.useState<GitBookFrameClient | null>(null);
+
+    const frameURL = React.useMemo(() => gitbook.getFrameURL({ visitor }), [gitbook, visitor]);
+
+    React.useEffect(() => {
+        if (frameRef.current) {
+            setGitbookFrame(gitbook.createFrame(frameRef.current));
+        }
+    }, [gitbook]);
+
+    React.useEffect(() => {
+        gitbookFrame?.configure({
+            buttons,
+            welcomeMessage,
+            suggestions,
+            tools,
+        });
+    }, [gitbookFrame, buttons, welcomeMessage, suggestions, tools]);
+
+    return (
+        <iframe
+            title="GitBook"
+            ref={frameRef}
+            src={frameURL}
+            width="100%"
+            height="100%"
+            className={className}
+        />
+    );
+}
diff --git a/packages/embed/src/react/index.ts b/packages/embed/src/react/index.ts
index 7b0d5b19cd..ff70bb4618 100644
--- a/packages/embed/src/react/index.ts
+++ b/packages/embed/src/react/index.ts
@@ -1 +1,2 @@
 export * from './GitBookProvider';
+export * from './GitBookFrame';

From d9268bfc302e300dca7bf3c2028f85527dda7ddb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 10:11:16 +0200
Subject: [PATCH 08/11] Basic navigation

---
 .../components/Embeddable/EmbeddableIframeAPI.tsx    | 12 +++++++++---
 .../components/Embeddable/EmbeddableRootLayout.tsx   |  4 +++-
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index aba9db3aa6..b166315ae0 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -5,6 +5,7 @@ import { createChannel } from 'bidc';
 import React from 'react';
 
 import { useAIChatController } from '@/components/AI';
+import { useRouter } from 'next/navigation';
 import { createStore, useStore } from 'zustand';
 import { Button } from '../primitives';
 
@@ -18,7 +19,12 @@ const embeddableConfiguration = createStore<GitBookEmbeddableConfiguration>(() =
 /**
  * Expose the API to communicate with the parent window.
  */
-export function EmbeddableIframeAPI() {
+export function EmbeddableIframeAPI(props: {
+    baseURL: string;
+}) {
+    const { baseURL } = props;
+
+    const router = useRouter();
     const chatController = useAIChatController();
 
     React.useEffect(() => {
@@ -50,11 +56,11 @@ export function EmbeddableIframeAPI() {
                     break;
                 }
                 case 'navigateToPage': {
-                    throw new Error('Not implemented');
+                    router.push(`${baseURL}/page/${message.pagePath}`);
                     break;
                 }
                 case 'navigateToAssistant': {
-                    throw new Error('Not implemented');
+                    router.push(`${baseURL}/assistant`);
                     break;
                 }
             }
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
index e46e3dede1..3e2ecd1ffa 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableRootLayout.tsx
@@ -38,7 +38,9 @@ export async function EmbeddableRootLayout({
                         }}
                     >
                         <div className="fixed inset-0 flex flex-col">{children}</div>
-                        <EmbeddableIframeAPI />
+                        <EmbeddableIframeAPI
+                            baseURL={context.linker.toPathInSpace('~gitbook/embed/')}
+                        />
                     </AIChatProvider>
                 </AIContextProvider>
             </SiteLayoutClientContexts>

From 661813b87f3b6f0134c7fce4dfe51c696ae6ea65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 10:22:26 +0200
Subject: [PATCH 09/11] Correctly pass tools

---
 packages/gitbook/src/components/AI/useAIChat.tsx            | 4 +++-
 .../src/components/Embeddable/EmbeddableIframeAPI.tsx       | 6 +++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/packages/gitbook/src/components/AI/useAIChat.tsx b/packages/gitbook/src/components/AI/useAIChat.tsx
index 43238e21a1..992209635a 100644
--- a/packages/gitbook/src/components/AI/useAIChat.tsx
+++ b/packages/gitbook/src/components/AI/useAIChat.tsx
@@ -346,7 +346,8 @@ export function AIChatProvider(props: {
                     loading: false,
                     error: false,
                 }));
-            } catch {
+            } catch (error) {
+                console.error('Error streaming AI response', error);
                 globalState.setState((state) => ({
                     ...state,
                     loading: false,
@@ -359,6 +360,7 @@ export function AIChatProvider(props: {
             renderMessageOptions?.withLinkPreviews,
             renderMessageOptions?.withToolCalls,
             renderMessageOptions?.asEmbeddable,
+            language,
         ]
     );
 
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index b166315ae0..f37dd4c55f 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -7,6 +7,7 @@ import React from 'react';
 import { useAIChatController } from '@/components/AI';
 import { useRouter } from 'next/navigation';
 import { createStore, useStore } from 'zustand';
+import { integrationsAssistantTools } from '../Integrations';
 import { Button } from '../primitives';
 
 const embeddableConfiguration = createStore<GitBookEmbeddableConfiguration>(() => ({
@@ -53,6 +54,9 @@ export function EmbeddableIframeAPI(props: {
                 }
                 case 'configure': {
                     embeddableConfiguration.setState(message.settings);
+                    integrationsAssistantTools.setState({
+                        tools: message.settings.tools,
+                    });
                     break;
                 }
                 case 'navigateToPage': {
@@ -70,7 +74,7 @@ export function EmbeddableIframeAPI(props: {
             console.log('[gitbook] cleanup');
             channel.cleanup();
         };
-    }, [chatController]);
+    }, [chatController, router, baseURL]);
 
     return null;
 }

From 0921cefbd96dcab97af79d23673337515e635f2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 10:23:25 +0200
Subject: [PATCH 10/11] Changeset

---
 .changeset/forty-trees-sniff.md | 5 +++++
 .changeset/sixty-pumas-tell.md  | 5 +++++
 2 files changed, 10 insertions(+)
 create mode 100644 .changeset/forty-trees-sniff.md
 create mode 100644 .changeset/sixty-pumas-tell.md

diff --git a/.changeset/forty-trees-sniff.md b/.changeset/forty-trees-sniff.md
new file mode 100644
index 0000000000..1696f2f02c
--- /dev/null
+++ b/.changeset/forty-trees-sniff.md
@@ -0,0 +1,5 @@
+---
+"@gitbook/embed": minor
+---
+
+Improve API to control the GitBook embed
diff --git a/.changeset/sixty-pumas-tell.md b/.changeset/sixty-pumas-tell.md
new file mode 100644
index 0000000000..7a750285b7
--- /dev/null
+++ b/.changeset/sixty-pumas-tell.md
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Support customization of buttons and tools through iframe API

From 59aee5cbb75470ecd1b3a4637cf469ccd9af48db Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Tue, 26 Aug 2025 10:41:43 +0200
Subject: [PATCH 11/11] Format

---
 biome.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/biome.json b/biome.json
index 69349302ac..53669a0a0b 100644
--- a/biome.json
+++ b/biome.json
@@ -18,6 +18,7 @@
             "**/.vercel/**/*",
             "**/.cache/**/*",
             "**/.wrangler/**/*",
+            "packages/embed/standalone/**/*",
             "packages/openapi-parser/src/fixtures/**/*",
             "packages/emoji-codepoints/index.ts",
             "packages/icons/src/data/*.json",