From 65fd3cc10168a228182542f71cf377db69898218 Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Thu, 2 Jul 2026 11:37:03 +0200
Subject: [PATCH 01/46] Gate AI features server-actions (#4353)

---
 .../[siteData]/~gitbook/embed/assistant/page.tsx     |  4 ++--
 .../[siteURL]/[siteData]/~gitbook/embed/page.tsx     |  4 ++--
 .../[siteData]/~gitbook/embed/assistant/page.tsx     |  4 ++--
 .../[siteURL]/[siteData]/~gitbook/embed/page.tsx     |  4 ++--
 .../gitbook/src/components/AI/server-actions/chat.ts |  8 +++++++-
 packages/gitbook/src/components/AI/useAI.tsx         |  7 ++++---
 .../AIChat/AskAITextSelection/AskAITextSelection.tsx |  4 ++--
 .../DocumentView/CodeBlock/AskAICodeButton.tsx       |  5 ++---
 .../components/Embeddable/EmbeddableIframeAPI.tsx    |  6 ++----
 .../gitbook/src/components/Search/server-actions.tsx | 10 ++++++++++
 .../src/components/SpaceLayout/SpaceLayout.tsx       |  9 +++------
 .../gitbook/src/components/utils/isAIChatEnabled.ts  | 12 +++++++++---
 packages/gitbook/src/routes/llms.ts                  |  5 +++++
 packages/gitbook/src/routes/markdownAsk.ts           |  5 +++++
 packages/gitbook/src/routes/markdownPage.ts          |  5 +++++
 15 files changed, 62 insertions(+), 30 deletions(-)

diff --git a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx
index 59736ceef..274f55334 100644
--- a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx
+++ b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx
@@ -1,7 +1,7 @@
 import type { RouteLayoutParams } from '@/app/utils';
 import { EmbeddableAssistantPage } from '@/components/Embeddable';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import { getEmbeddableDynamicContext } from '@/lib/embeddable';
-import { CustomizationAIMode } from '@gitbook/api';
 import { redirect } from 'next/navigation';
 
 type PageProps = {
@@ -15,7 +15,7 @@ export default async function Page(props: PageProps) {
     const { context } = await getEmbeddableDynamicContext(params);
 
     // If the assistant is not enabled, redirect to the docs
-    if (context.customization.ai.mode !== CustomizationAIMode.Assistant) {
+    if (!isAIChatEnabled(context.customization.ai.mode)) {
         redirect(`${context.linker.toPathInSite('~gitbook/embed/page/')}`);
     }
 
diff --git a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/page.tsx b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/page.tsx
index b847b5cf7..4abe02997 100644
--- a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/page.tsx
+++ b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/page.tsx
@@ -1,6 +1,6 @@
 import type { RouteLayoutParams } from '@/app/utils';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import { getEmbeddableDynamicContext } from '@/lib/embeddable';
-import { CustomizationAIMode } from '@gitbook/api';
 import { redirect } from 'next/navigation';
 
 type PageProps = {
@@ -13,7 +13,7 @@ export default async function Page(props: PageProps) {
     const baseURL = context.linker.toPathInSite('~gitbook/embed/');
 
     // If assistant is enabled, redirect to assistant, otherwise to docs
-    if (context.customization.ai.mode === CustomizationAIMode.Assistant) {
+    if (isAIChatEnabled(context.customization.ai.mode)) {
         redirect(`${baseURL}/assistant`);
     } else {
         redirect(`${baseURL}/page/`);
diff --git a/packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx b/packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx
index 9b8b40a76..b5e5cfa42 100644
--- a/packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx
+++ b/packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx
@@ -1,7 +1,7 @@
 import type { RouteParams } from '@/app/utils';
 import { EmbeddableAssistantPage } from '@/components/Embeddable';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import { getEmbeddableStaticContext } from '@/lib/embeddable';
-import { CustomizationAIMode } from '@gitbook/api';
 import { redirect } from 'next/navigation';
 
 export const dynamic = 'force-static';
@@ -15,7 +15,7 @@ export default async function Page(props: PageProps) {
     const { context } = await getEmbeddableStaticContext(params);
 
     // If the assistant is not enabled, redirect to the docs
-    if (context.customization.ai.mode !== CustomizationAIMode.Assistant) {
+    if (!isAIChatEnabled(context.customization.ai.mode)) {
         redirect(`${context.linker.toPathInSite('~gitbook/embed/page/')}`);
     }
 
diff --git a/packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/page.tsx b/packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/page.tsx
index 2f667d280..0198f23f2 100644
--- a/packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/page.tsx
+++ b/packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/page.tsx
@@ -1,6 +1,6 @@
 import type { RouteLayoutParams } from '@/app/utils';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import { getEmbeddableStaticContext } from '@/lib/embeddable';
-import { CustomizationAIMode } from '@gitbook/api';
 import { redirect } from 'next/navigation';
 
 export const dynamic = 'force-static';
@@ -15,7 +15,7 @@ export default async function Page(props: PageProps) {
     const baseURL = context.linker.toPathInSite('~gitbook/embed/');
 
     // If assistant is enabled, redirect to assistant, otherwise to docs
-    if (context.customization.ai.mode === CustomizationAIMode.Assistant) {
+    if (isAIChatEnabled(context.customization.ai.mode)) {
         redirect(`${baseURL}/assistant`);
     } else {
         redirect(`${baseURL}/page/`);
diff --git a/packages/gitbook/src/components/AI/server-actions/chat.ts b/packages/gitbook/src/components/AI/server-actions/chat.ts
index c5f65b285..beca9500b 100644
--- a/packages/gitbook/src/components/AI/server-actions/chat.ts
+++ b/packages/gitbook/src/components/AI/server-actions/chat.ts
@@ -1,6 +1,7 @@
 'use server';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import { getSiteURLDataFromMiddleware } from '@/lib/middleware';
-import { getServerActionBaseContext } from '@/lib/server-actions';
+import { fetchServerActionSiteContext, getServerActionBaseContext } from '@/lib/server-actions';
 import { traceErrorOnly } from '@/lib/tracing';
 import {
     type AIMessageContext,
@@ -39,6 +40,11 @@ export async function* streamAIChatResponse({
             isEmbeddable: options?.asEmbeddable,
         });
 
+        const siteContext = await fetchServerActionSiteContext(context);
+        if (!isAIChatEnabled(siteContext.customization.ai.mode)) {
+            throw new Error('The AI Assistant is not enabled for this site.');
+        }
+
         const siteURLData = await getSiteURLDataFromMiddleware();
 
         const api = await context.dataFetcher.api();
diff --git a/packages/gitbook/src/components/AI/useAI.tsx b/packages/gitbook/src/components/AI/useAI.tsx
index 9c6c81e06..e8322c1a2 100644
--- a/packages/gitbook/src/components/AI/useAI.tsx
+++ b/packages/gitbook/src/components/AI/useAI.tsx
@@ -1,10 +1,11 @@
 'use client';
 
-import { CustomizationAIMode } from '@gitbook/api';
+import type { CustomizationAIMode } from '@gitbook/api';
 import { Icon, type IconName } from '@gitbook/icons';
 import * as React from 'react';
 import type { ReactNode } from 'react';
 
+import { isAIChatEnabled, isAISearchEnabled } from '@/components/utils/isAIChatEnabled';
 import { tString, useLanguage } from '@/intl/client';
 import type { GitBookAssistant } from '@gitbook/browser-types';
 import { useAIChatController, useAIChatState } from '.';
@@ -89,7 +90,7 @@ export function useAI(): AIContext {
 
     const assistants: Assistant[] = [];
 
-    if (config.aiMode === CustomizationAIMode.Assistant) {
+    if (isAIChatEnabled(config.aiMode)) {
         assistants.push({
             id: 'gitbook-assistant',
             label: config.assistantName ?? getAIChatName(language, config.trademark),
@@ -110,7 +111,7 @@ export function useAI(): AIContext {
             ui: true,
             mode: 'sidebar',
         });
-    } else if (config.aiMode === CustomizationAIMode.Search) {
+    } else if (isAISearchEnabled(config.aiMode)) {
         assistants.push({
             id: 'gitbook-ai-search',
             label: tString(language, 'ai_chat_context_badge'),
diff --git a/packages/gitbook/src/components/AIChat/AskAITextSelection/AskAITextSelection.tsx b/packages/gitbook/src/components/AIChat/AskAITextSelection/AskAITextSelection.tsx
index 94056b6ee..ee3d00909 100644
--- a/packages/gitbook/src/components/AIChat/AskAITextSelection/AskAITextSelection.tsx
+++ b/packages/gitbook/src/components/AIChat/AskAITextSelection/AskAITextSelection.tsx
@@ -1,6 +1,5 @@
 'use client';
 
-import { CustomizationAIMode } from '@gitbook/api';
 import fnv1a from '@sindresorhus/fnv1a';
 import { AnimatePresence, motion } from 'motion/react';
 import * as React from 'react';
@@ -10,6 +9,7 @@ import { useAIChatController, useAIConfig } from '@/components/AI';
 import { useIsMobile } from '@/components/hooks/useIsMobile';
 import { useIsMounted } from '@/components/hooks/useIsMounted';
 import { Button } from '@/components/primitives';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import { t, useLanguage } from '@/intl/client';
 
 import { AIChatIcon } from '../AIChatIcon';
@@ -31,7 +31,7 @@ export function AskAITextSelection() {
     const isMobile = useIsMobile();
     const isMounted = useIsMounted();
 
-    const enabled = config.aiMode === CustomizationAIMode.Assistant && !isMobile;
+    const enabled = isAIChatEnabled(config.aiMode) && !isMobile;
 
     const toolbarRef = React.useRef<HTMLDivElement>(null);
     const { selection, clear } = useStableTextSelection({
diff --git a/packages/gitbook/src/components/DocumentView/CodeBlock/AskAICodeButton.tsx b/packages/gitbook/src/components/DocumentView/CodeBlock/AskAICodeButton.tsx
index 10a784439..850988337 100644
--- a/packages/gitbook/src/components/DocumentView/CodeBlock/AskAICodeButton.tsx
+++ b/packages/gitbook/src/components/DocumentView/CodeBlock/AskAICodeButton.tsx
@@ -1,10 +1,9 @@
 'use client';
 
-import { CustomizationAIMode } from '@gitbook/api';
-
 import { useAIChatController, useAIConfig } from '@/components/AI';
 import { AIChatIcon } from '@/components/AIChat';
 import { Button } from '@/components/primitives';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import { t, useLanguage } from '@/intl/client';
 import { type ClassValue, tcls } from '@/lib/tailwind';
 
@@ -22,7 +21,7 @@ export function AskAICodeButton(props: {
     const config = useAIConfig();
     const chatController = useAIChatController();
 
-    if (config.aiMode !== CustomizationAIMode.Assistant) {
+    if (!isAIChatEnabled(config.aiMode)) {
         return null;
     }
 
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index f4e116e23..b2b612ad5 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -4,8 +4,8 @@ import type { GitBookEmbeddableConfiguration, ParentToFrameMessage } from '@gitb
 import React, { useEffect, useRef } from 'react';
 
 import { useAI, useAIChatController } from '@/components/AI';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import { tString, useLanguage } from '@/intl/client';
-import { CustomizationAIMode } from '@gitbook/api';
 import { useRouter } from 'next/navigation';
 import { createStore, useStore } from 'zustand';
 import { integrationsAssistantTools } from '../Integrations';
@@ -186,9 +186,7 @@ export function EmbeddableIframeTabs(props: {
     const router = useRouter();
 
     const enabledTabs = [
-        config.aiMode === CustomizationAIMode.Assistant &&
-        assistants[0] &&
-        tabs.includes('assistant')
+        isAIChatEnabled(config.aiMode) && assistants[0] && tabs.includes('assistant')
             ? {
                   key: 'assistant',
                   label: assistants[0].label,
diff --git a/packages/gitbook/src/components/Search/server-actions.tsx b/packages/gitbook/src/components/Search/server-actions.tsx
index 1dca529a2..41e065e06 100644
--- a/packages/gitbook/src/components/Search/server-actions.tsx
+++ b/packages/gitbook/src/components/Search/server-actions.tsx
@@ -1,5 +1,6 @@
 'use server';
 
+import { isAIEnabled, isAISearchEnabled } from '@/components/utils/isAIChatEnabled';
 import type { GitBookSiteContext } from '@/lib/context';
 import { resolvePageId } from '@/lib/pages';
 import { fetchServerActionSiteContext, getServerActionBaseContext } from '@/lib/server-actions';
@@ -55,6 +56,10 @@ export async function streamAskQuestion({
                 await getServerActionBaseContext({ isEmbeddable: asEmbeddable })
             );
 
+            if (!isAISearchEnabled(context.customization.ai.mode)) {
+                throw new Error('AI Search is not enabled for this site.');
+            }
+
             const apiClient = await context.dataFetcher.api();
 
             const stream = apiClient.orgs.streamAskInSite(
@@ -151,6 +156,11 @@ export async function streamRecommendedQuestions(args: { siteSpaceId?: string })
         >();
 
         (async () => {
+            const siteContext = await fetchServerActionSiteContext(context);
+            if (!isAIEnabled(siteContext.customization.ai.mode)) {
+                throw new Error('AI is not enabled for this site.');
+            }
+
             const apiClient = await context.dataFetcher.api();
             const apiStream = apiClient.orgs.streamRecommendedQuestionsInSite(
                 siteURLData.organization,
diff --git a/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx b/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
index 5c095579c..ae3e69456 100644
--- a/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
+++ b/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
@@ -1,14 +1,11 @@
 import type { GitBookSiteContext } from '@/lib/context';
-import {
-    CustomizationAIMode,
-    CustomizationHeaderPreset,
-    CustomizationSearchStyle,
-} from '@gitbook/api';
+import { CustomizationHeaderPreset, CustomizationSearchStyle } from '@gitbook/api';
 import type React from 'react';
 
 import { Footer } from '@/components/Footer';
 import { Header, HeaderLogo } from '@/components/Header';
 import { TableOfContents } from '@/components/TableOfContents';
+import { isAIChatEnabled } from '@/components/utils/isAIChatEnabled';
 import type { VisitorAuthClaims } from '@/lib/adaptive';
 import { GITBOOK_APP_URL } from '@/lib/env';
 import { tcls } from '@/lib/tailwind';
@@ -128,7 +125,7 @@ export function SpaceLayout(props: SpaceLayoutProps) {
             <Announcement context={context} />
             <Header withTopHeader={withTopHeader} variants={variants} context={context} />
             <NavigationLoader />
-            {customization.ai?.mode === CustomizationAIMode.Assistant ? (
+            {isAIChatEnabled(customization.ai?.mode) ? (
                 <>
                     <AIChat />
                     <AskAITextSelection />
diff --git a/packages/gitbook/src/components/utils/isAIChatEnabled.ts b/packages/gitbook/src/components/utils/isAIChatEnabled.ts
index c23b60181..6d0051fbb 100644
--- a/packages/gitbook/src/components/utils/isAIChatEnabled.ts
+++ b/packages/gitbook/src/components/utils/isAIChatEnabled.ts
@@ -1,5 +1,11 @@
-import type { GitBookSiteContext } from '@/lib/context';
 import { CustomizationAIMode } from '@gitbook/api';
 
-export const isAIChatEnabled = (context: GitBookSiteContext) =>
-    context.customization.ai.mode === CustomizationAIMode.Assistant;
+// `ai.mode` is exclusive: Assistant (chat) and Search (ask) are distinct features; None means no AI.
+export const isAIChatEnabled = (mode: CustomizationAIMode | undefined) =>
+    mode === CustomizationAIMode.Assistant;
+
+export const isAISearchEnabled = (mode: CustomizationAIMode | undefined) =>
+    mode === CustomizationAIMode.Search;
+
+export const isAIEnabled = (mode: CustomizationAIMode | undefined) =>
+    isAIChatEnabled(mode) || isAISearchEnabled(mode);
diff --git a/packages/gitbook/src/routes/llms.ts b/packages/gitbook/src/routes/llms.ts
index d9c68b6cc..18faaea93 100644
--- a/packages/gitbook/src/routes/llms.ts
+++ b/packages/gitbook/src/routes/llms.ts
@@ -1,3 +1,4 @@
+import { isAIEnabled } from '@/components/utils/isAIChatEnabled';
 import { type GitBookSiteContext, checkIsRootSiteContext } from '@/lib/context';
 import { throwIfDataError } from '@/lib/data';
 import { type GitBookLinker, linkerWithMarkdownPages } from '@/lib/links';
@@ -203,6 +204,10 @@ export async function getMarkdownForPagesTree(
 }
 
 function renderAskFooter(context: GitBookSiteContext) {
+    if (!isAIEnabled(context.customization.ai.mode)) {
+        return '';
+    }
+
     return `\n\n---\n\n# Agent Instructions
 This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
 
diff --git a/packages/gitbook/src/routes/markdownAsk.ts b/packages/gitbook/src/routes/markdownAsk.ts
index dca64d5f5..87508cc49 100644
--- a/packages/gitbook/src/routes/markdownAsk.ts
+++ b/packages/gitbook/src/routes/markdownAsk.ts
@@ -1,3 +1,4 @@
+import { isAIEnabled } from '@/components/utils/isAIChatEnabled';
 import type { GitBookSiteContext } from '@/lib/context';
 import { throwIfDataError } from '@/lib/data';
 import { linkerWithMarkdownPages } from '@/lib/links';
@@ -27,6 +28,10 @@ export async function serveAskMarkdown(
     rawQuestion: string,
     options: ServeAskMarkdownOptions = {}
 ) {
+    if (!isAIEnabled(context.customization.ai.mode)) {
+        return new Response('Not Found', { status: 404 });
+    }
+
     return serveMarkdown(async () => {
         const question = rawQuestion.trim();
         const goal = options.goal?.trim() || undefined;
diff --git a/packages/gitbook/src/routes/markdownPage.ts b/packages/gitbook/src/routes/markdownPage.ts
index 21070b231..039e80a50 100644
--- a/packages/gitbook/src/routes/markdownPage.ts
+++ b/packages/gitbook/src/routes/markdownPage.ts
@@ -1,3 +1,4 @@
+import { isAIEnabled } from '@/components/utils/isAIChatEnabled';
 import type { GitBookSiteContext } from '@/lib/context';
 import { getExposableError } from '@/lib/data';
 import { linkerWithMarkdownPages } from '@/lib/links';
@@ -100,6 +101,10 @@ function renderAskFooter(
     context: GitBookSiteContext,
     pageLookup: ResolvedPagePath<RevisionPageDocument | RevisionPageGroup>
 ) {
+    if (!isAIEnabled(context.customization.ai.mode)) {
+        return '';
+    }
+
     const pageUrl = context.linker.toAbsoluteURL(
         context.linker.toPathForPage({
             page: pageLookup.page,

From c923c654bd6f4ffd8f94619adecb300586243147 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Thu, 2 Jul 2026 12:19:24 +0200
Subject: [PATCH 02/46] Fix centered paragraphs shifting left with the
 paragraph ask button (#4354)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/fix-ask-button-centered-paragraph.md        |  5 +++++
 .../gitbook/src/components/DocumentView/Paragraph.tsx  | 10 +++++++++-
 2 files changed, 14 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/fix-ask-button-centered-paragraph.md

diff --git a/.changeset/fix-ask-button-centered-paragraph.md b/.changeset/fix-ask-button-centered-paragraph.md
new file mode 100644
index 000000000..1f89e6c26
--- /dev/null
+++ b/.changeset/fix-ask-button-centered-paragraph.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix center- and end-aligned paragraphs shifting left on wide/no-TOC pages when the AI Assistant is enabled, caused by the per-paragraph ask-button wrapper not inheriting the block alignment.
diff --git a/packages/gitbook/src/components/DocumentView/Paragraph.tsx b/packages/gitbook/src/components/DocumentView/Paragraph.tsx
index d2f475acf..b58c2988a 100644
--- a/packages/gitbook/src/components/DocumentView/Paragraph.tsx
+++ b/packages/gitbook/src/components/DocumentView/Paragraph.tsx
@@ -33,8 +33,16 @@ export function Paragraph(props: BlockProps<DocumentBlockParagraph>) {
 
     const text = aiAssistantEnabled ? getNodeText(block) : '';
     if (aiAssistantEnabled && text.trim()) {
+        // The wrapper is now the flex child, so it must carry the block alignment (notably
+        // `self-center`/`self-end`) — otherwise centered paragraphs pin left on wide/no-TOC pages.
         return (
-            <div className={tcls('group/ask-ai relative', style)}>
+            <div
+                className={tcls(
+                    'group/ask-ai relative',
+                    style,
+                    getTextAlignment(block.data?.align)
+                )}
+            >
                 {paragraph}
                 <AskAIParagraphButton content={text} />
             </div>

From 578a3a829b64d87af8f8b225877f623fc00b6f5c Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Thu, 2 Jul 2026 14:06:41 +0200
Subject: [PATCH 03/46] Fix section tab dropdowns clipping their contents
 during animation (#4356)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/section-dropdown-clipping.md          |  5 +++++
 .../components/SiteSections/SiteSectionTabs.tsx  | 16 +++++++++++-----
 2 files changed, 16 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/section-dropdown-clipping.md

diff --git a/.changeset/section-dropdown-clipping.md b/.changeset/section-dropdown-clipping.md
new file mode 100644
index 000000000..a0fd5393d
--- /dev/null
+++ b/.changeset/section-dropdown-clipping.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix site section dropdowns not being bounded by their container during the open/resize animation, causing the contents to visually clip.
diff --git a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
index 0f6fa0c6e..8636c53c1 100644
--- a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
+++ b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
@@ -165,20 +165,26 @@ export function SiteSectionTabs(props: {
 
             <div
                 className="absolute top-full left-0 z-20 flex w-full"
-                style={{ paddingInline: `${SCREEN_OFFSET}px` }}
+                style={{
+                    paddingInline: `${SCREEN_OFFSET}px`,
+                    // Force a stacking context on this wrapper (rather than on the Viewport) to fix a rendering bug on
+                    // Safari. Keeping it here — off the clipped Viewport — avoids a Chromium bug where a clipped,
+                    // composited layer drops its text inside an iframe (empty dropdowns on embedded sites).
+                    transform: 'translateZ(0)',
+                }}
             >
                 <NavigationMenu.Viewport
                     className={tcls(
-                        // Note: this layer is composited (translateZ) and animated. Chromium fails to paint a clipped composited layer's text
-                        // inside an iframe or `overflow-hidden` ancestor. Clipping is done on the inner content wrapper instead.
-                        'relative origin-[center_top] circular-corners:rounded-3xl rounded-corners:rounded-xl border border-tint bg-tint-base shadow-lg',
+                        // `overflow-hidden` clips the content to this animating box, keeping it bounded by the rounded
+                        // container as the Viewport resizes/scales. The stacking context Safari needs lives on the
+                        // parent wrapper (translateZ), deliberately not here — see the note above.
+                        'relative origin-[center_top] overflow-hidden circular-corners:rounded-3xl rounded-corners:rounded-xl border border-tint bg-tint-base shadow-lg',
                         '-mt-0.5 h-(--radix-navigation-menu-viewport-height) w-full max-w-full md:w-(--radix-navigation-menu-viewport-width)',
                         'max-h-[calc(100vh-8rem)] data-[state=closed]:animate-scale-out data-[state=open]:animate-scale-in',
                         'ease has-[&[data-motion]]:transition-[left,width,height] has-[&[data-motion]]:duration-300'
                     )}
                     style={{
                         left: viewportLeft,
-                        translate: '0 0 0', // TranslateZ is needed to force a stacking context, fixing a rendering bug on Safari
                     }}
                 />
             </div>

From eaef259a80007f46a7223dbf3aa1f60f88cbcc76 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Thu, 2 Jul 2026 19:34:09 +0200
Subject: [PATCH 04/46] Refresh e2e customer list (#4360)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/deploy-preview.yaml  |   4 +-
 packages/gitbook/e2e/customers.spec.ts | 455 ++++++++++++++++++++++---
 2 files changed, 410 insertions(+), 49 deletions(-)

diff --git a/.github/workflows/deploy-preview.yaml b/.github/workflows/deploy-preview.yaml
index 726580de7..44269f1d1 100644
--- a/.github/workflows/deploy-preview.yaml
+++ b/.github/workflows/deploy-preview.yaml
@@ -168,7 +168,7 @@ jobs:
         name: Visual Testing Customers v2
         needs: deploy-v2-vercel
         if: ${{ always() && needs.deploy-v2-vercel.result == 'success' }}
-        timeout-minutes: 15
+        timeout-minutes: 30
         steps:
             - name: Checkout
               uses: actions/checkout@v4
@@ -192,7 +192,7 @@ jobs:
         name: Visual Testing Customers v2 (Cloudflare)
         needs: deploy-v2-cloudflare
         if: ${{ always() && needs.deploy-v2-cloudflare.result == 'success' }}
-        timeout-minutes: 15
+        timeout-minutes: 30
         steps:
             - name: Checkout
               uses: actions/checkout@v4
diff --git a/packages/gitbook/e2e/customers.spec.ts b/packages/gitbook/e2e/customers.spec.ts
index 207189d66..422e99ee4 100644
--- a/packages/gitbook/e2e/customers.spec.ts
+++ b/packages/gitbook/e2e/customers.spec.ts
@@ -40,11 +40,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://asiksupport-stg.dto.kemkes.go.id',
         tests: [{ name: 'Home', url: '/' }],
     },
-    {
-        name: 'jasons-tutorials.gitbook.io',
-        contentBaseURL: 'https://jasons-tutorials.gitbook.io',
-        tests: [{ name: 'Home', url: '/' }],
-    },
     {
         name: 'faq.deltaemulator.com',
         contentBaseURL: 'https://faq.deltaemulator.com',
@@ -70,11 +65,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://docs.gmgn.ai',
         tests: [{ name: 'Home', url: '/' }],
     },
-    // {
-    //     name: 'docs.spicychat.ai',
-    //     contentBaseURL: 'https://docs.spicychat.ai',
-    //     tests: [{ name: 'Home', url: '/' }],
-    // },
     {
         name: 'docs.portainer.io',
         contentBaseURL: 'https://docs.portainer.io',
@@ -110,27 +100,11 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://docs.midas.app',
         tests: [{ name: 'Home', url: '/' }],
     },
-    // Disabling for now, one of the image is making the tests timeout
-    // {
-    //     name: 'docs.keeper.io',
-    //     contentBaseURL: 'https://docs.keeper.io',
-    //     tests: [{ name: 'Home', url: '/en', run: waitForCookiesDialog }],
-    // },
     {
         name: 'adiblar.gitbook.io',
         contentBaseURL: 'https://adiblar.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
-    // {
-    //     name: 'docs.gradient.network',
-    //     contentBaseURL: 'https://docs.gradient.network',
-    //     tests: [{ name: 'Home', url: '/' }],
-    // },
-    // {
-    //     name: 'mygate-network.gitbook.io',
-    //     contentBaseURL: 'https://mygate-network.gitbook.io',
-    //     tests: [{ name: 'Home', url: '/' }],
-    // },
     {
         name: 'treasurenft.gitbook.io',
         contentBaseURL: 'https://treasurenft.gitbook.io',
@@ -166,16 +140,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://wiki.redmodding.org',
         tests: [{ name: 'Home', url: '/' }],
     },
-    // {
-    //     name: 'docs.cherry-ai.com',
-    //     contentBaseURL: 'https://docs.cherry-ai.com',
-    //     tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
-    // },
-    {
-        name: 'docs.snyk.io',
-        contentBaseURL: 'https://docs.snyk.io',
-        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
-    },
     {
         name: 'docs.realapp.link',
         contentBaseURL: 'https://docs.realapp.link',
@@ -208,11 +172,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://sosovalue-white-paper.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
-    // {
-    //     name: 'docs.revrobotics.com',
-    //     contentBaseURL: 'https://docs.revrobotics.com',
-    //     tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
-    // },
     {
         name: 'chartschool.stockcharts.com',
         contentBaseURL: 'https://chartschool.stockcharts.com',
@@ -223,12 +182,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://docs.soniclabs.com',
         tests: [{ name: 'Home', url: '/' }],
     },
-    // This one redirects to binance now
-    // {
-    //     name: 'docs.meshchain.ai',
-    //     contentBaseURL: 'https://docs.meshchain.ai',
-    //     tests: [{ name: 'Home', url: '/' }],
-    // },
     {
         name: 'docs.thousandeyes.com',
         contentBaseURL: 'https://docs.thousandeyes.com',
@@ -256,6 +209,414 @@ const testCases: TestsCase[] = [
             { name: 'OG Image', url: '/~gitbook/ogimage/h17zQIFwy3MaafVNmItO', mode: 'image' },
         ],
     },
+
+    // Additional customer docs sites.
+    {
+        name: 'unsloth.ai/docs',
+        contentBaseURL: 'https://unsloth.ai',
+        tests: [{ name: 'Home', url: '/docs' }],
+    },
+    {
+        name: 'mariadb.com/docs',
+        contentBaseURL: 'https://mariadb.com',
+        tests: [{ name: 'Home', url: '/docs' }],
+    },
+    {
+        name: 'docs.n8n.io',
+        contentBaseURL: 'https://docs.n8n.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.cherry-ai.com',
+        contentBaseURL: 'https://docs.cherry-ai.com',
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
+    },
+    {
+        name: 'library.zoom.com',
+        contentBaseURL: 'https://library.zoom.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'help.verkada.com',
+        contentBaseURL: 'https://help.verkada.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.overleaf.com',
+        contentBaseURL: 'https://docs.overleaf.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'wiki.tiltedphoques.com/tilted-online',
+        contentBaseURL: 'https://wiki.tiltedphoques.com',
+        tests: [{ name: 'Home', url: '/tilted-online' }],
+    },
+    {
+        name: 'handbook.musescore.org',
+        contentBaseURL: 'https://handbook.musescore.org',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'kakaobusiness.gitbook.io/main',
+        contentBaseURL: 'https://kakaobusiness.gitbook.io',
+        tests: [{ name: 'Home', url: '/main' }],
+    },
+    {
+        name: 'docs.maestro.dev',
+        contentBaseURL: 'https://docs.maestro.dev',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'developers.oxylabs.io',
+        contentBaseURL: 'https://developers.oxylabs.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.parallels.com/landing',
+        contentBaseURL: 'https://docs.parallels.com',
+        tests: [{ name: 'Home', url: '/landing' }],
+    },
+    {
+        name: 'help.impact.com',
+        contentBaseURL: 'https://help.impact.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.9proxy.com',
+        contentBaseURL: 'https://docs.9proxy.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'vimeo.com/legal',
+        contentBaseURL: 'https://vimeo.com',
+        tests: [{ name: 'Home', url: '/legal' }],
+    },
+    {
+        name: 'help.platipomiru.com',
+        contentBaseURL: 'https://help.platipomiru.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'help.aikido.dev',
+        contentBaseURL: 'https://help.aikido.dev',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'doc.demarche.numerique.gouv.fr',
+        contentBaseURL: 'https://doc.demarche.numerique.gouv.fr',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.adapta.org',
+        contentBaseURL: 'https://docs.adapta.org',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'www.xabuxa.com',
+        contentBaseURL: 'https://www.xabuxa.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.triumpharcade.com',
+        contentBaseURL: 'https://docs.triumpharcade.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.nats.io',
+        contentBaseURL: 'https://docs.nats.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'help.glpi-project.org',
+        contentBaseURL: 'https://help.glpi-project.org',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.waydro.id',
+        contentBaseURL: 'https://docs.waydro.id',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'bellingcat.gitbook.io/toolkit',
+        contentBaseURL: 'https://bellingcat.gitbook.io',
+        tests: [{ name: 'Home', url: '/toolkit' }],
+    },
+    {
+        name: 'wiki.project-fika.com',
+        contentBaseURL: 'https://wiki.project-fika.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.pinot.apache.org',
+        contentBaseURL: 'https://docs.pinot.apache.org',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.devolutions.net',
+        contentBaseURL: 'https://docs.devolutions.net',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'guides.gresb.com',
+        contentBaseURL: 'https://guides.gresb.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.prestashop-project.org/welcome',
+        contentBaseURL: 'https://docs.prestashop-project.org',
+        tests: [{ name: 'Home', url: '/welcome' }],
+    },
+    {
+        name: 'help.researchgate.net',
+        contentBaseURL: 'https://help.researchgate.net',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.verifone.com',
+        contentBaseURL: 'https://docs.verifone.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.roboflow.com',
+        contentBaseURL: 'https://docs.roboflow.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'www.netexec.wiki',
+        contentBaseURL: 'https://www.netexec.wiki',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'guide.strikepack.com',
+        contentBaseURL: 'https://guide.strikepack.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'gitbook.com/docs',
+        contentBaseURL: 'https://gitbook.com',
+        tests: [
+            { name: 'Home', url: '/docs' },
+            {
+                name: 'OpenAPI',
+                url: '/docs/developers/gitbook-api/api-reference/docs-sites/site-ai-ask',
+            },
+        ],
+    },
+    {
+        name: 'documentation.gravitee.io',
+        contentBaseURL: 'https://documentation.gravitee.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'faq.wanttopay.net/wanttopay-app',
+        contentBaseURL: 'https://faq.wanttopay.net',
+        tests: [{ name: 'Home', url: '/wanttopay-app' }],
+    },
+    {
+        name: 'guide.prismlive.com',
+        contentBaseURL: 'https://guide.prismlive.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.ionos.com/cloud',
+        contentBaseURL: 'https://docs.ionos.com',
+        tests: [{ name: 'Home', url: '/cloud' }],
+    },
+    {
+        name: 'support.evite.com',
+        contentBaseURL: 'https://support.evite.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'knowledge.illumina.com',
+        contentBaseURL: 'https://knowledge.illumina.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'wiki.retrobat.org',
+        contentBaseURL: 'https://wiki.retrobat.org',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'wiki.polymaker.com',
+        contentBaseURL: 'https://wiki.polymaker.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.ducks-services.com',
+        contentBaseURL: 'https://docs.ducks-services.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.hex-rays.com',
+        contentBaseURL: 'https://docs.hex-rays.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'whitepaper.interlinklabs.ai',
+        contentBaseURL: 'https://whitepaper.interlinklabs.ai',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'help.openloyalty.io',
+        contentBaseURL: 'https://help.openloyalty.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'retrozia.gitbook.io/retrozia',
+        contentBaseURL: 'https://retrozia.gitbook.io',
+        tests: [{ name: 'Home', url: '/retrozia' }],
+    },
+    {
+        name: 'helpcenter.channable.com',
+        contentBaseURL: 'https://helpcenter.channable.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'developerdocs.instructure.com',
+        contentBaseURL: 'https://developerdocs.instructure.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'legal.jagex.com',
+        contentBaseURL: 'https://legal.jagex.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'manual.edgetx.org',
+        contentBaseURL: 'https://manual.edgetx.org',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.cortex.io',
+        contentBaseURL: 'https://docs.cortex.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.mufy.ai',
+        contentBaseURL: 'https://docs.mufy.ai',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.ndi.video/all',
+        contentBaseURL: 'https://docs.ndi.video',
+        tests: [{ name: 'Home', url: '/all' }],
+    },
+    {
+        name: 'docs.sevenpens.com/drawtab',
+        contentBaseURL: 'https://docs.sevenpens.com',
+        tests: [{ name: 'Home', url: '/drawtab' }],
+    },
+    {
+        name: 'manuals.i-reporter.jp',
+        contentBaseURL: 'https://manuals.i-reporter.jp',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.holybro.com',
+        contentBaseURL: 'https://docs.holybro.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'help.tokenpocket.pro/en',
+        contentBaseURL: 'https://help.tokenpocket.pro',
+        tests: [{ name: 'Home', url: '/en' }],
+    },
+    {
+        name: 'docs.bullmq.io',
+        contentBaseURL: 'https://docs.bullmq.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'tools.osintnewsletter.com',
+        contentBaseURL: 'https://tools.osintnewsletter.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'wiki.mmorealms.gg',
+        contentBaseURL: 'https://wiki.mmorealms.gg',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.vectra.ai',
+        contentBaseURL: 'https://docs.vectra.ai',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.cipp.app',
+        contentBaseURL: 'https://docs.cipp.app',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'sinfa-com-co.gitbook.io/manual-de-usuario',
+        contentBaseURL: 'https://sinfa-com-co.gitbook.io',
+        tests: [{ name: 'Home', url: '/manual-de-usuario' }],
+    },
+    {
+        name: 'support.skylum.com',
+        contentBaseURL: 'https://support.skylum.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.jgscripts.com',
+        contentBaseURL: 'https://docs.jgscripts.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.patchmypc.com',
+        contentBaseURL: 'https://docs.patchmypc.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'guide.cryosparc.com',
+        contentBaseURL: 'https://guide.cryosparc.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'guides.stellaraio.com/stellar',
+        contentBaseURL: 'https://guides.stellaraio.com',
+        tests: [{ name: 'Home', url: '/stellar' }],
+    },
+    {
+        name: 'docs.iyzico.com',
+        contentBaseURL: 'https://docs.iyzico.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'help.wotnot.io',
+        contentBaseURL: 'https://help.wotnot.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.sportmonks.com/v3',
+        contentBaseURL: 'https://docs.sportmonks.com',
+        tests: [{ name: 'Home', url: '/v3' }],
+    },
+    {
+        name: 'docs.payments.thalescloud.io',
+        contentBaseURL: 'https://docs.payments.thalescloud.io',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'doc.anytype.io/anytype-docs',
+        contentBaseURL: 'https://doc.anytype.io',
+        tests: [{ name: 'Home', url: '/anytype-docs' }],
+    },
+    {
+        name: 'help.blotato.com',
+        contentBaseURL: 'https://help.blotato.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.cartographer3d.com',
+        contentBaseURL: 'https://docs.cartographer3d.com',
+        tests: [{ name: 'Home', url: '/' }],
+    },
+    {
+        name: 'docs.acestudio.ai',
+        contentBaseURL: 'https://docs.acestudio.ai',
+        tests: [{ name: 'Home', url: '/' }],
+    },
 ];
 
 runTestCases(testCases);

From 6102413d6b3d953c3ec0114c6a02b8be93fa6d95 Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Thu, 2 Jul 2026 23:19:07 +0200
Subject: [PATCH 05/46] Reuse shared AI mode helpers across AI actions and UI
 (#4355)

---
 .github/composite/deploy-cloudflare/action.yaml |  1 +
 .github/composite/deploy-vercel/action.yaml     |  1 +
 packages/gitbook/next.config.mjs                |  1 +
 packages/gitbook/src/lib/server-actions.ts      |  6 +++++-
 packages/gitbook/src/middleware.ts              | 14 ++++++++++++--
 5 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/.github/composite/deploy-cloudflare/action.yaml b/.github/composite/deploy-cloudflare/action.yaml
index 8e5ee4823..136ad52b1 100644
--- a/.github/composite/deploy-cloudflare/action.yaml
+++ b/.github/composite/deploy-cloudflare/action.yaml
@@ -66,6 +66,7 @@ runs:
           env:
             GITBOOK_RUNTIME: cloudflare
             GITBOOK_BLOCK_SEARCH_INDEXATION: ${{ inputs.environment == 'preview' && 'true' || '' }}
+            GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE: ${{ inputs.environment == 'preview' && 'true' || '' }}
           shell: bash
 
         - name: Upload the DO worker
diff --git a/.github/composite/deploy-vercel/action.yaml b/.github/composite/deploy-vercel/action.yaml
index bb7b81750..8c62577c7 100644
--- a/.github/composite/deploy-vercel/action.yaml
+++ b/.github/composite/deploy-vercel/action.yaml
@@ -72,6 +72,7 @@ runs:
             echo "GITBOOK_HEAD_SHA=$HEAD_SHA" >> .vercel/.env.${{ inputs.environment }}.local
             echo "GITBOOK_RUNTIME=vercel" >> .vercel/.env.${{ inputs.environment }}.local
             echo "GITBOOK_BLOCK_SEARCH_INDEXATION=true" >> .vercel/.env.${{ inputs.environment }}.local
+            echo "GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE=true" >> .vercel/.env.${{ inputs.environment }}.local
             echo "--- .vercel/.env.${{ inputs.environment }}.local after inject ---"
             cat .vercel/.env.${{ inputs.environment }}.local
         - name: Build Project Artifacts
diff --git a/packages/gitbook/next.config.mjs b/packages/gitbook/next.config.mjs
index 3db64e6a3..309e7d0e5 100644
--- a/packages/gitbook/next.config.mjs
+++ b/packages/gitbook/next.config.mjs
@@ -61,6 +61,7 @@ const nextConfig = {
         GITBOOK_FONTS_URL: process.env.GITBOOK_FONTS_URL,
         GITBOOK_RUNTIME: process.env.GITBOOK_RUNTIME,
         GITBOOK_BLOCK_SEARCH_INDEXATION: process.env.GITBOOK_BLOCK_SEARCH_INDEXATION,
+        GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE: process.env.GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE,
 
         // Next.js envs
         NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY,
diff --git a/packages/gitbook/src/lib/server-actions.ts b/packages/gitbook/src/lib/server-actions.ts
index 0e8c8ed93..40bc0282e 100644
--- a/packages/gitbook/src/lib/server-actions.ts
+++ b/packages/gitbook/src/lib/server-actions.ts
@@ -1,4 +1,5 @@
 import { type GitBookBaseContext, fetchSiteContextByURLLookup, getBaseContext } from './context';
+import { getDynamicCustomizationSettings } from './customization';
 import { getEmbeddableLinker } from './embeddable-linker';
 import {
     getSiteURLDataFromMiddleware,
@@ -37,5 +38,8 @@ export async function getServerActionBaseContext(options?: { isEmbeddable?: bool
  */
 export async function fetchServerActionSiteContext(baseContext: GitBookBaseContext) {
     const siteURLData = await getSiteURLDataFromMiddleware();
-    return fetchSiteContextByURLLookup(baseContext, siteURLData);
+    const context = await fetchSiteContextByURLLookup(baseContext, siteURLData);
+    // Apply the preview customization override
+    context.customization = await getDynamicCustomizationSettings(context.customization);
+    return context;
 }
diff --git a/packages/gitbook/src/middleware.ts b/packages/gitbook/src/middleware.ts
index 7fd652585..38071e2be 100644
--- a/packages/gitbook/src/middleware.ts
+++ b/packages/gitbook/src/middleware.ts
@@ -393,12 +393,22 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
         );
         requestHeaders.set(MiddlewareHeaders.SiteURLData, JSON.stringify(stableSiteURLData));
 
-        // Preview of customization/theme
+        // Preview of customization/theme.
+        // The customization override is only honored for a legitimate preview
+        // (backend-authoritative `siteURLData.preview`), so an anonymous public request can't
+        // force customization — e.g. ai.mode — via the query string or a forged cookie.
+        // Preview/test deployments opt in via GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE to drive it in e2e.
+        const allowCustomizationOverride =
+            siteURLData.preview || process.env.GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE === 'true';
         const customizationCookie = request.cookies.get(MiddlewareHeaders.Customization);
         const customization =
             siteRequestURL.searchParams.get('customization') ??
             (customizationCookie ? decodeURIComponent(customizationCookie.value) : undefined);
-        if (customization && validateSerializedCustomization(customization)) {
+        if (
+            allowCustomizationOverride &&
+            customization &&
+            validateSerializedCustomization(customization)
+        ) {
             routeType = 'dynamic';
             // We need to encode the customization headers, otherwise it will fail for some customization values containing non ASCII chars on vercel.
             requestHeaders.set(MiddlewareHeaders.Customization, encodeURIComponent(customization));

From 62ca6d3ce53528df0d369555c5554e76fa1dd49a Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Fri, 3 Jul 2026 12:36:07 +0200
Subject: [PATCH 06/46] Show a "Back to [space]" shortcut when a link leads to
 another space (#4358)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/back-to-space-toc.md               |   5 +
 .../Header/SpacesDropdownMenuItem.tsx         |  19 +-
 .../src/components/SitePage/SitePage.tsx      |  27 +--
 .../SiteSections/SiteSectionList.tsx          |   3 +-
 .../SiteSections/SiteSectionTabs.tsx          |   2 +
 .../TableOfContents/BackToSpaceButton.tsx     |  56 ++++++
 .../TableOfContents/TableOfContents.tsx       |   8 +
 .../gitbook/src/components/hooks/index.ts     |   1 +
 .../components/hooks/useBackToSpace.test.ts   | 104 ++++++++++
 .../src/components/hooks/useBackToSpace.tsx   | 178 ++++++++++++++++++
 packages/gitbook/src/intl/translations/ar.ts  |   1 +
 packages/gitbook/src/intl/translations/bg.ts  |   1 +
 packages/gitbook/src/intl/translations/cs.ts  |   1 +
 packages/gitbook/src/intl/translations/da.ts  |   1 +
 packages/gitbook/src/intl/translations/de.ts  |   1 +
 packages/gitbook/src/intl/translations/el.ts  |   1 +
 packages/gitbook/src/intl/translations/en.ts  |   1 +
 packages/gitbook/src/intl/translations/es.ts  |   1 +
 packages/gitbook/src/intl/translations/et.ts  |   1 +
 packages/gitbook/src/intl/translations/fi.ts  |   1 +
 packages/gitbook/src/intl/translations/fr.ts  |   1 +
 packages/gitbook/src/intl/translations/he.ts  |   1 +
 packages/gitbook/src/intl/translations/hi.ts  |   1 +
 packages/gitbook/src/intl/translations/hr.ts  |   1 +
 packages/gitbook/src/intl/translations/hu.ts  |   1 +
 packages/gitbook/src/intl/translations/id.ts  |   1 +
 packages/gitbook/src/intl/translations/it.ts  |   1 +
 packages/gitbook/src/intl/translations/ja.ts  |   1 +
 packages/gitbook/src/intl/translations/ko.ts  |   1 +
 packages/gitbook/src/intl/translations/lt.ts  |   1 +
 packages/gitbook/src/intl/translations/lv.ts  |   1 +
 packages/gitbook/src/intl/translations/ms.ts  |   1 +
 packages/gitbook/src/intl/translations/nl.ts  |   1 +
 packages/gitbook/src/intl/translations/no.ts  |   1 +
 packages/gitbook/src/intl/translations/pl.ts  |   1 +
 .../gitbook/src/intl/translations/pt-br.ts    |   1 +
 packages/gitbook/src/intl/translations/pt.ts  |   1 +
 packages/gitbook/src/intl/translations/ro.ts  |   1 +
 packages/gitbook/src/intl/translations/ru.ts  |   1 +
 packages/gitbook/src/intl/translations/sk.ts  |   1 +
 packages/gitbook/src/intl/translations/sl.ts  |   1 +
 packages/gitbook/src/intl/translations/sv.ts  |   1 +
 packages/gitbook/src/intl/translations/th.ts  |   1 +
 packages/gitbook/src/intl/translations/tr.ts  |   1 +
 packages/gitbook/src/intl/translations/uk.ts  |   1 +
 packages/gitbook/src/intl/translations/vi.ts  |   1 +
 packages/gitbook/src/intl/translations/yue.ts |   1 +
 .../gitbook/src/intl/translations/zh-tw.ts    |   1 +
 packages/gitbook/src/intl/translations/zh.ts  |   1 +
 packages/gitbook/src/lib/sites.ts             |  27 +++
 50 files changed, 440 insertions(+), 29 deletions(-)
 create mode 100644 .changeset/back-to-space-toc.md
 create mode 100644 packages/gitbook/src/components/TableOfContents/BackToSpaceButton.tsx
 create mode 100644 packages/gitbook/src/components/hooks/useBackToSpace.test.ts
 create mode 100644 packages/gitbook/src/components/hooks/useBackToSpace.tsx

diff --git a/.changeset/back-to-space-toc.md b/.changeset/back-to-space-toc.md
new file mode 100644
index 000000000..fc502837a
--- /dev/null
+++ b/.changeset/back-to-space-toc.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Show a "Back to [space]" shortcut at the top of the table of contents when a reader follows a link into a different space, so they don't lose track of where they were browsing from.
diff --git a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
index 68c28b8fc..6ca5aa50a 100644
--- a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
+++ b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
@@ -1,7 +1,11 @@
 'use client';
 
 import { joinPath } from '@/lib/paths';
-import { useCurrentPageMetadata, useCurrentPagePath } from '../hooks';
+import {
+    markSpaceNavigationFromPickerOnClick,
+    useCurrentPageMetadata,
+    useCurrentPagePath,
+} from '../hooks';
 import { DropdownMenuItem } from '../primitives/DropdownMenu';
 
 interface VariantSpace {
@@ -60,7 +64,18 @@ export function SpacesDropdownMenuItem(props: {
     const variantHref = useVariantSpaceHref(variantSpace, currentSpacePath, active);
 
     return (
-        <DropdownMenuItem key={variantSpace.id} href={variantHref} active={active}>
+        <DropdownMenuItem
+            key={variantSpace.id}
+            href={variantHref}
+            active={active}
+            onClick={(event) => {
+                // Switching variant/translation through the picker shouldn't offer to
+                // navigate "back" to the space we're leaving.
+                if (!active) {
+                    markSpaceNavigationFromPickerOnClick(event);
+                }
+            }}
+        >
             {variantSpace.title}
         </DropdownMenuItem>
     );
diff --git a/packages/gitbook/src/components/SitePage/SitePage.tsx b/packages/gitbook/src/components/SitePage/SitePage.tsx
index 073717f49..684115f3b 100644
--- a/packages/gitbook/src/components/SitePage/SitePage.tsx
+++ b/packages/gitbook/src/components/SitePage/SitePage.tsx
@@ -25,7 +25,7 @@ import {
 } from '@/lib/icons/inline';
 import { getResizedImageURL } from '@/lib/images';
 import { resolveContentRef } from '@/lib/references';
-import { getLocalizedTitle } from '@/lib/sites';
+import { getSiteStructureTitle } from '@/lib/sites';
 import { tcls } from '@/lib/tailwind';
 import { getPageRSSURL } from '@/routes/rss';
 import { PageContextProvider } from '../PageContext';
@@ -149,31 +149,6 @@ export async function generateSitePageViewport(context: GitBookSiteContext): Pro
     };
 }
 
-/**
- * A string concatenation of the site structure (sections and variants) titles.
- */
-function getSiteStructureTitle(context: GitBookSiteContext): string | null {
-    const { visibleSections: sections, siteSpace, visibleSiteSpaces: siteSpaces } = context;
-    const currentLanguage = context.locale;
-
-    const title = [];
-    if (
-        sections &&
-        sections.current.default === false && // Only if the current section is not the default one
-        sections.list.filter((section) => section.object === 'site-section').length > 1 // Only if there are multiple sections
-    ) {
-        title.push(getLocalizedTitle(sections.current, currentLanguage));
-    }
-    if (
-        siteSpaces.length > 1 && // Only if there are multiple variants
-        siteSpace.default === false && // Only if the variant is not the default one
-        siteSpaces.filter((space) => space.space.language === siteSpace.space.language).length > 1 // Only if there are multiple variants *for the current language*. This filters out spaces that are "just" translations of each other, not versions.
-    ) {
-        title.push(getLocalizedTitle(siteSpace, siteSpace.space.language));
-    }
-    return title.join(' ');
-}
-
 export async function generateSitePageMetadata(props: SitePageProps): Promise<Metadata> {
     const { context, pageTarget, pageMetaLinks } = await getPageDataWithFallback({
         context: props.context,
diff --git a/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx b/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx
index 399525a07..213325f44 100644
--- a/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx
+++ b/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx
@@ -6,7 +6,7 @@ import React from 'react';
 
 import { type ClassValue, tcls } from '@/lib/tailwind';
 import { findSectionInGroup } from '@/lib/utils';
-import { useToggleAnimation } from '../hooks';
+import { markSpaceNavigationFromPickerOnClick, useToggleAnimation } from '../hooks';
 import { Link, ToggleChevron } from '../primitives';
 import { ScrollContainer } from '../primitives/ScrollContainer';
 import { SectionIcon } from './SectionIcon';
@@ -31,6 +31,7 @@ export function SiteSectionList(props: { sections: ClientSiteSections; className
         sectionsAndGroups.length > 0 && (
             <nav
                 aria-label="Sections"
+                onClickCapture={markSpaceNavigationFromPickerOnClick}
                 className={tcls(
                     '-mx-5 before:contents[] relative border-tint-subtle border-b from-transparent sidebar-filled:to-tint-subtle theme-muted:to-tint-subtle to-tint-base text-sm text-tint before:pointer-events-none before:absolute before:right-2 before:bottom-0 before:left-0 before:h-12 before:bg-linear-to-b [html.sidebar-filled.theme-bold.tint_&]:to-tint-base [html.sidebar-filled.theme-bold.tint_&]:to-tint-subtle [html.sidebar-filled.theme-muted_&]:to-tint-base',
                     className
diff --git a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
index 8636c53c1..68990cdf9 100644
--- a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
+++ b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
@@ -7,6 +7,7 @@ import React from 'react';
 import { Button, Link, ToggleChevron } from '@/components/primitives';
 import { tcls } from '@/lib/tailwind';
 import { findSectionInGroup } from '@/lib/utils';
+import { markSpaceNavigationFromPickerOnClick } from '../hooks';
 import { useIsMobile } from '../hooks/useIsMobile';
 import { CONTAINER_STYLE } from '../layout';
 import { ScrollContainer } from '../primitives/ScrollContainer';
@@ -64,6 +65,7 @@ export function SiteSectionTabs(props: {
                 className
             )}
             ref={containerRef}
+            onClickCapture={markSpaceNavigationFromPickerOnClick}
             style={
                 {
                     '--site-section-column-width': COLUMN_WIDTH,
diff --git a/packages/gitbook/src/components/TableOfContents/BackToSpaceButton.tsx b/packages/gitbook/src/components/TableOfContents/BackToSpaceButton.tsx
new file mode 100644
index 000000000..5496105b9
--- /dev/null
+++ b/packages/gitbook/src/components/TableOfContents/BackToSpaceButton.tsx
@@ -0,0 +1,56 @@
+'use client';
+
+import { Icon } from '@gitbook/icons';
+
+import { t, useLanguage } from '@/intl/client';
+import { tcls } from '@/lib/tailwind';
+
+import { useBackToSpace } from '../hooks';
+import { Link } from '../primitives';
+
+/**
+ * Shortcut displayed at the top of the ToC to navigate back to the space the reader
+ * came from, when they followed a link into a different space.
+ *
+ * It renders nothing until a cross-space navigation is detected client-side (see
+ * {@link useBackToSpace}), so it has no effect on the vast majority of page views.
+ */
+export function BackToSpaceButton(props: { spaceId: string; spaceTitle: string }) {
+    const { spaceId, spaceTitle } = props;
+    const language = useLanguage();
+    const backToSpace = useBackToSpace({ spaceId, spaceTitle });
+
+    if (!backToSpace) {
+        return null;
+    }
+
+    return (
+        <div className="mb-2 px-2">
+            <Link
+                href={backToSpace.url}
+                className={tcls(
+                    'group/back-to-space',
+                    'flex items-center gap-2',
+                    'px-3 py-2',
+                    'circular-corners:rounded-xl rounded-md straight-corners:rounded-none',
+                    'text-sm text-tint',
+                    'bg-tint-base ring-1 ring-tint-subtle ring-inset',
+                    'transition-colors',
+                    'hover:bg-tint-hover hover:text-tint-strong',
+                    'contrast-more:ring-tint'
+                )}
+            >
+                <Icon
+                    icon="arrow-left"
+                    className={tcls(
+                        'size-3 shrink-0 text-tint-subtle transition-transform',
+                        'group-hover/back-to-space:-translate-x-0.5 group-hover/back-to-space:text-current'
+                    )}
+                />
+                <span className="truncate">
+                    {t(language, 'toc_back_to_space', backToSpace.spaceTitle)}
+                </span>
+            </Link>
+        </div>
+    );
+}
diff --git a/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx b/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
index 25d2c5b95..dcc7edcdf 100644
--- a/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
+++ b/packages/gitbook/src/components/TableOfContents/TableOfContents.tsx
@@ -2,9 +2,11 @@ import type { GitBookSiteContext } from '@/lib/context';
 import { SiteInsightsTrademarkPlacement } from '@gitbook/api';
 import type React from 'react';
 
+import { getSiteStructureTitle } from '@/lib/sites';
 import { tcls } from '@/lib/tailwind';
 import { ScrollContainer } from '../primitives/ScrollContainer';
 import { SideSheet } from '../primitives/SideSheet';
+import { BackToSpaceButton } from './BackToSpaceButton';
 import { PagesList } from './PagesList';
 import { TableOfContentsScript } from './TableOfContentsScript';
 import { Trademark } from './Trademark';
@@ -119,6 +121,12 @@ export async function TableOfContents(props: {
                         '[html.sidebar-filled.circular-corners_&]:layout-wide:rounded-4xl'
                     )}
                 >
+                    <BackToSpaceButton
+                        spaceId={context.space.id}
+                        // Use the section/variant title as shown in the site navigation,
+                        // falling back to the site title for the default space.
+                        spaceTitle={getSiteStructureTitle(context) || context.site.title}
+                    />
                     {innerHeader}
                     <ScrollContainer
                         data-testid="toc-scroll-container"
diff --git a/packages/gitbook/src/components/hooks/index.ts b/packages/gitbook/src/components/hooks/index.ts
index 42f8b30ee..a8d70b117 100644
--- a/packages/gitbook/src/components/hooks/index.ts
+++ b/packages/gitbook/src/components/hooks/index.ts
@@ -9,3 +9,4 @@ export * from './useCurrentPage';
 export * from './useNow';
 export * from './useListOverflow';
 export * from './useCurrentPageMetadata';
+export * from './useBackToSpace';
diff --git a/packages/gitbook/src/components/hooks/useBackToSpace.test.ts b/packages/gitbook/src/components/hooks/useBackToSpace.test.ts
new file mode 100644
index 000000000..79ee0e146
--- /dev/null
+++ b/packages/gitbook/src/components/hooks/useBackToSpace.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'bun:test';
+
+import { type SpaceLocation, resolveBackToSpace } from './useBackToSpace';
+
+const gettingStarted: SpaceLocation = {
+    spaceId: 'space_gs',
+    spaceTitle: 'Getting Started',
+    url: '/docs/getting-started',
+};
+const programmersGuide: SpaceLocation = {
+    spaceId: 'space_pg',
+    spaceTitle: "Programmer's Guide",
+    url: '/docs/programmers-guide',
+};
+const apiReference: SpaceLocation = {
+    spaceId: 'space_api',
+    spaceTitle: 'API Reference',
+    url: '/docs/api',
+};
+
+describe('resolveBackToSpace', () => {
+    it('offers nothing on the first navigation of a session', () => {
+        expect(
+            resolveBackToSpace({
+                current: gettingStarted,
+                lastLocation: null,
+                storedBack: null,
+                fromPicker: false,
+            })
+        ).toBeNull();
+    });
+
+    it('offers to go back after following a link into a different space', () => {
+        expect(
+            resolveBackToSpace({
+                current: programmersGuide,
+                lastLocation: gettingStarted,
+                storedBack: null,
+                fromPicker: false,
+            })
+        ).toEqual(gettingStarted);
+    });
+
+    it('keeps the back target while browsing within the destination space', () => {
+        const deeperInGuide: SpaceLocation = {
+            ...programmersGuide,
+            url: '/docs/programmers-guide/chapter-2',
+        };
+        expect(
+            resolveBackToSpace({
+                current: deeperInGuide,
+                lastLocation: programmersGuide,
+                storedBack: gettingStarted,
+                fromPicker: false,
+            })
+        ).toEqual(gettingStarted);
+    });
+
+    it('does not offer to go back when the space was changed through the picker', () => {
+        expect(
+            resolveBackToSpace({
+                current: programmersGuide,
+                lastLocation: gettingStarted,
+                storedBack: null,
+                fromPicker: true,
+            })
+        ).toBeNull();
+    });
+
+    it('clears the back target once the reader returns to the space they came from', () => {
+        expect(
+            resolveBackToSpace({
+                current: gettingStarted,
+                lastLocation: programmersGuide,
+                storedBack: gettingStarted,
+                fromPicker: false,
+            })
+        ).toBeNull();
+    });
+
+    it('points back to the most recent space when chaining cross-space links', () => {
+        // Was in Getting Started (stored back), followed a link from the Programmer's
+        // Guide into the API Reference: back should now point to the Programmer's Guide.
+        expect(
+            resolveBackToSpace({
+                current: apiReference,
+                lastLocation: programmersGuide,
+                storedBack: gettingStarted,
+                fromPicker: false,
+            })
+        ).toEqual(programmersGuide);
+    });
+
+    it('resets the back target when switching space through the picker even if one was set', () => {
+        expect(
+            resolveBackToSpace({
+                current: apiReference,
+                lastLocation: programmersGuide,
+                storedBack: gettingStarted,
+                fromPicker: true,
+            })
+        ).toBeNull();
+    });
+});
diff --git a/packages/gitbook/src/components/hooks/useBackToSpace.tsx b/packages/gitbook/src/components/hooks/useBackToSpace.tsx
new file mode 100644
index 000000000..481deffb8
--- /dev/null
+++ b/packages/gitbook/src/components/hooks/useBackToSpace.tsx
@@ -0,0 +1,178 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import * as React from 'react';
+
+import {
+    getSessionStorageItem,
+    removeSessionStorageItem,
+    setSessionStorageItem,
+} from '@/lib/browser';
+
+/**
+ * A location visited by the reader, scoped to the space it belongs to.
+ */
+export type SpaceLocation = {
+    /** Identifier of the space. */
+    spaceId: string;
+    /** Localized title of the space, used as the label of the "back" shortcut. */
+    spaceTitle: string;
+    /** Path (with query string) of the last page visited in the space. */
+    url: string;
+};
+
+// Keys used to persist the navigation state for the current tab session.
+const LAST_LOCATION_KEY = 'gitbook-space-navigation:last';
+const BACK_TO_SPACE_KEY = 'gitbook-space-navigation:back';
+const FROM_PICKER_KEY = 'gitbook-space-navigation:from-picker';
+
+/**
+ * Mark that the navigation about to happen was initiated from the section/variant
+ * picker (spaces dropdown, translations dropdown or section switcher).
+ *
+ * Such navigations are deliberate moves within the site's own structure and should
+ * not surface a "Back to space" shortcut. Set synchronously when a picker link is
+ * activated, so the flag is in place before the destination page reads it.
+ */
+function markSpaceNavigationFromPicker() {
+    setSessionStorageItem(FROM_PICKER_KEY, true);
+}
+
+/**
+ * Whether a click opens its link in a new tab or window instead of navigating the
+ * current tab (a modifier key or a non-primary button). These must not mark a picker
+ * navigation: the current tab stays put, so the flag would otherwise linger and be
+ * mis-attributed to a later, unrelated navigation.
+ */
+function opensInNewTab(event: React.MouseEvent): boolean {
+    return event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0;
+}
+
+/**
+ * Click handler for the section/variant/translation pickers that marks the upcoming
+ * navigation as picker-initiated, so arriving in the target space doesn't surface a
+ * "Back to space" shortcut.
+ *
+ * Attach it with `onClickCapture` on a picker container (section list/tabs) or as the
+ * `onClick` of a picker menu item (spaces dropdown). It intentionally does nothing for
+ * clicks that leave the current tab unchanged: re-selecting the already-active item,
+ * or opening the link in a new tab/window.
+ */
+export function markSpaceNavigationFromPickerOnClick(event: React.MouseEvent<HTMLElement>) {
+    if (opensInNewTab(event)) {
+        return;
+    }
+
+    const target = event.target;
+    if (!(target instanceof Element)) {
+        return;
+    }
+
+    const link = target.closest('a[href]');
+    if (!link) {
+        return;
+    }
+
+    // Skip the currently active item: re-selecting it doesn't navigate. The sidebar
+    // section list marks the active link with `aria-current`, while the header section
+    // tabs (rendered via the Button primitive) use `aria-pressed`.
+    if (
+        link.getAttribute('aria-current') === 'page' ||
+        link.getAttribute('aria-pressed') === 'true'
+    ) {
+        return;
+    }
+
+    markSpaceNavigationFromPicker();
+}
+
+/**
+ * Determine which space (if any) the reader should be offered to navigate back to,
+ * given the current location and the state persisted from the previous navigation.
+ *
+ * This is the pure decision logic behind {@link useBackToSpace}, extracted so it can
+ * be unit-tested without a DOM.
+ */
+export function resolveBackToSpace(input: {
+    current: SpaceLocation;
+    lastLocation: SpaceLocation | null;
+    storedBack: SpaceLocation | null;
+    fromPicker: boolean;
+}): SpaceLocation | null {
+    const { current, lastLocation, storedBack, fromPicker } = input;
+
+    // No previous navigation this session, or we're still browsing the same space:
+    // keep whatever "back" target we already had (it persists while browsing).
+    if (!lastLocation || lastLocation.spaceId === current.spaceId) {
+        return storedBack && storedBack.spaceId !== current.spaceId ? storedBack : null;
+    }
+
+    // The reader moved to a different space since the last navigation.
+
+    // Switching space through the picker is a deliberate navigation within the
+    // site structure: reset the context instead of offering to go back.
+    if (fromPicker) {
+        return null;
+    }
+
+    // The reader returned to the space they originally came from.
+    if (storedBack && storedBack.spaceId === current.spaceId) {
+        return null;
+    }
+
+    // The reader followed a link into a different space: offer to go back to the
+    // page they were on.
+    return lastLocation;
+}
+
+/**
+ * Track navigation between spaces and return the space to offer navigating back to.
+ *
+ * When a reader follows a link (in the ToC or in the content) into a space different
+ * from the one they were browsing, we remember where they came from so a "Back to
+ * [space]" shortcut can be surfaced. The shortcut persists while they browse the
+ * destination space and is cleared once they return or switch space through the
+ * section/variant picker.
+ *
+ * The state is kept in `sessionStorage` so it survives both client-side and full-page
+ * navigations within the tab, without leaking across tabs or sessions.
+ */
+export function useBackToSpace(current: {
+    spaceId: string;
+    spaceTitle: string;
+}): SpaceLocation | null {
+    const { spaceId, spaceTitle } = current;
+    const pathname = usePathname();
+    const [backToSpace, setBackToSpace] = React.useState<SpaceLocation | null>(null);
+
+    React.useEffect(() => {
+        const currentLocation: SpaceLocation = {
+            spaceId,
+            spaceTitle,
+            // `pathname` (from Next) is the app-relative path used for client navigation,
+            // paired with the current query string so we return to the exact same page.
+            url: `${pathname}${window.location.search}`,
+        };
+
+        const fromPicker = getSessionStorageItem<boolean>(FROM_PICKER_KEY, false);
+        removeSessionStorageItem(FROM_PICKER_KEY);
+
+        const back = resolveBackToSpace({
+            current: currentLocation,
+            lastLocation: getSessionStorageItem<SpaceLocation | null>(LAST_LOCATION_KEY, null),
+            storedBack: getSessionStorageItem<SpaceLocation | null>(BACK_TO_SPACE_KEY, null),
+            fromPicker,
+        });
+
+        if (back) {
+            setSessionStorageItem(BACK_TO_SPACE_KEY, back);
+        } else {
+            removeSessionStorageItem(BACK_TO_SPACE_KEY);
+        }
+        setSessionStorageItem(LAST_LOCATION_KEY, currentLocation);
+
+        setBackToSpace(back);
+    }, [pathname, spaceId, spaceTitle]);
+
+    return backToSpace;
+}
diff --git a/packages/gitbook/src/intl/translations/ar.ts b/packages/gitbook/src/intl/translations/ar.ts
index 769ce44ca..16a2e7d5c 100644
--- a/packages/gitbook/src/intl/translations/ar.ts
+++ b/packages/gitbook/src/intl/translations/ar.ts
@@ -44,6 +44,7 @@ export const ar: TranslationLanguage = {
     on_this_page: 'في هذه الصفحة',
     next_page: 'التالي',
     previous_page: 'السابق',
+    toc_back_to_space: 'العودة إلى ${1}',
     page_last_modified: 'آخر تحديث ${1}',
     was_this_helpful: 'هل كان هذا مفيدا؟',
     was_this_helpful_positive: 'نعم، كان مفيدا!',
diff --git a/packages/gitbook/src/intl/translations/bg.ts b/packages/gitbook/src/intl/translations/bg.ts
index 8bb82d0df..9dc337a1a 100644
--- a/packages/gitbook/src/intl/translations/bg.ts
+++ b/packages/gitbook/src/intl/translations/bg.ts
@@ -45,6 +45,7 @@ export const bg: TranslationLanguage = {
     on_this_page: 'На тази страница',
     next_page: 'Следваща',
     previous_page: 'Предишна',
+    toc_back_to_space: 'Обратно към ${1}',
     page_last_modified: 'Последна актуализация ${1}',
     was_this_helpful: 'Беше ли полезно?',
     was_this_helpful_positive: 'Да, беше!',
diff --git a/packages/gitbook/src/intl/translations/cs.ts b/packages/gitbook/src/intl/translations/cs.ts
index e4fc09a43..c44ffe3af 100644
--- a/packages/gitbook/src/intl/translations/cs.ts
+++ b/packages/gitbook/src/intl/translations/cs.ts
@@ -44,6 +44,7 @@ export const cs: TranslationLanguage = {
     on_this_page: 'Na této stránce',
     next_page: 'Další',
     previous_page: 'Předchozí',
+    toc_back_to_space: 'Zpět na ${1}',
     page_last_modified: 'Poslední aktualizace ${1}',
     was_this_helpful: 'Bylo to užitečné?',
     was_this_helpful_positive: 'Ano, bylo!',
diff --git a/packages/gitbook/src/intl/translations/da.ts b/packages/gitbook/src/intl/translations/da.ts
index b3130fd83..287328a5e 100644
--- a/packages/gitbook/src/intl/translations/da.ts
+++ b/packages/gitbook/src/intl/translations/da.ts
@@ -44,6 +44,7 @@ export const da: TranslationLanguage = {
     on_this_page: 'På denne side',
     next_page: 'Næste',
     previous_page: 'Forrige',
+    toc_back_to_space: 'Tilbage til ${1}',
     page_last_modified: 'Sidst opdateret ${1}',
     was_this_helpful: 'Var dette nyttigt?',
     was_this_helpful_positive: 'Ja, det var det!',
diff --git a/packages/gitbook/src/intl/translations/de.ts b/packages/gitbook/src/intl/translations/de.ts
index fdfb1b07e..9f6d330f6 100644
--- a/packages/gitbook/src/intl/translations/de.ts
+++ b/packages/gitbook/src/intl/translations/de.ts
@@ -46,6 +46,7 @@ export const de: TranslationLanguage = {
     on_this_page: 'Auf dieser Seite',
     next_page: 'Nächste',
     previous_page: 'Vorherige',
+    toc_back_to_space: 'Zurück zu ${1}',
     page_last_modified: 'Zuletzt aktualisiert ${1}',
     was_this_helpful: 'War das hilfreich?',
     was_this_helpful_positive: 'Ja, das war es!',
diff --git a/packages/gitbook/src/intl/translations/el.ts b/packages/gitbook/src/intl/translations/el.ts
index 32296d8db..3d734b40a 100644
--- a/packages/gitbook/src/intl/translations/el.ts
+++ b/packages/gitbook/src/intl/translations/el.ts
@@ -45,6 +45,7 @@ export const el: TranslationLanguage = {
     on_this_page: 'Σε αυτήν τη σελίδα',
     next_page: 'Επόμενη',
     previous_page: 'Προηγούμενη',
+    toc_back_to_space: 'Επιστροφή σε ${1}',
     page_last_modified: 'Τελευταία ενημέρωση ${1}',
     was_this_helpful: 'Ήταν χρήσιμο αυτό;',
     was_this_helpful_positive: 'Ναι, ήταν!',
diff --git a/packages/gitbook/src/intl/translations/en.ts b/packages/gitbook/src/intl/translations/en.ts
index e26f18458..93cc868b7 100644
--- a/packages/gitbook/src/intl/translations/en.ts
+++ b/packages/gitbook/src/intl/translations/en.ts
@@ -42,6 +42,7 @@ export const en = {
     on_this_page: 'On this page',
     next_page: 'Next',
     previous_page: 'Previous',
+    toc_back_to_space: 'Back to ${1}',
     page_last_modified: 'Last updated ${1}',
     was_this_helpful: 'Was this helpful?',
     was_this_helpful_positive: 'Yes, it was!',
diff --git a/packages/gitbook/src/intl/translations/es.ts b/packages/gitbook/src/intl/translations/es.ts
index 4557282ef..be02ee437 100644
--- a/packages/gitbook/src/intl/translations/es.ts
+++ b/packages/gitbook/src/intl/translations/es.ts
@@ -46,6 +46,7 @@ export const es: TranslationLanguage = {
     on_this_page: 'En esta página',
     next_page: 'Siguiente',
     previous_page: 'Anterior',
+    toc_back_to_space: 'Volver a ${1}',
     page_last_modified: 'Última actualización ${1}',
     was_this_helpful: '¿Te fue útil?',
     was_this_helpful_positive: '¡Sí, lo fue!',
diff --git a/packages/gitbook/src/intl/translations/et.ts b/packages/gitbook/src/intl/translations/et.ts
index 49e53b025..bdfe26619 100644
--- a/packages/gitbook/src/intl/translations/et.ts
+++ b/packages/gitbook/src/intl/translations/et.ts
@@ -44,6 +44,7 @@ export const et: TranslationLanguage = {
     on_this_page: 'Sellel lehel',
     next_page: 'Järgmine',
     previous_page: 'Eelmine',
+    toc_back_to_space: 'Tagasi: ${1}',
     page_last_modified: 'Viimati uuendatud ${1}',
     was_this_helpful: 'Kas sellest oli abi?',
     was_this_helpful_positive: 'Jah, oli!',
diff --git a/packages/gitbook/src/intl/translations/fi.ts b/packages/gitbook/src/intl/translations/fi.ts
index 6f573bec3..03e3de395 100644
--- a/packages/gitbook/src/intl/translations/fi.ts
+++ b/packages/gitbook/src/intl/translations/fi.ts
@@ -45,6 +45,7 @@ export const fi: TranslationLanguage = {
     on_this_page: 'Tällä sivulla',
     next_page: 'Seuraava',
     previous_page: 'Edellinen',
+    toc_back_to_space: 'Takaisin: ${1}',
     page_last_modified: 'Päivitetty viimeksi ${1}',
     was_this_helpful: 'Oliko tästä apua?',
     was_this_helpful_positive: 'Kyllä oli!',
diff --git a/packages/gitbook/src/intl/translations/fr.ts b/packages/gitbook/src/intl/translations/fr.ts
index 301e8270e..c5107c236 100644
--- a/packages/gitbook/src/intl/translations/fr.ts
+++ b/packages/gitbook/src/intl/translations/fr.ts
@@ -45,6 +45,7 @@ export const fr: TranslationLanguage = {
     on_this_page: 'Sur cette page',
     next_page: 'Suivant',
     previous_page: 'Précédent',
+    toc_back_to_space: 'Retour à ${1}',
     page_last_modified: 'Mis à jour ${1}',
     was_this_helpful: 'Ce contenu vous a-t-il été utile ?',
     was_this_helpful_positive: 'Oui, tout à fait !',
diff --git a/packages/gitbook/src/intl/translations/he.ts b/packages/gitbook/src/intl/translations/he.ts
index bafe59cb8..929187094 100644
--- a/packages/gitbook/src/intl/translations/he.ts
+++ b/packages/gitbook/src/intl/translations/he.ts
@@ -44,6 +44,7 @@ export const he: TranslationLanguage = {
     on_this_page: 'בדף הזה',
     next_page: 'הבא',
     previous_page: 'הקודם',
+    toc_back_to_space: 'חזרה אל ${1}',
     page_last_modified: 'עודכן לאחרונה ${1}',
     was_this_helpful: 'האם זה היה מועיל?',
     was_this_helpful_positive: 'כן, זה עזר!',
diff --git a/packages/gitbook/src/intl/translations/hi.ts b/packages/gitbook/src/intl/translations/hi.ts
index fa21019cd..b195edd58 100644
--- a/packages/gitbook/src/intl/translations/hi.ts
+++ b/packages/gitbook/src/intl/translations/hi.ts
@@ -44,6 +44,7 @@ export const hi: TranslationLanguage = {
     on_this_page: 'इस पृष्ठ पर',
     next_page: 'अगला',
     previous_page: 'पिछला',
+    toc_back_to_space: '${1} पर वापस जाएँ',
     page_last_modified: 'अंतिम अपडेट ${1}',
     was_this_helpful: 'क्या यह उपयोगी था?',
     was_this_helpful_positive: 'हां, था!',
diff --git a/packages/gitbook/src/intl/translations/hr.ts b/packages/gitbook/src/intl/translations/hr.ts
index 05c417d84..64a150bd8 100644
--- a/packages/gitbook/src/intl/translations/hr.ts
+++ b/packages/gitbook/src/intl/translations/hr.ts
@@ -44,6 +44,7 @@ export const hr: TranslationLanguage = {
     on_this_page: 'Na ovoj stranici',
     next_page: 'Sljedeća',
     previous_page: 'Prethodna',
+    toc_back_to_space: 'Natrag na ${1}',
     page_last_modified: 'Zadnje ažurirano ${1}',
     was_this_helpful: 'Je li ovo bilo korisno?',
     was_this_helpful_positive: 'Da, bilo je!',
diff --git a/packages/gitbook/src/intl/translations/hu.ts b/packages/gitbook/src/intl/translations/hu.ts
index 9c3d4586d..898b9bdf6 100644
--- a/packages/gitbook/src/intl/translations/hu.ts
+++ b/packages/gitbook/src/intl/translations/hu.ts
@@ -45,6 +45,7 @@ export const hu: TranslationLanguage = {
     on_this_page: 'Ezen az oldalon',
     next_page: 'Következő',
     previous_page: 'Előző',
+    toc_back_to_space: 'Vissza ide: ${1}',
     page_last_modified: 'Utoljára frissítve: ${1}',
     was_this_helpful: 'Hasznos volt ez?',
     was_this_helpful_positive: 'Igen, az volt!',
diff --git a/packages/gitbook/src/intl/translations/id.ts b/packages/gitbook/src/intl/translations/id.ts
index d87cf516e..342b706bf 100644
--- a/packages/gitbook/src/intl/translations/id.ts
+++ b/packages/gitbook/src/intl/translations/id.ts
@@ -44,6 +44,7 @@ export const id: TranslationLanguage = {
     on_this_page: 'Di halaman ini',
     next_page: 'Berikutnya',
     previous_page: 'Sebelumnya',
+    toc_back_to_space: 'Kembali ke ${1}',
     page_last_modified: 'Terakhir diperbarui ${1}',
     was_this_helpful: 'Apakah ini membantu?',
     was_this_helpful_positive: 'Ya, membantu!',
diff --git a/packages/gitbook/src/intl/translations/it.ts b/packages/gitbook/src/intl/translations/it.ts
index 30cecfe79..111b96159 100644
--- a/packages/gitbook/src/intl/translations/it.ts
+++ b/packages/gitbook/src/intl/translations/it.ts
@@ -46,6 +46,7 @@ export const it: TranslationLanguage = {
     on_this_page: 'In questa pagina',
     next_page: 'Successivo',
     previous_page: 'Precedente',
+    toc_back_to_space: 'Torna a ${1}',
     page_last_modified: 'Ultimo aggiornamento ${1}',
     was_this_helpful: 'È stato utile?',
     was_this_helpful_positive: 'Sì, lo è stato!',
diff --git a/packages/gitbook/src/intl/translations/ja.ts b/packages/gitbook/src/intl/translations/ja.ts
index a908bf42b..7f3533632 100644
--- a/packages/gitbook/src/intl/translations/ja.ts
+++ b/packages/gitbook/src/intl/translations/ja.ts
@@ -45,6 +45,7 @@ export const ja: TranslationLanguage = {
     on_this_page: 'このページ内',
     next_page: '次へ',
     previous_page: '前へ',
+    toc_back_to_space: '${1}に戻る',
     page_last_modified: '最終更新 ${1}',
     was_this_helpful: '役に立ちましたか？',
     was_this_helpful_positive: 'はい、役に立ちました！',
diff --git a/packages/gitbook/src/intl/translations/ko.ts b/packages/gitbook/src/intl/translations/ko.ts
index f5ed3d8e1..00bea3c40 100644
--- a/packages/gitbook/src/intl/translations/ko.ts
+++ b/packages/gitbook/src/intl/translations/ko.ts
@@ -45,6 +45,7 @@ export const ko: TranslationLanguage = {
     on_this_page: '이 페이지에서',
     next_page: '다음',
     previous_page: '이전',
+    toc_back_to_space: '${1}(으)로 돌아가기',
     page_last_modified: '마지막 업데이트 ${1}',
     was_this_helpful: '도움이 되었나요?',
     was_this_helpful_positive: '네, 도움이 되었어요!',
diff --git a/packages/gitbook/src/intl/translations/lt.ts b/packages/gitbook/src/intl/translations/lt.ts
index 9dcf78ccd..d759f250f 100644
--- a/packages/gitbook/src/intl/translations/lt.ts
+++ b/packages/gitbook/src/intl/translations/lt.ts
@@ -44,6 +44,7 @@ export const lt: TranslationLanguage = {
     on_this_page: 'Šiame puslapyje',
     next_page: 'Kitas',
     previous_page: 'Ankstesnis',
+    toc_back_to_space: 'Atgal į ${1}',
     page_last_modified: 'Paskutinį kartą atnaujinta ${1}',
     was_this_helpful: 'Ar tai buvo naudinga?',
     was_this_helpful_positive: 'Taip, buvo!',
diff --git a/packages/gitbook/src/intl/translations/lv.ts b/packages/gitbook/src/intl/translations/lv.ts
index 324f4ad22..2bf4fcf6d 100644
--- a/packages/gitbook/src/intl/translations/lv.ts
+++ b/packages/gitbook/src/intl/translations/lv.ts
@@ -44,6 +44,7 @@ export const lv: TranslationLanguage = {
     on_this_page: 'Šajā lapā',
     next_page: 'Nākamā',
     previous_page: 'Iepriekšējā',
+    toc_back_to_space: 'Atpakaļ uz ${1}',
     page_last_modified: 'Pēdoreiz atjaunināts ${1}',
     was_this_helpful: 'Vai tas bija noderīgi?',
     was_this_helpful_positive: 'Jā, bija!',
diff --git a/packages/gitbook/src/intl/translations/ms.ts b/packages/gitbook/src/intl/translations/ms.ts
index 84651b9b7..6b930599d 100644
--- a/packages/gitbook/src/intl/translations/ms.ts
+++ b/packages/gitbook/src/intl/translations/ms.ts
@@ -44,6 +44,7 @@ export const ms: TranslationLanguage = {
     on_this_page: 'Pada halaman ini',
     next_page: 'Seterusnya',
     previous_page: 'Sebelumnya',
+    toc_back_to_space: 'Kembali ke ${1}',
     page_last_modified: 'Terakhir dikemas kini ${1}',
     was_this_helpful: 'Adakah ini membantu?',
     was_this_helpful_positive: 'Ya, membantu!',
diff --git a/packages/gitbook/src/intl/translations/nl.ts b/packages/gitbook/src/intl/translations/nl.ts
index 6fe56a31e..8d9d32f41 100644
--- a/packages/gitbook/src/intl/translations/nl.ts
+++ b/packages/gitbook/src/intl/translations/nl.ts
@@ -46,6 +46,7 @@ export const nl: TranslationLanguage = {
     on_this_page: 'Op deze pagina',
     next_page: 'Volgende',
     previous_page: 'Vorige',
+    toc_back_to_space: 'Terug naar ${1}',
     page_last_modified: 'Laatst bijgewerkt ${1}',
     was_this_helpful: 'Was dit nuttig?',
     was_this_helpful_positive: 'Ja, het was nuttig!',
diff --git a/packages/gitbook/src/intl/translations/no.ts b/packages/gitbook/src/intl/translations/no.ts
index f9bc27f09..d73d097f2 100644
--- a/packages/gitbook/src/intl/translations/no.ts
+++ b/packages/gitbook/src/intl/translations/no.ts
@@ -45,6 +45,7 @@ export const no: TranslationLanguage = {
     on_this_page: 'På denne siden',
     next_page: 'Neste',
     previous_page: 'Forrige',
+    toc_back_to_space: 'Tilbake til ${1}',
     page_last_modified: 'Sist oppdatert ${1}',
     was_this_helpful: 'Var dette nyttig?',
     was_this_helpful_positive: 'Ja, det var det!',
diff --git a/packages/gitbook/src/intl/translations/pl.ts b/packages/gitbook/src/intl/translations/pl.ts
index a7a8fa41d..af3f3a3ab 100644
--- a/packages/gitbook/src/intl/translations/pl.ts
+++ b/packages/gitbook/src/intl/translations/pl.ts
@@ -44,6 +44,7 @@ export const pl: TranslationLanguage = {
     on_this_page: 'Na tej stronie',
     next_page: 'Dalej',
     previous_page: 'Wstecz',
+    toc_back_to_space: 'Powrót do ${1}',
     page_last_modified: 'Ostatnia aktualizacja ${1}',
     was_this_helpful: 'Czy to było pomocne?',
     was_this_helpful_positive: 'Tak!',
diff --git a/packages/gitbook/src/intl/translations/pt-br.ts b/packages/gitbook/src/intl/translations/pt-br.ts
index fe067c70a..e04cee319 100644
--- a/packages/gitbook/src/intl/translations/pt-br.ts
+++ b/packages/gitbook/src/intl/translations/pt-br.ts
@@ -46,6 +46,7 @@ export const pt_br: TranslationLanguage = {
     on_this_page: 'Nesta página',
     next_page: 'Próximo',
     previous_page: 'Anterior',
+    toc_back_to_space: 'Voltar para ${1}',
     page_last_modified: 'Atualizado ${1}',
     was_this_helpful: 'Isto foi útil?',
     was_this_helpful_positive: 'Sim, foi!',
diff --git a/packages/gitbook/src/intl/translations/pt.ts b/packages/gitbook/src/intl/translations/pt.ts
index a9fe630ea..0e0752984 100644
--- a/packages/gitbook/src/intl/translations/pt.ts
+++ b/packages/gitbook/src/intl/translations/pt.ts
@@ -45,6 +45,7 @@ export const pt: TranslationLanguage = {
     on_this_page: 'Nesta página',
     next_page: 'Seguinte',
     previous_page: 'Anterior',
+    toc_back_to_space: 'Voltar para ${1}',
     page_last_modified: 'Última atualização ${1}',
     was_this_helpful: 'Isto foi útil?',
     was_this_helpful_positive: 'Sim, foi!',
diff --git a/packages/gitbook/src/intl/translations/ro.ts b/packages/gitbook/src/intl/translations/ro.ts
index 379f2ff51..d784d5977 100644
--- a/packages/gitbook/src/intl/translations/ro.ts
+++ b/packages/gitbook/src/intl/translations/ro.ts
@@ -45,6 +45,7 @@ export const ro: TranslationLanguage = {
     on_this_page: 'Pe această pagină',
     next_page: 'Următoarea',
     previous_page: 'Anterioara',
+    toc_back_to_space: 'Înapoi la ${1}',
     page_last_modified: 'Ultima actualizare ${1}',
     was_this_helpful: 'A fost util?',
     was_this_helpful_positive: 'Da, a fost!',
diff --git a/packages/gitbook/src/intl/translations/ru.ts b/packages/gitbook/src/intl/translations/ru.ts
index faf8f1111..dad75aa4c 100644
--- a/packages/gitbook/src/intl/translations/ru.ts
+++ b/packages/gitbook/src/intl/translations/ru.ts
@@ -46,6 +46,7 @@ export const ru: TranslationLanguage = {
     on_this_page: 'На этой странице',
     next_page: 'Следующая',
     previous_page: 'Предыдущая',
+    toc_back_to_space: 'Назад к ${1}',
     page_last_modified: 'Последнее обновление ${1}',
     was_this_helpful: 'Это было полезно?',
     was_this_helpful_positive: 'Да, было!',
diff --git a/packages/gitbook/src/intl/translations/sk.ts b/packages/gitbook/src/intl/translations/sk.ts
index da48a3be2..b48507f6c 100644
--- a/packages/gitbook/src/intl/translations/sk.ts
+++ b/packages/gitbook/src/intl/translations/sk.ts
@@ -45,6 +45,7 @@ export const sk: TranslationLanguage = {
     on_this_page: 'Na tejto stránke',
     next_page: 'Ďalej',
     previous_page: 'Predchádzajúca',
+    toc_back_to_space: 'Späť na ${1}',
     page_last_modified: 'Naposledy aktualizované ${1}',
     was_this_helpful: 'Bolo to užitočné?',
     was_this_helpful_positive: 'Áno, bolo!',
diff --git a/packages/gitbook/src/intl/translations/sl.ts b/packages/gitbook/src/intl/translations/sl.ts
index b3ae2b620..5517de6d8 100644
--- a/packages/gitbook/src/intl/translations/sl.ts
+++ b/packages/gitbook/src/intl/translations/sl.ts
@@ -45,6 +45,7 @@ export const sl: TranslationLanguage = {
     on_this_page: 'Na tej strani',
     next_page: 'Naslednja',
     previous_page: 'Prejšnja',
+    toc_back_to_space: 'Nazaj na ${1}',
     page_last_modified: 'Nazadnje posodobljeno ${1}',
     was_this_helpful: 'Je bilo to koristno?',
     was_this_helpful_positive: 'Da, bilo je!',
diff --git a/packages/gitbook/src/intl/translations/sv.ts b/packages/gitbook/src/intl/translations/sv.ts
index 0c375c5da..33096bec8 100644
--- a/packages/gitbook/src/intl/translations/sv.ts
+++ b/packages/gitbook/src/intl/translations/sv.ts
@@ -44,6 +44,7 @@ export const sv: TranslationLanguage = {
     on_this_page: 'På den här sidan',
     next_page: 'Nästa',
     previous_page: 'Föregående',
+    toc_back_to_space: 'Tillbaka till ${1}',
     page_last_modified: 'Senast uppdaterad ${1}',
     was_this_helpful: 'Var detta till hjälp?',
     was_this_helpful_positive: 'Ja, det var det!',
diff --git a/packages/gitbook/src/intl/translations/th.ts b/packages/gitbook/src/intl/translations/th.ts
index 36cd3f058..b225d5dee 100644
--- a/packages/gitbook/src/intl/translations/th.ts
+++ b/packages/gitbook/src/intl/translations/th.ts
@@ -43,6 +43,7 @@ export const th: TranslationLanguage = {
     on_this_page: 'ในหน้านี้',
     next_page: 'ถัดไป',
     previous_page: 'ก่อนหน้า',
+    toc_back_to_space: 'กลับไปที่ ${1}',
     page_last_modified: 'อัปเดตล่าสุด ${1}',
     was_this_helpful: 'สิ่งนี้มีประโยชน์หรือไม่?',
     was_this_helpful_positive: 'ใช่ มีประโยชน์!',
diff --git a/packages/gitbook/src/intl/translations/tr.ts b/packages/gitbook/src/intl/translations/tr.ts
index f819970ad..49c6d7c82 100644
--- a/packages/gitbook/src/intl/translations/tr.ts
+++ b/packages/gitbook/src/intl/translations/tr.ts
@@ -44,6 +44,7 @@ export const tr: TranslationLanguage = {
     on_this_page: 'Bu sayfada',
     next_page: 'Sonraki',
     previous_page: 'Önceki',
+    toc_back_to_space: 'Şuraya dön: ${1}',
     page_last_modified: 'Son güncelleme ${1}',
     was_this_helpful: 'Bu yararlı oldu mu?',
     was_this_helpful_positive: 'Evet, oldu!',
diff --git a/packages/gitbook/src/intl/translations/uk.ts b/packages/gitbook/src/intl/translations/uk.ts
index 9bec9bad0..ded36466c 100644
--- a/packages/gitbook/src/intl/translations/uk.ts
+++ b/packages/gitbook/src/intl/translations/uk.ts
@@ -44,6 +44,7 @@ export const uk: TranslationLanguage = {
     on_this_page: 'На цій сторінці',
     next_page: 'Наступна',
     previous_page: 'Попередня',
+    toc_back_to_space: 'Назад до ${1}',
     page_last_modified: 'Останнє оновлення ${1}',
     was_this_helpful: 'Це було корисно?',
     was_this_helpful_positive: 'Так, було!',
diff --git a/packages/gitbook/src/intl/translations/vi.ts b/packages/gitbook/src/intl/translations/vi.ts
index 8d5f587ef..bf94065e1 100644
--- a/packages/gitbook/src/intl/translations/vi.ts
+++ b/packages/gitbook/src/intl/translations/vi.ts
@@ -44,6 +44,7 @@ export const vi: TranslationLanguage = {
     on_this_page: 'Trên trang này',
     next_page: 'Tiếp theo',
     previous_page: 'Trước',
+    toc_back_to_space: 'Quay lại ${1}',
     page_last_modified: 'Cập nhật lần cuối ${1}',
     was_this_helpful: 'Nội dung này có hữu ích không?',
     was_this_helpful_positive: 'Có, hữu ích!',
diff --git a/packages/gitbook/src/intl/translations/yue.ts b/packages/gitbook/src/intl/translations/yue.ts
index 436b4f94f..bdfa51a2c 100644
--- a/packages/gitbook/src/intl/translations/yue.ts
+++ b/packages/gitbook/src/intl/translations/yue.ts
@@ -43,6 +43,7 @@ export const yue: TranslationLanguage = {
     on_this_page: '本頁內容',
     next_page: '下一頁',
     previous_page: '上一頁',
+    toc_back_to_space: '返去${1}',
     page_last_modified: '最後更新 ${1}',
     was_this_helpful: '呢個有冇幫助？',
     was_this_helpful_positive: '有，幫到手！',
diff --git a/packages/gitbook/src/intl/translations/zh-tw.ts b/packages/gitbook/src/intl/translations/zh-tw.ts
index 830e519f7..033f8afcf 100644
--- a/packages/gitbook/src/intl/translations/zh-tw.ts
+++ b/packages/gitbook/src/intl/translations/zh-tw.ts
@@ -43,6 +43,7 @@ export const zh_tw: TranslationLanguage = {
     on_this_page: '本頁內容',
     next_page: '下一頁',
     previous_page: '上一頁',
+    toc_back_to_space: '返回${1}',
     page_last_modified: '最後更新於 ${1}',
     was_this_helpful: '這有幫助嗎？',
     was_this_helpful_positive: '有，很有幫助！',
diff --git a/packages/gitbook/src/intl/translations/zh.ts b/packages/gitbook/src/intl/translations/zh.ts
index ff64c3071..64467d78c 100644
--- a/packages/gitbook/src/intl/translations/zh.ts
+++ b/packages/gitbook/src/intl/translations/zh.ts
@@ -44,6 +44,7 @@ export const zh: TranslationLanguage = {
     on_this_page: '在本页',
     next_page: '下一页',
     previous_page: '上一页',
+    toc_back_to_space: '返回${1}',
     page_last_modified: '最后更新于 ${1}',
     was_this_helpful: '这有帮助吗？',
     was_this_helpful_positive: '是的，很有帮助！',
diff --git a/packages/gitbook/src/lib/sites.ts b/packages/gitbook/src/lib/sites.ts
index aae773614..e02dfd3af 100644
--- a/packages/gitbook/src/lib/sites.ts
+++ b/packages/gitbook/src/lib/sites.ts
@@ -259,6 +259,33 @@ export function getLocalizedTitle(
     return getLocalizedField(entity.localizedTitle, currentLanguage) ?? entity.title;
 }
 
+/**
+ * A string concatenation of the site structure (sections and variants) titles for the
+ * current context, as shown in the site's navigation. Returns an empty string when the
+ * current space is the default section and variant (i.e. it has no distinguishing label).
+ */
+export function getSiteStructureTitle(context: GitBookSiteContext): string {
+    const { visibleSections: sections, siteSpace, visibleSiteSpaces: siteSpaces } = context;
+    const currentLanguage = context.locale;
+
+    const title = [];
+    if (
+        sections &&
+        sections.current.default === false && // Only if the current section is not the default one
+        sections.list.filter((section) => section.object === 'site-section').length > 1 // Only if there are multiple sections
+    ) {
+        title.push(getLocalizedTitle(sections.current, currentLanguage));
+    }
+    if (
+        siteSpaces.length > 1 && // Only if there are multiple variants
+        siteSpace.default === false && // Only if the variant is not the default one
+        siteSpaces.filter((space) => space.space.language === siteSpace.space.language).length > 1 // Only if there are multiple variants *for the current language*. This filters out spaces that are "just" translations of each other, not versions.
+    ) {
+        title.push(getLocalizedTitle(siteSpace, siteSpace.space.language));
+    }
+    return title.join(' ');
+}
+
 /**
  * Get the localized description for a site entity.
  */

From 37c2dd8819e228486dec5bb9a333913307cdd96d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Greg=20Berg=C3=A9?= <berge.greg@gmail.com>
Date: Sun, 5 Jul 2026 22:06:20 +0200
Subject: [PATCH 07/46] Fix flaky customer screenshots caused by the cookie
 banner (#4363)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/customer-goto-domcontentloaded.md  |   5 +
 .changeset/flaky-cookie-banner-screenshots.md |   5 +
 .../hide-admin-toolbar-in-screenshots.md      |   5 +
 .../reduced-motion-maxwidth-transition.md     |   5 +
 .changeset/reset-cross-space-nav-e2e.md       |   5 +
 bun.lock                                      |  94 ++++++++++--
 packages/gitbook/e2e/customers.spec.ts        | 142 +++++++++---------
 packages/gitbook/e2e/internal.spec.ts         |  26 ++--
 packages/gitbook/e2e/util.ts                  |  38 ++++-
 packages/gitbook/package.json                 |   4 +-
 .../src/components/AdminToolbar/Toolbar.tsx   |   5 +-
 .../components/SpaceLayout/SpaceLayout.tsx    |   2 +-
 packages/gitbook/tests/markdown.test.ts       |   2 +-
 13 files changed, 233 insertions(+), 105 deletions(-)
 create mode 100644 .changeset/customer-goto-domcontentloaded.md
 create mode 100644 .changeset/flaky-cookie-banner-screenshots.md
 create mode 100644 .changeset/hide-admin-toolbar-in-screenshots.md
 create mode 100644 .changeset/reduced-motion-maxwidth-transition.md
 create mode 100644 .changeset/reset-cross-space-nav-e2e.md

diff --git a/.changeset/customer-goto-domcontentloaded.md b/.changeset/customer-goto-domcontentloaded.md
new file mode 100644
index 000000000..c34b07ba3
--- /dev/null
+++ b/.changeset/customer-goto-domcontentloaded.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Navigate customer visual tests with `domcontentloaded` to avoid `load`-event hangs on external sites.
diff --git a/.changeset/flaky-cookie-banner-screenshots.md b/.changeset/flaky-cookie-banner-screenshots.md
new file mode 100644
index 000000000..8f3b9601a
--- /dev/null
+++ b/.changeset/flaky-cookie-banner-screenshots.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix flaky customer e2e screenshots by waiting for the built-in cookie banner before capturing.
diff --git a/.changeset/hide-admin-toolbar-in-screenshots.md b/.changeset/hide-admin-toolbar-in-screenshots.md
new file mode 100644
index 000000000..76d60b905
--- /dev/null
+++ b/.changeset/hide-admin-toolbar-in-screenshots.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add a `data-testid` to the admin toolbar so e2e tests can assert its presence while hiding it from visual screenshots (it animates open, causing flaky diffs).
diff --git a/.changeset/reduced-motion-maxwidth-transition.md b/.changeset/reduced-motion-maxwidth-transition.md
new file mode 100644
index 000000000..682519b53
--- /dev/null
+++ b/.changeset/reduced-motion-maxwidth-transition.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Disable the content max-width transition under reduced motion, matching the surrounding layout transitions.
diff --git a/.changeset/reset-cross-space-nav-e2e.md b/.changeset/reset-cross-space-nav-e2e.md
new file mode 100644
index 000000000..e343faac9
--- /dev/null
+++ b/.changeset/reset-cross-space-nav-e2e.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Reset cross-space navigation state between e2e navigations so the "Back to <space>" shortcut can't leak in and cause flaky screenshots.
diff --git a/bun.lock b/bun.lock
index 072d9c885..e6214a000 100644
--- a/bun.lock
+++ b/bun.lock
@@ -201,8 +201,8 @@
         "zustand": "^5.0.3",
       },
       "devDependencies": {
-        "@argos-ci/playwright": "^6.4.2",
-        "@playwright/test": "^1.58.2",
+        "@argos-ci/playwright": "^7.2.0",
+        "@playwright/test": "^1.61.1",
         "@scalar/api-client-react": "catalog:",
         "@tailwindcss/postcss": "^4.1.11",
         "@types/js-cookie": "^3.0.6",
@@ -392,15 +392,15 @@
 
     "@antfu/install-pkg": ["@antfu/install-pkg@1.1.0", "", { "dependencies": { "package-manager-detector": "^1.3.0", "tinyexec": "^1.0.1" } }, "sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ=="],
 
-    "@argos-ci/api-client": ["@argos-ci/api-client@0.16.0", "", { "dependencies": { "debug": "^4.4.3", "openapi-fetch": "^0.15.0" } }, "sha512-BG6g+AZABKN8W2syzfPWKhPxxrAB9Wjp2iNS11R4IskHDV6T41+qeQDpT88GOq6eUZ64Sjzoh/nXG+9EpNxtfw=="],
+    "@argos-ci/api-client": ["@argos-ci/api-client@0.24.0", "", { "dependencies": { "debug": "^4.4.3", "openapi-fetch": "^0.17.0", "p-retry": "^8.0.0" } }, "sha512-pWEkmqVyD2CbGGG9KsTQgufWIYRzMsZVWyLY4d3lI2pUbuTlv0W0pvvmJybmKkIk3Tcn1T5vMBjT2DYuUiZbqQ=="],
 
-    "@argos-ci/browser": ["@argos-ci/browser@5.1.2", "", {}, "sha512-eQqtM54Vh83++Dac5+7ml4YXKW/KnUHRQWjTZ+VGeXfOJdjnZa4JjfVL6fnFG6CKrXjCK5dd9gcZRmbVpbt8rA=="],
+    "@argos-ci/browser": ["@argos-ci/browser@6.3.0", "", {}, "sha512-quTww/Yhm2jv+Y6q6dD4xEpm9Bb/SrZNFJaXgncAnCvW8jNnCrmDE2+8zAuGUh41Wkq1JQNDYKlBCO/RpY6A8Q=="],
 
-    "@argos-ci/core": ["@argos-ci/core@5.1.1", "", { "dependencies": { "@argos-ci/api-client": "0.16.0", "@argos-ci/util": "3.2.0", "convict": "^6.2.4", "debug": "^4.4.3", "fast-glob": "^3.3.3", "mime-types": "^3.0.2", "sharp": "^0.34.5", "tmp": "^0.2.5" } }, "sha512-RI5pYb5wmWUoXzWefNCjKSqGA3BroUB2ac9awlYV3McJjSAW8nCGJUt2Eds90Shkp+i4S6KbMLnLG56slhTCsg=="],
+    "@argos-ci/core": ["@argos-ci/core@6.4.0", "", { "dependencies": { "@argos-ci/api-client": "0.24.0", "@argos-ci/util": "4.0.0", "convict": "^6.2.5", "debug": "^4.4.3", "fast-glob": "^3.3.3", "mime-types": "^3.0.2", "p-retry": "^8.0.0", "sharp": "^0.35.2", "tmp": "^0.2.7" } }, "sha512-YUySBUbjHpI8GZKe96n4VzgPPXl90hjw/GCHLQ3U6xbbIEZczCBCHeHB/MDjyXCHyk+9T7FUJSE0ddWnpDRI8Q=="],
 
-    "@argos-ci/playwright": ["@argos-ci/playwright@6.4.2", "", { "dependencies": { "@argos-ci/browser": "5.1.2", "@argos-ci/core": "5.1.1", "@argos-ci/util": "3.2.0", "chalk": "^5.6.2", "debug": "^4.4.3" } }, "sha512-0HE4rmgx2/znlMUi3z0Bp8OD7u7zNls9SlljL+qTVoWQRW22sDvpmRdZpjzb4pEjoe6onqPTDOqm5/f8QYHMwg=="],
+    "@argos-ci/playwright": ["@argos-ci/playwright@7.2.0", "", { "dependencies": { "@argos-ci/browser": "6.3.0", "@argos-ci/core": "6.4.0", "@argos-ci/util": "4.0.0", "chalk": "^5.6.2", "debug": "^4.4.3" } }, "sha512-YkZswuc+hZLC8sUUp6QPzZJSfZsxnbt+sfyZr5DWSHuz5g2XRxJ8oEsXJwFraDMYku5jwfAtqXvza1J3WUo6qA=="],
 
-    "@argos-ci/util": ["@argos-ci/util@3.2.0", "", {}, "sha512-/Bn0qCH8VsdPv5WB9TUEf3oTgsIqsTMUEjPVDopHLzKK+j7nQYGOF3MnN7VhBow82BXeStBfJCS3UiZ6cgxRlw=="],
+    "@argos-ci/util": ["@argos-ci/util@4.0.0", "", {}, "sha512-2yrJr81OVpa2TkvSjzGZlGv6SVqZcxF62AVk6M79aZ7nXkwWFg3tjA8awbFwn2mODI67gkP5FarAD29bzx3P3w=="],
 
     "@ast-grep/napi": ["@ast-grep/napi@0.40.5", "", { "optionalDependencies": { "@ast-grep/napi-darwin-arm64": "0.40.5", "@ast-grep/napi-darwin-x64": "0.40.5", "@ast-grep/napi-linux-arm64-gnu": "0.40.5", "@ast-grep/napi-linux-arm64-musl": "0.40.5", "@ast-grep/napi-linux-x64-gnu": "0.40.5", "@ast-grep/napi-linux-x64-musl": "0.40.5", "@ast-grep/napi-win32-arm64-msvc": "0.40.5", "@ast-grep/napi-win32-ia32-msvc": "0.40.5", "@ast-grep/napi-win32-x64-msvc": "0.40.5" } }, "sha512-hJA62OeBKUQT68DD2gDyhOqJxZxycqg8wLxbqjgqSzYttCMSDL9tiAQ9abgekBYNHudbJosm9sWOEbmCDfpX2A=="],
 
@@ -812,6 +812,8 @@
 
     "@img/sharp-darwin-x64": ["@img/sharp-darwin-x64@0.34.5", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-x64": "1.2.4" }, "os": "darwin", "cpu": "x64" }, "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw=="],
 
+    "@img/sharp-freebsd-wasm32": ["@img/sharp-freebsd-wasm32@0.35.3", "", { "dependencies": { "@img/sharp-wasm32": "0.35.3" }, "os": "freebsd" }, "sha512-lUxcqWIj2wMQ9BrwNjngcr1gWUr5xgaGThBRqPPalIC2n67Cqj1uPh8NnA/ZhAg8hUbKl+kVHKwgUIwe6ZYPrg=="],
+
     "@img/sharp-libvips-darwin-arm64": ["@img/sharp-libvips-darwin-arm64@1.2.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g=="],
 
     "@img/sharp-libvips-darwin-x64": ["@img/sharp-libvips-darwin-x64@1.2.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg=="],
@@ -850,6 +852,8 @@
 
     "@img/sharp-wasm32": ["@img/sharp-wasm32@0.34.5", "", { "dependencies": { "@emnapi/runtime": "^1.7.0" }, "cpu": "none" }, "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw=="],
 
+    "@img/sharp-webcontainers-wasm32": ["@img/sharp-webcontainers-wasm32@0.35.3", "", { "dependencies": { "@img/sharp-wasm32": "0.35.3" }, "cpu": "none" }, "sha512-2rnq7bX3NzeR2T4YWgz8qiG4h3TSdMe+vN1iQXpJleSJ3SM5zQ8Fy2SyyXAWlbxpEZ2Y+Z4u1BePgJEYbSy80Q=="],
+
     "@img/sharp-win32-arm64": ["@img/sharp-win32-arm64@0.34.5", "", { "os": "win32", "cpu": "arm64" }, "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g=="],
 
     "@img/sharp-win32-ia32": ["@img/sharp-win32-ia32@0.34.5", "", { "os": "win32", "cpu": "ia32" }, "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg=="],
@@ -1026,7 +1030,7 @@
 
     "@pkgjs/parseargs": ["@pkgjs/parseargs@0.11.0", "", {}, "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg=="],
 
-    "@playwright/test": ["@playwright/test@1.58.2", "", { "dependencies": { "playwright": "1.58.2" }, "bin": { "playwright": "cli.js" } }, "sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA=="],
+    "@playwright/test": ["@playwright/test@1.61.1", "", { "dependencies": { "playwright": "1.61.1" }, "bin": { "playwright": "cli.js" } }, "sha512-8nKv6+0RJSL9FE4jYOEGXnPeM/Hg12qZpmqzZjRh3qM0Y7c3z1mrOTfFLids72RDQYVh9WpLEfR5WdpNX4fkig=="],
 
     "@poppinss/colors": ["@poppinss/colors@4.1.5", "", { "dependencies": { "kleur": "^4.1.5" } }, "sha512-FvdDqtcRCtz6hThExcFOgW0cWX+xwSMWcRuQe5ZEb2m7cVQOAVZOIMt+/v9RxGiD9/OY16qJBXK4CVKWAPalBw=="],
 
@@ -2024,7 +2028,7 @@
 
     "convert-hrtime": ["convert-hrtime@3.0.0", "", {}, "sha512-7V+KqSvMiHp8yWDuwfww06XleMWVVB9b9tURBx+G7UTADuo5hYPuowKloz4OzOqbPezxgo+fdQ1522WzPG4OeA=="],
 
-    "convict": ["convict@6.2.4", "", { "dependencies": { "lodash.clonedeep": "^4.5.0", "yargs-parser": "^20.2.7" } }, "sha512-qN60BAwdMVdofckX7AlohVJ2x9UvjTNoKVXCL2LxFk1l7757EJqf1nySdMkPQer0bt8kQ5lQiyZ9/2NvrFBuwQ=="],
+    "convict": ["convict@6.2.5", "", { "dependencies": { "lodash.clonedeep": "^4.5.0", "yargs-parser": "^20.2.7" } }, "sha512-JtXpxqDqJ8P0UwEHwhxLzCIXQy97vlYBZR222Sbzb1q1Erex9ASrztJ29SyhWFQjod1AeFBaPzEEC8YvtZMIYg=="],
 
     "cookie": ["cookie@1.0.2", "", {}, "sha512-9Kr/j4O16ISv8zBBhJoi4bXOYNTkFLOqSL3UDB0njXxCXNezjeyVrJyGOWtgfs/q2km1gwBcfH8q1yEGoMYunA=="],
 
@@ -2908,11 +2912,11 @@
 
     "oniguruma-to-es": ["oniguruma-to-es@4.3.4", "", { "dependencies": { "oniguruma-parser": "^0.12.1", "regex": "^6.0.1", "regex-recursion": "^6.0.2" } }, "sha512-3VhUGN3w2eYxnTzHn+ikMI+fp/96KoRSVK9/kMTcFqj1NRDh2IhQCKvYxDnWePKRXY/AqH+Fuiyb7VHSzBjHfA=="],
 
-    "openapi-fetch": ["openapi-fetch@0.15.2", "", { "dependencies": { "openapi-typescript-helpers": "^0.0.15" } }, "sha512-rdYTzUmSsJevmNqg7fwUVGuKc2Gfb9h6ph74EVPkPfIGJaZTfqdIbJahtbJ3qg1LKinln30hqZniLnKpH0RJBg=="],
+    "openapi-fetch": ["openapi-fetch@0.17.0", "", { "dependencies": { "openapi-typescript-helpers": "^0.1.0" } }, "sha512-PsbZR1wAPcG91eEthKhN+Zn92FMHxv+/faECIwjXdxfTODGSGegYv0sc1Olz+HYPvKOuoXfp+0pA2XVt2cI0Ig=="],
 
     "openapi-types": ["openapi-types@12.1.3", "", {}, "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw=="],
 
-    "openapi-typescript-helpers": ["openapi-typescript-helpers@0.0.15", "", {}, "sha512-opyTPaunsklCBpTK8JGef6mfPhLSnyy5a0IN9vKtx3+4aExf+KxEqYwIy3hqkedXIB97u357uLMJsOnm3GVjsw=="],
+    "openapi-typescript-helpers": ["openapi-typescript-helpers@0.1.0", "", {}, "sha512-OKTGPthhivLw/fHz6c3OPtg72vi86qaMlqbJuVJ23qOvQ+53uw1n7HdmkJFibloF7QEjDrDkzJiOJuockM/ljw=="],
 
     "os-paths": ["os-paths@4.4.0", "", {}, "sha512-wrAwOeXp1RRMFfQY8Sy7VaGVmPocaLwSFOYCGKSyo8qmJ+/yaafCl5BCA1IQZWqFSRBrKDYFeR9d/VyQzfH/jg=="],
 
@@ -3322,7 +3326,7 @@
 
     "tldts-core": ["tldts-core@7.0.30", "", {}, "sha512-uiHN8PIB1VmWyS98eZYja4xzlYqeFZVjb4OuYlJQnZAuJhMw4PbKQOKgHKhBdJR3FE/t5mUQ1Kd80++B+qhD1Q=="],
 
-    "tmp": ["tmp@0.2.5", "", {}, "sha512-voyz6MApa1rQGUxT3E+BK7/ROe8itEx7vD8/HEvt4xwXucvQ5G5oeEiHkmHZJuBO21RpOf+YYm9MOivj709jow=="],
+    "tmp": ["tmp@0.2.7", "", {}, "sha512-e0votIpp4Uo2AJYSzVHV6xCcawuiez3DzqDAbrTc3YxBkplN6e+dM13ZeIcZnDg/QpSuU2zfZ3rzwY8ukEnaXw=="],
 
     "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
 
@@ -3538,6 +3542,8 @@
 
     "@argos-ci/core/mime-types": ["mime-types@3.0.2", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A=="],
 
+    "@argos-ci/core/sharp": ["sharp@0.35.3", "", { "dependencies": { "@img/colour": "^1.1.0", "detect-libc": "^2.1.2", "semver": "^7.8.5" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "0.35.3", "@img/sharp-darwin-x64": "0.35.3", "@img/sharp-freebsd-wasm32": "0.35.3", "@img/sharp-libvips-darwin-arm64": "1.3.2", "@img/sharp-libvips-darwin-x64": "1.3.2", "@img/sharp-libvips-linux-arm": "1.3.2", "@img/sharp-libvips-linux-arm64": "1.3.2", "@img/sharp-libvips-linux-ppc64": "1.3.2", "@img/sharp-libvips-linux-riscv64": "1.3.2", "@img/sharp-libvips-linux-s390x": "1.3.2", "@img/sharp-libvips-linux-x64": "1.3.2", "@img/sharp-libvips-linuxmusl-arm64": "1.3.2", "@img/sharp-libvips-linuxmusl-x64": "1.3.2", "@img/sharp-linux-arm": "0.35.3", "@img/sharp-linux-arm64": "0.35.3", "@img/sharp-linux-ppc64": "0.35.3", "@img/sharp-linux-riscv64": "0.35.3", "@img/sharp-linux-s390x": "0.35.3", "@img/sharp-linux-x64": "0.35.3", "@img/sharp-linuxmusl-arm64": "0.35.3", "@img/sharp-linuxmusl-x64": "0.35.3", "@img/sharp-webcontainers-wasm32": "0.35.3", "@img/sharp-win32-arm64": "0.35.3", "@img/sharp-win32-ia32": "0.35.3", "@img/sharp-win32-x64": "0.35.3" }, "peerDependencies": { "@types/node": "*" }, "optionalPeers": ["@types/node"] }, "sha512-ej0zVHuZGHCiABXcNxeYhpRnPNPAcvbG8RMdBAhDAxLKkCRVSpK3Iyu7qbqw3JMzoj0REeM6f3tJLtVwl0023Q=="],
+
     "@aws-crypto/crc32/@aws-sdk/types": ["@aws-sdk/types@3.734.0", "", { "dependencies": { "@smithy/types": "^4.1.0", "tslib": "^2.6.2" } }, "sha512-o11tSPTT70nAkGV1fN9wm/hAIiLPyWX6SuGf+9JyTp7S/rC2cFWhR26MvA69nplcjNaXVzB0f+QFrLXXjOqCrg=="],
 
     "@aws-crypto/crc32c/@aws-sdk/types": ["@aws-sdk/types@3.734.0", "", { "dependencies": { "@smithy/types": "^4.1.0", "tslib": "^2.6.2" } }, "sha512-o11tSPTT70nAkGV1fN9wm/hAIiLPyWX6SuGf+9JyTp7S/rC2cFWhR26MvA69nplcjNaXVzB0f+QFrLXXjOqCrg=="],
@@ -3630,6 +3636,10 @@
 
     "@hyperjump/json-schema/uuid": ["uuid@9.0.1", "", { "bin": { "uuid": "dist/bin/uuid" } }, "sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA=="],
 
+    "@img/sharp-freebsd-wasm32/@img/sharp-wasm32": ["@img/sharp-wasm32@0.35.3", "", { "dependencies": { "@emnapi/runtime": "^1.11.1" } }, "sha512-cZ0XkcYGpHZkqW6iCkqTcmUC0CD9DhD5d/qeZlZkfRBn6GnHniZXLUo5+9xw8Iv76YE6LQFN9YNBlKREcCG76w=="],
+
+    "@img/sharp-webcontainers-wasm32/@img/sharp-wasm32": ["@img/sharp-wasm32@0.35.3", "", { "dependencies": { "@emnapi/runtime": "^1.11.1" } }, "sha512-cZ0XkcYGpHZkqW6iCkqTcmUC0CD9DhD5d/qeZlZkfRBn6GnHniZXLUo5+9xw8Iv76YE6LQFN9YNBlKREcCG76w=="],
+
     "@isaacs/cliui/string-width": ["string-width@5.1.2", "", { "dependencies": { "eastasianwidth": "^0.2.0", "emoji-regex": "^9.2.2", "strip-ansi": "^7.0.1" } }, "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA=="],
 
     "@isaacs/cliui/strip-ansi": ["strip-ansi@7.1.0", "", { "dependencies": { "ansi-regex": "^6.0.1" } }, "sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ=="],
@@ -3682,7 +3692,7 @@
 
     "@oxc-transform/binding-wasm32-wasi/@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.1.1", "", { "dependencies": { "@emnapi/core": "^1.7.1", "@emnapi/runtime": "^1.7.1", "@tybys/wasm-util": "^0.10.1" } }, "sha512-p64ah1M1ld8xjWv3qbvFwHiFVWrq1yFvV4f7w+mzaqiR4IlSgkqhcRdHwsGgomwzBH51sRY4NEowLxnaBjcW/A=="],
 
-    "@playwright/test/playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
+    "@playwright/test/playwright": ["playwright@1.61.1", "", { "dependencies": { "playwright-core": "1.61.1" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ=="],
 
     "@poppinss/dumper/supports-color": ["supports-color@10.2.2", "", {}, "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g=="],
 
@@ -4288,6 +4298,58 @@
 
     "@argos-ci/core/mime-types/mime-db": ["mime-db@1.54.0", "", {}, "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ=="],
 
+    "@argos-ci/core/sharp/@img/colour": ["@img/colour@1.1.0", "", {}, "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ=="],
+
+    "@argos-ci/core/sharp/@img/sharp-darwin-arm64": ["@img/sharp-darwin-arm64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.3.2" }, "os": "darwin", "cpu": "arm64" }, "sha512-RMnFX7YQsMoh7lWfcM4NEHHymBX/rLuKNPVM84XE9ONPcaSCDgE7CHIHpSgPcO2xcRthgBy1HfNO319mwhIAkg=="],
+
+    "@argos-ci/core/sharp/@img/sharp-darwin-x64": ["@img/sharp-darwin-x64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-x64": "1.3.2" }, "os": "darwin", "cpu": "x64" }, "sha512-Xo+5uFBtLN0BKqieTxiFzFPQAUlBbbH5iBKyRX/z1JrbnYsHTfKJnUfL8+p2TPXr1pXqao4eeL4Rl144uDpK9w=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-darwin-arm64": ["@img/sharp-libvips-darwin-arm64@1.3.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-9J6ypZFpQBj4YnePGoq/S38w6nz+vqg5WZLrLGY4YuSemdMq47GMLBPO42MzwdGwpg/agZ7xzZcFHa48xlywfg=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-darwin-x64": ["@img/sharp-libvips-darwin-x64@1.3.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-m2pW1n6cns9VaubNwsZ+c3CRYjxNQWgJ5gPlnL1nbBcpkBvFm6SCFN5o0psFHI8w9n11NKhFkeEDns98tiqbEw=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-linux-arm": ["@img/sharp-libvips-linux-arm@1.3.2", "", { "os": "linux", "cpu": "arm" }, "sha512-1eMLzy92I4J6rmi4mAT8yC3HxOtniyGELlzGbNMLLeqe052ahFQ0h6LFq+lh5DsDIdYViIDst08abvSbcEdLXQ=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-linux-arm64": ["@img/sharp-libvips-linux-arm64@1.3.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-dqVSFynCox4C/J8kT16V7SIFAns0IjgLwkvYT7p8LQVmJ5OS5b6tI9IGflxTeuBS//zXeFIUbwt5dwxyZ17cnA=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-linux-ppc64": ["@img/sharp-libvips-linux-ppc64@1.3.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-3z0NHDxD6n5I9gc05U1eW1AyRm+Gznzq3naMrthPNqE6oYykcogW0l/jfpJdjYnuNl8R7yI9pNbE1XiUeyq0Aw=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-linux-riscv64": ["@img/sharp-libvips-linux-riscv64@1.3.2", "", { "os": "linux", "cpu": "none" }, "sha512-bsb4rI+NldGOsXuej2r8OdSS8+zXDVaCWxyWrcv6kneTOlgAHtZABRzBBCwdsPiD90J4myNJuHpg6kA20ImW/w=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-linux-s390x": ["@img/sharp-libvips-linux-s390x@1.3.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-/ABshyj8gCpyIrNXnHn4LorDJ0HHm1VhXPBlxZ8zAtfVPAaSafXPGn+sUSIRiwaSBy0mmFjSjiXI5mkcwdChKQ=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-linux-x64": ["@img/sharp-libvips-linux-x64@1.3.2", "", { "os": "linux", "cpu": "x64" }, "sha512-ITPEtgffGJ0S6G9dRyw/366tJQqFRcHWPHhC+Stpg3Z8AEMrDrTr2lhdz4f/Y/HMbRh//7Z5mBzEpVdi62Oc3w=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-linuxmusl-arm64": ["@img/sharp-libvips-linuxmusl-arm64@1.3.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-zE9EdiUzUmg5mDT5a1rk5fYJ6GWPloTwWBYDS14naqHsL+EaMpDj1AWnpLgh3u0YCORv2Tt50wrcrpYqkP97Kw=="],
+
+    "@argos-ci/core/sharp/@img/sharp-libvips-linuxmusl-x64": ["@img/sharp-libvips-linuxmusl-x64@1.3.2", "", { "os": "linux", "cpu": "x64" }, "sha512-m0lrLiUt+lBYnCFr8qV/65yMR4E/c7/wf78I5eKTdkEakFAlZ9QlzEM3QIhhAwVeUhLAHLcCq7a7Vszq/oFNZQ=="],
+
+    "@argos-ci/core/sharp/@img/sharp-linux-arm": ["@img/sharp-linux-arm@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-arm": "1.3.2" }, "os": "linux", "cpu": "arm" }, "sha512-affVWCTLooy8TSxbDx2qkzuDeaWLNVBA+P//FNBirHsXpP2fuBhk5AuboYUnrDnzoXes8GFjpTx0SBFOCRg+FA=="],
+
+    "@argos-ci/core/sharp/@img/sharp-linux-arm64": ["@img/sharp-linux-arm64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-arm64": "1.3.2" }, "os": "linux", "cpu": "arm64" }, "sha512-QgKDspHPnrU+GQ55XPhGwyhC8acLVOOSyAvo1oVfFmrIXLkDNmGWzAfDZ4xK8oSA1qBQrALcHX0G5UZni/SuFQ=="],
+
+    "@argos-ci/core/sharp/@img/sharp-linux-ppc64": ["@img/sharp-linux-ppc64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-ppc64": "1.3.2" }, "os": "linux", "cpu": "ppc64" }, "sha512-sMd8rDxmpLOwv/7N44klFjOD5DUO7FLdjiXDI0hoxYaf7Ar262dQIEkosE98bps+5HPLtp/EvNqeqQtOycP/IA=="],
+
+    "@argos-ci/core/sharp/@img/sharp-linux-riscv64": ["@img/sharp-linux-riscv64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-riscv64": "1.3.2" }, "os": "linux", "cpu": "none" }, "sha512-0Eob78yjlYPfL5vMNWAW55l3R9Y6BQS/gOfe0ZcP9mEz9ohhKSt4im1hayiknXgf8AWrFqMvJcKIdmLmEe7yeQ=="],
+
+    "@argos-ci/core/sharp/@img/sharp-linux-s390x": ["@img/sharp-linux-s390x@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-s390x": "1.3.2" }, "os": "linux", "cpu": "s390x" }, "sha512-KgAxQ0DxpNOq1rG2t5cgTgShJFGSuU7XO45cqC+1NVOuZnP6tlgZRuSYOfNupGkHID0o3cJOsw4DVeJpMovcGw=="],
+
+    "@argos-ci/core/sharp/@img/sharp-linux-x64": ["@img/sharp-linux-x64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-x64": "1.3.2" }, "os": "linux", "cpu": "x64" }, "sha512-8pqvxubL2PGdhlPy6GLqzDYMUjyRmKAwKHYKixpdJYBUK7PJ0C029XdsnpFIdgRZG68fZiGdHVWcKPvtiPB4cA=="],
+
+    "@argos-ci/core/sharp/@img/sharp-linuxmusl-arm64": ["@img/sharp-linuxmusl-arm64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linuxmusl-arm64": "1.3.2" }, "os": "linux", "cpu": "arm64" }, "sha512-Vz0iQjzzcSX3HCbfwFfCSG/9SCIqyO0mH2sXyiHaAYfBk0cRsCWXRyQYX0ovCK/PAQBbTzQ0dsPQHh5MAFL59w=="],
+
+    "@argos-ci/core/sharp/@img/sharp-linuxmusl-x64": ["@img/sharp-linuxmusl-x64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linuxmusl-x64": "1.3.2" }, "os": "linux", "cpu": "x64" }, "sha512-6O1NPKcDVj9QEdg7Hx549EX8U0rp6yXQERqru6yRN7fGBn32UvIRJUlWnk+8xDCiG76hXVBbX82NZ/ZKr0euIg=="],
+
+    "@argos-ci/core/sharp/@img/sharp-win32-arm64": ["@img/sharp-win32-arm64@0.35.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-4bPwFdMbeC4JQ8L8LOyWp6nsHcboP5fxkp6iPOXz2Vg49R42TuMs2whkJ5OAP4/Ul035qOzy0AecOF9VOscn4w=="],
+
+    "@argos-ci/core/sharp/@img/sharp-win32-ia32": ["@img/sharp-win32-ia32@0.35.3", "", { "os": "win32", "cpu": "ia32" }, "sha512-r53mXsBN6lFUDiST764SvgwUdHAqM4rPAiDzAmf4fLoB6X/rkfyTrLCg6+g17wJJiCmB3JYgHuUldCWUIRFSXw=="],
+
+    "@argos-ci/core/sharp/@img/sharp-win32-x64": ["@img/sharp-win32-x64@0.35.3", "", { "os": "win32", "cpu": "x64" }, "sha512-D4y1vNeZrIIJCN+uHaWVtH86B+aCrdMYYjicy9pXHvbGZeGYLLSd3wdVuC37FxVXlU1ARsk84eKWfWMXGYEqvA=="],
+
+    "@argos-ci/core/sharp/detect-libc": ["detect-libc@2.1.2", "", {}, "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ=="],
+
+    "@argos-ci/core/sharp/semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="],
+
     "@aws-crypto/crc32/@aws-sdk/types/@smithy/types": ["@smithy/types@4.1.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-enhjdwp4D7CXmwLtD6zbcDMbo6/T6WtuuKCY49Xxc6OMOmUWlBEBDREsxxgV2LIdeQPW756+f97GzcgAwp3iLw=="],
 
     "@aws-crypto/crc32c/@aws-sdk/types/@smithy/types": ["@smithy/types@4.1.0", "", { "dependencies": { "tslib": "^2.6.2" } }, "sha512-enhjdwp4D7CXmwLtD6zbcDMbo6/T6WtuuKCY49Xxc6OMOmUWlBEBDREsxxgV2LIdeQPW756+f97GzcgAwp3iLw=="],
@@ -4332,6 +4394,10 @@
 
     "@headlessui/react/@floating-ui/react/@floating-ui/react-dom": ["@floating-ui/react-dom@2.1.7", "", { "dependencies": { "@floating-ui/dom": "^1.7.5" }, "peerDependencies": { "react": ">=16.8.0", "react-dom": ">=16.8.0" } }, "sha512-0tLRojf/1Go2JgEVm+3Frg9A3IW8bJgKgdO0BN5RkF//ufuz2joZM63Npau2ff3J6lUVYgDSNzNkR+aH3IVfjg=="],
 
+    "@img/sharp-freebsd-wasm32/@img/sharp-wasm32/@emnapi/runtime": ["@emnapi/runtime@1.11.2", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA=="],
+
+    "@img/sharp-webcontainers-wasm32/@img/sharp-wasm32/@emnapi/runtime": ["@emnapi/runtime@1.11.2", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA=="],
+
     "@isaacs/cliui/string-width/emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],
 
     "@isaacs/cliui/strip-ansi/ansi-regex": ["ansi-regex@6.1.0", "", {}, "sha512-7HSX4QQb4CspciLpVFwyRe79O3xsIZDDLER21kERQ71oaPodF8jL725AgJMFAYbooIqolJoRLuM81SpeUkpkvA=="],
@@ -4370,7 +4436,7 @@
 
     "@playwright/test/playwright/fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
 
-    "@playwright/test/playwright/playwright-core": ["playwright-core@1.58.2", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg=="],
+    "@playwright/test/playwright/playwright-core": ["playwright-core@1.61.1", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg=="],
 
     "@radix-ui/react-arrow/@radix-ui/react-primitive/@radix-ui/react-slot": ["@radix-ui/react-slot@1.2.3", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.2" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A=="],
 
diff --git a/packages/gitbook/e2e/customers.spec.ts b/packages/gitbook/e2e/customers.spec.ts
index 422e99ee4..afd5410e0 100644
--- a/packages/gitbook/e2e/customers.spec.ts
+++ b/packages/gitbook/e2e/customers.spec.ts
@@ -65,11 +65,12 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://docs.gmgn.ai',
         tests: [{ name: 'Home', url: '/' }],
     },
-    {
-        name: 'docs.portainer.io',
-        contentBaseURL: 'https://docs.portainer.io',
-        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
-    },
+    // Removed, an AI widget, makes it flaky.
+    // {
+    //     name: 'docs.portainer.io',
+    //     contentBaseURL: 'https://docs.portainer.io',
+    //     tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
+    // },
     {
         name: 'docs.chirptoken.io',
         contentBaseURL: 'https://docs.chirptoken.io',
@@ -133,7 +134,7 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.tickettool.xyz',
         contentBaseURL: 'https://docs.tickettool.xyz',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'wiki.redmodding.org',
@@ -167,11 +168,6 @@ const testCases: TestsCase[] = [
             },
         ],
     },
-    {
-        name: 'sosovalue-white-paper.gitbook.io',
-        contentBaseURL: 'https://sosovalue-white-paper.gitbook.io',
-        tests: [{ name: 'Home', url: '/' }],
-    },
     {
         name: 'chartschool.stockcharts.com',
         contentBaseURL: 'https://chartschool.stockcharts.com',
@@ -180,18 +176,13 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.soniclabs.com',
         contentBaseURL: 'https://docs.soniclabs.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.thousandeyes.com',
         contentBaseURL: 'https://docs.thousandeyes.com',
         tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
-    {
-        name: 'docs.raydium.io',
-        contentBaseURL: 'https://docs.raydium.io',
-        tests: [{ name: 'Home', url: '/' }],
-    },
     {
         name: 'docs.fluentbit.io',
         contentBaseURL: 'https://docs.fluentbit.io',
@@ -214,17 +205,17 @@ const testCases: TestsCase[] = [
     {
         name: 'unsloth.ai/docs',
         contentBaseURL: 'https://unsloth.ai',
-        tests: [{ name: 'Home', url: '/docs' }],
+        tests: [{ name: 'Home', url: '/docs', run: waitForCookiesDialog }],
     },
     {
         name: 'mariadb.com/docs',
         contentBaseURL: 'https://mariadb.com',
-        tests: [{ name: 'Home', url: '/docs' }],
+        tests: [{ name: 'Home', url: '/docs', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.n8n.io',
         contentBaseURL: 'https://docs.n8n.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.cherry-ai.com',
@@ -234,17 +225,17 @@ const testCases: TestsCase[] = [
     {
         name: 'library.zoom.com',
         contentBaseURL: 'https://library.zoom.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'help.verkada.com',
         contentBaseURL: 'https://help.verkada.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.overleaf.com',
         contentBaseURL: 'https://docs.overleaf.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'wiki.tiltedphoques.com/tilted-online',
@@ -259,27 +250,27 @@ const testCases: TestsCase[] = [
     {
         name: 'kakaobusiness.gitbook.io/main',
         contentBaseURL: 'https://kakaobusiness.gitbook.io',
-        tests: [{ name: 'Home', url: '/main' }],
+        tests: [{ name: 'Home', url: '/main', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.maestro.dev',
         contentBaseURL: 'https://docs.maestro.dev',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'developers.oxylabs.io',
         contentBaseURL: 'https://developers.oxylabs.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.parallels.com/landing',
         contentBaseURL: 'https://docs.parallels.com',
-        tests: [{ name: 'Home', url: '/landing' }],
+        tests: [{ name: 'Home', url: '/landing', run: waitForCookiesDialog }],
     },
     {
         name: 'help.impact.com',
         contentBaseURL: 'https://help.impact.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.9proxy.com',
@@ -299,7 +290,7 @@ const testCases: TestsCase[] = [
     {
         name: 'help.aikido.dev',
         contentBaseURL: 'https://help.aikido.dev',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'doc.demarche.numerique.gouv.fr',
@@ -319,17 +310,17 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.triumpharcade.com',
         contentBaseURL: 'https://docs.triumpharcade.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.nats.io',
         contentBaseURL: 'https://docs.nats.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'help.glpi-project.org',
         contentBaseURL: 'https://help.glpi-project.org',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.waydro.id',
@@ -349,38 +340,39 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.pinot.apache.org',
         contentBaseURL: 'https://docs.pinot.apache.org',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.devolutions.net',
         contentBaseURL: 'https://docs.devolutions.net',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'guides.gresb.com',
         contentBaseURL: 'https://guides.gresb.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.prestashop-project.org/welcome',
         contentBaseURL: 'https://docs.prestashop-project.org',
-        tests: [{ name: 'Home', url: '/welcome' }],
+        tests: [{ name: 'Home', url: '/welcome', run: waitForCookiesDialog }],
     },
     {
         name: 'help.researchgate.net',
         contentBaseURL: 'https://help.researchgate.net',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.verifone.com',
         contentBaseURL: 'https://docs.verifone.com',
-        tests: [{ name: 'Home', url: '/' }],
-    },
-    {
-        name: 'docs.roboflow.com',
-        contentBaseURL: 'https://docs.roboflow.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
+    // Deactivate it because of a custom Ask AI that causes flakiness.
+    // {
+    //     name: 'docs.roboflow.com',
+    //     contentBaseURL: 'https://docs.roboflow.com',
+    //     tests: [{ name: 'Home', url: '/' }],
+    // },
     {
         name: 'www.netexec.wiki',
         contentBaseURL: 'https://www.netexec.wiki',
@@ -395,42 +387,43 @@ const testCases: TestsCase[] = [
         name: 'gitbook.com/docs',
         contentBaseURL: 'https://gitbook.com',
         tests: [
-            { name: 'Home', url: '/docs' },
+            { name: 'Home', url: '/docs', run: waitForCookiesDialog },
             {
                 name: 'OpenAPI',
                 url: '/docs/developers/gitbook-api/api-reference/docs-sites/site-ai-ask',
+                run: waitForCookiesDialog,
             },
         ],
     },
     {
         name: 'documentation.gravitee.io',
         contentBaseURL: 'https://documentation.gravitee.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'faq.wanttopay.net/wanttopay-app',
         contentBaseURL: 'https://faq.wanttopay.net',
-        tests: [{ name: 'Home', url: '/wanttopay-app' }],
+        tests: [{ name: 'Home', url: '/wanttopay-app', run: waitForCookiesDialog }],
     },
     {
         name: 'guide.prismlive.com',
         contentBaseURL: 'https://guide.prismlive.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.ionos.com/cloud',
         contentBaseURL: 'https://docs.ionos.com',
-        tests: [{ name: 'Home', url: '/cloud' }],
+        tests: [{ name: 'Home', url: '/cloud', run: waitForCookiesDialog }],
     },
     {
         name: 'support.evite.com',
         contentBaseURL: 'https://support.evite.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'knowledge.illumina.com',
         contentBaseURL: 'https://knowledge.illumina.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'wiki.retrobat.org',
@@ -440,7 +433,7 @@ const testCases: TestsCase[] = [
     {
         name: 'wiki.polymaker.com',
         contentBaseURL: 'https://wiki.polymaker.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.ducks-services.com',
@@ -450,7 +443,7 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.hex-rays.com',
         contentBaseURL: 'https://docs.hex-rays.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'whitepaper.interlinklabs.ai',
@@ -460,7 +453,7 @@ const testCases: TestsCase[] = [
     {
         name: 'help.openloyalty.io',
         contentBaseURL: 'https://help.openloyalty.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'retrozia.gitbook.io/retrozia',
@@ -470,17 +463,17 @@ const testCases: TestsCase[] = [
     {
         name: 'helpcenter.channable.com',
         contentBaseURL: 'https://helpcenter.channable.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'developerdocs.instructure.com',
         contentBaseURL: 'https://developerdocs.instructure.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'legal.jagex.com',
         contentBaseURL: 'https://legal.jagex.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'manual.edgetx.org',
@@ -490,17 +483,18 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.cortex.io',
         contentBaseURL: 'https://docs.cortex.io',
-        tests: [{ name: 'Home', url: '/' }],
-    },
-    {
-        name: 'docs.mufy.ai',
-        contentBaseURL: 'https://docs.mufy.ai',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
+    // Flaky because of the GIF
+    // {
+    //     name: 'docs.mufy.ai',
+    //     contentBaseURL: 'https://docs.mufy.ai',
+    //     tests: [{ name: 'Home', url: '/' }],
+    // },
     {
         name: 'docs.ndi.video/all',
         contentBaseURL: 'https://docs.ndi.video',
-        tests: [{ name: 'Home', url: '/all' }],
+        tests: [{ name: 'Home', url: '/all', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.sevenpens.com/drawtab',
@@ -515,7 +509,7 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.holybro.com',
         contentBaseURL: 'https://docs.holybro.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'help.tokenpocket.pro/en',
@@ -530,7 +524,7 @@ const testCases: TestsCase[] = [
     {
         name: 'tools.osintnewsletter.com',
         contentBaseURL: 'https://tools.osintnewsletter.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'wiki.mmorealms.gg',
@@ -540,7 +534,7 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.vectra.ai',
         contentBaseURL: 'https://docs.vectra.ai',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.cipp.app',
@@ -565,32 +559,32 @@ const testCases: TestsCase[] = [
     {
         name: 'docs.patchmypc.com',
         contentBaseURL: 'https://docs.patchmypc.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'guide.cryosparc.com',
         contentBaseURL: 'https://guide.cryosparc.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'guides.stellaraio.com/stellar',
         contentBaseURL: 'https://guides.stellaraio.com',
-        tests: [{ name: 'Home', url: '/stellar' }],
+        tests: [{ name: 'Home', url: '/stellar', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.iyzico.com',
         contentBaseURL: 'https://docs.iyzico.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'help.wotnot.io',
         contentBaseURL: 'https://help.wotnot.io',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.sportmonks.com/v3',
         contentBaseURL: 'https://docs.sportmonks.com',
-        tests: [{ name: 'Home', url: '/v3' }],
+        tests: [{ name: 'Home', url: '/v3', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.payments.thalescloud.io',
@@ -600,12 +594,12 @@ const testCases: TestsCase[] = [
     {
         name: 'doc.anytype.io/anytype-docs',
         contentBaseURL: 'https://doc.anytype.io',
-        tests: [{ name: 'Home', url: '/anytype-docs' }],
+        tests: [{ name: 'Home', url: '/anytype-docs', run: waitForCookiesDialog }],
     },
     {
         name: 'help.blotato.com',
         contentBaseURL: 'https://help.blotato.com',
-        tests: [{ name: 'Home', url: '/' }],
+        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
         name: 'docs.cartographer3d.com',
diff --git a/packages/gitbook/e2e/internal.spec.ts b/packages/gitbook/e2e/internal.spec.ts
index 77a86956f..77ee57d9d 100644
--- a/packages/gitbook/e2e/internal.spec.ts
+++ b/packages/gitbook/e2e/internal.spec.ts
@@ -32,6 +32,7 @@ import {
     runTestCases,
     setTimeToMorning,
     waitForAIChatResponse,
+    waitForAdminToolbar,
     waitForCookiesDialog,
     waitForCoverImages,
     waitForNotFound,
@@ -612,21 +613,19 @@ const testCases: TestsCase[] = [
                 name: 'Site with sections and section groups',
                 url: '',
             },
-            {
-                name: 'Section group dropdown',
-                url: '',
-                run: async (page) => {
-                    await page.getByRole('button', { name: 'Test Section Group 1' }).hover();
-                    await expect(page.getByRole('link', { name: /Section B/ })).toBeVisible();
-                },
-            },
             {
                 name: 'Section group link',
                 url: '',
                 screenshot: false,
                 run: async (page) => {
-                    const sectionGroupDropdown = await page.getByText('Test Section Group 1');
-                    await sectionGroupDropdown.hover();
+                    const trigger = page.getByRole('button', { name: 'Test Section Group 1' });
+                    // Radix NavigationMenu opens the dropdown on a `pointermove`. A single
+                    // synthetic hover can land before hydration and be lost, so re-hover
+                    // until the dropdown content actually appears.
+                    await expect(async () => {
+                        await trigger.hover();
+                        await expect(page.getByText('Section B')).toBeVisible({ timeout: 1000 });
+                    }).toPass({ timeout: 15000 });
                     await page.getByText('Section B').click();
                     await page.waitForURL((url) => url.pathname.includes('/sections/sections-4'));
                 },
@@ -656,7 +655,12 @@ const testCases: TestsCase[] = [
             {
                 name: 'Revision',
                 url: '~/revisions/S55pwsEr5UVoroaOiWnP/blocks/headings',
-                run: waitForCookiesDialog,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+                    // Viewing a past revision shows the admin toolbar; assert it is
+                    // present (it is hidden from the screenshot as it animates open).
+                    await waitForAdminToolbar(page);
+                },
             },
             {
                 name: 'Invalid revision',
diff --git a/packages/gitbook/e2e/util.ts b/packages/gitbook/e2e/util.ts
index 9b170e78c..402f4aede 100644
--- a/packages/gitbook/e2e/util.ts
+++ b/packages/gitbook/e2e/util.ts
@@ -172,6 +172,19 @@ export async function waitForCookiesDialog(page: Page) {
     });
 }
 
+/**
+ * Wait for the GitBook admin toolbar to be present.
+ *
+ * The toolbar only renders when signed in to GitBook. It is hidden from
+ * screenshots (see `argosCSS`) because it auto-expands with an animation, so
+ * use this to assert it is rendered without capturing its flaky visual state.
+ */
+export async function waitForAdminToolbar(page: Page) {
+    await expect(page.getByTestId('admin-toolbar')).toBeVisible({
+        timeout: 10_000,
+    });
+}
+
 export async function waitForNotFound(_page: Page, response: Response | null) {
     expect(response).not.toBeNull();
     expect(response?.status()).toBe(404);
@@ -248,6 +261,19 @@ export function runTestCases(testCases: TestsCase[]) {
                         );
                     }
 
+                    // Reset the cross-space navigation state on every document load so the
+                    // "Back to <space>" shortcut never leaks between navigations/tests. It is
+                    // detected client-side from this sessionStorage, and a stale value (e.g.
+                    // after a retry or a cross-space redirect) makes it appear or not
+                    // non-deterministically, causing flaky screenshots.
+                    await page.addInitScript(() => {
+                        try {
+                            sessionStorage.removeItem('gitbook-space-navigation:last');
+                            sessionStorage.removeItem('gitbook-space-navigation:back');
+                            sessionStorage.removeItem('gitbook-space-navigation:from-picker');
+                        } catch {}
+                    });
+
                     // Set the header to disable the Vercel toolbar
                     // But only on the main document as it'd cause CORS issues on other resources
                     await page.route('**/*', async (route, request) => {
@@ -263,7 +289,11 @@ export function runTestCases(testCases: TestsCase[]) {
                         }
                     });
 
-                    const response = await page.goto(url);
+                    // Wait only for `domcontentloaded` rather than the default `load`: these
+                    // are real customer sites whose third-party subresources can hang and
+                    // never fire `load`, aborting the navigation. Argos stabilization (run in
+                    // `beforeScreenshot`) still waits for images/fonts before capturing.
+                    const response = await page.goto(url, { waitUntil: 'domcontentloaded' });
                     if (testEntry.run) {
                         await testEntry.run(page, response);
                     }
@@ -283,6 +313,12 @@ export function runTestCases(testCases: TestsCase[]) {
                             /* Hide Intercom */
                             .intercom-lightweight-app {
                                 display: none !important;
+                            }
+                            /* Hide the GitBook admin toolbar: it auto-expands with an
+                               animation, so its state at capture time is non-deterministic.
+                               Its presence is asserted separately via waitForAdminToolbar. */
+                            [data-testid="admin-toolbar"] {
+                                display: none !important;
                             }
                                 `,
                                 threshold: screenshotOptions?.threshold ?? undefined,
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index eb46bcf3e..37a97b527 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -93,8 +93,8 @@
         "zustand": "^5.0.3"
     },
     "devDependencies": {
-        "@argos-ci/playwright": "^6.4.2",
-        "@playwright/test": "^1.58.2",
+        "@argos-ci/playwright": "^7.2.0",
+        "@playwright/test": "^1.61.1",
         "@scalar/api-client-react": "catalog:",
         "@tailwindcss/postcss": "^4.1.11",
         "@types/js-cookie": "^3.0.6",
diff --git a/packages/gitbook/src/components/AdminToolbar/Toolbar.tsx b/packages/gitbook/src/components/AdminToolbar/Toolbar.tsx
index 8b62699a6..93f70d63a 100644
--- a/packages/gitbook/src/components/AdminToolbar/Toolbar.tsx
+++ b/packages/gitbook/src/components/AdminToolbar/Toolbar.tsx
@@ -105,7 +105,10 @@ export function Toolbar(props: ToolbarProps) {
     }
 
     return (
-        <motion.div className="-translate-x-1/2 fixed bottom-5 left-1/2 z-40 w-auto max-w-xl transform px-4">
+        <motion.div
+            data-testid="admin-toolbar"
+            className="-translate-x-1/2 fixed bottom-5 left-1/2 z-40 w-auto max-w-xl transform px-4"
+        >
             <ToolbarVisibilityHint show={showHint} />
 
             <AnimatePresence mode="wait">
diff --git a/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx b/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
index ae3e69456..a516cba1a 100644
--- a/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
+++ b/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
@@ -141,7 +141,7 @@ export function SpaceLayout(props: SpaceLayoutProps) {
                         'lg:flex-row',
                         'lg:justify-center',
                         CONTAINER_STYLE,
-                        'transition-[max-width] duration-300',
+                        'transition-[max-width] duration-300 motion-reduce:transition-none',
 
                         !withTopHeader || variants.generic.length > 1
                             ? 'has-sidebar'
diff --git a/packages/gitbook/tests/markdown.test.ts b/packages/gitbook/tests/markdown.test.ts
index 0360e675f..d2d55b676 100644
--- a/packages/gitbook/tests/markdown.test.ts
+++ b/packages/gitbook/tests/markdown.test.ts
@@ -191,7 +191,7 @@ describe('markdown ask responses', () => {
             expect(response.headers.get('x-robots-tag')).toBe('noindex');
             expect(text).toContain(ASK_QUESTION_HEADING);
         },
-        { timeout: 30_000 }
+        { timeout: 60_000 }
     );
 
     it(

From 139b897521bb2312c1b04ed17f8486594ac72e07 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Mon, 6 Jul 2026 11:03:39 +0200
Subject: [PATCH 08/46] Improve language selector on mobile (#4361)

---
 .../gitbook/src/components/Header/Header.tsx  |  4 +-
 .../src/components/Header/SpacesDropdown.tsx  | 41 ++++++++++---------
 .../components/SpaceLayout/SpaceLayout.tsx    |  3 +-
 3 files changed, 26 insertions(+), 22 deletions(-)

diff --git a/packages/gitbook/src/components/Header/Header.tsx b/packages/gitbook/src/components/Header/Header.tsx
index ae04b9390..b4c791047 100644
--- a/packages/gitbook/src/components/Header/Header.tsx
+++ b/packages/gitbook/src/components/Header/Header.tsx
@@ -196,7 +196,7 @@ export async function Header(props: {
                                             ) ?? siteSpace
                                         }
                                         siteSpaces={variants.translations}
-                                        className="flex! site-header:theme-bold:text-header-link hover:site-header:theme-bold:bg-header-link/3 focus-visible:site-header:theme-bold:bg-header-link/3 aria-expanded:site-header:theme-bold:bg-header-link/5"
+                                        className="flex! -mx-3 site-header:theme-bold:text-header-link hover:site-header:theme-bold:bg-header-link/3 focus-visible:site-header:theme-bold:bg-header-link/3 aria-expanded:site-header:theme-bold:bg-header-link/5"
                                     />
                                 ) : null}
                             </HeaderLinks>
@@ -217,7 +217,7 @@ export async function Header(props: {
                                     ) ?? siteSpace
                                 }
                                 siteSpaces={variants.translations}
-                                className="my-1.5 ml-2 self-start"
+                                className="-mx-3 my-1.5 ml-2 self-start"
                             />
                         ) : null}
                     </SiteSectionTabs>
diff --git a/packages/gitbook/src/components/Header/SpacesDropdown.tsx b/packages/gitbook/src/components/Header/SpacesDropdown.tsx
index 477a87a6f..c9fa092bc 100644
--- a/packages/gitbook/src/components/Header/SpacesDropdown.tsx
+++ b/packages/gitbook/src/components/Header/SpacesDropdown.tsx
@@ -14,15 +14,15 @@ function startsWithEmoji(text: string): boolean {
     return EMOJI_REGEX.test(text);
 }
 
-export function SpacesDropdown(props: {
-    context: GitBookSiteContext;
-    siteSpace: SiteSpace;
-    siteSpaces: SiteSpace[];
-    className?: string;
-    variant?: ButtonProps['variant'];
-    icon?: IconName;
-}) {
-    const { context, siteSpace, siteSpaces, className, variant = 'secondary', icon } = props;
+export function SpacesDropdown(
+    props: {
+        context: GitBookSiteContext;
+        siteSpace: SiteSpace;
+        siteSpaces: SiteSpace[];
+        className?: string;
+    } & ButtonProps
+) {
+    const { context, siteSpace, siteSpaces, className, ...buttonProps } = props;
     const currentLanguage = context.locale;
 
     const dropdownClassName = tcls(
@@ -41,8 +41,8 @@ export function SpacesDropdown(props: {
     return (
         <SpacesDropdownClient
             title={getLocalizedTitle(siteSpace, currentLanguage)}
-            icon={icon}
-            variant={variant}
+            icon={buttonProps.icon as IconName}
+            variant={buttonProps.variant ?? 'secondary'}
             className={className}
             dropdownClassName={dropdownClassName}
             slimSpaces={slimSpaces}
@@ -51,13 +51,15 @@ export function SpacesDropdown(props: {
     );
 }
 
-export function TranslationsDropdown(props: {
-    context: GitBookSiteContext;
-    siteSpace: SiteSpace;
-    siteSpaces: SiteSpace[];
-    className?: string;
-}) {
-    const { context, siteSpace, siteSpaces, className } = props;
+export function TranslationsDropdown(
+    props: {
+        context: GitBookSiteContext;
+        siteSpace: SiteSpace;
+        siteSpaces: SiteSpace[];
+        className?: string;
+    } & ButtonProps
+) {
+    const { context, siteSpace, siteSpaces, className, ...buttonProps } = props;
 
     const title = getLocalizedTitle(siteSpace, context.locale);
     const hasEmojiPrefix = startsWithEmoji(title);
@@ -70,12 +72,13 @@ export function TranslationsDropdown(props: {
             siteSpaces={siteSpaces}
             variant="blank"
             className={tcls(
-                '-mx-3 bg-transparent lg:max-w-64 max-md:[&_.button-content]:hidden',
+                'bg-transparent lg:max-w-64 max-md:[&_.button-content]:hidden',
                 hasEmojiPrefix
                     ? 'md:[&_.button-leading-icon]:hidden' // If the title starts with an emoji, don't show the icon (on desktop)
                     : '',
                 className
             )}
+            {...buttonProps}
         />
     );
 }
diff --git a/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx b/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
index a516cba1a..1f273a1d4 100644
--- a/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
+++ b/packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx
@@ -171,7 +171,7 @@ export function SpaceLayout(props: SpaceLayoutProps) {
                                     // On bold themes also color the TOC header so the logo looks correct.
                                     'site-header:theme-bold:bg-header-background',
                                     'site-header:theme-bold:m-[-1.5rem_-1px_-0.5rem_-2rem]',
-                                    'site-header:theme-bold:p-[1rem_0_1rem_2rem]'
+                                    'site-header:theme-bold:p-[1rem_1rem_1rem_2rem]'
                                 )}
                             >
                                 <HeaderLogo context={context} />
@@ -185,6 +185,7 @@ export function SpaceLayout(props: SpaceLayoutProps) {
                                         }
                                         siteSpaces={variants.translations}
                                         className="[&_.button-leading-icon]:block! ml-auto py-2 [&_.button-content]:hidden"
+                                        variant="header"
                                     />
                                 ) : null}
                             </div>

From fdea8f1c47fd95e7c167d7874c23eacb5c24cfe1 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Mon, 6 Jul 2026 11:49:47 +0200
Subject: [PATCH 09/46] Show section, variant & section groups in page
 breadcrumbs (#4357)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/breadcrumbs-section-variant.md     |   5 +
 .../Header/SpacesDropdownMenuItem.tsx         |   2 +-
 .../PageBody/BreadcrumbItemDropdown.tsx       | 102 ++++++
 .../src/components/PageBody/PageHeader.tsx    | 315 ++++++++++++++++--
 .../SiteSections/encodeClientSiteSections.ts  |   4 +-
 .../components/primitives/DropdownMenu.tsx    |  71 +++-
 6 files changed, 460 insertions(+), 39 deletions(-)
 create mode 100644 .changeset/breadcrumbs-section-variant.md
 create mode 100644 packages/gitbook/src/components/PageBody/BreadcrumbItemDropdown.tsx

diff --git a/.changeset/breadcrumbs-section-variant.md b/.changeset/breadcrumbs-section-variant.md
new file mode 100644
index 000000000..0a7116f6d
--- /dev/null
+++ b/.changeset/breadcrumbs-section-variant.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Show where a page lives in the site at the start of the page breadcrumbs: its section (including any enclosing section groups) and variant. Hovering any breadcrumb item reveals a dropdown to switch to its siblings at the same level — other section groups, sections, variants, page groups or pages — computed on the server from already-available data (no extra request). Language variants are left to the dedicated language picker rather than shown as a crumb. Also restyles the breadcrumbs to normal casing (matching search results).
diff --git a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
index 6ca5aa50a..98c134ee8 100644
--- a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
+++ b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
@@ -8,7 +8,7 @@ import {
 } from '../hooks';
 import { DropdownMenuItem } from '../primitives/DropdownMenu';
 
-interface VariantSpace {
+export interface VariantSpace {
     id: string;
     title: string;
     url: string;
diff --git a/packages/gitbook/src/components/PageBody/BreadcrumbItemDropdown.tsx b/packages/gitbook/src/components/PageBody/BreadcrumbItemDropdown.tsx
new file mode 100644
index 000000000..16f36d107
--- /dev/null
+++ b/packages/gitbook/src/components/PageBody/BreadcrumbItemDropdown.tsx
@@ -0,0 +1,102 @@
+'use client';
+
+import { type ClassValue, tcls } from '@/lib/tailwind';
+
+import { PageIcon } from '../PageIcon';
+import { StyledLink } from '../primitives';
+import { DropdownMenu, DropdownMenuItem } from '../primitives/DropdownMenu';
+
+export type BreadcrumbSibling = {
+    id: string;
+    title: string;
+    href: string;
+    emoji?: string;
+    icon?: string;
+    /** Whether this sibling is the one currently represented by the breadcrumb item. */
+    isActive: boolean;
+};
+
+/**
+ * A breadcrumb item. It navigates on click, and when there is more than one sibling at the same
+ * level (another section, variant, group or page) it reveals a dropdown of those siblings on hover
+ * so the reader can jump between them.
+ *
+ * This is a client component so the trigger/menu — which Radix clones through its `Slot` — is built
+ * from serializable props, mirroring `HeaderLinkDropdown`.
+ */
+export function BreadcrumbItemDropdown(props: {
+    /** Link for the crumb. Omitted for non-navigable items such as section groups. */
+    href?: string;
+    label: string;
+    emoji?: string;
+    icon?: string;
+    /** Class names for the breadcrumb link itself. */
+    linkClassName: ClassValue;
+    /** All items at the same level, including the current one (flagged `isActive`). */
+    siblings: BreadcrumbSibling[];
+    /**
+     * Custom dropdown content, rendered instead of the `siblings` list. Used by the variant crumb to
+     * reuse the header's variant switcher, whose entries resolve to the current page in the target
+     * variant (via per-page alternates) rather than just its landing page. When set, the dropdown is
+     * always shown.
+     */
+    children?: React.ReactNode;
+}) {
+    const { href, label, emoji, icon, linkClassName, siblings, children } = props;
+
+    const content = (
+        <>
+            {emoji || icon ? (
+                <PageIcon page={{ emoji, icon }} style="mr-1 inline size-[1em] shrink-0" />
+            ) : null}
+            {label}
+        </>
+    );
+
+    // Navigable crumbs render a link; section groups (no href) render a plain label. An empty href
+    // is still a real link — it's the site's first page — so key on `undefined`, not falsiness, and
+    // normalize "" to "/" the way the table of contents does.
+    const trigger =
+        href !== undefined ? (
+            <StyledLink href={href || '/'} className={tcls(linkClassName)}>
+                {content}
+            </StyledLink>
+        ) : (
+            <span className={tcls(linkClassName, 'cursor-default hover:no-underline')}>
+                {content}
+            </span>
+        );
+
+    // No dropdown when there is nowhere else to go at this level.
+    if (children == null && siblings.length <= 1) {
+        return trigger;
+    }
+
+    return (
+        <DropdownMenu
+            openOnHover
+            openDelay={200}
+            button={trigger}
+            className="max-h-72 overflow-auto text-sm"
+        >
+            {children ??
+                siblings.map((sibling) => (
+                    <DropdownMenuItem
+                        key={sibling.id}
+                        href={sibling.href || '/'}
+                        active={sibling.isActive}
+                        leadingIcon={
+                            sibling.emoji || sibling.icon ? (
+                                <PageIcon
+                                    page={{ emoji: sibling.emoji, icon: sibling.icon }}
+                                    style="size-3 shrink-0 text-tint-subtle"
+                                />
+                            ) : undefined
+                        }
+                    >
+                        {sibling.title}
+                    </DropdownMenuItem>
+                ))}
+        </DropdownMenu>
+    );
+}
diff --git a/packages/gitbook/src/components/PageBody/PageHeader.tsx b/packages/gitbook/src/components/PageBody/PageHeader.tsx
index c48d86697..bef42c772 100644
--- a/packages/gitbook/src/components/PageBody/PageHeader.tsx
+++ b/packages/gitbook/src/components/PageBody/PageHeader.tsx
@@ -1,14 +1,19 @@
 import type { GitBookSiteContext } from '@/lib/context';
-import type { AncestorRevisionPage } from '@/lib/pages';
+import { type AncestorRevisionPage, resolveFirstDocument } from '@/lib/pages';
+import { getLocalizedTitle, getSiteSpaceURL } from '@/lib/sites';
 import { tcls } from '@/lib/tailwind';
 import { getPageRSSURL } from '@/routes/rss';
 import {
     CustomizationPageActionType,
+    type RevisionPage,
     type RevisionPageDocument,
+    type SiteSection,
+    type SiteSectionGroup,
     SiteVisibility,
 } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
 import urlJoin from 'url-join';
+import { SpacesDropdownMenuItems, type VariantSpace } from '../Header/SpacesDropdownMenuItem';
 import { getPDFURLSearchParams } from '../PDF';
 import {
     PageActionsDropdown,
@@ -16,8 +21,10 @@ import {
 } from '../PageActions/PageActionsDropdown';
 import { PageAsideToggleButton } from '../PageAside/PageAsideButton';
 import { PageIcon } from '../PageIcon';
+import { findBestTargetURL } from '../SiteSections/encodeClientSiteSections';
+import { categorizeVariants } from '../SpaceLayout/categorizeVariants';
 import { CONTENT_STYLE, CONTENT_STYLE_REDUCED } from '../layout';
-import { StyledLink } from '../primitives';
+import { BreadcrumbItemDropdown, type BreadcrumbSibling } from './BreadcrumbItemDropdown';
 import { PageTags } from './PageTags';
 
 export async function PageHeader(props: {
@@ -31,6 +38,86 @@ export async function PageHeader(props: {
 
     const hasAncestors = ancestors.length > 0;
 
+    // Surface where the page lives in the site at the start of the breadcrumbs: the section (with
+    // its enclosing section groups) and the variant. Each crumb also carries its siblings, so
+    // hovering it reveals a dropdown to switch to them.
+    // Only surface section crumbs when the site actually has more than one section to switch between
+    // (mirroring the section tabs). A single-space site has one section named after the site, which
+    // is not a meaningful breadcrumb.
+    const hasMultipleSections = Boolean(
+        context.visibleSections && context.visibleSections.list.length > 1
+    );
+    const currentSection = hasMultipleSections ? (context.sections?.current ?? null) : null;
+    // Variants to offer as a crumb: only the "generic" variants (versions, etc.). Language variants
+    // are excluded — they belong to the dedicated language picker — using the same split it uses.
+    // Only surface the variant crumb when there's more than one to switch between.
+    const variantSpaces = categorizeVariants(context).generic;
+    const currentSiteSpace = variantSpaces.length > 1 ? context.siteSpace : null;
+    const contextCrumbs: BreadcrumbContextCrumb[] = [];
+    if (currentSection) {
+        // Walk the full section tree so the current section (and its enclosing groups) always shows
+        // as a crumb, even when it's hidden in the site structure. Only *visible* sections/groups
+        // are offered as siblings to switch to, though.
+        const chain = context.sections
+            ? findSectionChain(context.sections.list, currentSection.id)
+            : [];
+        const visibleSectionIds = context.visibleSections
+            ? collectSectionNodeIds(context.visibleSections.list)
+            : null;
+        for (const { node, siblings } of chain) {
+            contextCrumbs.push({
+                key: `section-${node.id}`,
+                // Section groups have no URL of their own; only sections are navigable. Resolve the
+                // section to the site space matching the current variant so switching sections keeps
+                // the reader on their current variant (same logic as the section tabs).
+                href: node.object === 'site-section' ? findBestTargetURL(context, node) : undefined,
+                label: getLocalizedTitle(node, context.locale),
+                icon: node.icon,
+                siblings: siblings
+                    // Don't offer hidden sections/groups as switch targets.
+                    .filter((sibling) => !visibleSectionIds || visibleSectionIds.has(sibling.id))
+                    .map((sibling) => {
+                        const href = getSectionNodeURL(context, sibling);
+                        // Keep siblings whose URL is "" (the site's first page); only drop the ones
+                        // with no resolvable URL at all.
+                        return href !== undefined
+                            ? {
+                                  id: sibling.id,
+                                  title: getLocalizedTitle(sibling, context.locale),
+                                  href,
+                                  icon: sibling.icon,
+                                  isActive: sibling.id === node.id,
+                              }
+                            : null;
+                    })
+                    .filter((sibling) => sibling !== null),
+            });
+        }
+    }
+    if (currentSiteSpace) {
+        contextCrumbs.push({
+            key: `variant-${currentSiteSpace.id}`,
+            href: getSiteSpaceURL(context, currentSiteSpace),
+            label: getLocalizedTitle(currentSiteSpace, context.locale),
+            siblings: [],
+            // Reuse the header's variant switcher rather than plain per-variant links, so each entry
+            // resolves to the current page in the target variant (via per-page alternates) instead
+            // of that variant's landing page.
+            variantSwitcher: {
+                slimSpaces: variantSpaces.map((siteSpace) => ({
+                    id: siteSpace.id,
+                    title: getLocalizedTitle(siteSpace, context.locale),
+                    url: getSiteSpaceURL(context, siteSpace),
+                    isActive: siteSpace.id === currentSiteSpace.id,
+                    spaceId: siteSpace.space.id,
+                })),
+                curPath: currentSiteSpace.path,
+            },
+        });
+    }
+    const hasContextCrumbs = contextCrumbs.length > 0;
+    const showBreadcrumbs = hasAncestors || hasContextCrumbs;
+
     const pageActionsEnabled = page.layout.actions !== false;
 
     // Show page actions if *any* of the configured actions are enabled, or if the RSS feed is
@@ -55,7 +142,7 @@ export async function PageHeader(props: {
             <div
                 className={tcls(
                     'float-right ml-4 flex gap-2',
-                    hasAncestors ? '-my-0.5' : '-mt-3 xs:mt-2'
+                    showBreadcrumbs ? '-mb-1 -mt-1.5' : '-mt-3 xs:mt-2'
                 )}
             >
                 {hasPageActions ? (
@@ -74,44 +161,43 @@ export async function PageHeader(props: {
                 <PageAsideToggleButton />
             </div>
 
-            {hasAncestors && (
-                <nav aria-label="Breadcrumb" className="text-tint leading-snug">
+            {showBreadcrumbs && (
+                // Hide the breadcrumbs on wide pages that have no table of contents: there the
+                // content spans the full width with no navigation column, so the crumbs sit stranded.
+                <nav
+                    aria-label="Breadcrumb"
+                    className="layout-wide:page-no-toc:hidden text-tint text-xs leading-relaxed"
+                >
                     <ol className="inline">
+                        {contextCrumbs.map((crumb, index) => (
+                            <li key={crumb.key} className="inline">
+                                <ContextCrumb crumb={crumb} />
+                                {(index !== contextCrumbs.length - 1 || hasAncestors) && (
+                                    <BreadcrumbSeparator />
+                                )}
+                            </li>
+                        ))}
                         {ancestors.map((breadcrumb, index) => {
+                            const parentPages = ancestors[index - 1]?.pages ?? revision.pages;
                             const href = linker.toPathForPage({
                                 pages: revision.pages,
                                 page: breadcrumb,
                             });
                             return (
                                 <li key={breadcrumb.id} className="inline">
-                                    <StyledLink
+                                    <BreadcrumbItemDropdown
                                         href={href}
-                                        className={tcls(
-                                            'inline',
-                                            'no-underline',
-                                            'hover:underline',
-                                            'text-xs',
-                                            'tracking-wide',
-                                            'font-semibold',
-                                            'uppercase',
-                                            'items-center',
-                                            'contrast-more:underline',
-                                            'contrast-more:decoration-current'
+                                        label={breadcrumb.title}
+                                        emoji={breadcrumb.emoji}
+                                        icon={breadcrumb.icon}
+                                        linkClassName={BREADCRUMB_LINK_CLASSES}
+                                        siblings={getPageSiblings(
+                                            context,
+                                            parentPages,
+                                            breadcrumb.id
                                         )}
-                                    >
-                                        <PageIcon
-                                            page={breadcrumb}
-                                            style="mr-1 inline size-3.5 shrink-0"
-                                        />
-                                        {breadcrumb.title}
-                                    </StyledLink>
-                                    {index !== ancestors.length - 1 && (
-                                        <Icon
-                                            aria-hidden
-                                            icon="chevron-right"
-                                            className="mx-2 inline-flex size-2 text-tint-subtle"
-                                        />
-                                    )}
+                                    />
+                                    {index !== ancestors.length - 1 && <BreadcrumbSeparator />}
                                 </li>
                             );
                         })}
@@ -149,6 +235,173 @@ export async function PageHeader(props: {
     );
 }
 
+/**
+ * Shared styling for the individual breadcrumb links. Uses normal casing/weight to match the way
+ * breadcrumbs are rendered in search results.
+ */
+const BREADCRUMB_LINK_CLASSES = [
+    'inline',
+    'no-underline',
+    'hover:underline',
+    'text-xs',
+    'font-normal',
+    'items-center',
+    'contrast-more:underline',
+    'contrast-more:decoration-current',
+];
+
+/** A section-group, section or variant crumb shown at the start of the breadcrumbs. */
+type BreadcrumbContextCrumb = {
+    key: string;
+    href?: string;
+    label: string;
+    // Sections, section groups and variants only ever carry an icon, never an emoji.
+    icon?: string;
+    siblings: BreadcrumbSibling[];
+    /**
+     * Present only for the variant crumb: the header's variant switcher data, whose dropdown entries
+     * resolve to the current page in each variant. Rendered instead of `siblings`.
+     */
+    variantSwitcher?: { slimSpaces: VariantSpace[]; curPath: string };
+};
+
+/** Render a context crumb (section group / section / variant) with its sibling dropdown. */
+function ContextCrumb({ crumb }: { crumb: BreadcrumbContextCrumb }) {
+    return (
+        <BreadcrumbItemDropdown
+            href={crumb.href}
+            label={crumb.label}
+            icon={crumb.icon}
+            linkClassName={BREADCRUMB_LINK_CLASSES}
+            siblings={crumb.siblings}
+        >
+            {crumb.variantSwitcher ? (
+                <SpacesDropdownMenuItems
+                    slimSpaces={crumb.variantSwitcher.slimSpaces}
+                    curPath={crumb.variantSwitcher.curPath}
+                />
+            ) : undefined}
+        </BreadcrumbItemDropdown>
+    );
+}
+
+type SectionNode = SiteSection | SiteSectionGroup;
+
+/**
+ * Walk the section tree from the root down to the section with the given id, returning one entry per
+ * level (each enclosing section group, then the section) along with that level's siblings. Returns
+ * an empty array if the section isn't found.
+ */
+function findSectionChain(
+    list: SectionNode[],
+    sectionId: string
+): Array<{ node: SectionNode; siblings: SectionNode[] }> {
+    for (const item of list) {
+        if (item.object === 'site-section') {
+            if (item.id === sectionId) {
+                return [{ node: item, siblings: list }];
+            }
+        } else {
+            const nested = findSectionChain(item.children, sectionId);
+            if (nested.length > 0) {
+                return [{ node: item, siblings: list }, ...nested];
+            }
+        }
+    }
+    return [];
+}
+
+/**
+ * The first navigable section within a node — the node itself if it's a section, otherwise the first
+ * section found in its (possibly nested) children.
+ */
+function findFirstSection(node: SectionNode): SiteSection | null {
+    if (node.object === 'site-section') {
+        return node;
+    }
+    for (const child of node.children) {
+        const found = findFirstSection(child);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+}
+
+/**
+ * Resolve a section-tree node to a navigable URL. Sections use their own URL; section groups (which
+ * have none of their own) fall back to their first section, so they stay navigable in a dropdown.
+ * The URL resolves to the site space matching the current variant (same logic as the section tabs),
+ * so switching sections keeps the reader on their current variant.
+ */
+function getSectionNodeURL(context: GitBookSiteContext, node: SectionNode): string | undefined {
+    const section = findFirstSection(node);
+    return section ? findBestTargetURL(context, section) : undefined;
+}
+
+/** Collect the ids of every section and section group in a (visible) section tree. */
+function collectSectionNodeIds(list: SectionNode[]): Set<string> {
+    const ids = new Set<string>();
+    const walk = (nodes: SectionNode[]) => {
+        for (const node of nodes) {
+            ids.add(node.id);
+            if (node.object === 'site-section-group') {
+                walk(node.children);
+            }
+        }
+    };
+    walk(list);
+    return ids;
+}
+
+/**
+ * Build the sibling list for a page-level breadcrumb item, from the children of its parent.
+ * Only pages with a resolvable path (documents & groups) are navigable, so links and computed pages
+ * are skipped, as are hidden pages — except the active page itself, so its own crumb stays marked.
+ */
+function getPageSiblings(
+    context: GitBookSiteContext,
+    siblings: RevisionPage[],
+    activeId: string
+): BreadcrumbSibling[] {
+    const result: BreadcrumbSibling[] = [];
+    for (const page of siblings) {
+        if (page.type !== 'document' && page.type !== 'group') {
+            continue;
+        }
+        if (page.hidden && page.id !== activeId) {
+            continue;
+        }
+        // A group whose subtree has no document resolves to no page — the sidebar renders it as a
+        // non-clickable label, so don't offer it as a navigable sibling (its path would 404).
+        if (page.type === 'group' && page.id !== activeId && !resolveFirstDocument([page], [])) {
+            continue;
+        }
+        result.push({
+            id: page.id,
+            title: page.linkTitle || page.title,
+            href: context.linker.toPathForPage({ pages: context.revision.pages, page }),
+            emoji: page.emoji,
+            icon: page.icon,
+            isActive: page.id === activeId,
+        });
+    }
+    return result;
+}
+
+/**
+ * Separator rendered between two breadcrumb items.
+ */
+function BreadcrumbSeparator() {
+    return (
+        <Icon
+            aria-hidden
+            icon="chevron-right"
+            className="mx-2 inline-flex size-2 text-tint-subtle"
+        />
+    );
+}
+
 /**
  * Return the URLs for the page actions.
  */
diff --git a/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts b/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
index eb0309f29..6325db25c 100644
--- a/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
+++ b/packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts
@@ -132,10 +132,10 @@ function encodeSection(context: GitBookSiteContext, section: SiteSection, asEmbe
  * 4. Otherwise, return the default first language match.
  * 5. Otherwise, return the default one.
  */
-function findBestTargetURL(
+export function findBestTargetURL(
     context: GitBookSiteContext,
     section: SiteSection,
-    asEmbeddable: boolean
+    asEmbeddable = false
 ) {
     const { siteSpace: currentSiteSpace } = context;
 
diff --git a/packages/gitbook/src/components/primitives/DropdownMenu.tsx b/packages/gitbook/src/components/primitives/DropdownMenu.tsx
index 33ac845c3..095147d1f 100644
--- a/packages/gitbook/src/components/primitives/DropdownMenu.tsx
+++ b/packages/gitbook/src/components/primitives/DropdownMenu.tsx
@@ -2,7 +2,7 @@
 
 import { Icon, type IconName } from '@gitbook/icons';
 import type { DetailedHTMLProps, HTMLAttributes } from 'react';
-import { createContext, useCallback, useContext, useState } from 'react';
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
 
 import { type ClassValue, tcls } from '@/lib/tailwind';
 
@@ -31,6 +31,20 @@ const DROPDOWN_CONTENT_OUTER_CLASS =
 const DROPDOWN_CONTENT_INNER_CLASS =
     'flex flex-col gap-1 overflow-auto circular-corners:rounded-xl rounded-md straight-corners:rounded-none border border-tint bg-tint-base p-2 shadow-lg';
 
+/**
+ * Grace period before a hover-opened menu closes, so the pointer can travel from the trigger to the
+ * (portalled) menu without it collapsing. Only used when `openDelay` is set.
+ */
+const HOVER_CLOSE_DELAY_MS = 150;
+
+/** Clear a pending timeout ref, if any. */
+function clearTimer(ref: { current: ReturnType<typeof setTimeout> | null }) {
+    if (ref.current) {
+        clearTimeout(ref.current);
+        ref.current = null;
+    }
+}
+
 /**
  * Button with a dropdown.
  */
@@ -45,6 +59,11 @@ export function DropdownMenu(props: {
     className?: ClassValue;
     /** Open the dropdown on hover */
     openOnHover?: boolean;
+    /**
+     * Delay in milliseconds before the dropdown opens on hover. Only applies with `openOnHover`.
+     * @default 0
+     */
+    openDelay?: number;
     /**
      * Side of the dropdown
      * @default "bottom"
@@ -67,6 +86,7 @@ export function DropdownMenu(props: {
         children,
         className,
         openOnHover = false,
+        openDelay = 0,
         side = 'bottom',
         align = 'start',
         sideOffset = 0,
@@ -74,13 +94,54 @@ export function DropdownMenu(props: {
     const [hovered, setHovered] = useState(false);
     const [open, setOpen] = useState(false);
 
+    // Timers used to delay opening on hover (and to keep the menu open while the pointer travels
+    // between the trigger and the menu).
+    const openTimeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const closeTimeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+    // Clear any pending timers when unmounting.
+    useEffect(
+        () => () => {
+            clearTimer(openTimeout);
+            clearTimer(closeTimeout);
+        },
+        []
+    );
+
+    const handleHoverEnter = useCallback(() => {
+        clearTimer(closeTimeout);
+        if (openDelay > 0) {
+            if (!openTimeout.current) {
+                openTimeout.current = setTimeout(() => {
+                    openTimeout.current = null;
+                    setHovered(true);
+                }, openDelay);
+            }
+        } else {
+            setHovered(true);
+        }
+    }, [openDelay]);
+
+    const handleHoverLeave = useCallback(() => {
+        clearTimer(openTimeout);
+        clearTimer(closeTimeout);
+        if (openDelay > 0) {
+            // Grace period so moving between the trigger and the menu doesn't close it.
+            closeTimeout.current = setTimeout(() => {
+                closeTimeout.current = null;
+                setHovered(false);
+            }, HOVER_CLOSE_DELAY_MS);
+        } else {
+            setHovered(false);
+        }
+    }, [openDelay]);
+
     const isOpen = openOnHover ? open || hovered : open;
 
     const trigger = (
         <RadixDropdownMenu.Trigger
             asChild
-            onMouseEnter={() => setHovered(true)}
-            onMouseLeave={() => setHovered(false)}
+            onMouseEnter={handleHoverEnter}
+            onMouseLeave={handleHoverLeave}
             onClick={() => (openOnHover ? setOpen(!open) : null)}
             className="group/dropdown"
         >
@@ -108,8 +169,8 @@ export function DropdownMenu(props: {
                         data-testid="dropdown-menu"
                         hideWhenDetached
                         collisionPadding={8}
-                        onMouseEnter={() => setHovered(true)}
-                        onMouseLeave={() => setHovered(false)}
+                        onMouseEnter={handleHoverEnter}
+                        onMouseLeave={handleHoverLeave}
                         align={align}
                         side={side}
                         sideOffset={sideOffset}

From bcea23e886f7e19d5772ed45d626d34835472edf Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Mon, 6 Jul 2026 12:33:02 +0200
Subject: [PATCH 10/46] Handle nullable expressed via anyOf/oneOf with a null
 member (#4366)

---
 .changeset/rnd-11617-nullable-anyof.md       |  5 ++
 packages/react-openapi/src/OpenAPISchema.tsx | 14 ++-
 packages/react-openapi/src/utils.test.ts     | 94 +++++++++++++++++++-
 packages/react-openapi/src/utils.ts          | 60 +++++++++++++
 4 files changed, 169 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/rnd-11617-nullable-anyof.md

diff --git a/.changeset/rnd-11617-nullable-anyof.md b/.changeset/rnd-11617-nullable-anyof.md
new file mode 100644
index 000000000..b9b114e9d
--- /dev/null
+++ b/.changeset/rnd-11617-nullable-anyof.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Render `anyOf`/`oneOf` with a `null` member as a nullable schema instead of a `null` union branch.
diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx
index fee855a38..e3ac61b71 100644
--- a/packages/react-openapi/src/OpenAPISchema.tsx
+++ b/packages/react-openapi/src/OpenAPISchema.tsx
@@ -20,6 +20,7 @@ import {
     checkIsReference,
     getEffectiveArrayType,
     getSchemaTitle,
+    normalizeNullableUnion,
     resolveDescription,
     resolveFirstExample,
 } from './utils';
@@ -50,12 +51,18 @@ function OpenAPISchemaProperty(
         circularRefs: parentCircularRefs,
         context,
         className,
-        property,
+        property: rawProperty,
         discriminator,
         discriminatorValue,
         ...rest
     } = props;
 
+    // Normalize the OpenAPI 3.1+ `anyOf`/`oneOf` + `null` nullability idiom into a plain
+    // nullable schema before it enters the render pipeline.
+    const property = {
+        ...rawProperty,
+        schema: normalizeNullableUnion(rawProperty.schema),
+    };
     const { schema } = property;
 
     const id = useId();
@@ -201,11 +208,14 @@ function OpenAPIRootSchema(props: {
     circularRefs?: CircularRefsIds;
 }) {
     const {
-        schema,
         context,
         circularRefs: parentCircularRefs = new Map<OpenAPIV3.SchemaObject, string>(),
     } = props;
 
+    // Normalize the OpenAPI 3.1+ `anyOf`/`oneOf` + `null` nullability idiom into a plain
+    // nullable schema before it enters the render pipeline.
+    const schema = normalizeNullableUnion(props.schema);
+
     const id = useId();
     const ancestors = new Set(parentCircularRefs.keys());
     const alternatives = getSchemaAlternatives(schema, ancestors);
diff --git a/packages/react-openapi/src/utils.test.ts b/packages/react-openapi/src/utils.test.ts
index 08904a127..c5937a074 100644
--- a/packages/react-openapi/src/utils.test.ts
+++ b/packages/react-openapi/src/utils.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, it } from 'bun:test';
-import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
-import { extractNonNullTypes, getEffectiveArrayType, getSchemaTitle } from './utils';
+import type { OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import {
+    extractNonNullTypes,
+    getEffectiveArrayType,
+    getSchemaTitle,
+    normalizeNullableUnion,
+} from './utils';
 
 describe('getSchemaTitle', () => {
     it('should handle OpenAPI 3.1 nullable array with reference items', () => {
@@ -181,3 +186,88 @@ describe('extractNonNullTypes', () => {
         expect(result.hasNull).toBe(true);
     });
 });
+
+describe('normalizeNullableUnion', () => {
+    it('should collapse anyOf with a single non-null member into a nullable schema', () => {
+        const schema: OpenAPIV3_1.SchemaObject = {
+            anyOf: [{ type: 'string' }, { type: 'null' }],
+        };
+
+        expect(normalizeNullableUnion(schema)).toEqual({ type: 'string', nullable: true });
+    });
+
+    it('should collapse oneOf with a single object member into a nullable object schema', () => {
+        const schema: OpenAPIV3_1.SchemaObject = {
+            oneOf: [
+                {
+                    type: 'object',
+                    properties: { id: { type: 'string' } },
+                },
+                { type: 'null' },
+            ],
+        };
+
+        expect(normalizeNullableUnion(schema)).toEqual({
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            nullable: true,
+        });
+    });
+
+    it('should handle a null member expressed as type: ["null"]', () => {
+        const schema: OpenAPIV3_1.SchemaObject = {
+            anyOf: [{ type: 'integer' }, { type: ['null'] }],
+        };
+
+        expect(normalizeNullableUnion(schema)).toEqual({ type: 'integer', nullable: true });
+    });
+
+    it('should keep the union (without null) and flag nullable for multiple non-null members', () => {
+        const schema: OpenAPIV3_1.SchemaObject = {
+            anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'null' }],
+        };
+
+        expect(normalizeNullableUnion(schema)).toEqual({
+            anyOf: [{ type: 'string' }, { type: 'number' }],
+            nullable: true,
+        });
+    });
+
+    it('should preserve outer-level metadata over the collapsed member', () => {
+        const schema: OpenAPIV3_1.SchemaObject = {
+            description: 'Outer description',
+            anyOf: [{ type: 'string', description: 'Member description' }, { type: 'null' }],
+        };
+
+        expect(normalizeNullableUnion(schema)).toEqual({
+            type: 'string',
+            description: 'Outer description',
+            nullable: true,
+        });
+    });
+
+    it('should return the schema unchanged when there is no null member', () => {
+        const schema: OpenAPIV3.SchemaObject = {
+            anyOf: [{ type: 'string' }, { type: 'number' }],
+        };
+
+        expect(normalizeNullableUnion(schema)).toBe(schema);
+    });
+
+    it('should return the schema unchanged when there is no union', () => {
+        const schema: OpenAPIV3.SchemaObject = { type: 'string' };
+
+        expect(normalizeNullableUnion(schema)).toBe(schema);
+    });
+
+    it('should keep a $ref member as a nullable union rather than inlining it', () => {
+        const schema: OpenAPIV3_1.SchemaObject = {
+            anyOf: [{ $ref: '#/components/schemas/Foo' }, { type: 'null' }],
+        };
+
+        expect(normalizeNullableUnion(schema)).toEqual({
+            anyOf: [{ $ref: '#/components/schemas/Foo' }],
+            nullable: true,
+        });
+    });
+});
diff --git a/packages/react-openapi/src/utils.ts b/packages/react-openapi/src/utils.ts
index 1c6ef6a88..b5e43029b 100644
--- a/packages/react-openapi/src/utils.ts
+++ b/packages/react-openapi/src/utils.ts
@@ -269,6 +269,66 @@ export function getEffectiveArrayType(schema: OpenAPIV3.SchemaObject | OpenAPIV3
     return { isArray: false, hasNull: false };
 }
 
+/**
+ * Check if a schema only describes the `null` type, i.e. it is used as a nullability
+ * marker inside an `anyOf`/`oneOf` (OpenAPI 3.1+).
+ */
+function isNullSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject): boolean {
+    if (checkIsReference(schema)) {
+        return false;
+    }
+    // `null` is only a valid type in OpenAPI 3.1+, hence the widening.
+    const type = schema.type as string | string[] | undefined;
+    if (Array.isArray(type)) {
+        return type.length > 0 && type.every((t) => t === 'null');
+    }
+    return type === 'null';
+}
+
+/**
+ * Normalize the OpenAPI 3.1+ idiom of expressing nullability through `anyOf`/`oneOf`
+ * (e.g. `anyOf: [{ type: 'string' }, { type: 'null' }]`) into a regular nullable schema,
+ * mirroring how `type: ['string', 'null']` is handled.
+ *
+ * - Single non-null member: collapse into that member with `nullable: true`.
+ * - Multiple non-null members (or a single `$ref` member): drop the null member and keep
+ *   the union, flagged `nullable: true`.
+ * - No null member: returned unchanged (preserves identity for circular-ref tracking).
+ */
+export function normalizeNullableUnion(
+    schema: OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject
+): OpenAPIV3.SchemaObject {
+    const typed = schema as OpenAPIV3.SchemaObject;
+
+    const isAnyOf = Array.isArray(typed.anyOf);
+    const isOneOf = !isAnyOf && Array.isArray(typed.oneOf);
+    if (!isAnyOf && !isOneOf) {
+        return typed;
+    }
+
+    const unionKey = isAnyOf ? 'anyOf' : 'oneOf';
+    const union = (isAnyOf ? typed.anyOf : typed.oneOf) as (
+        | OpenAPIV3.SchemaObject
+        | OpenAPIV3.ReferenceObject
+    )[];
+
+    const nonNullMembers = union.filter((member) => !isNullSchema(member));
+    if (nonNullMembers.length === union.length) {
+        // No null member, nothing to normalize.
+        return typed;
+    }
+
+    const { anyOf: _anyOf, oneOf: _oneOf, ...rest } = typed;
+
+    const single = nonNullMembers.length === 1 ? nonNullMembers[0] : undefined;
+    if (single && !checkIsReference(single)) {
+        // Outer-level metadata (description, title, …) takes precedence over the member's.
+        return { ...single, ...rest, nullable: true };
+    }
+
+    return { ...rest, [unionKey]: nonNullMembers, nullable: true };
+}
+
 export function getSchemaTitle(
     schema: OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject,
     options?: { ignoreAlternatives?: boolean }

From 3fedaaa08cb038a13dfcaef81af821477c8e276b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Greg=20Berg=C3=A9?= <berge.greg@gmail.com>
Date: Mon, 6 Jul 2026 14:31:54 +0200
Subject: [PATCH 11/46] Install eval-estree-expression from npm instead of a
 GitHub commit (#4367)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/expr-eval-estree-from-npm.md | 5 +++++
 bun.lock                                | 4 ++--
 packages/expr/package.json              | 2 +-
 3 files changed, 8 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/expr-eval-estree-from-npm.md

diff --git a/.changeset/expr-eval-estree-from-npm.md b/.changeset/expr-eval-estree-from-npm.md
new file mode 100644
index 000000000..2aec2692e
--- /dev/null
+++ b/.changeset/expr-eval-estree-from-npm.md
@@ -0,0 +1,5 @@
+---
+"@gitbook/expr": patch
+---
+
+Depend on `eval-estree-expression` from the npm registry (`^3.0.1`) instead of a pinned GitHub commit. The published `3.0.1` release is built from the exact commit the package was pinned to, so the code is unchanged — this only removes the fragile git/tarball dependency so consumers install it from npm like any other package.
diff --git a/bun.lock b/bun.lock
index e6214a000..e749e7550 100644
--- a/bun.lock
+++ b/bun.lock
@@ -81,7 +81,7 @@
         "acorn-walk": "^8.3.4",
         "assert-never": "catalog:",
         "escodegen": "^2.1.0",
-        "eval-estree-expression": "github:jonschlinkert/eval-estree-expression#fb0246a",
+        "eval-estree-expression": "^3.0.1",
       },
       "devDependencies": {
         "@tsconfig/node20": "catalog:",
@@ -2274,7 +2274,7 @@
 
     "etag": ["etag@1.8.1", "", {}, "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg=="],
 
-    "eval-estree-expression": ["eval-estree-expression@github:jonschlinkert/eval-estree-expression#fb0246a", {}, "jonschlinkert-eval-estree-expression-fb0246a"],
+    "eval-estree-expression": ["eval-estree-expression@3.0.1", "", {}, "sha512-zTLKGbiVdQYp4rQkSoXPibrFf5ZoPn6jzExegRLEQ13F+FSxu5iLgaRH6hlDs2kWSUa6vp8yD20cdJi0me6pEw=="],
 
     "event-emitter": ["event-emitter@0.3.5", "", { "dependencies": { "d": "1", "es5-ext": "~0.10.14" } }, "sha512-D9rRn9y7kLPnJ+hMq7S/nhvoKwwvVJahBi2BPmx3bvbsEdK3W9ii8cBSGjP+72/LnM4n6fo3+dkCX5FeTQruXA=="],
 
diff --git a/packages/expr/package.json b/packages/expr/package.json
index 5189c0b2c..129e51273 100644
--- a/packages/expr/package.json
+++ b/packages/expr/package.json
@@ -16,7 +16,7 @@
         "acorn-walk": "^8.3.4",
         "assert-never": "catalog:",
         "escodegen": "^2.1.0",
-        "eval-estree-expression": "github:jonschlinkert/eval-estree-expression#fb0246a"
+        "eval-estree-expression": "^3.0.1"
     },
     "devDependencies": {
         "@tsconfig/strictest": "catalog:",

From 3a31100efe33bee97f6ef1c0ba77bc4b7a1ec04c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Samy=20Pess=C3=A9?= <samypesse@gmail.com>
Date: Mon, 6 Jul 2026 14:52:44 +0200
Subject: [PATCH 12/46] Version Packages (#4335)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
---
 .changeset/ask-ai-paragraph-margin-button.md  |  5 ----
 .changeset/back-to-space-toc.md               |  5 ----
 .changeset/breadcrumbs-section-variant.md     |  5 ----
 .changeset/customer-goto-domcontentloaded.md  |  5 ----
 .changeset/expr-eval-estree-from-npm.md       |  5 ----
 .../fix-ask-button-centered-paragraph.md      |  5 ----
 .changeset/flaky-cookie-banner-screenshots.md |  5 ----
 .../hide-admin-toolbar-in-screenshots.md      |  5 ----
 .changeset/markdown-ask-goal-param.md         |  5 ----
 .changeset/mcp-available-badge.md             |  7 -----
 .changeset/mcp-search-best-section.md         |  5 ----
 .../reduced-motion-maxwidth-transition.md     |  5 ----
 .changeset/reset-cross-space-nav-e2e.md       |  5 ----
 .changeset/rnd-11617-nullable-anyof.md        |  5 ----
 .changeset/rnd-11620-changed-pages-toolbar.md |  5 ----
 .changeset/section-dropdown-clipping.md       |  5 ----
 .changeset/section-dropdown-embedded-empty.md |  5 ----
 .changeset/spicy-pages-rescue.md              |  5 ----
 bun.lock                                      | 22 +++++++--------
 package.json                                  |  2 +-
 packages/expr/CHANGELOG.md                    |  6 +++++
 packages/expr/package.json                    |  2 +-
 packages/gitbook/CHANGELOG.md                 | 27 +++++++++++++++++++
 packages/gitbook/package.json                 |  2 +-
 packages/openapi-parser/CHANGELOG.md          |  6 +++++
 packages/openapi-parser/package.json          |  2 +-
 packages/react-openapi/CHANGELOG.md           | 10 +++++++
 packages/react-openapi/package.json           |  2 +-
 28 files changed, 65 insertions(+), 108 deletions(-)
 delete mode 100644 .changeset/ask-ai-paragraph-margin-button.md
 delete mode 100644 .changeset/back-to-space-toc.md
 delete mode 100644 .changeset/breadcrumbs-section-variant.md
 delete mode 100644 .changeset/customer-goto-domcontentloaded.md
 delete mode 100644 .changeset/expr-eval-estree-from-npm.md
 delete mode 100644 .changeset/fix-ask-button-centered-paragraph.md
 delete mode 100644 .changeset/flaky-cookie-banner-screenshots.md
 delete mode 100644 .changeset/hide-admin-toolbar-in-screenshots.md
 delete mode 100644 .changeset/markdown-ask-goal-param.md
 delete mode 100644 .changeset/mcp-available-badge.md
 delete mode 100644 .changeset/mcp-search-best-section.md
 delete mode 100644 .changeset/reduced-motion-maxwidth-transition.md
 delete mode 100644 .changeset/reset-cross-space-nav-e2e.md
 delete mode 100644 .changeset/rnd-11617-nullable-anyof.md
 delete mode 100644 .changeset/rnd-11620-changed-pages-toolbar.md
 delete mode 100644 .changeset/section-dropdown-clipping.md
 delete mode 100644 .changeset/section-dropdown-embedded-empty.md
 delete mode 100644 .changeset/spicy-pages-rescue.md

diff --git a/.changeset/ask-ai-paragraph-margin-button.md b/.changeset/ask-ai-paragraph-margin-button.md
deleted file mode 100644
index a273e6a38..000000000
--- a/.changeset/ask-ai-paragraph-margin-button.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Add a hover affordance in the document margin to ask the AI Assistant about a paragraph. On devices with a fine pointer, hovering a top-level paragraph reveals a small button that stages the paragraph's text as context and opens the assistant — making the existing text-selection "Ask" flow more discoverable.
diff --git a/.changeset/back-to-space-toc.md b/.changeset/back-to-space-toc.md
deleted file mode 100644
index fc502837a..000000000
--- a/.changeset/back-to-space-toc.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Show a "Back to [space]" shortcut at the top of the table of contents when a reader follows a link into a different space, so they don't lose track of where they were browsing from.
diff --git a/.changeset/breadcrumbs-section-variant.md b/.changeset/breadcrumbs-section-variant.md
deleted file mode 100644
index 0a7116f6d..000000000
--- a/.changeset/breadcrumbs-section-variant.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Show where a page lives in the site at the start of the page breadcrumbs: its section (including any enclosing section groups) and variant. Hovering any breadcrumb item reveals a dropdown to switch to its siblings at the same level — other section groups, sections, variants, page groups or pages — computed on the server from already-available data (no extra request). Language variants are left to the dedicated language picker rather than shown as a crumb. Also restyles the breadcrumbs to normal casing (matching search results).
diff --git a/.changeset/customer-goto-domcontentloaded.md b/.changeset/customer-goto-domcontentloaded.md
deleted file mode 100644
index c34b07ba3..000000000
--- a/.changeset/customer-goto-domcontentloaded.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Navigate customer visual tests with `domcontentloaded` to avoid `load`-event hangs on external sites.
diff --git a/.changeset/expr-eval-estree-from-npm.md b/.changeset/expr-eval-estree-from-npm.md
deleted file mode 100644
index 2aec2692e..000000000
--- a/.changeset/expr-eval-estree-from-npm.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"@gitbook/expr": patch
----
-
-Depend on `eval-estree-expression` from the npm registry (`^3.0.1`) instead of a pinned GitHub commit. The published `3.0.1` release is built from the exact commit the package was pinned to, so the code is unchanged — this only removes the fragile git/tarball dependency so consumers install it from npm like any other package.
diff --git a/.changeset/fix-ask-button-centered-paragraph.md b/.changeset/fix-ask-button-centered-paragraph.md
deleted file mode 100644
index 1f89e6c26..000000000
--- a/.changeset/fix-ask-button-centered-paragraph.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Fix center- and end-aligned paragraphs shifting left on wide/no-TOC pages when the AI Assistant is enabled, caused by the per-paragraph ask-button wrapper not inheriting the block alignment.
diff --git a/.changeset/flaky-cookie-banner-screenshots.md b/.changeset/flaky-cookie-banner-screenshots.md
deleted file mode 100644
index 8f3b9601a..000000000
--- a/.changeset/flaky-cookie-banner-screenshots.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Fix flaky customer e2e screenshots by waiting for the built-in cookie banner before capturing.
diff --git a/.changeset/hide-admin-toolbar-in-screenshots.md b/.changeset/hide-admin-toolbar-in-screenshots.md
deleted file mode 100644
index 76d60b905..000000000
--- a/.changeset/hide-admin-toolbar-in-screenshots.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Add a `data-testid` to the admin toolbar so e2e tests can assert its presence while hiding it from visual screenshots (it animates open, causing flaky diffs).
diff --git a/.changeset/markdown-ask-goal-param.md b/.changeset/markdown-ask-goal-param.md
deleted file mode 100644
index d10324fda..000000000
--- a/.changeset/markdown-ask-goal-param.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Support an optional `goal` query parameter on the markdown ask interface (`?ask=…&goal=…`), letting agents describe the broader end goal they are working towards so the answer can be steered towards it.
diff --git a/.changeset/mcp-available-badge.md b/.changeset/mcp-available-badge.md
deleted file mode 100644
index 67a7b53bd..000000000
--- a/.changeset/mcp-available-badge.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-"@gitbook/openapi-parser": patch
-"@gitbook/react-openapi": patch
-"gitbook": patch
----
-
-Add an "Available in MCP" badge on OpenAPI operations marked with `x-gitbook-mcp: true`. When `x-gitbook-mcp-url` is set (on the operation, path, or root — most specific wins), the badge becomes a button that copies the MCP server URL to the clipboard.
diff --git a/.changeset/mcp-search-best-section.md b/.changeset/mcp-search-best-section.md
deleted file mode 100644
index 189c1799a..000000000
--- a/.changeset/mcp-search-best-section.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Reduce the size of `searchDocumentation` MCP responses by returning only the best-matching section per page instead of concatenating every section body.
diff --git a/.changeset/reduced-motion-maxwidth-transition.md b/.changeset/reduced-motion-maxwidth-transition.md
deleted file mode 100644
index 682519b53..000000000
--- a/.changeset/reduced-motion-maxwidth-transition.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Disable the content max-width transition under reduced motion, matching the surrounding layout transitions.
diff --git a/.changeset/reset-cross-space-nav-e2e.md b/.changeset/reset-cross-space-nav-e2e.md
deleted file mode 100644
index e343faac9..000000000
--- a/.changeset/reset-cross-space-nav-e2e.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Reset cross-space navigation state between e2e navigations so the "Back to <space>" shortcut can't leak in and cause flaky screenshots.
diff --git a/.changeset/rnd-11617-nullable-anyof.md b/.changeset/rnd-11617-nullable-anyof.md
deleted file mode 100644
index b9b114e9d..000000000
--- a/.changeset/rnd-11617-nullable-anyof.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Render `anyOf`/`oneOf` with a `null` member as a nullable schema instead of a `null` union branch.
diff --git a/.changeset/rnd-11620-changed-pages-toolbar.md b/.changeset/rnd-11620-changed-pages-toolbar.md
deleted file mode 100644
index 8847645f3..000000000
--- a/.changeset/rnd-11620-changed-pages-toolbar.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Show changed pages in preview toolbars for change requests and revisions.
diff --git a/.changeset/section-dropdown-clipping.md b/.changeset/section-dropdown-clipping.md
deleted file mode 100644
index a0fd5393d..000000000
--- a/.changeset/section-dropdown-clipping.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Fix site section dropdowns not being bounded by their container during the open/resize animation, causing the contents to visually clip.
diff --git a/.changeset/section-dropdown-embedded-empty.md b/.changeset/section-dropdown-embedded-empty.md
deleted file mode 100644
index dfd70d68f..000000000
--- a/.changeset/section-dropdown-embedded-empty.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Fix grouped top-nav section dropdowns rendering empty when the site is embedded in an iframe (visitor-auth embeds, editor preview) or shown in the embeddable view. The dropdown viewport is composited and animated, and a clipped composited layer fails to rasterize its text in Chromium when painted inside a sub compositing root; the rounded-corner clipping is now done on an inner wrapper so the viewport itself is no longer clipped.
diff --git a/.changeset/spicy-pages-rescue.md b/.changeset/spicy-pages-rescue.md
deleted file mode 100644
index 123ecbefb..000000000
--- a/.changeset/spicy-pages-rescue.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Improve the 404 page: remove the table of contents sidebar and center the content, suggest related pages (ranked from the already-cached search index, so no extra request per 404), show a search or assistant input depending on the site's AI configuration, and move "Go to homepage" to the bottom as a last resort.
diff --git a/bun.lock b/bun.lock
index e749e7550..742f26e50 100644
--- a/bun.lock
+++ b/bun.lock
@@ -74,7 +74,7 @@
     },
     "packages/expr": {
       "name": "@gitbook/expr",
-      "version": "1.3.0",
+      "version": "1.3.1",
       "dependencies": {
         "acorn": "^8.15.0",
         "acorn-loose": "^8.5.2",
@@ -109,7 +109,7 @@
     },
     "packages/gitbook": {
       "name": "gitbook",
-      "version": "0.27.1",
+      "version": "0.27.2",
       "dependencies": {
         "@cloudflare/workers-types": "^4.20251011.0",
         "@gitbook/api": "catalog:",
@@ -253,7 +253,7 @@
     },
     "packages/openapi-parser": {
       "name": "@gitbook/openapi-parser",
-      "version": "3.0.11",
+      "version": "3.0.12",
       "dependencies": {
         "@scalar/json-magic": "^0.9.4",
         "@scalar/openapi-parser": "^0.24.5",
@@ -312,7 +312,7 @@
     },
     "packages/react-openapi": {
       "name": "@gitbook/react-openapi",
-      "version": "1.5.14",
+      "version": "1.5.15",
       "dependencies": {
         "@gitbook/expr": "workspace:*",
         "@gitbook/openapi-parser": "workspace:*",
@@ -1594,17 +1594,17 @@
 
     "@tsconfig/strictest": ["@tsconfig/strictest@2.0.6", "", {}, "sha512-tPOhmDhIUcDjvpDDYyiUdssP84Eqm7n5KxJe5J3/g+s6xoDIPAf+SIn06dhw7VkhxIvLOnhDDrX7tsqMHNEhDg=="],
 
-    "@turbo/darwin-64": ["@turbo/darwin-64@2.9.18", "", { "os": "darwin", "cpu": "x64" }, "sha512-9f27peFu16ur8c0v9nUFUEyBnbKuuFsUTjHFWfmwGfzySBXbHwzU44QhZon6Mznz0cHsIr3984NQj/bVrnGSRw=="],
+    "@turbo/darwin-64": ["@turbo/darwin-64@2.10.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-guuiO2kKc7yUQFU2jhWyM/BrYGD/brqb0+JvJIXTQ/QI1NlWfHZ1id50kkkOWqxmBiDc8DgW2orfY85pQIc7gw=="],
 
-    "@turbo/darwin-arm64": ["@turbo/darwin-arm64@2.9.18", "", { "os": "darwin", "cpu": "arm64" }, "sha512-9A6TMRq/Ib+QnbhLlgkhOm+624wO4pzSQ/yQviQfWHOlFvaYxdnIAYmu2H6TS6y7kSVL0DvzNe04NbESTOzFVQ=="],
+    "@turbo/darwin-arm64": ["@turbo/darwin-arm64@2.10.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-UglEDl/r1/h5Vw6oS6cEE29Jugz2sDLxHCSupNznKatj1fDMRXFqYKFcbvm8RTFhtYPI45NxkrPNo9BqNychBg=="],
 
-    "@turbo/linux-64": ["@turbo/linux-64@2.9.18", "", { "os": "linux", "cpu": "x64" }, "sha512-zCdIDtz69AnbYh913elJRRoF3QY5aa2HNnf+4rAkc7bQ+tWujiDkCNV7stazOUPggaDvhKIf2Z87qHftTeXSkw=="],
+    "@turbo/linux-64": ["@turbo/linux-64@2.10.3", "", { "os": "linux", "cpu": "x64" }, "sha512-KuQxaPWD7OBmwEZqO0sgijwcuXR5eMWbo7BEt2m1D2Q3RylJDj7WMcJ0Btv2VJA0QC+khzAaTAm1yWowJ0CWAw=="],
 
-    "@turbo/linux-arm64": ["@turbo/linux-arm64@2.9.18", "", { "os": "linux", "cpu": "arm64" }, "sha512-Va1kXI04naMgYwqv/5Dfa36dTDx8015U7oaQAjrXa45ua9OoFjSV4OmvkML4EmXvUclQHCiBRbY8bvd0jV7eAg=="],
+    "@turbo/linux-arm64": ["@turbo/linux-arm64@2.10.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-DPkIKQ+6p0sho3Cx/e/A3F+AKgXQJA+z//cHsTcyyM1YWRGSYA0UTP8NUpb4iS2tVBSniGwmjRUr73hpq8kcDg=="],
 
-    "@turbo/windows-64": ["@turbo/windows-64@2.9.18", "", { "os": "win32", "cpu": "x64" }, "sha512-m0kDhZANxSNz9ck1ybogFscHabriAsp4eDFNrN/1H5WrgTF7b3VlcPZnhuO3v2+E2KnCbeAc+UUT10BZZHdDKw=="],
+    "@turbo/windows-64": ["@turbo/windows-64@2.10.3", "", { "os": "win32", "cpu": "x64" }, "sha512-8NvFAze9D4PsosZAnK3aGqHz2vLzREz9lNIxLgfE0jRchq2sZQE190cwFm7WX17yg3ftPvwCvWH3rhLbG1UHCQ=="],
 
-    "@turbo/windows-arm64": ["@turbo/windows-arm64@2.9.18", "", { "os": "win32", "cpu": "arm64" }, "sha512-nUdR8WqoomUys9iIQmG45TMiizJ+5BV8egSeLLZba/AWblyp3fVBcIH1kSE58OtK4g2YzbMJEth6Ttv9w5rqMA=="],
+    "@turbo/windows-arm64": ["@turbo/windows-arm64@2.10.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-AqjqV5cHbFa0YRaQ+Dyw6lSm6as4h/Uf8LcZ7VN8i+Odr23ShFD5SUvVAR1d3rZqibFVs9c0VdtXdfQfkdcs3A=="],
 
     "@tusbar/cache-control": ["@tusbar/cache-control@1.0.2", "", {}, "sha512-PXfjYTYBVvMPYCLDWj+xIOA9ITFbbhWCHzLcqUCJ5TPGm4JO4cxpGb7x3K8Q1K1ADgNgfBxLsDcTMVRydtZB9A=="],
 
@@ -3360,7 +3360,7 @@
 
     "tsx": ["tsx@4.21.0", "", { "dependencies": { "esbuild": "~0.27.0", "get-tsconfig": "^4.7.5" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "bin": { "tsx": "dist/cli.mjs" } }, "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw=="],
 
-    "turbo": ["turbo@2.9.18", "", { "optionalDependencies": { "@turbo/darwin-64": "2.9.18", "@turbo/darwin-arm64": "2.9.18", "@turbo/linux-64": "2.9.18", "@turbo/linux-arm64": "2.9.18", "@turbo/windows-64": "2.9.18", "@turbo/windows-arm64": "2.9.18" }, "bin": { "turbo": "bin/turbo" } }, "sha512-bwabv6PupzeavybzEoArBAkwq5fnzwf8OFnRtpHwnviFWuwJPFxtyH+aVp36TmIqK3aYYgtTJ3J0m2ysxxSzQg=="],
+    "turbo": ["turbo@2.10.3", "", { "optionalDependencies": { "@turbo/darwin-64": "2.10.3", "@turbo/darwin-arm64": "2.10.3", "@turbo/linux-64": "2.10.3", "@turbo/linux-arm64": "2.10.3", "@turbo/windows-64": "2.10.3", "@turbo/windows-arm64": "2.10.3" }, "bin": { "turbo": "bin/turbo" } }, "sha512-uZIqzfgtWbyqu1Tqwdd0giRnPGgL0ejbcdF8eZLJhtTTVSrOgArZGzYeXTD6XNcc7ANgdhqex11Y9bHBeyiQLQ=="],
 
     "type": ["type@2.7.3", "", {}, "sha512-8j+1QmAbPvLZow5Qpi6NCaN8FB60p/6x8/vfNqOk/hC+HuvFZhL4+WfekuhQLiqFZXOgQdrs3B+XxEmCc6b3FQ=="],
 
diff --git a/package.json b/package.json
index c46549d49..f90d30817 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,7 @@
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
         "@changesets/cli": "^2.31.0",
-        "turbo": "^2.9.18",
+        "turbo": "^2.10.3",
         "vercel": "50.37.3"
     },
     "packageManager": "bun@1.3.7",
diff --git a/packages/expr/CHANGELOG.md b/packages/expr/CHANGELOG.md
index ff056b763..62ba8e602 100644
--- a/packages/expr/CHANGELOG.md
+++ b/packages/expr/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @gitbook/expr
 
+## 1.3.1
+
+### Patch Changes
+
+- 3fedaaa: Depend on `eval-estree-expression` from the npm registry (`^3.0.1`) instead of a pinned GitHub commit. The published `3.0.1` release is built from the exact commit the package was pinned to, so the code is unchanged — this only removes the fragile git/tarball dependency so consumers install it from npm like any other package.
+
 ## 1.3.0
 
 ### Minor Changes
diff --git a/packages/expr/package.json b/packages/expr/package.json
index 129e51273..7b4a0e8d1 100644
--- a/packages/expr/package.json
+++ b/packages/expr/package.json
@@ -1,7 +1,7 @@
 {
     "name": "@gitbook/expr",
     "description": "Safely evaluate & parse user-defined GitBook expressions.",
-    "version": "1.3.0",
+    "version": "1.3.1",
     "type": "module",
     "exports": {
         ".": {
diff --git a/packages/gitbook/CHANGELOG.md b/packages/gitbook/CHANGELOG.md
index 42dc1275d..359c414a6 100644
--- a/packages/gitbook/CHANGELOG.md
+++ b/packages/gitbook/CHANGELOG.md
@@ -1,5 +1,32 @@
 # gitbook
 
+## 0.27.2
+
+### Patch Changes
+
+- bb30db1: Add a hover affordance in the document margin to ask the AI Assistant about a paragraph. On devices with a fine pointer, hovering a top-level paragraph reveals a small button that stages the paragraph's text as context and opens the assistant — making the existing text-selection "Ask" flow more discoverable.
+- 62ca6d3: Show a "Back to [space]" shortcut at the top of the table of contents when a reader follows a link into a different space, so they don't lose track of where they were browsing from.
+- fdea8f1: Show where a page lives in the site at the start of the page breadcrumbs: its section (including any enclosing section groups) and variant. Hovering any breadcrumb item reveals a dropdown to switch to its siblings at the same level — other section groups, sections, variants, page groups or pages — computed on the server from already-available data (no extra request). Language variants are left to the dedicated language picker rather than shown as a crumb. Also restyles the breadcrumbs to normal casing (matching search results).
+- 37c2dd8: Navigate customer visual tests with `domcontentloaded` to avoid `load`-event hangs on external sites.
+- c923c65: Fix center- and end-aligned paragraphs shifting left on wide/no-TOC pages when the AI Assistant is enabled, caused by the per-paragraph ask-button wrapper not inheriting the block alignment.
+- 37c2dd8: Fix flaky customer e2e screenshots by waiting for the built-in cookie banner before capturing.
+- 37c2dd8: Add a `data-testid` to the admin toolbar so e2e tests can assert its presence while hiding it from visual screenshots (it animates open, causing flaky diffs).
+- 36dbdb4: Support an optional `goal` query parameter on the markdown ask interface (`?ask=…&goal=…`), letting agents describe the broader end goal they are working towards so the answer can be steered towards it.
+- 7e55cd5: Add an "Available in MCP" badge on OpenAPI operations marked with `x-gitbook-mcp: true`. When `x-gitbook-mcp-url` is set (on the operation, path, or root — most specific wins), the badge becomes a button that copies the MCP server URL to the clipboard.
+- 6146f8e: Reduce the size of `searchDocumentation` MCP responses by returning only the best-matching section per page instead of concatenating every section body.
+- 37c2dd8: Disable the content max-width transition under reduced motion, matching the surrounding layout transitions.
+- 37c2dd8: Reset cross-space navigation state between e2e navigations so the "Back to <space>" shortcut can't leak in and cause flaky screenshots.
+- bcea23e: Render `anyOf`/`oneOf` with a `null` member as a nullable schema instead of a `null` union branch.
+- 77efd44: Show changed pages in preview toolbars for change requests and revisions.
+- 578a3a8: Fix site section dropdowns not being bounded by their container during the open/resize animation, causing the contents to visually clip.
+- 2dc76a2: Fix grouped top-nav section dropdowns rendering empty when the site is embedded in an iframe (visitor-auth embeds, editor preview) or shown in the embeddable view. The dropdown viewport is composited and animated, and a clipped composited layer fails to rasterize its text in Chromium when painted inside a sub compositing root; the rounded-corner clipping is now done on an inner wrapper so the viewport itself is no longer clipped.
+- 9f65133: Improve the 404 page: remove the table of contents sidebar and center the content, suggest related pages (ranked from the already-cached search index, so no extra request per 404), show a search or assistant input depending on the site's AI configuration, and move "Go to homepage" to the bottom as a last resort.
+- Updated dependencies [3fedaaa]
+- Updated dependencies [7e55cd5]
+  - @gitbook/expr@1.3.1
+  - @gitbook/openapi-parser@3.0.12
+  - @gitbook/react-openapi@1.5.15
+
 ## 0.27.1
 
 ### Patch Changes
diff --git a/packages/gitbook/package.json b/packages/gitbook/package.json
index 37a97b527..8afd96e79 100644
--- a/packages/gitbook/package.json
+++ b/packages/gitbook/package.json
@@ -1,6 +1,6 @@
 {
     "name": "gitbook",
-    "version": "0.27.1",
+    "version": "0.27.2",
     "private": true,
     "dependencies": {
         "@cloudflare/workers-types": "^4.20251011.0",
diff --git a/packages/openapi-parser/CHANGELOG.md b/packages/openapi-parser/CHANGELOG.md
index 64c4ad271..81a8ea7f3 100644
--- a/packages/openapi-parser/CHANGELOG.md
+++ b/packages/openapi-parser/CHANGELOG.md
@@ -1,5 +1,11 @@
 # @gitbook/openapi-parser
 
+## 3.0.12
+
+### Patch Changes
+
+- 7e55cd5: Add an "Available in MCP" badge on OpenAPI operations marked with `x-gitbook-mcp: true`. When `x-gitbook-mcp-url` is set (on the operation, path, or root — most specific wins), the badge becomes a button that copies the MCP server URL to the clipboard.
+
 ## 3.0.11
 
 ### Patch Changes
diff --git a/packages/openapi-parser/package.json b/packages/openapi-parser/package.json
index ef2cd2c43..f41988437 100644
--- a/packages/openapi-parser/package.json
+++ b/packages/openapi-parser/package.json
@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "3.0.11",
+    "version": "3.0.12",
     "sideEffects": false,
     "dependencies": {
         "@scalar/json-magic": "^0.9.4",
diff --git a/packages/react-openapi/CHANGELOG.md b/packages/react-openapi/CHANGELOG.md
index 5e49f072a..fa01a5f30 100644
--- a/packages/react-openapi/CHANGELOG.md
+++ b/packages/react-openapi/CHANGELOG.md
@@ -1,5 +1,15 @@
 # @gitbook/react-openapi
 
+## 1.5.15
+
+### Patch Changes
+
+- 7e55cd5: Add an "Available in MCP" badge on OpenAPI operations marked with `x-gitbook-mcp: true`. When `x-gitbook-mcp-url` is set (on the operation, path, or root — most specific wins), the badge becomes a button that copies the MCP server URL to the clipboard.
+- Updated dependencies [3fedaaa]
+- Updated dependencies [7e55cd5]
+  - @gitbook/expr@1.3.1
+  - @gitbook/openapi-parser@3.0.12
+
 ## 1.5.14
 
 ### Patch Changes
diff --git a/packages/react-openapi/package.json b/packages/react-openapi/package.json
index 8793c4d94..b7c1bf3db 100644
--- a/packages/react-openapi/package.json
+++ b/packages/react-openapi/package.json
@@ -7,7 +7,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.5.14",
+    "version": "1.5.15",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/expr": "workspace:*",

From 8676ad19e201e9265e0139fd7941616424e26e13 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Mon, 6 Jul 2026 16:58:02 +0100
Subject: [PATCH 13/46] RND-11788: hide unlabelled button from screen readers
 (#4369)

---
 .changeset/strict-jokes-play.md                              | 5 +++++
 .../src/components/TableOfContents/ToggleableLinkItem.tsx    | 1 +
 2 files changed, 6 insertions(+)
 create mode 100644 .changeset/strict-jokes-play.md

diff --git a/.changeset/strict-jokes-play.md b/.changeset/strict-jokes-play.md
new file mode 100644
index 000000000..fa5130941
--- /dev/null
+++ b/.changeset/strict-jokes-play.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Hide unfocusable unlabelled button from screen readers
diff --git a/packages/gitbook/src/components/TableOfContents/ToggleableLinkItem.tsx b/packages/gitbook/src/components/TableOfContents/ToggleableLinkItem.tsx
index 118a5ea51..b287f4741 100644
--- a/packages/gitbook/src/components/TableOfContents/ToggleableLinkItem.tsx
+++ b/packages/gitbook/src/components/TableOfContents/ToggleableLinkItem.tsx
@@ -172,6 +172,7 @@ function Toggler(props: {
             size="xsmall"
             iconOnly
             variant="blank"
+            aria-hidden="true" // The button has no label or focus so hiding it from screen readers.
             className="-my-0.5 ml-auto min-h-6 min-w-6 text-current hover:bg-tint-base"
             tabIndex={-1} // Prevent focus on the button since it's already inside a clickable link that performs the same toggle action.
         />

From f3408ed4950319cd6ca63ba3e57fd22e918fcce8 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Mon, 6 Jul 2026 16:58:23 +0100
Subject: [PATCH 14/46] A11y fix: table structure (#4368)

---
 .changeset/wacky-eyes-post.md                               | 5 +++++
 .../src/components/DocumentView/Table/StickyViewGrid.tsx    | 6 +++++-
 .../gitbook/src/components/DocumentView/Table/Table.tsx     | 5 ++++-
 .../gitbook/src/components/DocumentView/Table/ViewGrid.tsx  | 6 +-----
 4 files changed, 15 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/wacky-eyes-post.md

diff --git a/.changeset/wacky-eyes-post.md b/.changeset/wacky-eyes-post.md
new file mode 100644
index 000000000..0ef6f6347
--- /dev/null
+++ b/.changeset/wacky-eyes-post.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+a11y screen reader fixes
diff --git a/packages/gitbook/src/components/DocumentView/Table/StickyViewGrid.tsx b/packages/gitbook/src/components/DocumentView/Table/StickyViewGrid.tsx
index 791902054..7268d3dbb 100644
--- a/packages/gitbook/src/components/DocumentView/Table/StickyViewGrid.tsx
+++ b/packages/gitbook/src/components/DocumentView/Table/StickyViewGrid.tsx
@@ -28,7 +28,10 @@ function DefaultHeaderScrollGrid({
 
     return (
         <div className={className}>
-            <div className="group/table relative flex w-full min-w-0 max-w-full flex-col rounded-lg border-tint-subtle">
+            <div
+                role="table"
+                className="group/table relative flex w-full min-w-0 max-w-full flex-col rounded-lg border-tint-subtle"
+            >
                 <div className="w-full min-w-0 overflow-x-auto overflow-y-hidden overscroll-x-none border-tint-subtle">
                     <div className={tcls('flex', 'flex-col', resolvedTableClassName)}>
                         {header}
@@ -137,6 +140,7 @@ function StickyHeaderOverlayScrollGrid({
                 ref={rootRef}
                 className="group/table relative flex w-full min-w-0 max-w-full flex-col rounded-lg border-tint-subtle data-[scrollable=true]:border"
                 data-scrollable="false"
+                role="table"
             >
                 {header ? (
                     <div
diff --git a/packages/gitbook/src/components/DocumentView/Table/Table.tsx b/packages/gitbook/src/components/DocumentView/Table/Table.tsx
index 3e0c1ffd7..8166ebeea 100644
--- a/packages/gitbook/src/components/DocumentView/Table/Table.tsx
+++ b/packages/gitbook/src/components/DocumentView/Table/Table.tsx
@@ -140,7 +140,10 @@ function TableView({
                             'w-full min-w-0 overflow-x-auto overflow-y-hidden overscroll-x-none border-tint-subtle '
                         )}
                     >
-                        <div className={tcls('flex', 'flex-col', tableContainerClassName)}>
+                        <div
+                            className={tcls('flex', 'flex-col', tableContainerClassName)}
+                            role="table"
+                        >
                             {withHeader ? (
                                 <ViewGridHeader
                                     {...gridProps}
diff --git a/packages/gitbook/src/components/DocumentView/Table/ViewGrid.tsx b/packages/gitbook/src/components/DocumentView/Table/ViewGrid.tsx
index 53a6b23a1..7249647f4 100644
--- a/packages/gitbook/src/components/DocumentView/Table/ViewGrid.tsx
+++ b/packages/gitbook/src/components/DocumentView/Table/ViewGrid.tsx
@@ -108,9 +108,5 @@ export function ViewGrid(props: ViewGridProps) {
         </div>
     );
 
-    return (
-        <div role="table" className={tcls('flex', 'flex-col', tableClassName ?? tableWidth)}>
-            {body}
-        </div>
-    );
+    return <div className={tcls('flex', 'flex-col', tableClassName ?? tableWidth)}>{body}</div>;
 }

From ad3399b42ee20feb2c89b29ab2d09b6ebf1e510a Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Mon, 6 Jul 2026 19:27:04 +0200
Subject: [PATCH 15/46] Refine the per-paragraph ask button (shorter tooltip,
 hide inside cards) (#4365)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/shorten-paragraph-ask-tooltip.md            |  5 +++++
 .../AskAIParagraphButton/AskAIParagraphButton.tsx      | 10 ++++------
 .../src/components/DocumentView/Table/RecordCard.tsx   |  3 +++
 packages/gitbook/src/intl/translations/ar.ts           |  1 -
 packages/gitbook/src/intl/translations/bg.ts           |  1 -
 packages/gitbook/src/intl/translations/cs.ts           |  1 -
 packages/gitbook/src/intl/translations/da.ts           |  1 -
 packages/gitbook/src/intl/translations/de.ts           |  1 -
 packages/gitbook/src/intl/translations/el.ts           |  1 -
 packages/gitbook/src/intl/translations/en.ts           |  1 -
 packages/gitbook/src/intl/translations/es.ts           |  1 -
 packages/gitbook/src/intl/translations/et.ts           |  1 -
 packages/gitbook/src/intl/translations/fi.ts           |  1 -
 packages/gitbook/src/intl/translations/fr.ts           |  1 -
 packages/gitbook/src/intl/translations/he.ts           |  1 -
 packages/gitbook/src/intl/translations/hi.ts           |  1 -
 packages/gitbook/src/intl/translations/hr.ts           |  1 -
 packages/gitbook/src/intl/translations/hu.ts           |  1 -
 packages/gitbook/src/intl/translations/id.ts           |  1 -
 packages/gitbook/src/intl/translations/it.ts           |  1 -
 packages/gitbook/src/intl/translations/ja.ts           |  1 -
 packages/gitbook/src/intl/translations/ko.ts           |  1 -
 packages/gitbook/src/intl/translations/lt.ts           |  1 -
 packages/gitbook/src/intl/translations/lv.ts           |  1 -
 packages/gitbook/src/intl/translations/ms.ts           |  1 -
 packages/gitbook/src/intl/translations/nl.ts           |  1 -
 packages/gitbook/src/intl/translations/no.ts           |  1 -
 packages/gitbook/src/intl/translations/pl.ts           |  1 -
 packages/gitbook/src/intl/translations/pt-br.ts        |  1 -
 packages/gitbook/src/intl/translations/pt.ts           |  1 -
 packages/gitbook/src/intl/translations/ro.ts           |  1 -
 packages/gitbook/src/intl/translations/ru.ts           |  1 -
 packages/gitbook/src/intl/translations/sk.ts           |  1 -
 packages/gitbook/src/intl/translations/sl.ts           |  1 -
 packages/gitbook/src/intl/translations/sv.ts           |  1 -
 packages/gitbook/src/intl/translations/th.ts           |  1 -
 packages/gitbook/src/intl/translations/tr.ts           |  1 -
 packages/gitbook/src/intl/translations/uk.ts           |  1 -
 packages/gitbook/src/intl/translations/vi.ts           |  1 -
 packages/gitbook/src/intl/translations/yue.ts          |  1 -
 packages/gitbook/src/intl/translations/zh-tw.ts        |  1 -
 packages/gitbook/src/intl/translations/zh.ts           |  1 -
 42 files changed, 12 insertions(+), 45 deletions(-)
 create mode 100644 .changeset/shorten-paragraph-ask-tooltip.md

diff --git a/.changeset/shorten-paragraph-ask-tooltip.md b/.changeset/shorten-paragraph-ask-tooltip.md
new file mode 100644
index 000000000..19028516b
--- /dev/null
+++ b/.changeset/shorten-paragraph-ask-tooltip.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Refine the per-paragraph AI ask button: shorten its tooltip to "Ask" (from "Ask <assistant> about this"), and hide it inside cards where it would otherwise be clipped by the card's overflow.
diff --git a/packages/gitbook/src/components/AIChat/AskAIParagraphButton/AskAIParagraphButton.tsx b/packages/gitbook/src/components/AIChat/AskAIParagraphButton/AskAIParagraphButton.tsx
index 2f2b269a1..0df53f8cc 100644
--- a/packages/gitbook/src/components/AIChat/AskAIParagraphButton/AskAIParagraphButton.tsx
+++ b/packages/gitbook/src/components/AIChat/AskAIParagraphButton/AskAIParagraphButton.tsx
@@ -7,7 +7,6 @@ import { Button } from '@/components/primitives';
 import { t, tString, useLanguage } from '@/intl/client';
 import { type ClassValue, tcls } from '@/lib/tailwind';
 
-import { getAIChatName } from '../AIChat';
 import { AIChatIcon } from '../AIChatIcon';
 
 /**
@@ -48,13 +47,16 @@ export function AskAIParagraphButton(props: { content: string; className?: Class
                 // Per-block nudges: `in-[…]` matches an ancestor (tag or class) with no markup
                 // changes elsewhere — add a self-contained rule per block type to clear its gutter.
                 'in-[.hint]:-top-0.5 in-[.hint]:pr-2',
+                'in-[li]:-left-14',
                 'in-[blockquote]:pr-0',
                 // Hover affordance only: hidden until the paragraph (or the button) is hovered.
                 'invisible opacity-0 transition-opacity duration-150',
                 'hover:visible hover:opacity-100 group-hover/ask-ai:visible group-hover/ask-ai:opacity-100',
                 // Never shown on touch / hover-less contexts.
                 'not-pointer-fine:hidden',
+                // Hidden where an overflow-clipped ancestor would cut it off (tables, record cards).
                 'in-[[role=table]]:hidden',
+                'in-[[data-card]]:hidden',
                 className
             )}
         >
@@ -63,11 +65,7 @@ export function AskAIParagraphButton(props: { content: string; className?: Class
                 size="xsmall"
                 iconOnly
                 icon={<AIChatIcon state="default" trademark={config.trademark} />}
-                label={t(
-                    language,
-                    'ai_chat_ask_about_this',
-                    config.assistantName ?? getAIChatName(language, config.trademark)
-                )}
+                label={t(language, 'ask')}
                 onClick={onClick}
                 // Don't steal focus (and shift the scroll position) when clicked with the mouse.
                 onMouseDown={(event) => event.preventDefault()}
diff --git a/packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx b/packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx
index 04ca7edfc..ba4132bbf 100644
--- a/packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx
+++ b/packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx
@@ -46,6 +46,9 @@ export async function RecordCard(
 
     const body = (
         <div
+            // Marks the card body so overflow-clipped affordances (e.g. the paragraph "Ask"
+            // button) can opt out of rendering inside it.
+            data-card=""
             className={tcls(
                 'grid-area-1-1',
                 'relative',
diff --git a/packages/gitbook/src/intl/translations/ar.ts b/packages/gitbook/src/intl/translations/ar.ts
index 16a2e7d5c..33c5220ac 100644
--- a/packages/gitbook/src/intl/translations/ar.ts
+++ b/packages/gitbook/src/intl/translations/ar.ts
@@ -147,7 +147,6 @@ export const ar: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'تم استدعاء ${1}',
     ai_chat_ask: 'اسأل ${1}',
     ai_chat_ask_about: 'اسأل ${1} عن ${2}',
-    ai_chat_ask_about_this: 'اسأل ${1} عن هذا',
     this_page: 'هذه الصفحة',
     ai_chat_paragraph_draft: 'أخبرني المزيد عن هذا',
     ai_chat_ask_query: 'اسأل ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/bg.ts b/packages/gitbook/src/intl/translations/bg.ts
index 9dc337a1a..fb041290a 100644
--- a/packages/gitbook/src/intl/translations/bg.ts
+++ b/packages/gitbook/src/intl/translations/bg.ts
@@ -151,7 +151,6 @@ export const bg: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Извика ${1}',
     ai_chat_ask: 'Попитайте ${1}',
     ai_chat_ask_about: 'Попитайте ${1} за ${2}',
-    ai_chat_ask_about_this: 'Попитайте ${1} за това',
     this_page: 'тази страница',
     ai_chat_paragraph_draft: 'Кажи ми повече за това',
     ai_chat_ask_query: 'Попитайте ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/cs.ts b/packages/gitbook/src/intl/translations/cs.ts
index c44ffe3af..f444563dc 100644
--- a/packages/gitbook/src/intl/translations/cs.ts
+++ b/packages/gitbook/src/intl/translations/cs.ts
@@ -149,7 +149,6 @@ export const cs: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Zavolal ${1}',
     ai_chat_ask: 'Zeptat se ${1}',
     ai_chat_ask_about: 'Zeptat se ${1} na ${2}',
-    ai_chat_ask_about_this: 'Zeptat se ${1} na to',
     this_page: 'tuto stránku',
     ai_chat_paragraph_draft: 'Řekni mi o tom více',
     ai_chat_ask_query: 'Zeptat se ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/da.ts b/packages/gitbook/src/intl/translations/da.ts
index 287328a5e..775393096 100644
--- a/packages/gitbook/src/intl/translations/da.ts
+++ b/packages/gitbook/src/intl/translations/da.ts
@@ -148,7 +148,6 @@ export const da: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Kaldte ${1}',
     ai_chat_ask: 'Spørg ${1}',
     ai_chat_ask_about: 'Spørg ${1} om ${2}',
-    ai_chat_ask_about_this: 'Spørg ${1} om dette',
     this_page: 'denne side',
     ai_chat_paragraph_draft: 'Fortæl mig mere om dette',
     ai_chat_ask_query: 'Spørg ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/de.ts b/packages/gitbook/src/intl/translations/de.ts
index 9f6d330f6..1346a6473 100644
--- a/packages/gitbook/src/intl/translations/de.ts
+++ b/packages/gitbook/src/intl/translations/de.ts
@@ -155,7 +155,6 @@ export const de: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '${1} aufgerufen',
     ai_chat_ask: '${1} fragen',
     ai_chat_ask_about: '${1} zu ${2} befragen',
-    ai_chat_ask_about_this: '${1} dazu befragen',
     this_page: 'dieser Seite',
     ai_chat_paragraph_draft: 'Erzähl mir mehr darüber',
     copy_for_llms: 'Für LLMs kopieren',
diff --git a/packages/gitbook/src/intl/translations/el.ts b/packages/gitbook/src/intl/translations/el.ts
index 3d734b40a..ff293e8d1 100644
--- a/packages/gitbook/src/intl/translations/el.ts
+++ b/packages/gitbook/src/intl/translations/el.ts
@@ -153,7 +153,6 @@ export const el: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Κλήθηκε ${1}',
     ai_chat_ask: 'Ρωτήστε ${1}',
     ai_chat_ask_about: 'Ρωτήστε ${1} για ${2}',
-    ai_chat_ask_about_this: 'Ρωτήστε ${1} για αυτό',
     this_page: 'αυτή τη σελίδα',
     ai_chat_paragraph_draft: 'Πες μου περισσότερα για αυτό',
     ai_chat_ask_query: 'Ρωτήστε ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/en.ts b/packages/gitbook/src/intl/translations/en.ts
index 93cc868b7..a387b7c01 100644
--- a/packages/gitbook/src/intl/translations/en.ts
+++ b/packages/gitbook/src/intl/translations/en.ts
@@ -146,7 +146,6 @@ export const en = {
     ai_chat_tools_mcp_tool: 'Called ${1}',
     ai_chat_ask: 'Ask ${1}',
     ai_chat_ask_about: 'Ask ${1} about ${2}',
-    ai_chat_ask_about_this: 'Ask ${1} about this',
     ai_chat_ask_query: 'Ask ${1} "${2}"',
     this_page: 'this page',
     ai_chat_paragraph_draft: 'Tell me more about this',
diff --git a/packages/gitbook/src/intl/translations/es.ts b/packages/gitbook/src/intl/translations/es.ts
index be02ee437..66ed1c869 100644
--- a/packages/gitbook/src/intl/translations/es.ts
+++ b/packages/gitbook/src/intl/translations/es.ts
@@ -153,7 +153,6 @@ export const es: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Llamó a ${1}',
     ai_chat_ask: 'Preguntar a ${1}',
     ai_chat_ask_about: 'Preguntar a ${1} sobre ${2}',
-    ai_chat_ask_about_this: 'Preguntar a ${1} sobre esto',
     this_page: 'esta página',
     ai_chat_paragraph_draft: 'Cuéntame más sobre esto',
     copy_for_llms: 'Copiar para LLMs',
diff --git a/packages/gitbook/src/intl/translations/et.ts b/packages/gitbook/src/intl/translations/et.ts
index bdfe26619..bce15a732 100644
--- a/packages/gitbook/src/intl/translations/et.ts
+++ b/packages/gitbook/src/intl/translations/et.ts
@@ -148,7 +148,6 @@ export const et: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Kutsus ${1}',
     ai_chat_ask: 'Küsi ${1}',
     ai_chat_ask_about: 'Küsi ${1}: ${2}',
-    ai_chat_ask_about_this: 'Küsi ${1} käest selle kohta',
     this_page: 'seda lehte',
     ai_chat_paragraph_draft: 'Räägi mulle sellest lähemalt',
     ai_chat_ask_query: 'Küsi ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/fi.ts b/packages/gitbook/src/intl/translations/fi.ts
index 03e3de395..5bf46c819 100644
--- a/packages/gitbook/src/intl/translations/fi.ts
+++ b/packages/gitbook/src/intl/translations/fi.ts
@@ -150,7 +150,6 @@ export const fi: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Kutsuttiin ${1}',
     ai_chat_ask: 'Kysy ${1}',
     ai_chat_ask_about: 'Kysy ${1}: ${2}',
-    ai_chat_ask_about_this: 'Kysy ${1}:lta tästä',
     this_page: 'tätä sivua',
     ai_chat_paragraph_draft: 'Kerro minulle tästä lisää',
     ai_chat_ask_query: 'Kysy ${1}: "${2}"',
diff --git a/packages/gitbook/src/intl/translations/fr.ts b/packages/gitbook/src/intl/translations/fr.ts
index c5107c236..3213b5987 100644
--- a/packages/gitbook/src/intl/translations/fr.ts
+++ b/packages/gitbook/src/intl/translations/fr.ts
@@ -149,7 +149,6 @@ export const fr: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'A appelé ${1}',
     ai_chat_ask: 'Demander à ${1}',
     ai_chat_ask_about: 'Demander à ${1} à propos de ${2}',
-    ai_chat_ask_about_this: 'Interroger ${1} à ce sujet',
     this_page: 'cette page',
     ai_chat_paragraph_draft: 'En savoir plus à ce sujet',
     copy_for_llms: 'Copier pour un LLM',
diff --git a/packages/gitbook/src/intl/translations/he.ts b/packages/gitbook/src/intl/translations/he.ts
index 929187094..4c52d884b 100644
--- a/packages/gitbook/src/intl/translations/he.ts
+++ b/packages/gitbook/src/intl/translations/he.ts
@@ -146,7 +146,6 @@ export const he: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'קרא ל-${1}',
     ai_chat_ask: 'שאל את ${1}',
     ai_chat_ask_about: 'שאל את ${1} על ${2}',
-    ai_chat_ask_about_this: 'שאל את ${1} על זה',
     this_page: 'הדף הזה',
     ai_chat_paragraph_draft: 'ספר לי עוד על זה',
     ai_chat_ask_query: 'שאל את ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/hi.ts b/packages/gitbook/src/intl/translations/hi.ts
index b195edd58..6ef65af32 100644
--- a/packages/gitbook/src/intl/translations/hi.ts
+++ b/packages/gitbook/src/intl/translations/hi.ts
@@ -147,7 +147,6 @@ export const hi: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '${1} को कॉल किया',
     ai_chat_ask: '${1} से पूछें',
     ai_chat_ask_about: '${1} से ${2} के बारे में पूछें',
-    ai_chat_ask_about_this: '${1} से इसके बारे में पूछें',
     this_page: 'इस पृष्ठ',
     ai_chat_paragraph_draft: 'इसके बारे में और बताएं',
     ai_chat_ask_query: '${1} से "${2}" पूछें',
diff --git a/packages/gitbook/src/intl/translations/hr.ts b/packages/gitbook/src/intl/translations/hr.ts
index 64a150bd8..a76487ed0 100644
--- a/packages/gitbook/src/intl/translations/hr.ts
+++ b/packages/gitbook/src/intl/translations/hr.ts
@@ -149,7 +149,6 @@ export const hr: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Pozvao ${1}',
     ai_chat_ask: 'Pitaj ${1}',
     ai_chat_ask_about: 'Pitaj ${1} o ${2}',
-    ai_chat_ask_about_this: 'Pitaj ${1} o ovome',
     this_page: 'ova stranica',
     ai_chat_paragraph_draft: 'Reci mi više o ovome',
     ai_chat_ask_query: 'Pitaj ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/hu.ts b/packages/gitbook/src/intl/translations/hu.ts
index 898b9bdf6..8c7d8e43b 100644
--- a/packages/gitbook/src/intl/translations/hu.ts
+++ b/packages/gitbook/src/intl/translations/hu.ts
@@ -150,7 +150,6 @@ export const hu: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '${1} meghívva',
     ai_chat_ask: '${1} kérdezése',
     ai_chat_ask_about: '${1} megkérdezése ${2} témában',
-    ai_chat_ask_about_this: '${1} megkérdezése erről',
     this_page: 'ez az oldal',
     ai_chat_paragraph_draft: 'Mesélj erről többet',
     ai_chat_ask_query: '${1} kérdezése: "${2}"',
diff --git a/packages/gitbook/src/intl/translations/id.ts b/packages/gitbook/src/intl/translations/id.ts
index 342b706bf..6fa6ce542 100644
--- a/packages/gitbook/src/intl/translations/id.ts
+++ b/packages/gitbook/src/intl/translations/id.ts
@@ -148,7 +148,6 @@ export const id: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Memanggil ${1}',
     ai_chat_ask: 'Tanya ${1}',
     ai_chat_ask_about: 'Tanya ${1} tentang ${2}',
-    ai_chat_ask_about_this: 'Tanya ${1} tentang ini',
     this_page: 'halaman ini',
     ai_chat_paragraph_draft: 'Ceritakan lebih banyak tentang ini',
     ai_chat_ask_query: 'Tanya ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/it.ts b/packages/gitbook/src/intl/translations/it.ts
index 111b96159..18af7b971 100644
--- a/packages/gitbook/src/intl/translations/it.ts
+++ b/packages/gitbook/src/intl/translations/it.ts
@@ -152,7 +152,6 @@ export const it: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Ha chiamato ${1}',
     ai_chat_ask: 'Chiedi a ${1}',
     ai_chat_ask_about: 'Chiedi a ${1} riguardo a ${2}',
-    ai_chat_ask_about_this: 'Chiedi a ${1} riguardo a questo',
     this_page: 'questa pagina',
     ai_chat_paragraph_draft: 'Dimmi di più a riguardo',
     copy_for_llms: 'Copia per LLM',
diff --git a/packages/gitbook/src/intl/translations/ja.ts b/packages/gitbook/src/intl/translations/ja.ts
index 7f3533632..bb5183149 100644
--- a/packages/gitbook/src/intl/translations/ja.ts
+++ b/packages/gitbook/src/intl/translations/ja.ts
@@ -149,7 +149,6 @@ export const ja: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '${1} を呼び出しました',
     ai_chat_ask: '${1} に質問する',
     ai_chat_ask_about: '${1}に${2}について質問する',
-    ai_chat_ask_about_this: '${1}にこれについて質問する',
     this_page: 'このページ',
     ai_chat_paragraph_draft: 'これについてもっと教えて',
     copy_for_llms: 'LLM 用にコピー',
diff --git a/packages/gitbook/src/intl/translations/ko.ts b/packages/gitbook/src/intl/translations/ko.ts
index 00bea3c40..35aab6eb0 100644
--- a/packages/gitbook/src/intl/translations/ko.ts
+++ b/packages/gitbook/src/intl/translations/ko.ts
@@ -148,7 +148,6 @@ export const ko: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '${1} 호출함',
     ai_chat_ask: '${1}에게 질문',
     ai_chat_ask_about: '${1}에게 ${2}에 대해 질문',
-    ai_chat_ask_about_this: '${1}에게 이에 대해 질문',
     this_page: '이 페이지',
     ai_chat_paragraph_draft: '이것에 대해 더 알려줘',
     copy_for_llms: 'LLM용 복사',
diff --git a/packages/gitbook/src/intl/translations/lt.ts b/packages/gitbook/src/intl/translations/lt.ts
index d759f250f..965ffd19d 100644
--- a/packages/gitbook/src/intl/translations/lt.ts
+++ b/packages/gitbook/src/intl/translations/lt.ts
@@ -149,7 +149,6 @@ export const lt: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Iškviesta ${1}',
     ai_chat_ask: 'Klausti ${1}',
     ai_chat_ask_about: 'Klausti ${1} apie ${2}',
-    ai_chat_ask_about_this: 'Klausti ${1} apie tai',
     this_page: 'šį puslapį',
     ai_chat_paragraph_draft: 'Papasakok apie tai daugiau',
     ai_chat_ask_query: 'Klausti ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/lv.ts b/packages/gitbook/src/intl/translations/lv.ts
index 2bf4fcf6d..30b72ef5e 100644
--- a/packages/gitbook/src/intl/translations/lv.ts
+++ b/packages/gitbook/src/intl/translations/lv.ts
@@ -147,7 +147,6 @@ export const lv: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Izsauca ${1}',
     ai_chat_ask: 'Jautāt ${1}',
     ai_chat_ask_about: 'Jautāt ${1} par ${2}',
-    ai_chat_ask_about_this: 'Jautāt ${1} par to',
     this_page: 'šo lapu',
     ai_chat_paragraph_draft: 'Pastāsti man par to vairāk',
     ai_chat_ask_query: 'Jautāt ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/ms.ts b/packages/gitbook/src/intl/translations/ms.ts
index 6b930599d..bd5fca1d7 100644
--- a/packages/gitbook/src/intl/translations/ms.ts
+++ b/packages/gitbook/src/intl/translations/ms.ts
@@ -148,7 +148,6 @@ export const ms: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Memanggil ${1}',
     ai_chat_ask: 'Tanya ${1}',
     ai_chat_ask_about: 'Tanya ${1} tentang ${2}',
-    ai_chat_ask_about_this: 'Tanya ${1} tentang ini',
     this_page: 'halaman ini',
     ai_chat_paragraph_draft: 'Beritahu saya lebih lanjut tentang ini',
     ai_chat_ask_query: 'Tanya ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/nl.ts b/packages/gitbook/src/intl/translations/nl.ts
index 8d9d32f41..000105a33 100644
--- a/packages/gitbook/src/intl/translations/nl.ts
+++ b/packages/gitbook/src/intl/translations/nl.ts
@@ -151,7 +151,6 @@ export const nl: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '${1} aangeroepen',
     ai_chat_ask: 'Vraag het aan ${1}',
     ai_chat_ask_about: 'Stel ${1} een vraag over ${2}',
-    ai_chat_ask_about_this: 'Stel ${1} een vraag hierover',
     this_page: 'deze pagina',
     ai_chat_paragraph_draft: 'Vertel me hier meer over',
     copy_for_llms: 'Kopiëren voor LLMs',
diff --git a/packages/gitbook/src/intl/translations/no.ts b/packages/gitbook/src/intl/translations/no.ts
index d73d097f2..2761be77c 100644
--- a/packages/gitbook/src/intl/translations/no.ts
+++ b/packages/gitbook/src/intl/translations/no.ts
@@ -150,7 +150,6 @@ export const no: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Kalte ${1}',
     ai_chat_ask: 'Spør ${1}',
     ai_chat_ask_about: 'Spør ${1} om ${2}',
-    ai_chat_ask_about_this: 'Spør ${1} om dette',
     this_page: 'denne siden',
     ai_chat_paragraph_draft: 'Fortell meg mer om dette',
     copy_for_llms: 'Kopier for LLMs',
diff --git a/packages/gitbook/src/intl/translations/pl.ts b/packages/gitbook/src/intl/translations/pl.ts
index af3f3a3ab..0e9e262b3 100644
--- a/packages/gitbook/src/intl/translations/pl.ts
+++ b/packages/gitbook/src/intl/translations/pl.ts
@@ -149,7 +149,6 @@ export const pl: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Wywołano ${1}',
     ai_chat_ask: 'Zapytaj ${1}',
     ai_chat_ask_about: 'Zapytaj ${1} o ${2}',
-    ai_chat_ask_about_this: 'Zapytaj ${1} o to',
     this_page: 'tę stronę',
     ai_chat_paragraph_draft: 'Powiedz mi o tym więcej',
     ai_chat_ask_query: 'Zapytaj ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/pt-br.ts b/packages/gitbook/src/intl/translations/pt-br.ts
index e04cee319..43b3109ae 100644
--- a/packages/gitbook/src/intl/translations/pt-br.ts
+++ b/packages/gitbook/src/intl/translations/pt-br.ts
@@ -153,7 +153,6 @@ export const pt_br: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Chamou ${1}',
     ai_chat_ask: 'Perguntar a ${1}',
     ai_chat_ask_about: 'Perguntar a ${1} sobre ${2}',
-    ai_chat_ask_about_this: 'Perguntar a ${1} sobre isso',
     this_page: 'esta página',
     ai_chat_paragraph_draft: 'Conte-me mais sobre isso',
     copy_for_llms: 'Copiar para LLMs',
diff --git a/packages/gitbook/src/intl/translations/pt.ts b/packages/gitbook/src/intl/translations/pt.ts
index 0e0752984..7fea444a5 100644
--- a/packages/gitbook/src/intl/translations/pt.ts
+++ b/packages/gitbook/src/intl/translations/pt.ts
@@ -150,7 +150,6 @@ export const pt: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Chamou ${1}',
     ai_chat_ask: 'Perguntar a ${1}',
     ai_chat_ask_about: 'Perguntar a ${1} sobre ${2}',
-    ai_chat_ask_about_this: 'Perguntar a ${1} sobre isto',
     this_page: 'esta página',
     ai_chat_paragraph_draft: 'Conta-me mais sobre isto',
     ai_chat_ask_query: 'Perguntar a ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/ro.ts b/packages/gitbook/src/intl/translations/ro.ts
index d784d5977..d794ba2e2 100644
--- a/packages/gitbook/src/intl/translations/ro.ts
+++ b/packages/gitbook/src/intl/translations/ro.ts
@@ -152,7 +152,6 @@ export const ro: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'A apelat ${1}',
     ai_chat_ask: 'Întreabă ${1}',
     ai_chat_ask_about: 'Întreabă ${1} despre ${2}',
-    ai_chat_ask_about_this: 'Întreabă ${1} despre asta',
     this_page: 'această pagină',
     ai_chat_paragraph_draft: 'Spune-mi mai multe despre asta',
     ai_chat_ask_query: 'Întreabă ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/ru.ts b/packages/gitbook/src/intl/translations/ru.ts
index dad75aa4c..8a75f6b4c 100644
--- a/packages/gitbook/src/intl/translations/ru.ts
+++ b/packages/gitbook/src/intl/translations/ru.ts
@@ -152,7 +152,6 @@ export const ru: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Вызван ${1}',
     ai_chat_ask: 'Спросить у ${1}',
     ai_chat_ask_about: 'Спросить у ${1} о ${2}',
-    ai_chat_ask_about_this: 'Спросить у ${1} об этом',
     this_page: 'этой странице',
     ai_chat_paragraph_draft: 'Расскажи мне об этом подробнее',
     copy_for_llms: 'Скопировать для LLM',
diff --git a/packages/gitbook/src/intl/translations/sk.ts b/packages/gitbook/src/intl/translations/sk.ts
index b48507f6c..2d7a9b526 100644
--- a/packages/gitbook/src/intl/translations/sk.ts
+++ b/packages/gitbook/src/intl/translations/sk.ts
@@ -151,7 +151,6 @@ export const sk: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Zavolal ${1}',
     ai_chat_ask: 'Opýtať sa ${1}',
     ai_chat_ask_about: 'Opýtať sa ${1} na ${2}',
-    ai_chat_ask_about_this: 'Opýtať sa ${1} na to',
     this_page: 'túto stránku',
     ai_chat_paragraph_draft: 'Povedz mi o tom viac',
     ai_chat_ask_query: 'Opýtať sa ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/sl.ts b/packages/gitbook/src/intl/translations/sl.ts
index 5517de6d8..8c3816765 100644
--- a/packages/gitbook/src/intl/translations/sl.ts
+++ b/packages/gitbook/src/intl/translations/sl.ts
@@ -149,7 +149,6 @@ export const sl: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Poklicano ${1}',
     ai_chat_ask: 'Vprašaj ${1}',
     ai_chat_ask_about: 'Vprašaj ${1} o ${2}',
-    ai_chat_ask_about_this: 'Vprašaj ${1} o tem',
     this_page: 'to stran',
     ai_chat_paragraph_draft: 'Povej mi več o tem',
     ai_chat_ask_query: 'Vprašaj ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/sv.ts b/packages/gitbook/src/intl/translations/sv.ts
index 33096bec8..f9202eb61 100644
--- a/packages/gitbook/src/intl/translations/sv.ts
+++ b/packages/gitbook/src/intl/translations/sv.ts
@@ -149,7 +149,6 @@ export const sv: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Anropade ${1}',
     ai_chat_ask: 'Fråga ${1}',
     ai_chat_ask_about: 'Fråga ${1} om ${2}',
-    ai_chat_ask_about_this: 'Fråga ${1} om det här',
     this_page: 'den här sidan',
     ai_chat_paragraph_draft: 'Berätta mer om det här',
     ai_chat_ask_query: 'Fråga ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/th.ts b/packages/gitbook/src/intl/translations/th.ts
index b225d5dee..e22084743 100644
--- a/packages/gitbook/src/intl/translations/th.ts
+++ b/packages/gitbook/src/intl/translations/th.ts
@@ -145,7 +145,6 @@ export const th: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'เรียกใช้ ${1}',
     ai_chat_ask: 'ถาม ${1}',
     ai_chat_ask_about: 'ถาม ${1} เกี่ยวกับ ${2}',
-    ai_chat_ask_about_this: 'ถาม ${1} เกี่ยวกับเรื่องนี้',
     this_page: 'หน้านี้',
     ai_chat_paragraph_draft: 'บอกฉันเพิ่มเติมเกี่ยวกับเรื่องนี้',
     ai_chat_ask_query: 'ถาม ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/tr.ts b/packages/gitbook/src/intl/translations/tr.ts
index 49c6d7c82..186343ef0 100644
--- a/packages/gitbook/src/intl/translations/tr.ts
+++ b/packages/gitbook/src/intl/translations/tr.ts
@@ -147,7 +147,6 @@ export const tr: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '${1} çağrıldı',
     ai_chat_ask: '${1} sor',
     ai_chat_ask_about: '${1} için ${2} hakkında sor',
-    ai_chat_ask_about_this: '${1} için bununla ilgili sor',
     this_page: 'bu sayfa',
     ai_chat_paragraph_draft: 'Bana bundan daha fazla bahset',
     ai_chat_ask_query: '${1} için "${2}" sor',
diff --git a/packages/gitbook/src/intl/translations/uk.ts b/packages/gitbook/src/intl/translations/uk.ts
index ded36466c..1bbac50d3 100644
--- a/packages/gitbook/src/intl/translations/uk.ts
+++ b/packages/gitbook/src/intl/translations/uk.ts
@@ -147,7 +147,6 @@ export const uk: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Викликано ${1}',
     ai_chat_ask: 'Запитати ${1}',
     ai_chat_ask_about: 'Запитати ${1} про ${2}',
-    ai_chat_ask_about_this: 'Запитати ${1} про це',
     this_page: 'цю сторінку',
     ai_chat_paragraph_draft: 'Розкажи мені про це більше',
     ai_chat_ask_query: 'Запитати ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/vi.ts b/packages/gitbook/src/intl/translations/vi.ts
index bf94065e1..c652980c6 100644
--- a/packages/gitbook/src/intl/translations/vi.ts
+++ b/packages/gitbook/src/intl/translations/vi.ts
@@ -147,7 +147,6 @@ export const vi: TranslationLanguage = {
     ai_chat_tools_mcp_tool: 'Đã gọi ${1}',
     ai_chat_ask: 'Hỏi ${1}',
     ai_chat_ask_about: 'Hỏi ${1} về ${2}',
-    ai_chat_ask_about_this: 'Hỏi ${1} về điều này',
     this_page: 'trang này',
     ai_chat_paragraph_draft: 'Cho tôi biết thêm về điều này',
     ai_chat_ask_query: 'Hỏi ${1} "${2}"',
diff --git a/packages/gitbook/src/intl/translations/yue.ts b/packages/gitbook/src/intl/translations/yue.ts
index bdfa51a2c..b74b5e457 100644
--- a/packages/gitbook/src/intl/translations/yue.ts
+++ b/packages/gitbook/src/intl/translations/yue.ts
@@ -144,7 +144,6 @@ export const yue: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '已呼叫 ${1}',
     ai_chat_ask: '問 ${1}',
     ai_chat_ask_about: '問 ${1} 關於${2}',
-    ai_chat_ask_about_this: '問 ${1} 關於呢樣嘢',
     this_page: '此頁面',
     ai_chat_paragraph_draft: '同我講多啲呢方面嘅嘢',
     ai_chat_ask_query: '問 ${1}「${2}」',
diff --git a/packages/gitbook/src/intl/translations/zh-tw.ts b/packages/gitbook/src/intl/translations/zh-tw.ts
index 033f8afcf..6b0f97a39 100644
--- a/packages/gitbook/src/intl/translations/zh-tw.ts
+++ b/packages/gitbook/src/intl/translations/zh-tw.ts
@@ -144,7 +144,6 @@ export const zh_tw: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '已呼叫 ${1}',
     ai_chat_ask: '詢問 ${1}',
     ai_chat_ask_about: '詢問 ${1} 關於${2}',
-    ai_chat_ask_about_this: '詢問 ${1} 關於這個',
     this_page: '此頁面',
     ai_chat_paragraph_draft: '告訴我更多相關資訊',
     ai_chat_ask_query: '詢問 ${1}「${2}」',
diff --git a/packages/gitbook/src/intl/translations/zh.ts b/packages/gitbook/src/intl/translations/zh.ts
index 64467d78c..9a69ef104 100644
--- a/packages/gitbook/src/intl/translations/zh.ts
+++ b/packages/gitbook/src/intl/translations/zh.ts
@@ -145,7 +145,6 @@ export const zh: TranslationLanguage = {
     ai_chat_tools_mcp_tool: '调用了 ${1}',
     ai_chat_ask: '向 ${1} 提问',
     ai_chat_ask_about: '向 ${1} 询问${2}',
-    ai_chat_ask_about_this: '向 ${1} 询问这个',
     this_page: '此页面',
     ai_chat_paragraph_draft: '告诉我更多相关信息',
     copy_for_llms: '复制供 LLMs 使用',

From e24632c80b69cb80fe1756712a43a66af6cb5e23 Mon Sep 17 00:00:00 2001
From: conico974 <nicodorseuil@yahoo.fr>
Date: Tue, 7 Jul 2026 16:21:32 +0200
Subject: [PATCH 16/46] Integrate GitBook image resizing service and remove
 cdn-cgi mode (#4285)

---
 .../composite/deploy-cloudflare/action.yaml   |  3 +-
 .github/composite/deploy-vercel/action.yaml   |  3 +-
 packages/gitbook/next.config.mjs              |  1 +
 packages/gitbook/src/lib/env/globals.ts       |  5 +-
 .../gitbook/src/lib/images/resizer/cdn-cgi.ts | 49 --------------
 .../src/lib/images/resizer/gitbook-service.ts | 65 +++++++++++++++++++
 .../src/lib/images/resizer/resizeImage.ts     |  7 +-
 7 files changed, 77 insertions(+), 56 deletions(-)
 delete mode 100644 packages/gitbook/src/lib/images/resizer/cdn-cgi.ts
 create mode 100644 packages/gitbook/src/lib/images/resizer/gitbook-service.ts

diff --git a/.github/composite/deploy-cloudflare/action.yaml b/.github/composite/deploy-cloudflare/action.yaml
index 136ad52b1..f8b7181a5 100644
--- a/.github/composite/deploy-cloudflare/action.yaml
+++ b/.github/composite/deploy-cloudflare/action.yaml
@@ -57,7 +57,8 @@ runs:
             GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
             GITBOOK_INTEGRATIONS_CONTENT_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_CONTENT_HOST
             GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
-            GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL
+            GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL_2
+            GITBOOK_IMAGE_RESIZE_SALT: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SALT
             GITBOOK_IMAGE_RESIZE_MODE: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_MODE
             GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
             GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
diff --git a/.github/composite/deploy-vercel/action.yaml b/.github/composite/deploy-vercel/action.yaml
index 8c62577c7..b796c5a59 100644
--- a/.github/composite/deploy-vercel/action.yaml
+++ b/.github/composite/deploy-vercel/action.yaml
@@ -59,7 +59,8 @@ runs:
             GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
             GITBOOK_INTEGRATIONS_CONTENT_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_CONTENT_HOST
             GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
-            GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL
+            GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL_2
+            GITBOOK_IMAGE_RESIZE_SALT: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SALT
             GITBOOK_IMAGE_RESIZE_MODE: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_MODE
             GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
             GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
diff --git a/packages/gitbook/next.config.mjs b/packages/gitbook/next.config.mjs
index 309e7d0e5..992281a11 100644
--- a/packages/gitbook/next.config.mjs
+++ b/packages/gitbook/next.config.mjs
@@ -50,6 +50,7 @@ const nextConfig = {
         GITBOOK_INTEGRATIONS_HOST: process.env.GITBOOK_INTEGRATIONS_HOST,
         GITBOOK_INTEGRATIONS_CONTENT_HOST: process.env.GITBOOK_INTEGRATIONS_CONTENT_HOST,
         GITBOOK_IMAGE_RESIZE_URL: process.env.GITBOOK_IMAGE_RESIZE_URL,
+        GITBOOK_IMAGE_RESIZE_SALT: process.env.GITBOOK_IMAGE_RESIZE_SALT,
         GITBOOK_ICONS_URL: process.env.GITBOOK_ICONS_URL,
         GITBOOK_ICONS_TOKEN: process.env.GITBOOK_ICONS_TOKEN,
         GITBOOK_URL: process.env.GITBOOK_URL,
diff --git a/packages/gitbook/src/lib/env/globals.ts b/packages/gitbook/src/lib/env/globals.ts
index 85b069cd9..92970e753 100644
--- a/packages/gitbook/src/lib/env/globals.ts
+++ b/packages/gitbook/src/lib/env/globals.ts
@@ -105,14 +105,15 @@ export const GITBOOK_FONTS_URL = process.env.GITBOOK_FONTS_URL || 'https://fonts
 export const GITBOOK_IMAGE_RESIZE_URL = process.env.GITBOOK_IMAGE_RESIZE_URL ?? null;
 export const GITBOOK_IMAGE_RESIZE_SIGNING_KEY =
     process.env.GITBOOK_IMAGE_RESIZE_SIGNING_KEY ?? null;
+export const GITBOOK_IMAGE_RESIZE_SALT = process.env.GITBOOK_IMAGE_RESIZE_SALT ?? null;
 
 /**
  * Mode used for resizing images.
  */
 export const GITBOOK_IMAGE_RESIZE_MODE = enforceEnum(
     'GITBOOK_IMAGE_RESIZE_MODE',
-    process.env.GITBOOK_IMAGE_RESIZE_MODE || 'cdn-cgi',
-    ['cdn-cgi', 'cf-fetch']
+    process.env.GITBOOK_IMAGE_RESIZE_MODE || 'cf-fetch',
+    ['cf-fetch', 'gitbook-service', 'cdn-cgi']
 );
 
 /**
diff --git a/packages/gitbook/src/lib/images/resizer/cdn-cgi.ts b/packages/gitbook/src/lib/images/resizer/cdn-cgi.ts
deleted file mode 100644
index 1151c59b0..000000000
--- a/packages/gitbook/src/lib/images/resizer/cdn-cgi.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-import { GITBOOK_IMAGE_RESIZE_URL } from '@/lib/env';
-import { getLogger } from '@/lib/logger';
-import type { CloudflareImageOptions } from './types';
-import { copyImageResponse } from './utils';
-
-/**
- * Resize an image by doing a request to a /cdn/cgi/ endpoint.
- * https://developers.cloudflare.com/images/transform-images/transform-via-url/
- */
-export async function resizeImageWithCDNCgi(
-    input: string,
-    options: CloudflareImageOptions & {
-        signal?: AbortSignal;
-    }
-): Promise<Response> {
-    const { signal, ...resizeOptions } = options;
-
-    // Since Cloudflare Images options on fetch are not supported on Cloudflare Pages,
-    // we need to use the Cloudflare Image Resize API directly.
-    if (!GITBOOK_IMAGE_RESIZE_URL) {
-        throw new Error('GITBOOK_IMAGE_RESIZE_URL is not set for cdn-cgi image resize mode');
-    }
-
-    const resizeURL = `${GITBOOK_IMAGE_RESIZE_URL}${stringifyOptions(
-        resizeOptions
-    )}/${encodeURIComponent(input)}`;
-
-    const logger = getLogger().subLogger('imageResizing');
-    logger.log(`resize image using cdn-cgi: ${resizeURL}`);
-
-    return copyImageResponse(
-        await fetch(resizeURL, {
-            headers: {
-                // Pass the `Accept` header, as Cloudflare uses this to validate the format.
-                Accept:
-                    resizeOptions.format === 'json'
-                        ? 'application/json'
-                        : `image/${resizeOptions.format || 'jpeg'}`,
-            },
-            signal,
-        })
-    );
-}
-
-function stringifyOptions(options: CloudflareImageOptions): string {
-    return Object.entries({ ...options }).reduce((rest, [key, value]) => {
-        return `${rest}${rest ? ',' : ''}${key}=${value}`;
-    }, '');
-}
diff --git a/packages/gitbook/src/lib/images/resizer/gitbook-service.ts b/packages/gitbook/src/lib/images/resizer/gitbook-service.ts
new file mode 100644
index 000000000..f1e890afd
--- /dev/null
+++ b/packages/gitbook/src/lib/images/resizer/gitbook-service.ts
@@ -0,0 +1,65 @@
+import { GITBOOK_IMAGE_RESIZE_SALT, GITBOOK_IMAGE_RESIZE_URL } from '@/lib/env';
+import { getLogger } from '@/lib/logger';
+import type { CloudflareImageOptions } from './types';
+import { copyImageResponse } from './utils';
+
+function sdbmHash(str: string): number {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        hash = str.charCodeAt(i) + (hash << 6) + (hash << 16) - hash;
+        hash |= 0; // ensure 32-bit int
+    }
+    return hash;
+}
+
+/**
+ * Resize an image using the GitBook image service.
+ * https://images.gitbook.com/__img/options/encoded-url
+ */
+export async function resizeImageWithGitbookServices(
+    input: string,
+    options: CloudflareImageOptions & {
+        signal?: AbortSignal;
+    }
+): Promise<Response> {
+    const { signal, ...resizeOptions } = options;
+
+    if (!GITBOOK_IMAGE_RESIZE_SALT) {
+        throw new Error(
+            'GITBOOK_IMAGE_RESIZE_SALT is not set for gitbook-service image resize mode'
+        );
+    }
+
+    if (!GITBOOK_IMAGE_RESIZE_URL) {
+        throw new Error(
+            'GITBOOK_IMAGE_RESIZE_URL is not set for gitbook-service image resize mode'
+        );
+    }
+
+    const signature = sdbmHash(`${input}:${GITBOOK_IMAGE_RESIZE_SALT}`).toString();
+    const resizeURL = `${GITBOOK_IMAGE_RESIZE_URL}${stringifyOptions({
+        ...resizeOptions,
+        signature,
+    })}/${encodeURIComponent(input)}`;
+
+    const logger = getLogger().subLogger('imageResizing');
+    logger.log(`resize image using gitbook-service: ${resizeURL}, format: ${resizeOptions.format}`);
+
+    return copyImageResponse(
+        await fetch(resizeURL, {
+            headers: {
+                Accept:
+                    resizeOptions.format === 'json'
+                        ? 'application/json'
+                        : `image/${resizeOptions.format || 'jpeg'}`,
+            },
+            signal,
+        })
+    );
+}
+
+function stringifyOptions(options: CloudflareImageOptions & { signature: string }): string {
+    return Object.entries({ ...options }).reduce((rest, [key, value]) => {
+        return `${rest}${rest ? ',' : ''}${key}=${value}`;
+    }, '');
+}
diff --git a/packages/gitbook/src/lib/images/resizer/resizeImage.ts b/packages/gitbook/src/lib/images/resizer/resizeImage.ts
index 1e65ffc1e..f2dccbd44 100644
--- a/packages/gitbook/src/lib/images/resizer/resizeImage.ts
+++ b/packages/gitbook/src/lib/images/resizer/resizeImage.ts
@@ -3,8 +3,8 @@ import { getLogger } from '@/lib/logger';
 import assertNever from 'assert-never';
 import { GITBOOK_IMAGE_RESIZE_MODE } from '../../env';
 import { SizableImageAction, checkIsSizableImageURL } from '../checkIsSizableImageURL';
-import { resizeImageWithCDNCgi } from './cdn-cgi';
 import { resizeImageWithCFFetch } from './cf-fetch';
+import { resizeImageWithGitbookServices } from './gitbook-service';
 import type { CloudflareImageJsonFormat, CloudflareImageOptions } from './types';
 
 /**
@@ -71,10 +71,11 @@ export async function resizeImage(
     }
 
     switch (GITBOOK_IMAGE_RESIZE_MODE) {
-        case 'cdn-cgi':
-            return resizeImageWithCDNCgi(input, options);
         case 'cf-fetch':
             return resizeImageWithCFFetch(input, options);
+        case 'gitbook-service':
+        case 'cdn-cgi':
+            return resizeImageWithGitbookServices(input, options);
         default:
             assertNever(GITBOOK_IMAGE_RESIZE_MODE);
     }

From 57f3077006fc2a22205a5bf78a0cda70996de142 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Tue, 7 Jul 2026 19:10:55 +0200
Subject: [PATCH 17/46] Keep the page outline and Ask button in view while
 scrolling API reference pages (#4371)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/sticky-api-page-actions.md         |  5 ++
 .../components/DocumentView/OpenAPI/style.css | 11 ++-
 .../src/components/PageBody/PageBody.tsx      | 13 ++-
 .../src/components/PageBody/PageHeader.tsx    | 85 +++++++++++++------
 packages/gitbook/src/lib/document.tsx         | 15 ++++
 5 files changed, 100 insertions(+), 29 deletions(-)
 create mode 100644 .changeset/sticky-api-page-actions.md

diff --git a/.changeset/sticky-api-page-actions.md b/.changeset/sticky-api-page-actions.md
new file mode 100644
index 000000000..b8a2efe1c
--- /dev/null
+++ b/.changeset/sticky-api-page-actions.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Keep the "On this page" and "Ask" buttons pinned below the header while scrolling on desktop API reference pages, so the page outline stays reachable throughout long operations.
diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
index 40aef9390..f7caf8370 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
@@ -178,10 +178,13 @@ button.openapi-mcp {
 }
 
 .openapi-column-preview {
-    /* Only on the 2-column layout is the preview a sticky pane capped to the viewport so both panels fit
-       (max-height accounts for the top offset + a 1.5rem bottom margin). On mobile (single column) it flows
-       normally, each block bounded by max-h-96, so the response isn't crammed into the viewport. */
-    @apply flex flex-col flex-1 scroll-mt-4 lg:sticky lg:self-start lg:max-h-[calc(100vh-var(--toc-top-offset)-3rem)] lg:top-[calc(var(--toc-top-offset)+1.5rem)];
+    /* Only on the 2-column layout is the preview a sticky pane capped to the viewport so both panels fit.
+       The top offset clears the site header (--toc-top-offset) plus the sticky page-actions bar pinned just
+       below it on desktop API pages (~3rem: its 1rem gap under the header + the button row), landing 4rem
+       down with a small gap beneath the bar. The max-height subtracts that same 4rem top offset plus a
+       1.5rem bottom margin. On mobile (single column) it flows normally, each block bounded by max-h-96, so
+       the response isn't crammed into the viewport. */
+    @apply flex flex-col flex-1 scroll-mt-4 lg:sticky lg:self-start lg:max-h-[calc(100vh-var(--toc-top-offset)-5.5rem)] lg:top-[calc(var(--toc-top-offset)+4rem)];
 }
 
 .openapi-column-preview-body {
diff --git a/packages/gitbook/src/components/PageBody/PageBody.tsx b/packages/gitbook/src/components/PageBody/PageBody.tsx
index adb97b94d..84574ad53 100644
--- a/packages/gitbook/src/components/PageBody/PageBody.tsx
+++ b/packages/gitbook/src/components/PageBody/PageBody.tsx
@@ -3,7 +3,13 @@ import type { JSONDocument, RevisionPageDocument, SiteInsightsDisplayContext } f
 
 import { getSpaceLanguage } from '@/intl/server';
 import { t } from '@/intl/translate';
-import { hasFullWidthBlock, hasMoreThan, hasTopLevelBlock, isNodeEmpty } from '@/lib/document';
+import {
+    hasAPIBlock,
+    hasFullWidthBlock,
+    hasMoreThan,
+    hasTopLevelBlock,
+    isNodeEmpty,
+} from '@/lib/document';
 import { getLLMsTxtURL, getPageMarkdownURL } from '@/lib/llms-directive';
 import type { AncestorRevisionPage } from '@/lib/pages';
 import { tcls } from '@/lib/tailwind';
@@ -59,6 +65,10 @@ export async function PageBody(props: {
     // Determine if content should use wide layout (2-column or 1-column instead of 3-column)
     // This happens when: (1) document has full-width blocks, OR (2) page layout is explicitly set to 'wide'
     const wideContent = document ? hasFullWidthBlock(document) : false;
+    // Whether the page has OpenAPI/Swagger blocks — used to scope the sticky, extracted page-actions
+    // to API-reference pages only (matching the `page-api-block` styling), so other pages keep the
+    // header structure untouched.
+    const hasAPIBlocks = document ? hasAPIBlock(document) : false;
     const wideLayout = wideContent || page.layout.width === 'wide';
     const language = await getSpaceLanguage(context);
     const updatedAt = page.updatedAt ?? page.createdAt;
@@ -99,6 +109,7 @@ export async function PageBody(props: {
                     page={page}
                     ancestors={ancestors}
                     withRSSFeed={contentHasUpdates}
+                    hasAPIBlocks={hasAPIBlocks}
                 />
                 {document && !isNodeEmpty(document) ? (
                     <OptionalSuspense
diff --git a/packages/gitbook/src/components/PageBody/PageHeader.tsx b/packages/gitbook/src/components/PageBody/PageHeader.tsx
index bef42c772..a449be4b3 100644
--- a/packages/gitbook/src/components/PageBody/PageHeader.tsx
+++ b/packages/gitbook/src/components/PageBody/PageHeader.tsx
@@ -32,8 +32,14 @@ export async function PageHeader(props: {
     page: RevisionPageDocument;
     ancestors: AncestorRevisionPage[];
     withRSSFeed: boolean;
+    /**
+     * Whether the page has OpenAPI/Swagger blocks. On desktop, such pages get the page-actions
+     * pinned below the site header (see the render below); everywhere else the header is left
+     * exactly as-is.
+     */
+    hasAPIBlocks: boolean;
 }) {
-    const { context, page, ancestors, withRSSFeed } = props;
+    const { context, page, ancestors, withRSSFeed, hasAPIBlocks } = props;
     const { revision, linker } = context;
 
     const hasAncestors = ancestors.length > 0;
@@ -137,30 +143,43 @@ export async function PageHeader(props: {
         return null;
     }
 
-    return (
-        <header className={tcls(CONTENT_STYLE, 'mb-6 space-y-3 after:clear-both after:block')}>
-            <div
-                className={tcls(
-                    'float-right ml-4 flex gap-2',
-                    showBreadcrumbs ? '-mb-1 -mt-1.5' : '-mt-3 xs:mt-2'
-                )}
-            >
-                {hasPageActions ? (
-                    <PageActionsDropdown
-                        siteTitle={context.site.title}
-                        urls={getPageActionsURLs({ context, page, withRSSFeed })}
-                        actions={context.customization.pageActions}
-                        page={{
-                            id: page.id,
-                            title: page.title,
-                            path: page.path,
-                            href: linker.toPathForPage({ pages: revision.pages, page }),
-                        }}
-                    />
-                ) : null}
-                <PageAsideToggleButton />
-            </div>
+    const pageActions = (
+        <div
+            className={tcls(
+                'float-right ml-4 flex gap-2',
+                showBreadcrumbs ? '-mb-1 -mt-1.5' : '-mt-3 xs:mt-2',
+                // On desktop API pages (where this <div> is rendered as a sibling of <header>, see
+                // below) keep the actions pinned below the site header while scrolling long
+                // operations. The offset tracks the header height (banner, cover…) via the same
+                // --toc-top-offset the outline and code samples use. Hidden while the outline drawer
+                // is open (drawer widths only) so it doesn't overlap the sheet.
+                hasAPIBlocks && [
+                    'page-api-block:lg:sticky',
+                    'page-api-block:lg:top-[calc(var(--toc-top-offset,4rem)+1rem)]',
+                    'page-api-block:lg:z-20',
+                    'lg:max-[96rem]:[body.outline-open:has(.openapi-block)_&]:hidden',
+                ]
+            )}
+        >
+            {hasPageActions ? (
+                <PageActionsDropdown
+                    siteTitle={context.site.title}
+                    urls={getPageActionsURLs({ context, page, withRSSFeed })}
+                    actions={context.customization.pageActions}
+                    page={{
+                        id: page.id,
+                        title: page.title,
+                        path: page.path,
+                        href: linker.toPathForPage({ pages: revision.pages, page }),
+                    }}
+                />
+            ) : null}
+            <PageAsideToggleButton />
+        </div>
+    );
 
+    const headerContent = (
+        <>
             {showBreadcrumbs && (
                 // Hide the breadcrumbs on wide pages that have no table of contents: there the
                 // content spans the full width with no navigation column, so the crumbs sit stranded.
@@ -231,6 +250,24 @@ export async function PageHeader(props: {
                     {page.description}
                 </p>
             ) : null}
+        </>
+    );
+
+    const headerClassName = tcls(CONTENT_STYLE, 'mb-6 space-y-3 after:clear-both after:block');
+
+    // On API pages the actions are pulled out of <header> so their sticky containing block is the
+    // full-height <main> rather than the short header (a sticky element can't outlive its containing
+    // block). Everywhere else they stay inside <header> exactly as before, so those pages render
+    // byte-for-byte identically.
+    return hasAPIBlocks ? (
+        <>
+            {pageActions}
+            <header className={headerClassName}>{headerContent}</header>
+        </>
+    ) : (
+        <header className={headerClassName}>
+            {pageActions}
+            {headerContent}
         </header>
     );
 }
diff --git a/packages/gitbook/src/lib/document.tsx b/packages/gitbook/src/lib/document.tsx
index 13053dd01..aad4e57e3 100644
--- a/packages/gitbook/src/lib/document.tsx
+++ b/packages/gitbook/src/lib/document.tsx
@@ -36,6 +36,21 @@ export function hasFullWidthBlock(document: JSONDocument): boolean {
     });
 }
 
+/**
+ * Check if the document contains an OpenAPI/Swagger block at the top level.
+ * Mirrors the `page-api-block` CSS variant (`body:has(.openapi-block)`) so server-rendered layout
+ * decisions can be scoped to API-reference pages the same way the styling is.
+ */
+export function hasAPIBlock(document: JSONDocument): boolean {
+    return hasTopLevelBlock(
+        document,
+        (block) =>
+            block.type === 'swagger' ||
+            block.type === 'openapi-operation' ||
+            block.type === 'openapi-webhook'
+    );
+}
+
 /**
  * Check if a top level block matches a predicate.
  */

From e14609cb3e3d78a060481b9064b57ad1abf49b93 Mon Sep 17 00:00:00 2001
From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com>
Date: Tue, 7 Jul 2026 20:10:02 +0200
Subject: [PATCH 18/46] fix(theme): resolve system theme before first paint to
 avoid dark/light flash (RND-11643) (#4373)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .changeset/rnd-11643-fix-system-theme-flash.md |  5 +++++
 .../src/components/SiteLayout/SiteLayout.tsx   |  6 +++++-
 packages/gitbook/src/lib/embeddable.test.ts    | 18 ++++++++++++++++++
 packages/gitbook/src/lib/embeddable.ts         |  8 +++++---
 4 files changed, 33 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/rnd-11643-fix-system-theme-flash.md

diff --git a/.changeset/rnd-11643-fix-system-theme-flash.md b/.changeset/rnd-11643-fix-system-theme-flash.md
new file mode 100644
index 000000000..621e8270d
--- /dev/null
+++ b/.changeset/rnd-11643-fix-system-theme-flash.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix a light/dark flash on published sites configured to respect the system default (no theme toggle). Such sites forced the `system` theme, but `next-themes`' pre-paint script applies a forced value verbatim without resolving `prefers-color-scheme`, so the page painted light and only switched to dark after hydration. We now leave the theme unforced when the default is `system` (only concrete light/dark themes are forced), letting `next-themes`' existing pre-paint script resolve the system preference before first paint.
diff --git a/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx b/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
index 42d837f49..23b6c6aa0 100644
--- a/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
+++ b/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
@@ -56,7 +56,11 @@ export async function SiteLayout(props: {
             contextId={context.contextId}
             forcedTheme={
                 forcedTheme ??
-                (customization.themes.toggeable ? undefined : customization.themes.default)
+                // Only force concrete light/dark; System stays unforced so next-themes resolves prefers-color-scheme pre-paint (avoids the flash). A theme saved while the toggle was previously on still wins — see the PR's "Known limitation". RND-11643
+                (customization.themes.toggeable ||
+                customization.themes.default === CustomizationDefaultThemeMode.System
+                    ? undefined
+                    : customization.themes.default)
             }
             defaultTheme={customization.themes.default}
             externalLinksTarget={customization.externalLinks.target}
diff --git a/packages/gitbook/src/lib/embeddable.test.ts b/packages/gitbook/src/lib/embeddable.test.ts
index 468b84202..c63b59545 100644
--- a/packages/gitbook/src/lib/embeddable.test.ts
+++ b/packages/gitbook/src/lib/embeddable.test.ts
@@ -161,4 +161,22 @@ describe('resolveEmbeddableTheme', () => {
             forcedTheme: CustomizationDefaultThemeMode.Light,
         });
     });
+
+    it('does not force `system` for single-theme sites set to the system default', () => {
+        // Forcing `system` makes next-themes' pre-paint script skip
+        // prefers-color-scheme resolution, causing a light→dark flash (RND-11643).
+        // It must stay unforced so next-themes resolves it before first paint.
+        expect(
+            resolveEmbeddableTheme(
+                createCustomization({
+                    toggeable: false,
+                    default: CustomizationDefaultThemeMode.System,
+                })
+            )
+        ).toEqual({
+            htmlTheme: CustomizationDefaultThemeMode.System,
+            defaultTheme: CustomizationDefaultThemeMode.System,
+            forcedTheme: undefined,
+        });
+    });
 });
diff --git a/packages/gitbook/src/lib/embeddable.ts b/packages/gitbook/src/lib/embeddable.ts
index 760903664..4687d51fe 100644
--- a/packages/gitbook/src/lib/embeddable.ts
+++ b/packages/gitbook/src/lib/embeddable.ts
@@ -47,10 +47,12 @@ export function resolveEmbeddableTheme(
     forcedTheme?: CustomizationDefaultThemeMode | null
 ) {
     if (!customization.themes.toggeable) {
+        const mode = customization.themes.default;
         return {
-            htmlTheme: customization.themes.default,
-            defaultTheme: customization.themes.default,
-            forcedTheme: customization.themes.default,
+            htmlTheme: mode,
+            defaultTheme: mode,
+            // Only force concrete light/dark; System stays unforced so next-themes resolves prefers-color-scheme pre-paint (avoids the flash). A theme saved while the toggle was previously on still wins — see the PR's "Known limitation". RND-11643
+            forcedTheme: mode === CustomizationDefaultThemeMode.System ? undefined : mode,
         };
     }
 

From 597fe34d3bf818ae9ac3d1dccd56bc6ccdea7db0 Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Wed, 8 Jul 2026 09:08:21 +0200
Subject: [PATCH 19/46] Sync responses selector with the Responses collapsibles
 (#4376)

---
 .../rnd-11616-responses-selector-sync.md      |  5 +++
 .../src/OpenAPIDisclosureGroup.tsx            | 15 ++++---
 .../src/OpenAPIResponseExample.tsx            |  8 +---
 .../src/OpenAPIResponseExampleContent.tsx     | 37 ++++++-----------
 .../react-openapi/src/OpenAPIResponses.tsx    | 41 ++++++++++++++-----
 5 files changed, 58 insertions(+), 48 deletions(-)
 create mode 100644 .changeset/rnd-11616-responses-selector-sync.md

diff --git a/.changeset/rnd-11616-responses-selector-sync.md b/.changeset/rnd-11616-responses-selector-sync.md
new file mode 100644
index 000000000..ab563228f
--- /dev/null
+++ b/.changeset/rnd-11616-responses-selector-sync.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Sync the API reference responses selector with the "Responses" collapsibles, and keep the selected response in sync across every operation on the page (like the code sample language selector). Selecting a status code now expands the matching response section and applies to all operations at once.
diff --git a/packages/react-openapi/src/OpenAPIDisclosureGroup.tsx b/packages/react-openapi/src/OpenAPIDisclosureGroup.tsx
index 71413da3e..c62783fb9 100644
--- a/packages/react-openapi/src/OpenAPIDisclosureGroup.tsx
+++ b/packages/react-openapi/src/OpenAPIDisclosureGroup.tsx
@@ -59,10 +59,11 @@ export function OpenAPIDisclosureGroup(props: DisclosureGroupProps & Props) {
         onExpandedChange,
     } = props;
 
-    const initialKeys =
-        expandedKeys || defaultExpandedKeys
-            ? new Set(expandedKeys || defaultExpandedKeys)
-            : undefined;
+    // When `expandedKeys` is provided, the group is controlled by the parent. Otherwise it owns
+    // its expanded state in a store keyed by `stateKey`.
+    const isControlled = expandedKeys !== undefined;
+
+    const initialKeys = defaultExpandedKeys ? new Set(defaultExpandedKeys) : undefined;
     const { expandedKeys: storeExpandedKeys, setExpandedKeys } = useDisclosureGroupStore(
         stateKey,
         initialKeys
@@ -70,9 +71,11 @@ export function OpenAPIDisclosureGroup(props: DisclosureGroupProps & Props) {
 
     const state = useDisclosureGroupState({
         ...props,
-        expandedKeys: storeExpandedKeys,
+        expandedKeys: isControlled ? expandedKeys : storeExpandedKeys,
         onExpandedChange: (keys) => {
-            setExpandedKeys(keys);
+            if (!isControlled) {
+                setExpandedKeys(keys);
+            }
             onExpandedChange?.(keys);
         },
     });
diff --git a/packages/react-openapi/src/OpenAPIResponseExample.tsx b/packages/react-openapi/src/OpenAPIResponseExample.tsx
index 945ace4f1..794817d06 100644
--- a/packages/react-openapi/src/OpenAPIResponseExample.tsx
+++ b/packages/react-openapi/src/OpenAPIResponseExample.tsx
@@ -93,13 +93,7 @@ export function OpenAPIResponseExample(props: {
         return null;
     }
 
-    return (
-        <OpenAPIResponseExampleContent
-            selectIcon={context.icons.chevronDown}
-            blockKey={context.blockKey}
-            items={tabs}
-        />
-    );
+    return <OpenAPIResponseExampleContent selectIcon={context.icons.chevronDown} items={tabs} />;
 }
 
 function OpenAPIResponse(props: {
diff --git a/packages/react-openapi/src/OpenAPIResponseExampleContent.tsx b/packages/react-openapi/src/OpenAPIResponseExampleContent.tsx
index 74c2f1142..58e4a7b92 100644
--- a/packages/react-openapi/src/OpenAPIResponseExampleContent.tsx
+++ b/packages/react-openapi/src/OpenAPIResponseExampleContent.tsx
@@ -14,42 +14,31 @@ type OpenAPIResponseExampleItem = OpenAPISelectItem & {
 /**
  * Get the state of the response examples select.
  */
-export function useResponseExamplesState(
-    blockKey: string | undefined,
-    initialKey: Key = 'default'
-) {
-    return useSelectState(getResponseExampleStateKey(blockKey), initialKey);
+export function useResponseExamplesState(initialKey: Key = 'default') {
+    return useSelectState(getResponseExampleStateKey(), initialKey);
 }
 
 export function OpenAPIResponseExampleContent(props: {
     items: OpenAPIResponseExampleItem[];
-    blockKey?: string;
     selectIcon?: React.ReactNode;
 }) {
-    const { blockKey, items, selectIcon } = props;
+    const { items, selectIcon } = props;
 
     return (
         <StaticSection
-            header={
-                <OpenAPIResponseExampleHeader
-                    selectIcon={selectIcon}
-                    blockKey={blockKey}
-                    items={items}
-                />
-            }
+            header={<OpenAPIResponseExampleHeader selectIcon={selectIcon} items={items} />}
             className="openapi-response-examples"
         >
-            <OpenAPIResponseExampleBody blockKey={blockKey} items={items} />
+            <OpenAPIResponseExampleBody items={items} />
         </StaticSection>
     );
 }
 
 function OpenAPIResponseExampleHeader(props: {
     items: OpenAPIResponseExampleItem[];
-    blockKey?: string;
     selectIcon?: React.ReactNode;
 }) {
-    const { items, blockKey, selectIcon } = props;
+    const { items, selectIcon } = props;
 
     if (items.length === 1) {
         const item = items[0];
@@ -69,7 +58,7 @@ function OpenAPIResponseExampleHeader(props: {
         <OpenAPISelect
             items={items}
             icon={selectIcon}
-            stateKey={getResponseExampleStateKey(blockKey)}
+            stateKey={getResponseExampleStateKey()}
             placement="bottom start"
         >
             {items.map((item) => (
@@ -103,10 +92,9 @@ function OpenAPIResponseExampleItem(props: {
 
 function OpenAPIResponseExampleBody(props: {
     items: OpenAPIResponseExampleItem[];
-    blockKey?: string;
 }) {
-    const { blockKey, items } = props;
-    const state = useResponseExamplesState(blockKey, items[0]?.key);
+    const { items } = props;
+    const state = useResponseExamplesState(items[0]?.key);
 
     const selectedItem = items.find((item) => item.key === state.key) ?? items[0];
 
@@ -118,8 +106,9 @@ function OpenAPIResponseExampleBody(props: {
 }
 
 /**
- * Return the state key for the response examples.
+ * Return the state key for the response examples. Not scoped to a block so the selected response
+ * stays in sync across every operation on the page (like the code sample language selector).
  */
-function getResponseExampleStateKey(blockKey: string | undefined) {
-    return createStateKey('openapi-responses', blockKey);
+function getResponseExampleStateKey() {
+    return createStateKey('openapi-responses');
 }
diff --git a/packages/react-openapi/src/OpenAPIResponses.tsx b/packages/react-openapi/src/OpenAPIResponses.tsx
index 0af72cb24..cac99e909 100644
--- a/packages/react-openapi/src/OpenAPIResponses.tsx
+++ b/packages/react-openapi/src/OpenAPIResponses.tsx
@@ -2,6 +2,7 @@
 
 import type { OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
 import clsx from 'classnames';
+import type { Key } from 'react-aria';
 import { Markdown } from './Markdown';
 import { OpenAPIDisclosureGroup } from './OpenAPIDisclosureGroup';
 import { OpenAPIResponse } from './OpenAPIResponse';
@@ -105,29 +106,47 @@ export function OpenAPIResponses(props: {
             };
         });
 
-    const state = useResponseExamplesState(context.blockKey, groups[0]?.key);
+    const state = useResponseExamplesState(groups[0]?.key);
 
     const expandAll = context.expandAllResponses;
-    const expandedKeys = expandAll
-        ? new Set(groups.map((g) => g.key))
-        : state.key
-          ? new Set([state.key])
-          : new Set<string>();
+
+    // In expand-all mode the group manages its own (multiple) expanded rows; otherwise it's
+    // controlled and stays in sync with the page-wide responses selector.
+    const disclosureProps = expandAll
+        ? {
+              stateKey: createStateKey('openapi-responses-disclosure', context.blockKey),
+              defaultExpandedKeys: groups.map((g) => g.key),
+          }
+        : {
+              expandedKeys: getExpandedResponseKeys(groups, state.key),
+              onExpandedChange: (keys: Set<Key>) => {
+                  state.setKey(keys.values().next().value ?? null);
+              },
+          };
 
     return (
         <StaticSection header={t(context.translation, 'responses')} className="openapi-responses">
             <OpenAPIDisclosureGroup
                 icon={context.icons.chevronRight}
                 allowsMultipleExpanded={expandAll}
-                expandedKeys={expandedKeys}
-                onExpandedChange={(keys) => {
-                    const key = keys.values().next().value ?? null;
-                    state.setKey(key);
-                }}
                 groups={groups}
                 selectIcon={context.icons.chevronDown}
                 selectStateKey={createStateKey('response-media-types', context.blockKey)}
+                {...disclosureProps}
             />
         </StaticSection>
     );
 }
+
+/**
+ * Resolve the expanded response for the controlled accordion: nothing when the selection is
+ * cleared, otherwise the selected status code, falling back to the first response when this
+ * operation doesn't define it.
+ */
+function getExpandedResponseKeys(groups: { key: string }[], selectedKey: Key | null): Set<string> {
+    if (selectedKey == null) {
+        return new Set<string>();
+    }
+    const key = groups.find((g) => g.key === selectedKey)?.key ?? groups[0]?.key;
+    return key ? new Set([key]) : new Set<string>();
+}

From 4e9071d1b5745491c66a078e501405565cff856e Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Wed, 8 Jul 2026 11:02:49 +0200
Subject: [PATCH 20/46] Fix docs embed `navigateToPage` for cross-space/section
 deep links (#4374)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../embed-navigate-to-page-normalize.md       |  5 ++
 packages/embed/README.md                      |  4 +-
 .../embed/src/client/createGitBookFrame.ts    |  7 +-
 .../Embeddable/EmbeddableIframeAPI.tsx        | 24 ++++++-
 .../components/Embeddable/server-actions.ts   | 64 +++++++++++++++++++
 5 files changed, 100 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/embed-navigate-to-page-normalize.md
 create mode 100644 packages/gitbook/src/components/Embeddable/server-actions.ts

diff --git a/.changeset/embed-navigate-to-page-normalize.md b/.changeset/embed-navigate-to-page-normalize.md
new file mode 100644
index 000000000..a2d7e41bc
--- /dev/null
+++ b/.changeset/embed-navigate-to-page-normalize.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix the docs embed `navigateToPage` API on multi-space sites. Deep-linking to a page in a different space/section (e.g. `navigateToPage('/help-center/integrations')`) previously 404'd because the section base was not placed before `~gitbook/embed/page`. The target is now resolved to its space server-side, so pages in any space resolve correctly. The input accepts the page path, an absolute path, or the full published URL.
diff --git a/packages/embed/README.md b/packages/embed/README.md
index 47166e799..f422bd043 100644
--- a/packages/embed/README.md
+++ b/packages/embed/README.md
@@ -187,7 +187,7 @@ function MyComponent() {
 - `GitBook('open')` - Open widget window
 - `GitBook('close')` - Close widget window
 - `GitBook('toggle')` - Toggle widget window
-- `GitBook('navigateToPage', path: string)` - Navigate to page
+- `GitBook('navigateToPage', path: string)` - Navigate to page (accepts the page path within the site, an absolute path, or the full published URL; resolves pages in any space/section)
 - `GitBook('navigateToAssistant')` - Navigate to assistant tab
 - `GitBook('postUserMessage', message: string)` - Post message to chat
 - `GitBook('clearChat')` - Clear chat history
@@ -202,7 +202,7 @@ function MyComponent() {
 - `client.createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient`
 
 **Frame Client:**
-- `frame.navigateToPage(path: string)` → `void`
+- `frame.navigateToPage(path: string)` → `void` (accepts the page path within the site, an absolute path, or the full published URL; resolves pages in any space/section)
 - `frame.navigateToAssistant()` → `void`
 - `frame.postUserMessage(message: string)` → `void`
 - `frame.clearChat()` → `void`
diff --git a/packages/embed/src/client/createGitBookFrame.ts b/packages/embed/src/client/createGitBookFrame.ts
index fe4fa4c90..579bb5725 100644
--- a/packages/embed/src/client/createGitBookFrame.ts
+++ b/packages/embed/src/client/createGitBookFrame.ts
@@ -7,7 +7,12 @@ import type {
 
 export type GitBookFrameClient = {
     /**
-     * Navigate to a page by its path.
+     * Navigate to a page in the docs tab.
+     *
+     * Accepts the page's path within the site (e.g. `getting-started/quickstart`),
+     * an absolute path (e.g. `/help-center/integrations`), or its full published URL.
+     * The target page may live in any space/section of the site — including one other
+     * than the embed is currently showing — and is resolved to the right space.
      */
     navigateToPage: (path: string) => void;
 
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
index b2b612ad5..1c1d96096 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableIframeAPI.tsx
@@ -11,6 +11,7 @@ import { createStore, useStore } from 'zustand';
 import { integrationsAssistantTools } from '../Integrations';
 import { Button, LinkContext, type LinkContextType } from '../primitives';
 import { getChannel } from './channel';
+import { resolveEmbedPageLink } from './server-actions';
 
 const embeddableConfiguration = createStore<GitBookEmbeddableConfiguration>(() => ({
     tabs: [],
@@ -44,9 +45,14 @@ export function EmbeddableIframeAPI(props: {
         refs.current = { router, chatController, baseURL };
     });
 
+    // Bumped on every navigation so an in-flight (async) `navigateToPage` can tell it has
+    // been superseded by a later command and skip its now-stale `router.push`.
+    const navToken = useRef(0);
+
     React.useEffect(() => {
         return chatController.on('open', () => {
             const { baseURL, router } = refs.current;
+            navToken.current++;
             router.push(`${baseURL}/assistant`);
         });
     }, [chatController]);
@@ -82,10 +88,26 @@ export function EmbeddableIframeAPI(props: {
                     break;
                 }
                 case 'navigateToPage': {
-                    router.push(`${baseURL}/page/${message.pagePath}`);
+                    // Resolve the target server-side: on a multi-space site the page may
+                    // live in another space/section, whose base must go before
+                    // `~gitbook/embed/page`. Fall back to a same-space push on failure.
+                    const { pagePath } = message;
+                    const token = ++navToken.current;
+                    // Ignore the result if a later navigation has since superseded this one.
+                    const push = (href: string) => {
+                        if (navToken.current === token) {
+                            router.push(href);
+                        }
+                    };
+                    resolveEmbedPageLink(pagePath)
+                        .then((resolved) =>
+                            push('href' in resolved ? resolved.href : `${baseURL}/page/${pagePath}`)
+                        )
+                        .catch(() => push(`${baseURL}/page/${pagePath}`));
                     break;
                 }
                 case 'navigateToAssistant': {
+                    navToken.current++;
                     router.push(`${baseURL}/assistant`);
                     break;
                 }
diff --git a/packages/gitbook/src/components/Embeddable/server-actions.ts b/packages/gitbook/src/components/Embeddable/server-actions.ts
new file mode 100644
index 000000000..bb3ab770f
--- /dev/null
+++ b/packages/gitbook/src/components/Embeddable/server-actions.ts
@@ -0,0 +1,64 @@
+'use server';
+
+import { toEmbeddableLinkForPublishedContent } from '@/lib/embeddable-linker';
+import { withTrailingSlash } from '@/lib/paths';
+import { fetchServerActionSiteContext, getServerActionBaseContext } from '@/lib/server-actions';
+import { findSiteSpaceByUrl } from '@/lib/sites';
+import { traceErrorOnly } from '@/lib/tracing';
+
+/**
+ * Resolve a `navigateToPage` reference into the embed link for that page.
+ *
+ * The reference can be a page path relative to the docs root
+ * (e.g. `getting-started/quickstart` or `/help-center/integrations`) or the full
+ * published URL. Paths are resolved relative to the site's published URL, so a
+ * leading slash means "from the docs root" even when the site is served from a
+ * subdirectory (e.g. `example.com/docs`).
+ *
+ * On a multi-space site the target may live in a different space/section than the one
+ * the embed is currently showing, and the section base must go *before*
+ * `~gitbook/embed/page` (e.g. `/help-center/~gitbook/embed/page/integrations`). We find
+ * the space that owns the target from the site structure and build the link with the
+ * embeddable linker, so a cross-space deep link resolves instead of 404ing.
+ */
+export async function resolveEmbedPageLink(
+    reference: string
+): Promise<{ href: string } | { error: string }> {
+    return traceErrorOnly('Embed.resolveEmbedPageLink', async () => {
+        const baseContext = await getServerActionBaseContext();
+        const context = await fetchServerActionSiteContext(baseContext);
+
+        // Use the site's published URL (not the linker's, which is proxy-prefixed in
+        // `/url/...` mode) so the reference matches the spaces' published URLs.
+        const sitePublishedURL = context.site.urls.published;
+        if (!sitePublishedURL) {
+            return { error: 'The site has no published URL.' };
+        }
+
+        // Resolve the reference to a full URL within the published site. Strip a leading
+        // slash so an absolute-looking path is treated as relative to the docs root
+        // rather than the domain root (which matters when the site is on a subdirectory).
+        let target: URL;
+        try {
+            target = new URL(reference.replace(/^\/+/, ''), withTrailingSlash(sitePublishedURL));
+        } catch {
+            return { error: `Invalid page reference: ${reference}` };
+        }
+
+        // Find the space that owns the target and the page path within it, then build the
+        // embed link so the section base lands before `~gitbook/embed/page`.
+        const match = findSiteSpaceByUrl(context.structure, target.href);
+        const spacePublishedURL = match?.siteSpace.urls.published;
+        if (!match || !spacePublishedURL) {
+            return { error: `Could not resolve a page for "${reference}".` };
+        }
+
+        const href = toEmbeddableLinkForPublishedContent(
+            context.linker,
+            spacePublishedURL,
+            match.pagePath ?? ''
+        );
+        // Carry through a section anchor (e.g. `#install`) from the reference.
+        return { href: `${href}${target.hash}` };
+    });
+}

From 8e9a49de1a097ea0616d5addda3907253fffc295 Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Wed, 8 Jul 2026 16:11:26 +0200
Subject: [PATCH 21/46] Separate prompt block actions (#4379)

---
 ...rnd-11847-separate-prompt-block-actions.md |  5 ++
 .../components/DocumentView/Prompt/Prompt.tsx | 22 ++---
 .../DocumentView/Prompt/PromptClient.tsx      | 89 ++++++-------------
 packages/gitbook/src/intl/translations/ar.ts  |  1 +
 packages/gitbook/src/intl/translations/bg.ts  |  1 +
 packages/gitbook/src/intl/translations/cs.ts  |  1 +
 packages/gitbook/src/intl/translations/da.ts  |  1 +
 packages/gitbook/src/intl/translations/de.ts  |  1 +
 packages/gitbook/src/intl/translations/el.ts  |  1 +
 packages/gitbook/src/intl/translations/en.ts  |  1 +
 packages/gitbook/src/intl/translations/es.ts  |  1 +
 packages/gitbook/src/intl/translations/et.ts  |  1 +
 packages/gitbook/src/intl/translations/fi.ts  |  1 +
 packages/gitbook/src/intl/translations/fr.ts  |  1 +
 packages/gitbook/src/intl/translations/he.ts  |  1 +
 packages/gitbook/src/intl/translations/hi.ts  |  1 +
 packages/gitbook/src/intl/translations/hr.ts  |  1 +
 packages/gitbook/src/intl/translations/hu.ts  |  1 +
 packages/gitbook/src/intl/translations/id.ts  |  1 +
 packages/gitbook/src/intl/translations/it.ts  |  1 +
 packages/gitbook/src/intl/translations/ja.ts  |  1 +
 packages/gitbook/src/intl/translations/ko.ts  |  1 +
 packages/gitbook/src/intl/translations/lt.ts  |  1 +
 packages/gitbook/src/intl/translations/lv.ts  |  1 +
 packages/gitbook/src/intl/translations/ms.ts  |  1 +
 packages/gitbook/src/intl/translations/nl.ts  |  1 +
 packages/gitbook/src/intl/translations/no.ts  |  1 +
 packages/gitbook/src/intl/translations/pl.ts  |  1 +
 .../gitbook/src/intl/translations/pt-br.ts    |  1 +
 packages/gitbook/src/intl/translations/pt.ts  |  1 +
 packages/gitbook/src/intl/translations/ro.ts  |  1 +
 packages/gitbook/src/intl/translations/ru.ts  |  1 +
 packages/gitbook/src/intl/translations/sk.ts  |  1 +
 packages/gitbook/src/intl/translations/sl.ts  |  1 +
 packages/gitbook/src/intl/translations/sv.ts  |  1 +
 packages/gitbook/src/intl/translations/th.ts  |  1 +
 packages/gitbook/src/intl/translations/tr.ts  |  1 +
 packages/gitbook/src/intl/translations/uk.ts  |  1 +
 packages/gitbook/src/intl/translations/vi.ts  |  1 +
 packages/gitbook/src/intl/translations/yue.ts |  1 +
 .../gitbook/src/intl/translations/zh-tw.ts    |  1 +
 packages/gitbook/src/intl/translations/zh.ts  |  1 +
 42 files changed, 76 insertions(+), 79 deletions(-)
 create mode 100644 .changeset/rnd-11847-separate-prompt-block-actions.md

diff --git a/.changeset/rnd-11847-separate-prompt-block-actions.md b/.changeset/rnd-11847-separate-prompt-block-actions.md
new file mode 100644
index 000000000..b93ee22c5
--- /dev/null
+++ b/.changeset/rnd-11847-separate-prompt-block-actions.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Separate the prompt block actions into a primary "Open in" dropdown and a secondary "Copy prompt" button, instead of a single combined button group, and align the block's design with the expandable block (bordered frame, left disclosure chevron, and subtle elevation when expanded).
diff --git a/packages/gitbook/src/components/DocumentView/Prompt/Prompt.tsx b/packages/gitbook/src/components/DocumentView/Prompt/Prompt.tsx
index b4c50f356..c1ecc4efb 100644
--- a/packages/gitbook/src/components/DocumentView/Prompt/Prompt.tsx
+++ b/packages/gitbook/src/components/DocumentView/Prompt/Prompt.tsx
@@ -1,4 +1,3 @@
-import { tcls } from '@/lib/tailwind';
 import {
     CustomizationPageActionType,
     type DocumentBlockPrompt,
@@ -15,21 +14,12 @@ export function Prompt(props: BlockProps<DocumentBlockPrompt>) {
         block.data.icon && validateIconName(block.data.icon) ? block.data.icon : null;
 
     return (
-        <div
-            className={tcls(
-                'relative flex w-full flex-col overflow-hidden',
-                'border border-tint-subtle bg-tint-subtle theme-bold-tint:bg-tint-base theme-muted:bg-tint-base text-tint-strong contrast-more:border-tint contrast-more:bg-tint-base',
-                'circular-corners:rounded-2xl rounded-corners:rounded-xl straight-corners:rounded-xs',
-                'depth-subtle:shadow-xs'
-            )}
-        >
-            <PromptClient
-                contentIcon={contentIcon}
-                description={block.data.description}
-                prompt={getPromptText(block)}
-                openInAIProviders={getOpenInAIProviders(props)}
-            />
-        </div>
+        <PromptClient
+            contentIcon={contentIcon}
+            description={block.data.description}
+            prompt={getPromptText(block)}
+            openInAIProviders={getOpenInAIProviders(props)}
+        />
     );
 }
 
diff --git a/packages/gitbook/src/components/DocumentView/Prompt/PromptClient.tsx b/packages/gitbook/src/components/DocumentView/Prompt/PromptClient.tsx
index b768e99c7..cb2fbfe69 100644
--- a/packages/gitbook/src/components/DocumentView/Prompt/PromptClient.tsx
+++ b/packages/gitbook/src/components/DocumentView/Prompt/PromptClient.tsx
@@ -1,12 +1,6 @@
 'use client';
 
-import {
-    Button,
-    ButtonGroup,
-    DropdownMenu,
-    DropdownMenuItem,
-    ToggleChevron,
-} from '@/components/primitives';
+import { Button, DropdownMenu, DropdownMenuItem, ToggleChevron } from '@/components/primitives';
 import { getURLForLLM } from '@/components/utils';
 import { tString, useLanguage } from '@/intl/client';
 import { tcls } from '@/lib/tailwind';
@@ -26,10 +20,21 @@ export function PromptClient(props: {
     const language = useLanguage();
     const promptId = React.useId();
     const [open, setOpen] = React.useState(false);
-    const [headerHasFocus, setHeaderHasFocus] = React.useState(false);
     return (
-        <>
-            <div className="group/prompt-header relative flex min-h-9 flex-row items-center justify-between gap-4 px-3 py-2">
+        <div
+            className={tcls(
+                'relative flex w-full flex-col overflow-hidden circular-corners:rounded-2xl rounded-corners:rounded-xl straight-corners:rounded-xs text-tint-strong',
+                'border border-tint-subtle contrast-more:border-tint',
+                'transition',
+                open ? 'bg-tint depth-subtle:shadow-xs' : 'bg-tint-base'
+            )}
+        >
+            <div
+                className={tcls(
+                    'group/prompt-header relative flex min-h-9 flex-row items-center justify-between gap-4 p-3 transition-colors',
+                    open ? 'hover:bg-tint-hover' : 'hover:bg-tint-subtle'
+                )}
+            >
                 <button
                     type="button"
                     aria-controls={promptId}
@@ -40,16 +45,15 @@ export function PromptClient(props: {
                         'focus-visible:ring-2 focus-visible:ring-primary-hover'
                     )}
                     disabled={!prompt}
-                    onBlur={() => setHeaderHasFocus(false)}
                     onClick={() => setOpen((prev) => !prev)}
-                    onFocus={() => setHeaderHasFocus(true)}
                 />
                 <div className="pointer-events-none relative z-0 flex min-w-0 flex-row items-center gap-2 text-tint-strong">
-                    <PromptDisclosureIcon
-                        contentIcon={contentIcon}
-                        headerHasFocus={headerHasFocus}
+                    <ToggleChevron
                         open={open}
+                        orientation="right-to-down"
+                        className="size-3 shrink-0 text-tint-subtle transition-colors group-hover/prompt-header:text-tint-strong"
                     />
+                    {contentIcon ? <Icon icon={contentIcon} className="size-4 shrink-0" /> : null}
                     <span className="min-w-0 truncate">{description}</span>
                 </div>
                 <PromptActions prompt={prompt} openInAIProviders={openInAIProviders} />
@@ -63,45 +67,7 @@ export function PromptClient(props: {
                     </pre>
                 </div>
             ) : null}
-        </>
-    );
-}
-
-function PromptDisclosureIcon(props: {
-    contentIcon: IconName | null;
-    headerHasFocus: boolean;
-    open: boolean;
-}) {
-    const { contentIcon, headerHasFocus, open } = props;
-    return (
-        <span className="relative flex size-4 shrink-0 items-center justify-center">
-            {contentIcon ? (
-                <>
-                    <span
-                        className={tcls(
-                            'flex items-center transition-opacity duration-150 group-hover/prompt-header:opacity-0',
-                            headerHasFocus && 'opacity-0'
-                        )}
-                    >
-                        <Icon icon={contentIcon} className="size-4 shrink-0" />
-                    </span>
-                    <span
-                        className={tcls(
-                            'absolute inset-0 flex items-center justify-center text-tint-subtle opacity-0 transition-opacity duration-150 group-hover/prompt-header:opacity-100',
-                            headerHasFocus && 'opacity-100'
-                        )}
-                    >
-                        <ToggleChevron open={open} orientation="right-to-down" className="size-3" />
-                    </span>
-                </>
-            ) : (
-                <ToggleChevron
-                    open={open}
-                    orientation="right-to-down"
-                    className="size-3 text-tint-subtle"
-                />
-            )}
-        </span>
+        </div>
     );
 }
 
@@ -109,10 +75,10 @@ function PromptActions(props: { prompt: string; openInAIProviders: boolean }) {
     const { prompt, openInAIProviders } = props;
 
     return (
-        <ButtonGroup className="relative z-20 shrink-0 overflow-visible">
+        <div className="relative z-20 flex shrink-0 items-center gap-2">
             <CopyPromptButton prompt={prompt} />
             {openInAIProviders ? <OpenPromptDropdown prompt={prompt} /> : null}
-        </ButtonGroup>
+        </div>
     );
 }
 
@@ -140,11 +106,9 @@ function CopyPromptButton(props: { prompt: string }) {
 
     return (
         <Button
-            variant="secondary"
+            variant="primary"
             size="xsmall"
-            icon={copied ? 'check' : 'copy'}
             label={copied ? tString(language, 'code_copied') : tString(language, 'prompt_copy')}
-            className="bg-tint-base"
             disabled={!prompt}
             onClick={() => {
                 navigator.clipboard.writeText(prompt);
@@ -164,12 +128,11 @@ function OpenPromptDropdown(props: { prompt: string }) {
             className="!min-w-48 max-w-max"
             button={
                 <Button
-                    icon={<ToggleChevron className="size-text-sm" />}
-                    label={tString(language, 'open')}
-                    iconOnly
+                    label={tString(language, 'open_in_ai')}
+                    trailing={<ToggleChevron className="size-text-sm" />}
                     size="xsmall"
                     variant="secondary"
-                    className="bg-tint-base"
+                    className="max-sm:hidden"
                     disabled={!prompt}
                 />
             }
diff --git a/packages/gitbook/src/intl/translations/ar.ts b/packages/gitbook/src/intl/translations/ar.ts
index 33c5220ac..d6dda28ac 100644
--- a/packages/gitbook/src/intl/translations/ar.ts
+++ b/packages/gitbook/src/intl/translations/ar.ts
@@ -156,6 +156,7 @@ export const ar: TranslationLanguage = {
     view_page_markdown: 'عرض كـ Markdown',
     view_page_plaintext: 'عرض هذه الصفحة كنص عادي',
     open_in: 'فتح في ${1}',
+    open_in_ai: 'فتح في',
     open_in_llms_pre_prompt: 'اقرأ ${1} وأجب عن الأسئلة المتعلقة بالمحتوى.',
     connect_mcp_to: 'الاتصال بـ ${1}',
     install_mcp_on: 'استخدام MCP هذا في ${1}',
diff --git a/packages/gitbook/src/intl/translations/bg.ts b/packages/gitbook/src/intl/translations/bg.ts
index fb041290a..eec77392c 100644
--- a/packages/gitbook/src/intl/translations/bg.ts
+++ b/packages/gitbook/src/intl/translations/bg.ts
@@ -160,6 +160,7 @@ export const bg: TranslationLanguage = {
     view_page_markdown: 'Преглед като Markdown',
     view_page_plaintext: 'Преглед на тази страница като обикновен текст',
     open_in: 'Отваряне в ${1}',
+    open_in_ai: 'Отвори в',
     open_in_llms_pre_prompt: 'Прочетете ${1} и отговорете на въпроси за съдържанието.',
     connect_mcp_to: 'Свързване към ${1}',
     install_mcp_on: 'Използване на този MCP в ${1}',
diff --git a/packages/gitbook/src/intl/translations/cs.ts b/packages/gitbook/src/intl/translations/cs.ts
index f444563dc..00214d672 100644
--- a/packages/gitbook/src/intl/translations/cs.ts
+++ b/packages/gitbook/src/intl/translations/cs.ts
@@ -158,6 +158,7 @@ export const cs: TranslationLanguage = {
     view_page_markdown: 'Zobrazit jako Markdown',
     view_page_plaintext: 'Zobrazit tuto stránku jako prostý text',
     open_in: 'Otevřít v ${1}',
+    open_in_ai: 'Otevřít v',
     open_in_llms_pre_prompt: 'Přečtěte si ${1} a odpovězte na otázky o obsahu.',
     connect_mcp_to: 'Připojit k ${1}',
     install_mcp_on: 'Použít tento MCP v ${1}',
diff --git a/packages/gitbook/src/intl/translations/da.ts b/packages/gitbook/src/intl/translations/da.ts
index 775393096..65b030db0 100644
--- a/packages/gitbook/src/intl/translations/da.ts
+++ b/packages/gitbook/src/intl/translations/da.ts
@@ -157,6 +157,7 @@ export const da: TranslationLanguage = {
     view_page_markdown: 'Vis som Markdown',
     view_page_plaintext: 'Vis denne side som almindelig tekst',
     open_in: 'Åbn i ${1}',
+    open_in_ai: 'Åbn i',
     open_in_llms_pre_prompt: 'Læs ${1}, og besvar spørgsmål om indholdet.',
     connect_mcp_to: 'Opret forbindelse til ${1}',
     install_mcp_on: 'Brug denne MCP i ${1}',
diff --git a/packages/gitbook/src/intl/translations/de.ts b/packages/gitbook/src/intl/translations/de.ts
index 1346a6473..979ba3900 100644
--- a/packages/gitbook/src/intl/translations/de.ts
+++ b/packages/gitbook/src/intl/translations/de.ts
@@ -163,6 +163,7 @@ export const de: TranslationLanguage = {
     view_page_markdown: 'Als Markdown anzeigen',
     view_page_plaintext: 'Diese Seite als Klartext anzeigen',
     open_in: 'Öffnen in ${1}',
+    open_in_ai: 'Öffnen in',
     open_in_llms_pre_prompt: 'Lies ${1} und beantworte Fragen zum Inhalt.',
     connect_mcp_to: 'Mit ${1} verbinden',
     install_mcp_on: 'Dieses MCP in ${1} verwenden',
diff --git a/packages/gitbook/src/intl/translations/el.ts b/packages/gitbook/src/intl/translations/el.ts
index ff293e8d1..1950cefaa 100644
--- a/packages/gitbook/src/intl/translations/el.ts
+++ b/packages/gitbook/src/intl/translations/el.ts
@@ -162,6 +162,7 @@ export const el: TranslationLanguage = {
     view_page_markdown: 'Προβολή ως Markdown',
     view_page_plaintext: 'Προβολή αυτής της σελίδας ως απλού κειμένου',
     open_in: 'Άνοιγμα στο ${1}',
+    open_in_ai: 'Άνοιγμα σε',
     open_in_llms_pre_prompt: 'Διαβάστε το ${1} και απαντήστε σε ερωτήσεις για το περιεχόμενο.',
     connect_mcp_to: 'Σύνδεση με ${1}',
     install_mcp_on: 'Χρήση αυτού του MCP στο ${1}',
diff --git a/packages/gitbook/src/intl/translations/en.ts b/packages/gitbook/src/intl/translations/en.ts
index a387b7c01..3ea3a77e7 100644
--- a/packages/gitbook/src/intl/translations/en.ts
+++ b/packages/gitbook/src/intl/translations/en.ts
@@ -155,6 +155,7 @@ export const en = {
     view_page_markdown: 'View as Markdown',
     view_page_plaintext: 'View this page as plain text',
     open_in: 'Open in ${1}',
+    open_in_ai: 'Open in',
     open_in_llms_pre_prompt: 'Read ${1} and answer questions about the content.',
     connect_mcp_to: 'Connect to ${1}',
     install_mcp_on: 'Use this MCP in ${1}',
diff --git a/packages/gitbook/src/intl/translations/es.ts b/packages/gitbook/src/intl/translations/es.ts
index 66ed1c869..6cdc4e78a 100644
--- a/packages/gitbook/src/intl/translations/es.ts
+++ b/packages/gitbook/src/intl/translations/es.ts
@@ -161,6 +161,7 @@ export const es: TranslationLanguage = {
     view_page_markdown: 'Ver como Markdown',
     view_page_plaintext: 'Ver esta página como texto plano',
     open_in: 'Abrir en ${1}',
+    open_in_ai: 'Abrir en',
     open_in_llms_pre_prompt: 'Lee ${1} y responde preguntas sobre el contenido.',
     connect_mcp_to: 'Conectar a ${1}',
     install_mcp_on: 'Usar este MCP en ${1}',
diff --git a/packages/gitbook/src/intl/translations/et.ts b/packages/gitbook/src/intl/translations/et.ts
index bce15a732..67f103978 100644
--- a/packages/gitbook/src/intl/translations/et.ts
+++ b/packages/gitbook/src/intl/translations/et.ts
@@ -157,6 +157,7 @@ export const et: TranslationLanguage = {
     view_page_markdown: 'Kuva Markdownina',
     view_page_plaintext: 'Kuva see leht lihttekstina',
     open_in: 'Ava rakenduses ${1}',
+    open_in_ai: 'Ava rakenduses',
     open_in_llms_pre_prompt: 'Lugege ${1} ja vastake sisu puudutavatele küsimustele.',
     connect_mcp_to: 'Ühenda teenusega ${1}',
     install_mcp_on: 'Kasuta seda MCP-d rakenduses ${1}',
diff --git a/packages/gitbook/src/intl/translations/fi.ts b/packages/gitbook/src/intl/translations/fi.ts
index 5bf46c819..c9df29b99 100644
--- a/packages/gitbook/src/intl/translations/fi.ts
+++ b/packages/gitbook/src/intl/translations/fi.ts
@@ -159,6 +159,7 @@ export const fi: TranslationLanguage = {
     view_page_markdown: 'Näytä Markdownina',
     view_page_plaintext: 'Näytä tämä sivu pelkkänä tekstinä',
     open_in: 'Avaa sovelluksessa ${1}',
+    open_in_ai: 'Avaa sovelluksessa',
     open_in_llms_pre_prompt: 'Lue ${1} ja vastaa sisältöä koskeviin kysymyksiin.',
     connect_mcp_to: 'Yhdistä kohteeseen ${1}',
     install_mcp_on: 'Käytä tätä MCP:tä sovelluksessa ${1}',
diff --git a/packages/gitbook/src/intl/translations/fr.ts b/packages/gitbook/src/intl/translations/fr.ts
index 3213b5987..8e6c93559 100644
--- a/packages/gitbook/src/intl/translations/fr.ts
+++ b/packages/gitbook/src/intl/translations/fr.ts
@@ -157,6 +157,7 @@ export const fr: TranslationLanguage = {
     view_page_markdown: 'Voir en Markdown',
     view_page_plaintext: 'Voir en texte brut',
     open_in: 'Ouvrir dans ${1}',
+    open_in_ai: 'Ouvrir dans',
     open_in_llms_pre_prompt: 'Lire ${1} et répondre aux questions sur le contenu.',
     connect_mcp_to: 'Se connecter à ${1}',
     install_mcp_on: 'Utiliser ce MCP dans ${1}',
diff --git a/packages/gitbook/src/intl/translations/he.ts b/packages/gitbook/src/intl/translations/he.ts
index 4c52d884b..fd1bb8fb9 100644
--- a/packages/gitbook/src/intl/translations/he.ts
+++ b/packages/gitbook/src/intl/translations/he.ts
@@ -155,6 +155,7 @@ export const he: TranslationLanguage = {
     view_page_markdown: 'הצגה כ-Markdown',
     view_page_plaintext: 'הצגת דף זה כטקסט פשוט',
     open_in: 'פתיחה ב-${1}',
+    open_in_ai: 'פתיחה באמצעות',
     open_in_llms_pre_prompt: 'קרא את ${1} וענה על שאלות לגבי התוכן.',
     connect_mcp_to: 'התחברות אל ${1}',
     install_mcp_on: 'שימוש ב-MCP הזה ב-${1}',
diff --git a/packages/gitbook/src/intl/translations/hi.ts b/packages/gitbook/src/intl/translations/hi.ts
index 6ef65af32..71e0ba453 100644
--- a/packages/gitbook/src/intl/translations/hi.ts
+++ b/packages/gitbook/src/intl/translations/hi.ts
@@ -156,6 +156,7 @@ export const hi: TranslationLanguage = {
     view_page_markdown: 'Markdown के रूप में देखें',
     view_page_plaintext: 'इस पृष्ठ को सादे पाठ के रूप में देखें',
     open_in: '${1} में खोलें',
+    open_in_ai: 'इसमें खोलें',
     open_in_llms_pre_prompt: '${1} पढ़ें और सामग्री के बारे में प्रश्नों का उत्तर दें।',
     connect_mcp_to: '${1} से कनेक्ट करें',
     install_mcp_on: 'इस MCP को ${1} में उपयोग करें',
diff --git a/packages/gitbook/src/intl/translations/hr.ts b/packages/gitbook/src/intl/translations/hr.ts
index a76487ed0..f08f00f69 100644
--- a/packages/gitbook/src/intl/translations/hr.ts
+++ b/packages/gitbook/src/intl/translations/hr.ts
@@ -158,6 +158,7 @@ export const hr: TranslationLanguage = {
     view_page_markdown: 'Prikaži kao Markdown',
     view_page_plaintext: 'Prikaži ovu stranicu kao običan tekst',
     open_in: 'Otvori u ${1}',
+    open_in_ai: 'Otvori u',
     open_in_llms_pre_prompt: 'Pročitajte ${1} i odgovorite na pitanja o sadržaju.',
     connect_mcp_to: 'Poveži s ${1}',
     install_mcp_on: 'Upotrijebi ovaj MCP u ${1}',
diff --git a/packages/gitbook/src/intl/translations/hu.ts b/packages/gitbook/src/intl/translations/hu.ts
index 8c7d8e43b..9b28a6dd8 100644
--- a/packages/gitbook/src/intl/translations/hu.ts
+++ b/packages/gitbook/src/intl/translations/hu.ts
@@ -159,6 +159,7 @@ export const hu: TranslationLanguage = {
     view_page_markdown: 'Megtekintés Markdownként',
     view_page_plaintext: 'Az oldal megtekintése egyszerű szövegként',
     open_in: 'Megnyitás itt: ${1}',
+    open_in_ai: 'Megnyitás ebben:',
     open_in_llms_pre_prompt:
         'Olvassa el ezt: ${1}, és válaszoljon a tartalommal kapcsolatos kérdésekre.',
     connect_mcp_to: 'Csatlakozás ehhez: ${1}',
diff --git a/packages/gitbook/src/intl/translations/id.ts b/packages/gitbook/src/intl/translations/id.ts
index 6fa6ce542..f4027297d 100644
--- a/packages/gitbook/src/intl/translations/id.ts
+++ b/packages/gitbook/src/intl/translations/id.ts
@@ -157,6 +157,7 @@ export const id: TranslationLanguage = {
     view_page_markdown: 'Lihat sebagai Markdown',
     view_page_plaintext: 'Lihat halaman ini sebagai teks biasa',
     open_in: 'Buka di ${1}',
+    open_in_ai: 'Buka di',
     open_in_llms_pre_prompt: 'Baca ${1} dan jawab pertanyaan tentang kontennya.',
     connect_mcp_to: 'Hubungkan ke ${1}',
     install_mcp_on: 'Gunakan MCP ini di ${1}',
diff --git a/packages/gitbook/src/intl/translations/it.ts b/packages/gitbook/src/intl/translations/it.ts
index 18af7b971..a05882fcd 100644
--- a/packages/gitbook/src/intl/translations/it.ts
+++ b/packages/gitbook/src/intl/translations/it.ts
@@ -160,6 +160,7 @@ export const it: TranslationLanguage = {
     view_page_markdown: 'Visualizza come Markdown',
     view_page_plaintext: 'Visualizza questa pagina come testo semplice',
     open_in: 'Apri in ${1}',
+    open_in_ai: 'Apri in',
     open_in_llms_pre_prompt: 'Leggi ${1} e rispondi alle domande sul contenuto.',
     connect_mcp_to: 'Connetti a ${1}',
     install_mcp_on: 'Usa questo MCP in ${1}',
diff --git a/packages/gitbook/src/intl/translations/ja.ts b/packages/gitbook/src/intl/translations/ja.ts
index bb5183149..2b7a1603d 100644
--- a/packages/gitbook/src/intl/translations/ja.ts
+++ b/packages/gitbook/src/intl/translations/ja.ts
@@ -157,6 +157,7 @@ export const ja: TranslationLanguage = {
     view_page_markdown: 'Markdown として表示',
     view_page_plaintext: 'このページをプレーンテキストで表示',
     open_in: '${1} で開く',
+    open_in_ai: '以下で開く',
     open_in_llms_pre_prompt: '${1} を読んで内容に関する質問に答えてください。',
     connect_mcp_to: '${1} に接続',
     install_mcp_on: '${1} でこのMCPを使用',
diff --git a/packages/gitbook/src/intl/translations/ko.ts b/packages/gitbook/src/intl/translations/ko.ts
index 35aab6eb0..f99f97c21 100644
--- a/packages/gitbook/src/intl/translations/ko.ts
+++ b/packages/gitbook/src/intl/translations/ko.ts
@@ -156,6 +156,7 @@ export const ko: TranslationLanguage = {
     view_page_markdown: 'Markdown으로 보기',
     view_page_plaintext: '이 페이지를 일반 텍스트로 보기',
     open_in: '${1}에서 열기',
+    open_in_ai: '다음에서 열기',
     open_in_llms_pre_prompt: '${1}을(를) 읽고 콘텐츠에 대한 질문에 답하세요.',
     connect_mcp_to: '${1}에 연결',
     install_mcp_on: '${1}에서 이 MCP 사용',
diff --git a/packages/gitbook/src/intl/translations/lt.ts b/packages/gitbook/src/intl/translations/lt.ts
index 965ffd19d..911544889 100644
--- a/packages/gitbook/src/intl/translations/lt.ts
+++ b/packages/gitbook/src/intl/translations/lt.ts
@@ -158,6 +158,7 @@ export const lt: TranslationLanguage = {
     view_page_markdown: 'Peržiūrėti kaip Markdown',
     view_page_plaintext: 'Peržiūrėti šį puslapį kaip paprastą tekstą',
     open_in: 'Atidaryti ${1}',
+    open_in_ai: 'Atidaryti su',
     open_in_llms_pre_prompt: 'Perskaitykite ${1} ir atsakykite į klausimus apie turinį.',
     connect_mcp_to: 'Prisijungti prie ${1}',
     install_mcp_on: 'Naudoti šį MCP ${1}',
diff --git a/packages/gitbook/src/intl/translations/lv.ts b/packages/gitbook/src/intl/translations/lv.ts
index 30b72ef5e..8c98ebc81 100644
--- a/packages/gitbook/src/intl/translations/lv.ts
+++ b/packages/gitbook/src/intl/translations/lv.ts
@@ -156,6 +156,7 @@ export const lv: TranslationLanguage = {
     view_page_markdown: 'Skatīt kā Markdown',
     view_page_plaintext: 'Skatīt šo lapu kā vienkāršu tekstu',
     open_in: 'Atvērt ${1}',
+    open_in_ai: 'Atvērt ar',
     open_in_llms_pre_prompt: 'Izlasiet ${1} un atbildiet uz jautājumiem par saturu.',
     connect_mcp_to: 'Savienot ar ${1}',
     install_mcp_on: 'Izmantot šo MCP ${1}',
diff --git a/packages/gitbook/src/intl/translations/ms.ts b/packages/gitbook/src/intl/translations/ms.ts
index bd5fca1d7..42fba8a6c 100644
--- a/packages/gitbook/src/intl/translations/ms.ts
+++ b/packages/gitbook/src/intl/translations/ms.ts
@@ -157,6 +157,7 @@ export const ms: TranslationLanguage = {
     view_page_markdown: 'Lihat sebagai Markdown',
     view_page_plaintext: 'Lihat halaman ini sebagai teks biasa',
     open_in: 'Buka dalam ${1}',
+    open_in_ai: 'Buka dalam',
     open_in_llms_pre_prompt: 'Baca ${1} dan jawab soalan tentang kandungan.',
     connect_mcp_to: 'Sambung ke ${1}',
     install_mcp_on: 'Gunakan MCP ini dalam ${1}',
diff --git a/packages/gitbook/src/intl/translations/nl.ts b/packages/gitbook/src/intl/translations/nl.ts
index 000105a33..85fdf019a 100644
--- a/packages/gitbook/src/intl/translations/nl.ts
+++ b/packages/gitbook/src/intl/translations/nl.ts
@@ -159,6 +159,7 @@ export const nl: TranslationLanguage = {
     view_page_markdown: 'Bekijk als Markdown',
     view_page_plaintext: 'Bekijk deze pagina als platte tekst',
     open_in: 'Open in ${1}',
+    open_in_ai: 'Openen in',
     open_in_llms_pre_prompt: 'Lees ${1} en beantwoord vragen over de inhoud.',
     connect_mcp_to: 'Verbind met ${1}',
     install_mcp_on: 'Gebruik deze MCP in ${1}',
diff --git a/packages/gitbook/src/intl/translations/no.ts b/packages/gitbook/src/intl/translations/no.ts
index 2761be77c..4e0450a88 100644
--- a/packages/gitbook/src/intl/translations/no.ts
+++ b/packages/gitbook/src/intl/translations/no.ts
@@ -158,6 +158,7 @@ export const no: TranslationLanguage = {
     view_page_markdown: 'Vis som Markdown',
     view_page_plaintext: 'Vis denne siden som ren tekst',
     open_in: 'Åpne i ${1}',
+    open_in_ai: 'Åpne i',
     open_in_llms_pre_prompt: 'Les ${1} og besvar spørsmål om innholdet.',
     connect_mcp_to: 'Koble til ${1}',
     install_mcp_on: 'Bruk denne MCP i ${1}',
diff --git a/packages/gitbook/src/intl/translations/pl.ts b/packages/gitbook/src/intl/translations/pl.ts
index 0e9e262b3..cb8a7d83f 100644
--- a/packages/gitbook/src/intl/translations/pl.ts
+++ b/packages/gitbook/src/intl/translations/pl.ts
@@ -158,6 +158,7 @@ export const pl: TranslationLanguage = {
     view_page_markdown: 'Wyświetl jako Markdown',
     view_page_plaintext: 'Wyświetl tę stronę jako zwykły tekst',
     open_in: 'Otwórz w ${1}',
+    open_in_ai: 'Otwórz w',
     open_in_llms_pre_prompt: 'Przeczytaj ${1} i odpowiedz na pytania dotyczące treści.',
     connect_mcp_to: 'Połącz z ${1}',
     install_mcp_on: 'Użyj tego MCP w ${1}',
diff --git a/packages/gitbook/src/intl/translations/pt-br.ts b/packages/gitbook/src/intl/translations/pt-br.ts
index 43b3109ae..a48da4428 100644
--- a/packages/gitbook/src/intl/translations/pt-br.ts
+++ b/packages/gitbook/src/intl/translations/pt-br.ts
@@ -161,6 +161,7 @@ export const pt_br: TranslationLanguage = {
     view_page_markdown: 'Ver como Markdown',
     view_page_plaintext: 'Ver esta página em texto simples',
     open_in: 'Abrir no ${1}',
+    open_in_ai: 'Abrir em',
     open_in_llms_pre_prompt: 'Leia ${1} e responda perguntas sobre o conteúdo.',
     connect_mcp_to: 'Conectar a ${1}',
     install_mcp_on: 'Usar este MCP no ${1}',
diff --git a/packages/gitbook/src/intl/translations/pt.ts b/packages/gitbook/src/intl/translations/pt.ts
index 7fea444a5..f363d1828 100644
--- a/packages/gitbook/src/intl/translations/pt.ts
+++ b/packages/gitbook/src/intl/translations/pt.ts
@@ -159,6 +159,7 @@ export const pt: TranslationLanguage = {
     view_page_markdown: 'Ver como Markdown',
     view_page_plaintext: 'Ver esta página como texto simples',
     open_in: 'Abrir em ${1}',
+    open_in_ai: 'Abrir em',
     open_in_llms_pre_prompt: 'Leia ${1} e responda a perguntas sobre o conteúdo.',
     connect_mcp_to: 'Ligar a ${1}',
     install_mcp_on: 'Usar este MCP em ${1}',
diff --git a/packages/gitbook/src/intl/translations/ro.ts b/packages/gitbook/src/intl/translations/ro.ts
index d794ba2e2..216fa6c9b 100644
--- a/packages/gitbook/src/intl/translations/ro.ts
+++ b/packages/gitbook/src/intl/translations/ro.ts
@@ -161,6 +161,7 @@ export const ro: TranslationLanguage = {
     view_page_markdown: 'Vizualizează ca Markdown',
     view_page_plaintext: 'Vizualizează această pagină ca text simplu',
     open_in: 'Deschide în ${1}',
+    open_in_ai: 'Deschide în',
     open_in_llms_pre_prompt: 'Citește ${1} și răspunde la întrebări despre conținut.',
     connect_mcp_to: 'Conectează la ${1}',
     install_mcp_on: 'Folosește acest MCP în ${1}',
diff --git a/packages/gitbook/src/intl/translations/ru.ts b/packages/gitbook/src/intl/translations/ru.ts
index 8a75f6b4c..9d80a0139 100644
--- a/packages/gitbook/src/intl/translations/ru.ts
+++ b/packages/gitbook/src/intl/translations/ru.ts
@@ -160,6 +160,7 @@ export const ru: TranslationLanguage = {
     view_page_markdown: 'Посмотреть как Markdown',
     view_page_plaintext: 'Посмотреть как текст без форматирования',
     open_in: 'Открыть в ${1}',
+    open_in_ai: 'Открыть в',
     open_in_llms_pre_prompt: 'Прочитай ${1} и ответь на вопросы о содержимом.',
     connect_mcp_to: 'Подключиться к ${1}',
     install_mcp_on: 'Использовать этот MCP в ${1}',
diff --git a/packages/gitbook/src/intl/translations/sk.ts b/packages/gitbook/src/intl/translations/sk.ts
index 2d7a9b526..168c85d24 100644
--- a/packages/gitbook/src/intl/translations/sk.ts
+++ b/packages/gitbook/src/intl/translations/sk.ts
@@ -160,6 +160,7 @@ export const sk: TranslationLanguage = {
     view_page_markdown: 'Zobraziť ako Markdown',
     view_page_plaintext: 'Zobraziť túto stránku ako obyčajný text',
     open_in: 'Otvoriť v ${1}',
+    open_in_ai: 'Otvoriť v',
     open_in_llms_pre_prompt: 'Prečítajte si ${1} a odpovedzte na otázky o obsahu.',
     connect_mcp_to: 'Pripojiť k ${1}',
     install_mcp_on: 'Použiť tento MCP v ${1}',
diff --git a/packages/gitbook/src/intl/translations/sl.ts b/packages/gitbook/src/intl/translations/sl.ts
index 8c3816765..bccaabeff 100644
--- a/packages/gitbook/src/intl/translations/sl.ts
+++ b/packages/gitbook/src/intl/translations/sl.ts
@@ -158,6 +158,7 @@ export const sl: TranslationLanguage = {
     view_page_markdown: 'Prikaži kot Markdown',
     view_page_plaintext: 'Prikaži to stran kot navadno besedilo',
     open_in: 'Odpri v ${1}',
+    open_in_ai: 'Odpri v',
     open_in_llms_pre_prompt: 'Preberite ${1} in odgovorite na vprašanja o vsebini.',
     connect_mcp_to: 'Poveži z ${1}',
     install_mcp_on: 'Uporabi ta MCP v ${1}',
diff --git a/packages/gitbook/src/intl/translations/sv.ts b/packages/gitbook/src/intl/translations/sv.ts
index f9202eb61..d2c75b85a 100644
--- a/packages/gitbook/src/intl/translations/sv.ts
+++ b/packages/gitbook/src/intl/translations/sv.ts
@@ -158,6 +158,7 @@ export const sv: TranslationLanguage = {
     view_page_markdown: 'Visa som Markdown',
     view_page_plaintext: 'Visa den här sidan som vanlig text',
     open_in: 'Öppna i ${1}',
+    open_in_ai: 'Öppna i',
     open_in_llms_pre_prompt: 'Läs ${1} och svara på frågor om innehållet.',
     connect_mcp_to: 'Anslut till ${1}',
     install_mcp_on: 'Använd denna MCP i ${1}',
diff --git a/packages/gitbook/src/intl/translations/th.ts b/packages/gitbook/src/intl/translations/th.ts
index e22084743..85d7480b6 100644
--- a/packages/gitbook/src/intl/translations/th.ts
+++ b/packages/gitbook/src/intl/translations/th.ts
@@ -154,6 +154,7 @@ export const th: TranslationLanguage = {
     view_page_markdown: 'ดูเป็น Markdown',
     view_page_plaintext: 'ดูหน้านี้เป็นข้อความธรรมดา',
     open_in: 'เปิดใน ${1}',
+    open_in_ai: 'เปิดใน',
     open_in_llms_pre_prompt: 'อ่าน ${1} แล้วตอบคำถามเกี่ยวกับเนื้อหา',
     connect_mcp_to: 'เชื่อมต่อกับ ${1}',
     install_mcp_on: 'ใช้ MCP นี้ใน ${1}',
diff --git a/packages/gitbook/src/intl/translations/tr.ts b/packages/gitbook/src/intl/translations/tr.ts
index 186343ef0..c70c509d7 100644
--- a/packages/gitbook/src/intl/translations/tr.ts
+++ b/packages/gitbook/src/intl/translations/tr.ts
@@ -156,6 +156,7 @@ export const tr: TranslationLanguage = {
     view_page_markdown: 'Markdown olarak görüntüle',
     view_page_plaintext: 'Bu sayfayı düz metin olarak görüntüle',
     open_in: '${1} içinde aç',
+    open_in_ai: 'Şununla aç',
     open_in_llms_pre_prompt: '${1} içeriğini okuyun ve içerikle ilgili soruları yanıtlayın.',
     connect_mcp_to: '${1} ile bağlan',
     install_mcp_on: 'Bu MCPyi ${1} içinde kullan',
diff --git a/packages/gitbook/src/intl/translations/uk.ts b/packages/gitbook/src/intl/translations/uk.ts
index 1bbac50d3..8837ec1a8 100644
--- a/packages/gitbook/src/intl/translations/uk.ts
+++ b/packages/gitbook/src/intl/translations/uk.ts
@@ -156,6 +156,7 @@ export const uk: TranslationLanguage = {
     view_page_markdown: 'Переглянути як Markdown',
     view_page_plaintext: 'Переглянути цю сторінку як звичайний текст',
     open_in: 'Відкрити в ${1}',
+    open_in_ai: 'Відкрити в',
     open_in_llms_pre_prompt: 'Прочитайте ${1} і дайте відповіді на запитання про вміст.',
     connect_mcp_to: 'Підключитися до ${1}',
     install_mcp_on: 'Використати цей MCP у ${1}',
diff --git a/packages/gitbook/src/intl/translations/vi.ts b/packages/gitbook/src/intl/translations/vi.ts
index c652980c6..3c4d81025 100644
--- a/packages/gitbook/src/intl/translations/vi.ts
+++ b/packages/gitbook/src/intl/translations/vi.ts
@@ -156,6 +156,7 @@ export const vi: TranslationLanguage = {
     view_page_markdown: 'Xem dưới dạng Markdown',
     view_page_plaintext: 'Xem trang này dưới dạng văn bản thuần',
     open_in: 'Mở trong ${1}',
+    open_in_ai: 'Mở trong',
     open_in_llms_pre_prompt: 'Đọc ${1} và trả lời câu hỏi về nội dung.',
     connect_mcp_to: 'Kết nối với ${1}',
     install_mcp_on: 'Dùng MCP này trong ${1}',
diff --git a/packages/gitbook/src/intl/translations/yue.ts b/packages/gitbook/src/intl/translations/yue.ts
index b74b5e457..c3d487d01 100644
--- a/packages/gitbook/src/intl/translations/yue.ts
+++ b/packages/gitbook/src/intl/translations/yue.ts
@@ -153,6 +153,7 @@ export const yue: TranslationLanguage = {
     view_page_markdown: '以 Markdown 檢視',
     view_page_plaintext: '以純文字檢視此頁面',
     open_in: '喺 ${1} 開啟',
+    open_in_ai: '開啟方式',
     open_in_llms_pre_prompt: '閱讀 ${1}，並回答關於內容嘅問題。',
     connect_mcp_to: '連接到 ${1}',
     install_mcp_on: '喺 ${1} 使用此 MCP',
diff --git a/packages/gitbook/src/intl/translations/zh-tw.ts b/packages/gitbook/src/intl/translations/zh-tw.ts
index 6b0f97a39..dce5dbab8 100644
--- a/packages/gitbook/src/intl/translations/zh-tw.ts
+++ b/packages/gitbook/src/intl/translations/zh-tw.ts
@@ -153,6 +153,7 @@ export const zh_tw: TranslationLanguage = {
     view_page_markdown: '以 Markdown 檢視',
     view_page_plaintext: '以純文字檢視此頁面',
     open_in: '在 ${1} 中開啟',
+    open_in_ai: '開啟方式',
     open_in_llms_pre_prompt: '閱讀 ${1}，並回答關於內容的問題。',
     connect_mcp_to: '連線至 ${1}',
     install_mcp_on: '在 ${1} 使用此 MCP',
diff --git a/packages/gitbook/src/intl/translations/zh.ts b/packages/gitbook/src/intl/translations/zh.ts
index 9a69ef104..510a048a0 100644
--- a/packages/gitbook/src/intl/translations/zh.ts
+++ b/packages/gitbook/src/intl/translations/zh.ts
@@ -153,6 +153,7 @@ export const zh: TranslationLanguage = {
     view_page_markdown: '以 Markdown 查看',
     view_page_plaintext: '以纯文本查看此页面',
     open_in: '在 ${1} 中打开',
+    open_in_ai: '打开方式',
     open_in_llms_pre_prompt: '阅读 ${1} 并回答内容相关的问题。',
     connect_mcp_to: '连接到 ${1}',
     install_mcp_on: '在 ${1} 中使用此 MCP',

From 89c4a0f8081db0e89658e8feae4996ca63a324fe Mon Sep 17 00:00:00 2001
From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com>
Date: Thu, 9 Jul 2026 13:11:05 +0200
Subject: [PATCH 22/46] feat(mcp): add askQuestion tool to the site MCP server
 (#4372)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Zeno Kapitein <zeno@gitbook.io>
---
 .changeset/mcp-ask-question-tool.md           |   5 +
 bun.lock                                      |   6 +-
 package.json                                  |   2 +-
 .../[siteData]/~gitbook/mcp/handler.ts        | 106 ++++++++++++++-
 packages/gitbook/src/lib/ask.ts               | 124 ++++++++++++++++++
 packages/gitbook/src/routes/markdownAsk.ts    |  88 +------------
 6 files changed, 242 insertions(+), 89 deletions(-)
 create mode 100644 .changeset/mcp-ask-question-tool.md
 create mode 100644 packages/gitbook/src/lib/ask.ts

diff --git a/.changeset/mcp-ask-question-tool.md b/.changeset/mcp-ask-question-tool.md
new file mode 100644
index 000000000..25eedc203
--- /dev/null
+++ b/.changeset/mcp-ask-question-tool.md
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Add an `askQuestion` tool to the site MCP server. Alongside `searchDocumentation` and `getPage`, MCP clients can now ask a natural-language question and get a synthesized answer with links to the source pages, powered by the same AI search backend as the site's "ask a question" experience. The tool accepts an optional `goal` param so calling agents can attach the intent they're trying to accomplish, which tailors the answer and is tracked in analytics. The tool is only exposed on sites that have AI enabled.
diff --git a/bun.lock b/bun.lock
index 742f26e50..d03076122 100644
--- a/bun.lock
+++ b/bun.lock
@@ -7,7 +7,7 @@
       "devDependencies": {
         "@biomejs/biome": "^1.9.4",
         "@changesets/cli": "^2.31.0",
-        "turbo": "^2.9.18",
+        "turbo": "^2.10.3",
         "vercel": "50.37.3",
       },
     },
@@ -360,7 +360,7 @@
     "react-dom": "catalog:",
   },
   "catalog": {
-    "@gitbook/api": "0.186.0",
+    "@gitbook/api": "0.187.0",
     "@scalar/api-client-react": "^1.3.46",
     "@tsconfig/node20": "^20.1.6",
     "@tsconfig/strictest": "^2.0.6",
@@ -756,7 +756,7 @@
 
     "@fortawesome/fontawesome-svg-core": ["@fortawesome/fontawesome-svg-core@7.2.0", "", { "dependencies": { "@fortawesome/fontawesome-common-types": "7.2.0" } }, "sha512-6639htZMjEkwskf3J+e6/iar+4cTNM9qhoWuRfj9F3eJD6r7iCzV1SWnQr2Mdv0QT0suuqU8BoJCZUyCtP9R4Q=="],
 
-    "@gitbook/api": ["@gitbook/api@0.186.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-UAF+tVtstqyA8s9OYXoYhgHfOUQaaQBRjQX4WLEB1YxcYtJZ9YM/EM8Ouj38Tg4qW3tr76t1/OESZipCE6t8cw=="],
+    "@gitbook/api": ["@gitbook/api@0.187.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-ec2TuMm19ycPzFZXUt2D7xSNjbF3vh9Ft3zTgG4Td4UkVuNiB+zpRYmnduqzE0XsiMEwwKLEj/HWMXe+QK4Piw=="],
 
     "@gitbook/browser-types": ["@gitbook/browser-types@workspace:packages/browser-types"],
 
diff --git a/package.json b/package.json
index f90d30817..3f1872296 100644
--- a/package.json
+++ b/package.json
@@ -43,7 +43,7 @@
         "catalog": {
             "@tsconfig/strictest": "^2.0.6",
             "@tsconfig/node20": "^20.1.6",
-            "@gitbook/api": "0.186.0",
+            "@gitbook/api": "0.187.0",
             "@scalar/api-client-react": "^1.3.46",
             "@types/react": "^19.0.0",
             "@types/react-dom": "^19.0.0",
diff --git a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
index 5b496a838..17c76df0b 100644
--- a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
+++ b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
@@ -1,8 +1,10 @@
 import { CustomizationPageActionType, SiteInsightsDisplayContext } from '@gitbook/api';
 
 import { type RouteLayoutParams, getDynamicSiteContext } from '@/app/utils';
+import { isAIEnabled } from '@/components/utils/isAIChatEnabled';
+import { renderAskSourcesMarkdown, streamSiteAskAnswer } from '@/lib/ask';
 import { getExposableError, throwIfDataError } from '@/lib/data';
-import { getMarkdownForPageInSpace } from '@/lib/markdownPage';
+import { fromPageMarkdown, getMarkdownForPageInSpace, toPageMarkdown } from '@/lib/markdownPage';
 import { resolvePagePath } from '@/lib/pages';
 import { joinPathWithBaseURL } from '@/lib/paths';
 import { getBestScoredResult } from '@/lib/search';
@@ -236,6 +238,108 @@ export async function handleMcpRequest(
                     }
                 }
             );
+
+            // Only expose the answer tool when the site has AI enabled, since it relies on
+            // the same AI search backend that powers the site's "ask a question" experience.
+            if (isAIEnabled(context.customization.ai.mode)) {
+                server.tool(
+                    'askQuestion',
+                    `Ask a natural-language question about ${site.title} and get a synthesized answer, with links to the source pages. Prefer this over \`searchDocumentation\` when you want a direct answer to a question rather than a list of matching pages; use \`searchDocumentation\`/\`getPage\` when you need to browse or read full pages yourself.`,
+                    {
+                        question: z
+                            .string()
+                            .describe(
+                                `The natural-language question to answer about ${site.title}.`
+                            ),
+                        goal: z
+                            .string()
+                            .optional()
+                            .describe(
+                                'The broader end goal you are ultimately trying to accomplish (as/on behalf of the user). Used to tailor the answer to be most useful for your goal. Optional.'
+                            ),
+                    },
+                    {
+                        title: 'Ask a question',
+                        readOnlyHint: true,
+                        destructiveHint: false,
+                        idempotentHint: false,
+                        openWorldHint: true,
+                    },
+                    async ({ question, goal }) => {
+                        try {
+                            const trimmedQuestion = question.trim();
+                            if (!trimmedQuestion) {
+                                return {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: 'Please provide a question to answer.',
+                                        },
+                                    ],
+                                    isError: true,
+                                };
+                            }
+
+                            const trimmedGoal = goal?.trim() || undefined;
+
+                            const answer = await streamSiteAskAnswer(context, trimmedQuestion, {
+                                goal: trimmedGoal,
+                            });
+
+                            trackMcpEvent({
+                                organizationId: context.organizationId,
+                                siteId: site.id,
+                                events: [
+                                    {
+                                        type: 'ask_question',
+                                        query: trimmedQuestion,
+                                        ...(trimmedGoal ? { goal: trimmedGoal } : {}),
+                                        location: {
+                                            displayContext: SiteInsightsDisplayContext.Mcp,
+                                        },
+                                    },
+                                ],
+                                request,
+                            });
+
+                            if (!answer || !answer.answer || !('markdown' in answer.answer)) {
+                                return {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: "We couldn't answer this question.",
+                                        },
+                                    ],
+                                };
+                            }
+
+                            const answerMarkdown = toPageMarkdown(
+                                await fromPageMarkdown(context, {
+                                    markdown: answer.answer.markdown,
+                                    pagePath: '',
+                                })
+                            );
+                            const sourcesMarkdown = await renderAskSourcesMarkdown(
+                                context,
+                                answer.sources ?? []
+                            );
+
+                            let text = answerMarkdown.trim();
+                            if (sourcesMarkdown) {
+                                text += `\n\n# Sources\n\n${sourcesMarkdown}`;
+                            }
+
+                            return { content: [{ type: 'text', text }] };
+                        } catch (error) {
+                            const exposable = getExposableError(error);
+                            return {
+                                content: [{ type: 'text', text: exposable.message }],
+                                isError: true,
+                            };
+                        }
+                    }
+                );
+            }
         },
         {},
         {
diff --git a/packages/gitbook/src/lib/ask.ts b/packages/gitbook/src/lib/ask.ts
new file mode 100644
index 000000000..9bf840ef0
--- /dev/null
+++ b/packages/gitbook/src/lib/ask.ts
@@ -0,0 +1,124 @@
+import type { GitBookSiteContext } from '@/lib/context';
+import { throwIfDataError } from '@/lib/data';
+import { resolvePageId } from '@/lib/pages';
+import { findSiteSpaceBy, getFallbackSiteSpacePath } from '@/lib/sites';
+import { filterOutNullable } from '@/lib/typescript';
+import type { SearchAIAnswer, SearchAIAnswerSource } from '@gitbook/api';
+
+/**
+ * Options to steer a site AI answer.
+ */
+export interface StreamSiteAskOptions {
+    /**
+     * The end goal the calling agent is trying to accomplish on behalf of the user.
+     * Used by the backend to steer the answer.
+     */
+    goal?: string;
+}
+
+/**
+ * Ask a natural-language question against a site's AI search backend and return the
+ * final answer once the stream completes.
+ *
+ * This is the single entry point both the `?ask=` markdown route and the site MCP
+ * `askQuestion` tool go through, so they answer questions from the exact same backend
+ * (`streamAskInSite`) rather than reimplementing retrieval.
+ */
+export async function streamSiteAskAnswer(
+    context: GitBookSiteContext,
+    question: string,
+    options: StreamSiteAskOptions = {}
+): Promise<SearchAIAnswer | null> {
+    const apiClient = await context.dataFetcher.api();
+    const stream = apiClient.orgs.streamAskInSite(
+        context.organizationId,
+        context.site.id,
+        {
+            question,
+            context: {
+                siteSpaceId: context.siteSpace.id,
+                goal: options.goal,
+            },
+            scope: {
+                mode: 'default',
+                currentSiteSpace: context.siteSpace.id,
+            },
+        },
+        { format: 'markdown' }
+    );
+
+    let latestAnswer: SearchAIAnswer | null = null;
+
+    for await (const chunk of stream) {
+        if (chunk.type === 'answer') {
+            latestAnswer = chunk.answer;
+        }
+    }
+
+    return latestAnswer;
+}
+
+/**
+ * Render the sources of an AI answer as a markdown list of links.
+ *
+ * @param options.markdownLinks when true, page links point at the `.md` variant of each
+ * page (for the crawler-facing `?ask=` markdown route); when false they point at the
+ * regular published page URLs (for the MCP tool, so the URLs can be fed back into `getPage`).
+ */
+export async function renderAskSourcesMarkdown(
+    context: GitBookSiteContext,
+    sources: SearchAIAnswerSource[],
+    options: { markdownLinks?: boolean } = {}
+): Promise<string> {
+    const { markdownLinks = false } = options;
+
+    const items = (
+        await Promise.all(
+            sources.map(async (source) => {
+                if (source.type === 'record') {
+                    return {
+                        title: source.title,
+                        url: source.url,
+                    };
+                }
+
+                const revision =
+                    source.space === context.space.id && source.revision === context.revisionId
+                        ? context.revision
+                        : await throwIfDataError(
+                              context.dataFetcher.getRevision({
+                                  spaceId: source.space,
+                                  revisionId: source.revision,
+                              })
+                          );
+                const resolved = resolvePageId(revision.pages, source.page);
+                if (!resolved) {
+                    return null;
+                }
+
+                const found = findSiteSpaceBy(
+                    context.structure,
+                    (siteSpace) => siteSpace.space.id === source.space
+                );
+                const linker = found
+                    ? context.linker.withOtherSiteSpace({
+                          spaceBasePath: getFallbackSiteSpacePath(context, found.siteSpace),
+                      })
+                    : context.linker;
+
+                const path = linker.toPathInSpace(resolved.page.path);
+
+                return {
+                    title: resolved.page.title,
+                    url: linker.toAbsoluteURL(markdownLinks ? `${path}.md` : path),
+                };
+            })
+        )
+    ).filter(filterOutNullable);
+
+    if (items.length === 0) {
+        return '';
+    }
+
+    return items.map((item) => `- [${item.title}](${item.url})`).join('\n');
+}
diff --git a/packages/gitbook/src/routes/markdownAsk.ts b/packages/gitbook/src/routes/markdownAsk.ts
index 87508cc49..19cc25e2b 100644
--- a/packages/gitbook/src/routes/markdownAsk.ts
+++ b/packages/gitbook/src/routes/markdownAsk.ts
@@ -1,13 +1,9 @@
 import { isAIEnabled } from '@/components/utils/isAIChatEnabled';
+import { renderAskSourcesMarkdown, streamSiteAskAnswer } from '@/lib/ask';
 import type { GitBookSiteContext } from '@/lib/context';
-import { throwIfDataError } from '@/lib/data';
 import { linkerWithMarkdownPages } from '@/lib/links';
 import { fromPageMarkdown, toPageMarkdown } from '@/lib/markdownPage';
-import { resolvePageId } from '@/lib/pages';
-import { findSiteSpaceBy, getFallbackSiteSpacePath } from '@/lib/sites';
-import { filterOutNullable } from '@/lib/typescript';
 import { serveMarkdown } from '@/routes/markdownPage';
-import type { SearchAIAnswer, SearchAIAnswerSource } from '@gitbook/api';
 
 /**
  * Options to steer the AI answer served as markdown.
@@ -45,31 +41,7 @@ export async function serveAskMarkdown(
             return 'You forgot to pass a question in the `?ask=` parameter. Append a question to the URL in the `?ask=<question>` search parameter to get a complete answer and associated sources.';
         }
 
-        const apiClient = await context.dataFetcher.api();
-        const stream = apiClient.orgs.streamAskInSite(
-            context.organizationId,
-            context.site.id,
-            {
-                question,
-                context: {
-                    siteSpaceId: context.siteSpace.id,
-                    goal,
-                },
-                scope: {
-                    mode: 'default',
-                    currentSiteSpace: context.siteSpace.id,
-                },
-            },
-            { format: 'markdown' }
-        );
-
-        let latestAnswer: SearchAIAnswer | null = null;
-
-        for await (const chunk of stream) {
-            if (chunk.type === 'answer') {
-                latestAnswer = chunk.answer;
-            }
-        }
+        const latestAnswer = await streamSiteAskAnswer(context, question, { goal });
 
         if (!latestAnswer || !latestAnswer.answer || !('markdown' in latestAnswer.answer)) {
             return `We couldn't answer this question.`;
@@ -89,7 +61,8 @@ export async function serveAskMarkdown(
         );
         const sourcesMarkdown = await renderAskSourcesMarkdown(
             context,
-            latestAnswer?.sources ?? []
+            latestAnswer?.sources ?? [],
+            { markdownLinks: true }
         );
 
         let result = `# ${question}\n\n`;
@@ -121,56 +94,3 @@ export async function serveAskMarkdown(
         return result;
     });
 }
-
-async function renderAskSourcesMarkdown(
-    context: GitBookSiteContext,
-    sources: SearchAIAnswerSource[]
-) {
-    const items = (
-        await Promise.all(
-            sources.map(async (source) => {
-                if (source.type === 'record') {
-                    return {
-                        title: source.title,
-                        url: source.url,
-                    };
-                }
-
-                const revision =
-                    source.space === context.space.id && source.revision === context.revisionId
-                        ? context.revision
-                        : await throwIfDataError(
-                              context.dataFetcher.getRevision({
-                                  spaceId: source.space,
-                                  revisionId: source.revision,
-                              })
-                          );
-                const resolved = resolvePageId(revision.pages, source.page);
-                if (!resolved) {
-                    return null;
-                }
-
-                const found = findSiteSpaceBy(
-                    context.structure,
-                    (siteSpace) => siteSpace.space.id === source.space
-                );
-                const linker = found
-                    ? context.linker.withOtherSiteSpace({
-                          spaceBasePath: getFallbackSiteSpacePath(context, found.siteSpace),
-                      })
-                    : context.linker;
-
-                return {
-                    title: resolved.page.title,
-                    url: linker.toAbsoluteURL(`${linker.toPathInSpace(resolved.page.path)}.md`),
-                };
-            })
-        )
-    ).filter(filterOutNullable);
-
-    if (items.length === 0) {
-        return '';
-    }
-
-    return items.map((item) => `- [${item.title}](${item.url})`).join('\n');
-}

From 86c44299ebc1bcd5b963fe0d272e1f9045475b03 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Thu, 9 Jul 2026 14:16:26 +0200
Subject: [PATCH 23/46] docs(agents): discourage multi-line block comments
 (#4382)

Co-authored-by: Claude <noreply@anthropic.com>
---
 AGENTS.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 41e810c5b..0dd765268 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -75,3 +75,7 @@ Save as `.changeset/<name>.md`, then commit it separately with message: `changes
 ## Formatting
 
 Uses Biome (not ESLint/Prettier). Always run `bun run format` before committing.
+
+## Comments
+
+Comment to explain *why*, not *what* — the code already shows what it does. Keep comments short, ideally a single line. Avoid multi-line block comments that narrate mechanics a reader can follow from the code; they add noise and go stale. Reserve longer comments for genuinely non-obvious rationale: a subtle invariant, or a workaround and the reason it exists.

From 6cf4278f14d1e42804333e23280ab26758f96252 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Thu, 9 Jul 2026 14:32:11 +0200
Subject: [PATCH 24/46] Only show "Back to [space]" for table-of-contents
 cross-space links (#4381)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/stricter-back-to-space.md          |  5 +
 .../Header/SpacesDropdownMenuItem.tsx         | 19 +---
 .../SiteSections/SiteSectionList.tsx          |  3 +-
 .../SiteSections/SiteSectionTabs.tsx          |  2 -
 .../TableOfContents/BackToSpaceButton.tsx     |  4 +-
 .../components/TableOfContents/PagesList.tsx  |  9 +-
 .../components/hooks/useBackToSpace.test.ts   | 44 +++++----
 .../src/components/hooks/useBackToSpace.tsx   | 97 ++++++++++---------
 8 files changed, 95 insertions(+), 88 deletions(-)
 create mode 100644 .changeset/stricter-back-to-space.md

diff --git a/.changeset/stricter-back-to-space.md b/.changeset/stricter-back-to-space.md
new file mode 100644
index 000000000..41a2cefe1
--- /dev/null
+++ b/.changeset/stricter-back-to-space.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Only show the "Back to [space]" shortcut for cross-space links in the table of contents, not for in-content text links or other ways of reaching another space.
diff --git a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
index 98c134ee8..247010599 100644
--- a/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
+++ b/packages/gitbook/src/components/Header/SpacesDropdownMenuItem.tsx
@@ -1,11 +1,7 @@
 'use client';
 
 import { joinPath } from '@/lib/paths';
-import {
-    markSpaceNavigationFromPickerOnClick,
-    useCurrentPageMetadata,
-    useCurrentPagePath,
-} from '../hooks';
+import { useCurrentPageMetadata, useCurrentPagePath } from '../hooks';
 import { DropdownMenuItem } from '../primitives/DropdownMenu';
 
 export interface VariantSpace {
@@ -64,18 +60,7 @@ export function SpacesDropdownMenuItem(props: {
     const variantHref = useVariantSpaceHref(variantSpace, currentSpacePath, active);
 
     return (
-        <DropdownMenuItem
-            key={variantSpace.id}
-            href={variantHref}
-            active={active}
-            onClick={(event) => {
-                // Switching variant/translation through the picker shouldn't offer to
-                // navigate "back" to the space we're leaving.
-                if (!active) {
-                    markSpaceNavigationFromPickerOnClick(event);
-                }
-            }}
-        >
+        <DropdownMenuItem key={variantSpace.id} href={variantHref} active={active}>
             {variantSpace.title}
         </DropdownMenuItem>
     );
diff --git a/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx b/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx
index 213325f44..399525a07 100644
--- a/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx
+++ b/packages/gitbook/src/components/SiteSections/SiteSectionList.tsx
@@ -6,7 +6,7 @@ import React from 'react';
 
 import { type ClassValue, tcls } from '@/lib/tailwind';
 import { findSectionInGroup } from '@/lib/utils';
-import { markSpaceNavigationFromPickerOnClick, useToggleAnimation } from '../hooks';
+import { useToggleAnimation } from '../hooks';
 import { Link, ToggleChevron } from '../primitives';
 import { ScrollContainer } from '../primitives/ScrollContainer';
 import { SectionIcon } from './SectionIcon';
@@ -31,7 +31,6 @@ export function SiteSectionList(props: { sections: ClientSiteSections; className
         sectionsAndGroups.length > 0 && (
             <nav
                 aria-label="Sections"
-                onClickCapture={markSpaceNavigationFromPickerOnClick}
                 className={tcls(
                     '-mx-5 before:contents[] relative border-tint-subtle border-b from-transparent sidebar-filled:to-tint-subtle theme-muted:to-tint-subtle to-tint-base text-sm text-tint before:pointer-events-none before:absolute before:right-2 before:bottom-0 before:left-0 before:h-12 before:bg-linear-to-b [html.sidebar-filled.theme-bold.tint_&]:to-tint-base [html.sidebar-filled.theme-bold.tint_&]:to-tint-subtle [html.sidebar-filled.theme-muted_&]:to-tint-base',
                     className
diff --git a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
index 68990cdf9..8636c53c1 100644
--- a/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
+++ b/packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx
@@ -7,7 +7,6 @@ import React from 'react';
 import { Button, Link, ToggleChevron } from '@/components/primitives';
 import { tcls } from '@/lib/tailwind';
 import { findSectionInGroup } from '@/lib/utils';
-import { markSpaceNavigationFromPickerOnClick } from '../hooks';
 import { useIsMobile } from '../hooks/useIsMobile';
 import { CONTAINER_STYLE } from '../layout';
 import { ScrollContainer } from '../primitives/ScrollContainer';
@@ -65,7 +64,6 @@ export function SiteSectionTabs(props: {
                 className
             )}
             ref={containerRef}
-            onClickCapture={markSpaceNavigationFromPickerOnClick}
             style={
                 {
                     '--site-section-column-width': COLUMN_WIDTH,
diff --git a/packages/gitbook/src/components/TableOfContents/BackToSpaceButton.tsx b/packages/gitbook/src/components/TableOfContents/BackToSpaceButton.tsx
index 5496105b9..0b473aec9 100644
--- a/packages/gitbook/src/components/TableOfContents/BackToSpaceButton.tsx
+++ b/packages/gitbook/src/components/TableOfContents/BackToSpaceButton.tsx
@@ -25,7 +25,9 @@ export function BackToSpaceButton(props: { spaceId: string; spaceTitle: string }
     }
 
     return (
-        <div className="mb-2 px-2">
+        // Top margin so the shortcut, as the first element in the sidebar, isn't flush
+        // against the (rounded) filled-sidebar edge.
+        <div className="mt-2 mb-2 px-2">
             <Link
                 href={backToSpace.url}
                 className={tcls(
diff --git a/packages/gitbook/src/components/TableOfContents/PagesList.tsx b/packages/gitbook/src/components/TableOfContents/PagesList.tsx
index e00ee94b4..f164e2a90 100644
--- a/packages/gitbook/src/components/TableOfContents/PagesList.tsx
+++ b/packages/gitbook/src/components/TableOfContents/PagesList.tsx
@@ -5,6 +5,7 @@ import type { ClientTOCPage } from './encodeClientTableOfContents';
 import { type ClassValue, tcls } from '@/lib/tailwind';
 
 import assertNever from 'assert-never';
+import { markSpaceNavigationFromTOCLinkOnClick } from '../hooks';
 import { PageDocumentItem } from './PageDocumentItem';
 import { PageGroupItem } from './PageGroupItem';
 import { PageLinkItem } from './PageLinkItem';
@@ -17,7 +18,13 @@ export function PagesList(props: {
     const { pages, style, isRoot = false } = props;
 
     return (
-        <ul className={tcls('flex flex-col gap-y-0.5', style)}>
+        <ul
+            className={tcls('flex flex-col gap-y-0.5', style)}
+            // Flag navigations that start from a ToC link so the destination can offer a
+            // "Back to space" shortcut for cross-space links. Only needed on the root
+            // list: capture catches clicks on nested items too.
+            onClickCapture={isRoot ? markSpaceNavigationFromTOCLinkOnClick : undefined}
+        >
             {pages.map((page, idx) => {
                 switch (page.type) {
                     case 'document':
diff --git a/packages/gitbook/src/components/hooks/useBackToSpace.test.ts b/packages/gitbook/src/components/hooks/useBackToSpace.test.ts
index 79ee0e146..c03330131 100644
--- a/packages/gitbook/src/components/hooks/useBackToSpace.test.ts
+++ b/packages/gitbook/src/components/hooks/useBackToSpace.test.ts
@@ -25,22 +25,35 @@ describe('resolveBackToSpace', () => {
                 current: gettingStarted,
                 lastLocation: null,
                 storedBack: null,
-                fromPicker: false,
+                fromTocLink: false,
             })
         ).toBeNull();
     });
 
-    it('offers to go back after following a link into a different space', () => {
+    it('offers to go back after following a ToC link into a different space', () => {
         expect(
             resolveBackToSpace({
                 current: programmersGuide,
                 lastLocation: gettingStarted,
                 storedBack: null,
-                fromPicker: false,
+                fromTocLink: true,
             })
         ).toEqual(gettingStarted);
     });
 
+    it('does not offer to go back when reaching a different space without a ToC link', () => {
+        // e.g. an in-content text link, the section/variant picker, a direct URL or the
+        // browser history — none of which should surface the shortcut.
+        expect(
+            resolveBackToSpace({
+                current: programmersGuide,
+                lastLocation: gettingStarted,
+                storedBack: null,
+                fromTocLink: false,
+            })
+        ).toBeNull();
+    });
+
     it('keeps the back target while browsing within the destination space', () => {
         const deeperInGuide: SpaceLocation = {
             ...programmersGuide,
@@ -51,53 +64,42 @@ describe('resolveBackToSpace', () => {
                 current: deeperInGuide,
                 lastLocation: programmersGuide,
                 storedBack: gettingStarted,
-                fromPicker: false,
+                fromTocLink: false,
             })
         ).toEqual(gettingStarted);
     });
 
-    it('does not offer to go back when the space was changed through the picker', () => {
-        expect(
-            resolveBackToSpace({
-                current: programmersGuide,
-                lastLocation: gettingStarted,
-                storedBack: null,
-                fromPicker: true,
-            })
-        ).toBeNull();
-    });
-
     it('clears the back target once the reader returns to the space they came from', () => {
         expect(
             resolveBackToSpace({
                 current: gettingStarted,
                 lastLocation: programmersGuide,
                 storedBack: gettingStarted,
-                fromPicker: false,
+                fromTocLink: false,
             })
         ).toBeNull();
     });
 
-    it('points back to the most recent space when chaining cross-space links', () => {
-        // Was in Getting Started (stored back), followed a link from the Programmer's
+    it('points back to the most recent space when chaining cross-space ToC links', () => {
+        // Was in Getting Started (stored back), followed a ToC link from the Programmer's
         // Guide into the API Reference: back should now point to the Programmer's Guide.
         expect(
             resolveBackToSpace({
                 current: apiReference,
                 lastLocation: programmersGuide,
                 storedBack: gettingStarted,
-                fromPicker: false,
+                fromTocLink: true,
             })
         ).toEqual(programmersGuide);
     });
 
-    it('resets the back target when switching space through the picker even if one was set', () => {
+    it('clears an existing back target when reaching a new space without a ToC link', () => {
         expect(
             resolveBackToSpace({
                 current: apiReference,
                 lastLocation: programmersGuide,
                 storedBack: gettingStarted,
-                fromPicker: true,
+                fromTocLink: false,
             })
         ).toBeNull();
     });
diff --git a/packages/gitbook/src/components/hooks/useBackToSpace.tsx b/packages/gitbook/src/components/hooks/useBackToSpace.tsx
index 481deffb8..283a157be 100644
--- a/packages/gitbook/src/components/hooks/useBackToSpace.tsx
+++ b/packages/gitbook/src/components/hooks/useBackToSpace.tsx
@@ -24,23 +24,25 @@ export type SpaceLocation = {
 // Keys used to persist the navigation state for the current tab session.
 const LAST_LOCATION_KEY = 'gitbook-space-navigation:last';
 const BACK_TO_SPACE_KEY = 'gitbook-space-navigation:back';
-const FROM_PICKER_KEY = 'gitbook-space-navigation:from-picker';
+const FROM_TOC_LINK_KEY = 'gitbook-space-navigation:from-toc-link';
 
 /**
- * Mark that the navigation about to happen was initiated from the section/variant
- * picker (spaces dropdown, translations dropdown or section switcher).
+ * Mark that the navigation about to happen was initiated from a link in the table of
+ * contents.
  *
- * Such navigations are deliberate moves within the site's own structure and should
- * not surface a "Back to space" shortcut. Set synchronously when a picker link is
- * activated, so the flag is in place before the destination page reads it.
+ * Only deliberate, author-defined links in the ToC — including cross-space links — may
+ * surface a "Back to space" shortcut on the destination page. Reaching another space any
+ * other way (an in-content link, the section/variant picker, a direct URL or the browser
+ * history) must not. Set synchronously when a ToC link is activated, so the flag is in
+ * place before the destination page reads it.
  */
-function markSpaceNavigationFromPicker() {
-    setSessionStorageItem(FROM_PICKER_KEY, true);
+function markSpaceNavigationFromTOCLink() {
+    setSessionStorageItem(FROM_TOC_LINK_KEY, true);
 }
 
 /**
  * Whether a click opens its link in a new tab or window instead of navigating the
- * current tab (a modifier key or a non-primary button). These must not mark a picker
+ * current tab (a modifier key or a non-primary button). These must not mark a ToC
  * navigation: the current tab stays put, so the flag would otherwise linger and be
  * mis-attributed to a later, unrelated navigation.
  */
@@ -49,16 +51,19 @@ function opensInNewTab(event: React.MouseEvent): boolean {
 }
 
 /**
- * Click handler for the section/variant/translation pickers that marks the upcoming
- * navigation as picker-initiated, so arriving in the target space doesn't surface a
- * "Back to space" shortcut.
+ * Click handler for the table of contents that marks the upcoming navigation as
+ * ToC-initiated, so arriving in a different space can surface the "Back to space"
+ * shortcut.
  *
- * Attach it with `onClickCapture` on a picker container (section list/tabs) or as the
- * `onClick` of a picker menu item (spaces dropdown). It intentionally does nothing for
- * clicks that leave the current tab unchanged: re-selecting the already-active item,
- * or opening the link in a new tab/window.
+ * Attach it with `onClickCapture` on the root of the page list. It only flags clicks
+ * that will actually navigate to a different page, since the destination effect is what
+ * consumes the flag: a click that doesn't change the pathname would leave the flag
+ * lingering, to be mis-attributed to a later, unrelated navigation. So it does nothing
+ * for clicks that open a new tab/window, land on a nested control (e.g. the
+ * expand/collapse chevron, which toggles the tree rather than navigating), or target the
+ * current page (the active item or an in-page anchor).
  */
-export function markSpaceNavigationFromPickerOnClick(event: React.MouseEvent<HTMLElement>) {
+export function markSpaceNavigationFromTOCLinkOnClick(event: React.MouseEvent<HTMLElement>) {
     if (opensInNewTab(event)) {
         return;
     }
@@ -68,22 +73,25 @@ export function markSpaceNavigationFromPickerOnClick(event: React.MouseEvent<HTM
         return;
     }
 
+    // The expand/collapse chevron is a <button> nested inside the link; clicking it only
+    // toggles the tree (it calls preventDefault/stopPropagation), so it must not flag a
+    // navigation — and this runs in the capture phase, before that handler.
+    if (target.closest('button')) {
+        return;
+    }
+
     const link = target.closest('a[href]');
-    if (!link) {
+    if (!(link instanceof HTMLAnchorElement)) {
         return;
     }
 
-    // Skip the currently active item: re-selecting it doesn't navigate. The sidebar
-    // section list marks the active link with `aria-current`, while the header section
-    // tabs (rendered via the Button primitive) use `aria-pressed`.
-    if (
-        link.getAttribute('aria-current') === 'page' ||
-        link.getAttribute('aria-pressed') === 'true'
-    ) {
+    // Skip same-page links (the active item, or an in-page anchor): they don't change the
+    // pathname, so the effect never re-runs to consume the flag.
+    if (link.pathname === window.location.pathname) {
         return;
     }
 
-    markSpaceNavigationFromPicker();
+    markSpaceNavigationFromTOCLink();
 }
 
 /**
@@ -97,9 +105,9 @@ export function resolveBackToSpace(input: {
     current: SpaceLocation;
     lastLocation: SpaceLocation | null;
     storedBack: SpaceLocation | null;
-    fromPicker: boolean;
+    fromTocLink: boolean;
 }): SpaceLocation | null {
-    const { current, lastLocation, storedBack, fromPicker } = input;
+    const { current, lastLocation, storedBack, fromTocLink } = input;
 
     // No previous navigation this session, or we're still browsing the same space:
     // keep whatever "back" target we already had (it persists while browsing).
@@ -109,18 +117,20 @@ export function resolveBackToSpace(input: {
 
     // The reader moved to a different space since the last navigation.
 
-    // Switching space through the picker is a deliberate navigation within the
-    // site structure: reset the context instead of offering to go back.
-    if (fromPicker) {
-        return null;
-    }
-
-    // The reader returned to the space they originally came from.
+    // The reader returned to the space they originally came from: clear the shortcut.
     if (storedBack && storedBack.spaceId === current.spaceId) {
         return null;
     }
 
-    // The reader followed a link into a different space: offer to go back to the
+    // Only a deliberate cross-space link in the table of contents may surface the
+    // shortcut — that was the intent of the feature. Reaching a different space any
+    // other way (an in-content link, the section/variant picker, a direct URL or the
+    // browser history) must not introduce it, and clears any shortcut we were showing.
+    if (!fromTocLink) {
+        return null;
+    }
+
+    // The reader followed a ToC link into a different space: offer to go back to the
     // page they were on.
     return lastLocation;
 }
@@ -128,11 +138,10 @@ export function resolveBackToSpace(input: {
 /**
  * Track navigation between spaces and return the space to offer navigating back to.
  *
- * When a reader follows a link (in the ToC or in the content) into a space different
- * from the one they were browsing, we remember where they came from so a "Back to
- * [space]" shortcut can be surfaced. The shortcut persists while they browse the
- * destination space and is cleared once they return or switch space through the
- * section/variant picker.
+ * When a reader follows a cross-space link in the ToC into a space different from the
+ * one they were browsing, we remember where they came from so a "Back to [space]"
+ * shortcut can be surfaced. The shortcut persists while they browse the destination
+ * space and is cleared once they return or reach another space some other way.
  *
  * The state is kept in `sessionStorage` so it survives both client-side and full-page
  * navigations within the tab, without leaking across tabs or sessions.
@@ -154,14 +163,14 @@ export function useBackToSpace(current: {
             url: `${pathname}${window.location.search}`,
         };
 
-        const fromPicker = getSessionStorageItem<boolean>(FROM_PICKER_KEY, false);
-        removeSessionStorageItem(FROM_PICKER_KEY);
+        const fromTocLink = getSessionStorageItem<boolean>(FROM_TOC_LINK_KEY, false);
+        removeSessionStorageItem(FROM_TOC_LINK_KEY);
 
         const back = resolveBackToSpace({
             current: currentLocation,
             lastLocation: getSessionStorageItem<SpaceLocation | null>(LAST_LOCATION_KEY, null),
             storedBack: getSessionStorageItem<SpaceLocation | null>(BACK_TO_SPACE_KEY, null),
-            fromPicker,
+            fromTocLink,
         });
 
         if (back) {

From 98b2df42efcfaaea05ef4a4133bff1ea51ebaaef Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Thu, 9 Jul 2026 15:17:32 +0200
Subject: [PATCH 25/46] Add sendFeedback MCP tool for reporting documentation
 findings (#4384)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
---
 .changeset/rnd-11847-mcp-send-feedback.md     |   5 +
 .../[siteData]/~gitbook/mcp/handler.ts        | 126 +++++++++++++++++-
 packages/gitbook/tests/mcp.test.ts            |  30 +++++
 3 files changed, 160 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/rnd-11847-mcp-send-feedback.md

diff --git a/.changeset/rnd-11847-mcp-send-feedback.md b/.changeset/rnd-11847-mcp-send-feedback.md
new file mode 100644
index 000000000..dc016291b
--- /dev/null
+++ b/.changeset/rnd-11847-mcp-send-feedback.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add a `sendFeedback` MCP tool so AI agents can report documentation findings (outdated / incoherent / gap / other) as `agent_feedback` insights events. The tool only accepts finding categories, so it never records positive feedback.
diff --git a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
index 17c76df0b..fa319c0f2 100644
--- a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
+++ b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
@@ -1,4 +1,8 @@
-import { CustomizationPageActionType, SiteInsightsDisplayContext } from '@gitbook/api';
+import {
+    CustomizationPageActionType,
+    SiteFindingType,
+    SiteInsightsDisplayContext,
+} from '@gitbook/api';
 
 import { type RouteLayoutParams, getDynamicSiteContext } from '@/app/utils';
 import { isAIEnabled } from '@/components/utils/isAIChatEnabled';
@@ -340,6 +344,126 @@ export async function handleMcpRequest(
                     }
                 );
             }
+
+            server.tool(
+                'sendFeedback',
+                `Report an issue in the documentation of ${site.title} so the team can fix it. Use it whenever, while helping a user, you come across content that is outdated, contradictory, missing information, or otherwise unhelpful. Also use it when the user themselves reports a problem with the docs, even if you could not verify it yourself. If it's your own observation, do a quick sanity check that the issue is real before reporting — no need to exhaustively re-read the page. Send one call per distinct issue and do not report the same issue twice in a conversation. Do not use this tool to confirm that a page is accurate; it is for reporting problems only.`,
+                {
+                    category: z
+                        .nativeEnum(SiteFindingType)
+                        .describe(
+                            'The kind of issue. "content-outdated": the content was correct at some point but no longer matches the current product or reality. "incoherence": the content contradicts itself or another page. "content-gap": information the reader needs is missing entirely, whether or not it was ever documented. "other": only as a last resort when none of the above fits.'
+                        ),
+                    content: z
+                        .string()
+                        .min(1)
+                        .max(2048)
+                        .describe(
+                            'Explain the issue in full, as if writing to a documentation maintainer who never saw this conversation. Describe what is wrong, where on the page it appears (quote the exact sentence or section title when possible), what the user was trying to do, and, when relevant, what the correct or expected information should be. Write a few clear, specific sentences in English. Never include personal or confidential information from the conversation. Up to 2048 characters.'
+                        ),
+                    pageUrl: z
+                        .string()
+                        .describe(
+                            `The full URL of the page the issue is about (e.g. ${siteUrl}/getting-started). Provide it whenever you can so the finding is linked to the exact page.`
+                        )
+                        .transform((value, ctx) => {
+                            const candidate = URL.canParse(value)
+                                ? new URL(value)
+                                : URL.canParse(value, siteUrl)
+                                  ? new URL(value, siteUrl)
+                                  : null;
+
+                            if (
+                                !candidate ||
+                                (candidate.protocol !== 'https:' && candidate.protocol !== 'http:')
+                            ) {
+                                ctx.addIssue({
+                                    code: z.ZodIssueCode.custom,
+                                    message: `"${value}" is not a valid URL on this site. Expected a full URL like ${siteUrl}/getting-started`,
+                                });
+                                return z.NEVER;
+                            }
+
+                            return candidate.toString();
+                        })
+                        .optional(),
+                },
+                {
+                    title: 'Send feedback',
+                    readOnlyHint: false,
+                    destructiveHint: false,
+                    idempotentHint: false,
+                    openWorldHint: true,
+                },
+                async ({ category, content, pageUrl }) => {
+                    try {
+                        let pageLocation:
+                            | { page: string; space: string; revision: string }
+                            | undefined;
+
+                        if (pageUrl) {
+                            const match = findSiteSpaceByUrl(context.structure, pageUrl);
+                            if (!match) {
+                                return {
+                                    content: [
+                                        { type: 'text', text: `Page not found: "${pageUrl}"` },
+                                    ],
+                                    isError: true,
+                                };
+                            }
+
+                            const revision = await throwIfDataError(
+                                dataFetcher.getRevision({
+                                    spaceId: match.siteSpace.space.id,
+                                    revisionId: match.siteSpace.space.revision,
+                                })
+                            );
+
+                            const resolved = resolvePagePath(revision.pages, match.pagePath ?? '');
+                            if (!resolved) {
+                                return {
+                                    content: [
+                                        { type: 'text', text: `Page not found: "${pageUrl}"` },
+                                    ],
+                                    isError: true,
+                                };
+                            }
+
+                            pageLocation = {
+                                page: resolved.page.id,
+                                space: match.siteSpace.space.id,
+                                revision: match.siteSpace.space.revision,
+                            };
+                        }
+
+                        trackMcpEvent({
+                            organizationId: context.organizationId,
+                            siteId: site.id,
+                            events: [
+                                {
+                                    type: 'agent_feedback',
+                                    feedback: { content, category },
+                                    location: {
+                                        displayContext: SiteInsightsDisplayContext.Mcp,
+                                        ...pageLocation,
+                                    },
+                                },
+                            ],
+                            request,
+                        });
+
+                        return {
+                            content: [{ type: 'text', text: 'Feedback recorded. Thank you.' }],
+                        };
+                    } catch (error) {
+                        const exposable = getExposableError(error);
+                        return {
+                            content: [{ type: 'text', text: exposable.message }],
+                            isError: true,
+                        };
+                    }
+                }
+            );
         },
         {},
         {
diff --git a/packages/gitbook/tests/mcp.test.ts b/packages/gitbook/tests/mcp.test.ts
index 395d21adb..3f6cfcfa6 100644
--- a/packages/gitbook/tests/mcp.test.ts
+++ b/packages/gitbook/tests/mcp.test.ts
@@ -50,6 +50,36 @@ it(
         const tools = await client.listTools();
         expect(tools.tools[0]?.name).toBe('searchDocumentation');
         expect(tools.tools[1]?.name).toBe('getPage');
+        expect(tools.tools.some((tool) => tool.name === 'sendFeedback')).toBe(true);
+    },
+    { timeout: 10_000 }
+);
+
+it(
+    'should record agent feedback through MCP',
+    async () => {
+        const client = new Client({
+            name: 'test',
+            version: '1.0.0',
+        });
+
+        await client.connect(
+            new StreamableHTTPClientTransport(
+                new URL(getContentTestURL('https://gitbook.com/docs/~gitbook/mcp/auth'))
+            )
+        );
+
+        const response = await client.callTool({
+            name: 'sendFeedback',
+            arguments: {
+                category: 'content-gap',
+                content: 'The authentication section does not explain how to rotate API tokens.',
+            },
+        });
+
+        expect(response.isError).toBeFalsy();
+        // @ts-expect-error - response.content is of type unknown
+        expect(response.content[0]?.text).toContain('Feedback recorded');
     },
     { timeout: 10_000 }
 );

From 49d35aa0262edb50569065f2ace62ff9cde713f7 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Thu, 9 Jul 2026 21:00:01 +0200
Subject: [PATCH 26/46] Let visitors type a follow-up while the Assistant is
 answering (RND-11789) (#4377)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .changeset/assistant-type-while-answering.md  |  5 ++
 .../gitbook/src/components/AI/useAIChat.tsx   | 47 ++++++++++++++++++-
 .../gitbook/src/components/AIChat/AIChat.tsx  | 20 +++++++-
 .../src/components/AIChat/AIChatInput.tsx     |  5 +-
 .../components/AIChat/AIChatQueuedMessage.tsx | 44 +++++++++++++++++
 .../Embeddable/EmbeddableAIChat.tsx           |  1 +
 .../src/components/primitives/Input.tsx       |  4 +-
 packages/gitbook/src/intl/translations/ar.ts  |  1 +
 packages/gitbook/src/intl/translations/bg.ts  |  1 +
 packages/gitbook/src/intl/translations/cs.ts  |  1 +
 packages/gitbook/src/intl/translations/da.ts  |  1 +
 packages/gitbook/src/intl/translations/de.ts  |  1 +
 packages/gitbook/src/intl/translations/el.ts  |  1 +
 packages/gitbook/src/intl/translations/en.ts  |  1 +
 packages/gitbook/src/intl/translations/es.ts  |  1 +
 packages/gitbook/src/intl/translations/et.ts  |  1 +
 packages/gitbook/src/intl/translations/fi.ts  |  1 +
 packages/gitbook/src/intl/translations/fr.ts  |  1 +
 packages/gitbook/src/intl/translations/he.ts  |  1 +
 packages/gitbook/src/intl/translations/hi.ts  |  1 +
 packages/gitbook/src/intl/translations/hr.ts  |  1 +
 packages/gitbook/src/intl/translations/hu.ts  |  1 +
 packages/gitbook/src/intl/translations/id.ts  |  1 +
 packages/gitbook/src/intl/translations/it.ts  |  1 +
 packages/gitbook/src/intl/translations/ja.ts  |  1 +
 packages/gitbook/src/intl/translations/ko.ts  |  1 +
 packages/gitbook/src/intl/translations/lt.ts  |  1 +
 packages/gitbook/src/intl/translations/lv.ts  |  1 +
 packages/gitbook/src/intl/translations/ms.ts  |  1 +
 packages/gitbook/src/intl/translations/nl.ts  |  1 +
 packages/gitbook/src/intl/translations/no.ts  |  1 +
 packages/gitbook/src/intl/translations/pl.ts  |  1 +
 .../gitbook/src/intl/translations/pt-br.ts    |  1 +
 packages/gitbook/src/intl/translations/pt.ts  |  1 +
 packages/gitbook/src/intl/translations/ro.ts  |  1 +
 packages/gitbook/src/intl/translations/ru.ts  |  1 +
 packages/gitbook/src/intl/translations/sk.ts  |  1 +
 packages/gitbook/src/intl/translations/sl.ts  |  1 +
 packages/gitbook/src/intl/translations/sv.ts  |  1 +
 packages/gitbook/src/intl/translations/th.ts  |  1 +
 packages/gitbook/src/intl/translations/tr.ts  |  1 +
 packages/gitbook/src/intl/translations/uk.ts  |  1 +
 packages/gitbook/src/intl/translations/vi.ts  |  1 +
 packages/gitbook/src/intl/translations/yue.ts |  1 +
 .../gitbook/src/intl/translations/zh-tw.ts    |  1 +
 packages/gitbook/src/intl/translations/zh.ts  |  1 +
 46 files changed, 158 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/assistant-type-while-answering.md
 create mode 100644 packages/gitbook/src/components/AIChat/AIChatQueuedMessage.tsx

diff --git a/.changeset/assistant-type-while-answering.md b/.changeset/assistant-type-while-answering.md
new file mode 100644
index 000000000..760d05d1b
--- /dev/null
+++ b/.changeset/assistant-type-while-answering.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Assistant: you can now send follow-up questions while an answer is still being written. Each one appears as your own message with a "Queued" badge (hover for when it will send, × to cancel), and they're sent automatically one at a time as each answer completes.
diff --git a/packages/gitbook/src/components/AI/useAIChat.tsx b/packages/gitbook/src/components/AI/useAIChat.tsx
index 44389b432..3003ebc56 100644
--- a/packages/gitbook/src/components/AI/useAIChat.tsx
+++ b/packages/gitbook/src/components/AI/useAIChat.tsx
@@ -123,6 +123,14 @@ export type AIChatState = {
      * this value (seeding its editable content) and then clears it back to an empty string.
      */
     draft: string;
+
+    /**
+     * Follow-ups the visitor submitted while a previous turn was still streaming. They are held
+     * here and sent automatically, one at a time in submission order, as each answer finishes
+     * (see the flush in `streamResponse`), so submitting mid-stream isn't lost. Empty when
+     * nothing is queued.
+     */
+    queuedMessages: string[];
 };
 
 export type AIChatEvent =
@@ -158,6 +166,8 @@ export type AIChatController = {
     focus: () => void;
     /** Pre-fill the chat input with draft text, without sending it. */
     setDraft: (draft: string) => void;
+    /** Remove a follow-up queued to send after the current answer finishes, by its queue index. */
+    cancelQueuedMessage: (index: number) => void;
     /** Register an event listener */
     on: <T extends AIChatEvent['type']>(
         event: T,
@@ -182,6 +192,7 @@ const globalState = zustand.create<AIChatState>(() => {
         initialQuery: null,
         references: [],
         draft: '',
+        queuedMessages: [],
     };
 });
 
@@ -257,6 +268,9 @@ export function AIChatProvider(props: {
         notify(eventsRef.current.get('close'), {});
     }, [setSearchState]);
 
+    // Lets `streamResponse` flush a queued follow-up via `onPostMessage`, which is defined later.
+    const postMessageRef = React.useRef<((input: { message: string }) => void) | null>(null);
+
     // Stream a message with the AI backend
     const streamResponse = React.useCallback(
         async (input: {
@@ -512,6 +526,15 @@ export function AIChatProvider(props: {
                         loading: false,
                         error: false,
                     }));
+
+                    // Turn settled: send the next queued follow-up (oldest first). Held back while a
+                    // control is pending, since posting would throw; it flushes after that resolves.
+                    const { queuedMessages, control: activeControl } = globalState.getState();
+                    const [next, ...rest] = queuedMessages;
+                    if (next !== undefined && !activeControl) {
+                        globalState.setState((state) => ({ ...state, queuedMessages: rest }));
+                        postMessageRef.current?.({ message: next });
+                    }
                 }
             } catch (error) {
                 console.error('Error streaming AI response', error);
@@ -545,8 +568,12 @@ export function AIChatProvider(props: {
                 throw new Error("We can't post a message when a control is active");
             }
 
-            // Ignore duplicates while a previous turn is still streaming
+            // Still streaming: queue this follow-up instead of dropping it (flushed in order in `streamResponse`).
             if (responding) {
+                globalState.setState((state) => ({
+                    ...state,
+                    queuedMessages: [...state.queuedMessages, input.message],
+                }));
                 return;
             }
 
@@ -607,6 +634,21 @@ export function AIChatProvider(props: {
         [setSearchState, siteSpaceId, trackEvent, streamResponse]
     );
 
+    // Keep the ref current so `streamResponse` can flush a queued follow-up via the latest callback.
+    postMessageRef.current = onPostMessage;
+
+    // Remove a follow-up queued while the assistant is still answering (the × on the affordance).
+    const onCancelQueuedMessage = React.useCallback((index: number) => {
+        globalState.setState((state) =>
+            index < 0 || index >= state.queuedMessages.length
+                ? state
+                : {
+                      ...state,
+                      queuedMessages: state.queuedMessages.filter((_, i) => i !== index),
+                  }
+        );
+    }, []);
+
     // Clear the conversation and reset ask parameter
     const onClear = React.useCallback(() => {
         globalState.setState((state) => ({
@@ -621,6 +663,7 @@ export function AIChatProvider(props: {
             error: false,
             initialQuery: null,
             references: [],
+            queuedMessages: [],
         }));
 
         // Reset ask parameter to empty string (keeps chat open but clears content)
@@ -704,6 +747,7 @@ export function AIChatProvider(props: {
             clearReferences: onClearReferences,
             focus: onFocus,
             setDraft: onSetDraft,
+            cancelQueuedMessage: onCancelQueuedMessage,
             on: onEvent,
         };
     }, [
@@ -716,6 +760,7 @@ export function AIChatProvider(props: {
         onClearReferences,
         onFocus,
         onSetDraft,
+        onCancelQueuedMessage,
         onEvent,
     ]);
 
diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
index dbc6cfa3c..3b50ba9d1 100644
--- a/packages/gitbook/src/components/AIChat/AIChat.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -35,6 +35,7 @@ import { AIChatExpandButton } from './AIChatExpandButton';
 import { AIChatIcon } from './AIChatIcon';
 import { AIChatInput } from './AIChatInput';
 import { AIChatMessages } from './AIChatMessages';
+import { AIChatQueuedMessage } from './AIChatQueuedMessage';
 import { AIChatResizeHandle } from './AIChatResizeHandle';
 import AIChatSuggestedQuestions from './AIChatSuggestedQuestions';
 
@@ -119,6 +120,7 @@ export function AIChat() {
                             chat={chat}
                             suggestions={config.suggestions}
                             trademark={config.trademark}
+                            assistantName={config.assistantName}
                         />
                     </EmbeddableFrameBody>
                 </EmbeddableFrameMain>
@@ -207,14 +209,17 @@ export function AIChatBody(props: {
     welcomeMessage?: string;
     suggestions?: string[];
     trademark?: boolean;
+    /** Custom assistant name override; falls back to the branded/unbranded default name. */
+    assistantName?: string;
     greeting?: {
         title: string;
         subtitle: string;
     };
 }) {
-    const { chatController, chat, suggestions, greeting, trademark } = props;
+    const { chatController, chat, suggestions, greeting, trademark, assistantName } = props;
 
     const language = useLanguage();
+    const resolvedAssistantName = assistantName ?? getAIChatName(language, trademark ?? true);
     const now = useNow(60 * 60 * 1000); // Refresh every hour for greeting
 
     const isEmpty = !chat.messages.length;
@@ -280,13 +285,24 @@ export function AIChatBody(props: {
             </ScrollContainer>
 
             <div className="flex max-h-3/4 min-h-0 flex-col gap-2 not-embed:px-4 pb-4">
+                {!chat.error &&
+                    chat.queuedMessages.map((message, index) => (
+                        <AIChatQueuedMessage
+                            // Queue order is stable and items carry no local state, so the index is a
+                            // safe key here.
+                            key={index}
+                            message={message}
+                            assistantName={resolvedAssistantName}
+                            onRemove={() => chatController.cancelQueuedMessage(index)}
+                        />
+                    ))}
                 {/* Display an error banner when something went wrong. */}
                 {chat.error ? <AIChatError chatController={chatController} /> : null}
 
                 {chat.control ? <AIChatControl control={chat.control} /> : null}
                 <AIChatInput
                     responding={chat.responding}
-                    disabled={chat.responding || chat.error}
+                    disabled={chat.error}
                     onSubmit={(value) => {
                         chatController.postMessage({ message: value });
                     }}
diff --git a/packages/gitbook/src/components/AIChat/AIChatInput.tsx b/packages/gitbook/src/components/AIChat/AIChatInput.tsx
index 5e52ff8f4..c2ca5f379 100644
--- a/packages/gitbook/src/components/AIChat/AIChatInput.tsx
+++ b/packages/gitbook/src/components/AIChat/AIChatInput.tsx
@@ -11,7 +11,8 @@ import { AIChatReferenceChips } from './AIChatReferenceChips';
 export function AIChatInput(props: {
     disabled?: boolean;
     /**
-     * When true, the input is disabled
+     * When true, the assistant is streaming an answer. The field stays editable and submitting a
+     * follow-up queues it (sent automatically once the answer finishes) rather than being blocked.
      */
     responding: boolean;
     onSubmit: (value: string) => void;
@@ -110,7 +111,7 @@ export function AIChatInput(props: {
                       }
                     : undefined
             }
-            disabled={disabled || responding || chat.control !== null}
+            disabled={disabled || chat.control !== null}
             aria-busy={responding}
             ref={inputRef}
             header={
diff --git a/packages/gitbook/src/components/AIChat/AIChatQueuedMessage.tsx b/packages/gitbook/src/components/AIChat/AIChatQueuedMessage.tsx
new file mode 100644
index 000000000..f4bd3cadf
--- /dev/null
+++ b/packages/gitbook/src/components/AIChat/AIChatQueuedMessage.tsx
@@ -0,0 +1,44 @@
+import { t, useLanguage } from '@/intl/client';
+import { tcls } from '@/lib/tailwind';
+import { Icon } from '@gitbook/icons';
+import { Button, Tooltip } from '../primitives';
+
+/**
+ * Shows a follow-up the visitor submitted while the assistant was still answering. It mirrors a
+ * sent user message — a right-aligned, tinted bubble — so it reads as "theirs", with a clock icon
+ * marking it as pending and a tooltip (on the whole bubble) explaining it will be sent once the
+ * current answer finishes. The × beside the bubble drops it from the queue.
+ */
+export function AIChatQueuedMessage(props: {
+    message: string;
+    assistantName: string;
+    onRemove: () => void;
+}) {
+    const { message, assistantName, onRemove } = props;
+    const language = useLanguage();
+
+    return (
+        <div className="flex max-w-[80%] origin-top-right animate-scale-in items-center gap-1 self-end">
+            <Tooltip label={t(language, 'ai_chat_queued_message', assistantName)}>
+                <div
+                    className={tcls(
+                        'flex min-w-0 items-center gap-2 circular-corners:rounded-2xl rounded-corners:rounded-md',
+                        'bg-primary-solid/1 px-4 py-2 text-tint'
+                    )}
+                >
+                    <Icon icon="clock" className="size-3.5 shrink-0 text-tint" />
+                    <span className="min-w-0 break-words">{message}</span>
+                </div>
+            </Tooltip>
+            <Button
+                variant="blank"
+                size="small"
+                iconOnly
+                icon="xmark"
+                label={t(language, 'clear')}
+                onClick={onRemove}
+                className="shrink-0 text-tint"
+            />
+        </div>
+    );
+}
diff --git a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
index 545df7321..323c8cb44 100644
--- a/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
+++ b/packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx
@@ -102,6 +102,7 @@ export function EmbeddableAIChat(props: EmbeddableAIChatProps) {
                             suggestions={siteConfig.suggestions}
                             greeting={siteConfig.greeting}
                             trademark={trademark}
+                            assistantName={siteConfig.assistantName}
                         />
                     </LinkContext>
                 </EmbeddableFrameBody>
diff --git a/packages/gitbook/src/components/primitives/Input.tsx b/packages/gitbook/src/components/primitives/Input.tsx
index 44f2c3a42..78df01b23 100644
--- a/packages/gitbook/src/components/primitives/Input.tsx
+++ b/packages/gitbook/src/components/primitives/Input.tsx
@@ -195,7 +195,8 @@ export const Input = React.forwardRef<InputElement, InputProps>((props, passedRe
     };
 
     const inputClassName = tcls(
-        'peer -m-2 max-h-64 grow shrink resize-none leading-normal text-left outline-none placeholder:text-tint/8 placeholder-shown:text-ellipsis aria-busy:cursor-progress',
+        // `aria-busy` must not change the cursor: a busy field can still be editable.
+        'peer -m-2 max-h-64 grow shrink resize-none leading-normal text-left outline-none placeholder:text-tint/8 placeholder-shown:text-ellipsis',
         sizes[sizing].input
     );
 
@@ -228,7 +229,6 @@ export const Input = React.forwardRef<InputElement, InputProps>((props, passedRe
                           'focus-within:border-primary-hover focus-within:depth-subtle:shadow-lg focus-within:shadow-primary-subtle focus-within:ring-2 hover:not-has-[button:hover]:cursor-text hover:not-has-[button:hover]:border-tint-hover hover:not-has-[button:hover]:not-focus-within:bg-tint-subtle depth-subtle:hover:not-has-[button:hover]:not-focus-within:shadow-md focus-within:hover:not-has-[button:hover]:border-primary-hover',
                       ],
                 multiline ? 'flex-col' : 'flex-row',
-                ariaBusy ? 'cursor-progress' : '',
                 sizes[sizing].container,
                 className
             )}
diff --git a/packages/gitbook/src/intl/translations/ar.ts b/packages/gitbook/src/intl/translations/ar.ts
index d6dda28ac..c1c7ee69f 100644
--- a/packages/gitbook/src/intl/translations/ar.ts
+++ b/packages/gitbook/src/intl/translations/ar.ts
@@ -133,6 +133,7 @@ export const ar: TranslationLanguage = {
     ai_chat_context_previous_messages: 'الرسائل في محادثتك',
     ai_chat_context_disclaimer: 'قد تحتوي إجابات الذكاء الاصطناعي على أخطاء.',
     ai_chat_input_placeholder: 'اسأل أو ابحث أو اشرح...',
+    ai_chat_queued_message: 'سيتم إرسال هذه الرسالة بعد أن ينتهي ${1}',
     send: 'إرسال',
     actions: 'إجراءات',
     ai_chat_suggested_questions_title: 'أسئلة مقترحة',
diff --git a/packages/gitbook/src/intl/translations/bg.ts b/packages/gitbook/src/intl/translations/bg.ts
index eec77392c..1dd4a217e 100644
--- a/packages/gitbook/src/intl/translations/bg.ts
+++ b/packages/gitbook/src/intl/translations/bg.ts
@@ -137,6 +137,7 @@ export const bg: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Съобщения във вашия разговор',
     ai_chat_context_disclaimer: 'AI отговорите може да съдържат грешки.',
     ai_chat_input_placeholder: 'Попитайте, потърсете или обяснете...',
+    ai_chat_queued_message: 'Това съобщение ще бъде изпратено, след като ${1} приключи',
     send: 'Изпращане',
     actions: 'Действия',
     ai_chat_suggested_questions_title: 'Предложени въпроси',
diff --git a/packages/gitbook/src/intl/translations/cs.ts b/packages/gitbook/src/intl/translations/cs.ts
index 00214d672..d9458828f 100644
--- a/packages/gitbook/src/intl/translations/cs.ts
+++ b/packages/gitbook/src/intl/translations/cs.ts
@@ -135,6 +135,7 @@ export const cs: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Zprávy ve vaší konverzaci',
     ai_chat_context_disclaimer: 'Odpovědi AI mohou obsahovat chyby.',
     ai_chat_input_placeholder: 'Zeptejte se, hledejte nebo vysvětlete...',
+    ai_chat_queued_message: 'Tato zpráva se odešle, až ${1} dokončí odpověď',
     send: 'Odeslat',
     actions: 'Akce',
     ai_chat_suggested_questions_title: 'Navrhované otázky',
diff --git a/packages/gitbook/src/intl/translations/da.ts b/packages/gitbook/src/intl/translations/da.ts
index 65b030db0..620df8131 100644
--- a/packages/gitbook/src/intl/translations/da.ts
+++ b/packages/gitbook/src/intl/translations/da.ts
@@ -134,6 +134,7 @@ export const da: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Beskeder i din samtale',
     ai_chat_context_disclaimer: 'AI-svar kan indeholde fejl.',
     ai_chat_input_placeholder: 'Spørg, søg eller forklar...',
+    ai_chat_queued_message: 'Denne besked sendes, når ${1} er færdig',
     send: 'Send',
     actions: 'Handlinger',
     ai_chat_suggested_questions_title: 'Foreslåede spørgsmål',
diff --git a/packages/gitbook/src/intl/translations/de.ts b/packages/gitbook/src/intl/translations/de.ts
index 979ba3900..1ac38872d 100644
--- a/packages/gitbook/src/intl/translations/de.ts
+++ b/packages/gitbook/src/intl/translations/de.ts
@@ -141,6 +141,7 @@ export const de: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Nachrichten in Ihrem Gespräch',
     ai_chat_context_disclaimer: 'KI-Antworten können Fehler enthalten.',
     ai_chat_input_placeholder: 'Fragen, suchen oder erklären...',
+    ai_chat_queued_message: 'Diese Nachricht wird gesendet, sobald ${1} fertig ist',
     send: 'Senden',
     actions: 'Aktionen',
     ai_chat_suggested_questions_title: 'Vorgeschlagene Fragen',
diff --git a/packages/gitbook/src/intl/translations/el.ts b/packages/gitbook/src/intl/translations/el.ts
index 1950cefaa..006f705e4 100644
--- a/packages/gitbook/src/intl/translations/el.ts
+++ b/packages/gitbook/src/intl/translations/el.ts
@@ -139,6 +139,7 @@ export const el: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Μηνύματα στη συνομιλία σας',
     ai_chat_context_disclaimer: 'Οι απαντήσεις AI μπορεί να περιέχουν λάθη.',
     ai_chat_input_placeholder: 'Ρωτήστε, αναζητήστε ή εξηγήστε...',
+    ai_chat_queued_message: 'Αυτό το μήνυμα θα σταλεί μόλις ολοκληρώσει ${1}',
     send: 'Αποστολή',
     actions: 'Ενέργειες',
     ai_chat_suggested_questions_title: 'Προτεινόμενες ερωτήσεις',
diff --git a/packages/gitbook/src/intl/translations/en.ts b/packages/gitbook/src/intl/translations/en.ts
index 3ea3a77e7..2df98862c 100644
--- a/packages/gitbook/src/intl/translations/en.ts
+++ b/packages/gitbook/src/intl/translations/en.ts
@@ -132,6 +132,7 @@ export const en = {
     ai_chat_context_previous_messages: 'Messages in your conversation',
     ai_chat_context_disclaimer: 'AI responses may contain mistakes.',
     ai_chat_input_placeholder: 'Ask, search, or explain...',
+    ai_chat_queued_message: 'This message will be sent after ${1} finishes',
     send: 'Send',
     actions: 'Actions',
     ai_chat_suggested_questions_title: 'Suggested questions',
diff --git a/packages/gitbook/src/intl/translations/es.ts b/packages/gitbook/src/intl/translations/es.ts
index 6cdc4e78a..b4223a857 100644
--- a/packages/gitbook/src/intl/translations/es.ts
+++ b/packages/gitbook/src/intl/translations/es.ts
@@ -139,6 +139,7 @@ export const es: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Mensajes de tu conversación',
     ai_chat_context_disclaimer: 'Las respuestas de IA pueden contener errores.',
     ai_chat_input_placeholder: 'Pregunta, busca o explica...',
+    ai_chat_queued_message: 'Este mensaje se enviará cuando ${1} termine',
     send: 'Enviar',
     actions: 'Acciones',
     ai_chat_suggested_questions_title: 'Preguntas sugeridas',
diff --git a/packages/gitbook/src/intl/translations/et.ts b/packages/gitbook/src/intl/translations/et.ts
index 67f103978..07020d3e0 100644
--- a/packages/gitbook/src/intl/translations/et.ts
+++ b/packages/gitbook/src/intl/translations/et.ts
@@ -134,6 +134,7 @@ export const et: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Teie vestluse sõnumid',
     ai_chat_context_disclaimer: 'AI vastused võivad sisaldada vigu.',
     ai_chat_input_placeholder: 'Küsige, otsige või selgitage...',
+    ai_chat_queued_message: 'See sõnum saadetakse, kui ${1} on lõpetanud',
     send: 'Saada',
     actions: 'Toimingud',
     ai_chat_suggested_questions_title: 'Soovitatud küsimused',
diff --git a/packages/gitbook/src/intl/translations/fi.ts b/packages/gitbook/src/intl/translations/fi.ts
index c9df29b99..b42c0fa2a 100644
--- a/packages/gitbook/src/intl/translations/fi.ts
+++ b/packages/gitbook/src/intl/translations/fi.ts
@@ -136,6 +136,7 @@ export const fi: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Viestit keskustelussasi',
     ai_chat_context_disclaimer: 'AI-vastaukset voivat sisältää virheitä.',
     ai_chat_input_placeholder: 'Kysy, hae tai selitä...',
+    ai_chat_queued_message: 'Tämä viesti lähetetään, kun ${1} on valmis',
     send: 'Lähetä',
     actions: 'Toiminnot',
     ai_chat_suggested_questions_title: 'Ehdotetut kysymykset',
diff --git a/packages/gitbook/src/intl/translations/fr.ts b/packages/gitbook/src/intl/translations/fr.ts
index 8e6c93559..497afb335 100644
--- a/packages/gitbook/src/intl/translations/fr.ts
+++ b/packages/gitbook/src/intl/translations/fr.ts
@@ -135,6 +135,7 @@ export const fr: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Messages de votre conversation',
     ai_chat_context_disclaimer: 'Les réponses générées peuvent contenir des erreurs.',
     ai_chat_input_placeholder: 'Demander, rechercher ou expliquer...',
+    ai_chat_queued_message: 'Ce message sera envoyé une fois que ${1} aura terminé',
     send: 'Envoyer',
     actions: 'Actions',
     ai_chat_suggested_questions_title: 'Suggestions de questions',
diff --git a/packages/gitbook/src/intl/translations/he.ts b/packages/gitbook/src/intl/translations/he.ts
index fd1bb8fb9..1b0e73c0e 100644
--- a/packages/gitbook/src/intl/translations/he.ts
+++ b/packages/gitbook/src/intl/translations/he.ts
@@ -132,6 +132,7 @@ export const he: TranslationLanguage = {
     ai_chat_context_previous_messages: 'הודעות בשיחה שלך',
     ai_chat_context_disclaimer: 'תשובות AI עשויות להכיל טעויות.',
     ai_chat_input_placeholder: 'שאל, חפש או הסבר...',
+    ai_chat_queued_message: 'הודעה זו תישלח לאחר ש-${1} יסיים',
     send: 'שליחה',
     actions: 'פעולות',
     ai_chat_suggested_questions_title: 'שאלות מוצעות',
diff --git a/packages/gitbook/src/intl/translations/hi.ts b/packages/gitbook/src/intl/translations/hi.ts
index 71e0ba453..6b6b139ae 100644
--- a/packages/gitbook/src/intl/translations/hi.ts
+++ b/packages/gitbook/src/intl/translations/hi.ts
@@ -133,6 +133,7 @@ export const hi: TranslationLanguage = {
     ai_chat_context_previous_messages: 'आपकी बातचीत के संदेश',
     ai_chat_context_disclaimer: 'AI उत्तरों में गलतियां हो सकती हैं।',
     ai_chat_input_placeholder: 'पूछें, खोजें या समझाएं...',
+    ai_chat_queued_message: 'यह संदेश ${1} के समाप्त होने के बाद भेजा जाएगा',
     send: 'भेजें',
     actions: 'कार्रवाइयां',
     ai_chat_suggested_questions_title: 'सुझाए गए प्रश्न',
diff --git a/packages/gitbook/src/intl/translations/hr.ts b/packages/gitbook/src/intl/translations/hr.ts
index f08f00f69..3165a2573 100644
--- a/packages/gitbook/src/intl/translations/hr.ts
+++ b/packages/gitbook/src/intl/translations/hr.ts
@@ -135,6 +135,7 @@ export const hr: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Poruke u vašem razgovoru',
     ai_chat_context_disclaimer: 'AI odgovori mogu sadržavati pogreške.',
     ai_chat_input_placeholder: 'Pitajte, pretražite ili objasnite...',
+    ai_chat_queued_message: 'Ova poruka bit će poslana kada ${1} završi',
     send: 'Pošalji',
     actions: 'Radnje',
     ai_chat_suggested_questions_title: 'Predložena pitanja',
diff --git a/packages/gitbook/src/intl/translations/hu.ts b/packages/gitbook/src/intl/translations/hu.ts
index 9b28a6dd8..5207beff0 100644
--- a/packages/gitbook/src/intl/translations/hu.ts
+++ b/packages/gitbook/src/intl/translations/hu.ts
@@ -136,6 +136,7 @@ export const hu: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Üzenetek a beszélgetésében',
     ai_chat_context_disclaimer: 'Az AI-válaszok hibákat tartalmazhatnak.',
     ai_chat_input_placeholder: 'Kérdezzen, keressen vagy magyarázzon...',
+    ai_chat_queued_message: 'Ez az üzenet akkor lesz elküldve, amikor ${1} befejezi',
     send: 'Küldés',
     actions: 'Műveletek',
     ai_chat_suggested_questions_title: 'Javasolt kérdések',
diff --git a/packages/gitbook/src/intl/translations/id.ts b/packages/gitbook/src/intl/translations/id.ts
index f4027297d..e95348d96 100644
--- a/packages/gitbook/src/intl/translations/id.ts
+++ b/packages/gitbook/src/intl/translations/id.ts
@@ -134,6 +134,7 @@ export const id: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Pesan dalam percakapan Anda',
     ai_chat_context_disclaimer: 'Jawaban AI dapat berisi kesalahan.',
     ai_chat_input_placeholder: 'Tanya, cari, atau jelaskan...',
+    ai_chat_queued_message: 'Pesan ini akan dikirim setelah ${1} selesai',
     send: 'Kirim',
     actions: 'Tindakan',
     ai_chat_suggested_questions_title: 'Pertanyaan yang disarankan',
diff --git a/packages/gitbook/src/intl/translations/it.ts b/packages/gitbook/src/intl/translations/it.ts
index a05882fcd..04549821d 100644
--- a/packages/gitbook/src/intl/translations/it.ts
+++ b/packages/gitbook/src/intl/translations/it.ts
@@ -138,6 +138,7 @@ export const it: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Messaggi nella tua conversazione',
     ai_chat_context_disclaimer: "Le risposte dell'IA possono contenere errori.",
     ai_chat_input_placeholder: 'Chiedi, cerca o spiega...',
+    ai_chat_queued_message: 'Questo messaggio verrà inviato quando ${1} avrà finito',
     send: 'Invia',
     actions: 'Azioni',
     ai_chat_suggested_questions_title: 'Domande suggerite',
diff --git a/packages/gitbook/src/intl/translations/ja.ts b/packages/gitbook/src/intl/translations/ja.ts
index 2b7a1603d..ab583ca93 100644
--- a/packages/gitbook/src/intl/translations/ja.ts
+++ b/packages/gitbook/src/intl/translations/ja.ts
@@ -135,6 +135,7 @@ export const ja: TranslationLanguage = {
     ai_chat_context_previous_messages: '会話内のメッセージ',
     ai_chat_context_disclaimer: 'AIの回答には誤りが含まれる場合があります。',
     ai_chat_input_placeholder: '質問、検索、または説明...',
+    ai_chat_queued_message: '${1}の応答が完了したら、このメッセージが送信されます',
     send: '送信',
     actions: 'アクション',
     ai_chat_suggested_questions_title: 'おすすめの質問',
diff --git a/packages/gitbook/src/intl/translations/ko.ts b/packages/gitbook/src/intl/translations/ko.ts
index f99f97c21..fa1ffaadc 100644
--- a/packages/gitbook/src/intl/translations/ko.ts
+++ b/packages/gitbook/src/intl/translations/ko.ts
@@ -134,6 +134,7 @@ export const ko: TranslationLanguage = {
     ai_chat_context_previous_messages: '대화의 메시지',
     ai_chat_context_disclaimer: 'AI 응답에는 오류가 있을 수 있습니다.',
     ai_chat_input_placeholder: '질문, 검색 또는 설명...',
+    ai_chat_queued_message: '${1}의 응답이 끝나면 이 메시지가 전송됩니다',
     send: '전송',
     actions: '작업',
     ai_chat_suggested_questions_title: '추천 질문',
diff --git a/packages/gitbook/src/intl/translations/lt.ts b/packages/gitbook/src/intl/translations/lt.ts
index 911544889..35b54b593 100644
--- a/packages/gitbook/src/intl/translations/lt.ts
+++ b/packages/gitbook/src/intl/translations/lt.ts
@@ -135,6 +135,7 @@ export const lt: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Pranešimai jūsų pokalbyje',
     ai_chat_context_disclaimer: 'AI atsakymuose gali būti klaidų.',
     ai_chat_input_placeholder: 'Klauskite, ieškokite arba paaiškinkite...',
+    ai_chat_queued_message: 'Ši žinutė bus išsiųsta, kai ${1} baigs',
     send: 'Siųsti',
     actions: 'Veiksmai',
     ai_chat_suggested_questions_title: 'Siūlomi klausimai',
diff --git a/packages/gitbook/src/intl/translations/lv.ts b/packages/gitbook/src/intl/translations/lv.ts
index 8c98ebc81..58e188fa1 100644
--- a/packages/gitbook/src/intl/translations/lv.ts
+++ b/packages/gitbook/src/intl/translations/lv.ts
@@ -133,6 +133,7 @@ export const lv: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Ziņojumi jūsų sarunā',
     ai_chat_context_disclaimer: 'AI atbildēs var būt kļūdas.',
     ai_chat_input_placeholder: 'Jautājiet, meklējiet vai skaidrojiet...',
+    ai_chat_queued_message: 'Šī ziņa tiks nosūtīta, kad ${1} būs pabeidzis',
     send: 'Sūtīt',
     actions: 'Darbības',
     ai_chat_suggested_questions_title: 'Ieteiktie jautājumi',
diff --git a/packages/gitbook/src/intl/translations/ms.ts b/packages/gitbook/src/intl/translations/ms.ts
index 42fba8a6c..94f8a350f 100644
--- a/packages/gitbook/src/intl/translations/ms.ts
+++ b/packages/gitbook/src/intl/translations/ms.ts
@@ -134,6 +134,7 @@ export const ms: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Mesej dalam perbualan anda',
     ai_chat_context_disclaimer: 'Jawapan AI mungkin mengandungi kesilapan.',
     ai_chat_input_placeholder: 'Tanya, cari atau jelaskan...',
+    ai_chat_queued_message: 'Mesej ini akan dihantar setelah ${1} selesai',
     send: 'Hantar',
     actions: 'Tindakan',
     ai_chat_suggested_questions_title: 'Soalan yang dicadangkan',
diff --git a/packages/gitbook/src/intl/translations/nl.ts b/packages/gitbook/src/intl/translations/nl.ts
index 85fdf019a..9c55607e7 100644
--- a/packages/gitbook/src/intl/translations/nl.ts
+++ b/packages/gitbook/src/intl/translations/nl.ts
@@ -137,6 +137,7 @@ export const nl: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Berichten in je gesprek',
     ai_chat_context_disclaimer: 'AI-antwoorden kunnen fouten bevatten.',
     ai_chat_input_placeholder: 'Vraag, zoek of leg uit...',
+    ai_chat_queued_message: 'Dit bericht wordt verzonden zodra ${1} klaar is',
     send: 'Versturen',
     actions: 'Acties',
     ai_chat_suggested_questions_title: 'Voorgestelde vragen',
diff --git a/packages/gitbook/src/intl/translations/no.ts b/packages/gitbook/src/intl/translations/no.ts
index 4e0450a88..2b83e7864 100644
--- a/packages/gitbook/src/intl/translations/no.ts
+++ b/packages/gitbook/src/intl/translations/no.ts
@@ -136,6 +136,7 @@ export const no: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Meldinger i samtalen din',
     ai_chat_context_disclaimer: 'AI-svar kan inneholde feil.',
     ai_chat_input_placeholder: 'Spør, søk eller forklar...',
+    ai_chat_queued_message: 'Denne meldingen sendes når ${1} er ferdig',
     send: 'Send',
     actions: 'Handlinger',
     ai_chat_suggested_questions_title: 'Foreslåtte spørsmål',
diff --git a/packages/gitbook/src/intl/translations/pl.ts b/packages/gitbook/src/intl/translations/pl.ts
index cb8a7d83f..fd92e3e8a 100644
--- a/packages/gitbook/src/intl/translations/pl.ts
+++ b/packages/gitbook/src/intl/translations/pl.ts
@@ -135,6 +135,7 @@ export const pl: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Wiadomości w Twojej rozmowie',
     ai_chat_context_disclaimer: 'Odpowiedzi AI mogą zawierać błędy.',
     ai_chat_input_placeholder: 'Zapytaj, wyszukaj lub wyjaśnij...',
+    ai_chat_queued_message: 'Ta wiadomość zostanie wysłana, gdy ${1} zakończy',
     send: 'Wyślij',
     actions: 'Działania',
     ai_chat_suggested_questions_title: 'Sugerowane pytania',
diff --git a/packages/gitbook/src/intl/translations/pt-br.ts b/packages/gitbook/src/intl/translations/pt-br.ts
index a48da4428..133fa1a47 100644
--- a/packages/gitbook/src/intl/translations/pt-br.ts
+++ b/packages/gitbook/src/intl/translations/pt-br.ts
@@ -139,6 +139,7 @@ export const pt_br: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Mensagens na sua conversa',
     ai_chat_context_disclaimer: 'Respostas de IA podem conter erros.',
     ai_chat_input_placeholder: 'Pergunte, pesquise ou explique...',
+    ai_chat_queued_message: 'Esta mensagem será enviada quando ${1} terminar',
     send: 'Enviar',
     actions: 'Ações',
     ai_chat_suggested_questions_title: 'Perguntas sugeridas',
diff --git a/packages/gitbook/src/intl/translations/pt.ts b/packages/gitbook/src/intl/translations/pt.ts
index f363d1828..675ecd7d5 100644
--- a/packages/gitbook/src/intl/translations/pt.ts
+++ b/packages/gitbook/src/intl/translations/pt.ts
@@ -136,6 +136,7 @@ export const pt: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Mensagens na sua conversa',
     ai_chat_context_disclaimer: 'As respostas de IA podem conter erros.',
     ai_chat_input_placeholder: 'Pergunte, pesquise ou explique...',
+    ai_chat_queued_message: 'Esta mensagem será enviada quando ${1} terminar',
     send: 'Enviar',
     actions: 'Ações',
     ai_chat_suggested_questions_title: 'Perguntas sugeridas',
diff --git a/packages/gitbook/src/intl/translations/ro.ts b/packages/gitbook/src/intl/translations/ro.ts
index 216fa6c9b..8e9be487f 100644
--- a/packages/gitbook/src/intl/translations/ro.ts
+++ b/packages/gitbook/src/intl/translations/ro.ts
@@ -138,6 +138,7 @@ export const ro: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Mesaje din conversația ta',
     ai_chat_context_disclaimer: 'Răspunsurile AI pot conține greșeli.',
     ai_chat_input_placeholder: 'Întreabă, caută sau explică...',
+    ai_chat_queued_message: 'Acest mesaj va fi trimis după ce ${1} termină',
     send: 'Trimite',
     actions: 'Acțiuni',
     ai_chat_suggested_questions_title: 'Întrebări sugerate',
diff --git a/packages/gitbook/src/intl/translations/ru.ts b/packages/gitbook/src/intl/translations/ru.ts
index 9d80a0139..6e7010050 100644
--- a/packages/gitbook/src/intl/translations/ru.ts
+++ b/packages/gitbook/src/intl/translations/ru.ts
@@ -138,6 +138,7 @@ export const ru: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Сообщения в вашем разговоре',
     ai_chat_context_disclaimer: 'Ответы ИИ могут содержать ошибки.',
     ai_chat_input_placeholder: 'Спросите, найдите или объясните...',
+    ai_chat_queued_message: 'Это сообщение будет отправлено, когда ${1} закончит',
     send: 'Отправить',
     actions: 'Действия',
     ai_chat_suggested_questions_title: 'Предложенные вопросы',
diff --git a/packages/gitbook/src/intl/translations/sk.ts b/packages/gitbook/src/intl/translations/sk.ts
index 168c85d24..05acf053b 100644
--- a/packages/gitbook/src/intl/translations/sk.ts
+++ b/packages/gitbook/src/intl/translations/sk.ts
@@ -137,6 +137,7 @@ export const sk: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Správy vo vašej konverzácii',
     ai_chat_context_disclaimer: 'Odpovede AI môžu obsahovať chyby.',
     ai_chat_input_placeholder: 'Pýtajte sa, hľadajte alebo vysvetľujte...',
+    ai_chat_queued_message: 'Táto správa sa odošle, keď ${1} skončí',
     send: 'Odoslať',
     actions: 'Akcie',
     ai_chat_suggested_questions_title: 'Navrhované otázky',
diff --git a/packages/gitbook/src/intl/translations/sl.ts b/packages/gitbook/src/intl/translations/sl.ts
index bccaabeff..e8f7471b3 100644
--- a/packages/gitbook/src/intl/translations/sl.ts
+++ b/packages/gitbook/src/intl/translations/sl.ts
@@ -135,6 +135,7 @@ export const sl: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Sporočila v vašem pogovoru',
     ai_chat_context_disclaimer: 'Odgovori AI lahko vsebujejo napake.',
     ai_chat_input_placeholder: 'Vprašajte, iščite ali razložite...',
+    ai_chat_queued_message: 'To sporočilo bo poslano, ko ${1} zaključi',
     send: 'Pošlji',
     actions: 'Dejanja',
     ai_chat_suggested_questions_title: 'Predlagana vprašanja',
diff --git a/packages/gitbook/src/intl/translations/sv.ts b/packages/gitbook/src/intl/translations/sv.ts
index d2c75b85a..50db746ef 100644
--- a/packages/gitbook/src/intl/translations/sv.ts
+++ b/packages/gitbook/src/intl/translations/sv.ts
@@ -135,6 +135,7 @@ export const sv: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Meddelanden i din konversation',
     ai_chat_context_disclaimer: 'AI-svar kan innehålla fel.',
     ai_chat_input_placeholder: 'Fråga, sök eller förklara...',
+    ai_chat_queued_message: 'Det här meddelandet skickas när ${1} är klar',
     send: 'Skicka',
     actions: 'Åtgärder',
     ai_chat_suggested_questions_title: 'Föreslagna frågor',
diff --git a/packages/gitbook/src/intl/translations/th.ts b/packages/gitbook/src/intl/translations/th.ts
index 85d7480b6..2e6fd7766 100644
--- a/packages/gitbook/src/intl/translations/th.ts
+++ b/packages/gitbook/src/intl/translations/th.ts
@@ -131,6 +131,7 @@ export const th: TranslationLanguage = {
     ai_chat_context_previous_messages: 'ข้อความในการสนทนาของคุณ',
     ai_chat_context_disclaimer: 'คำตอบจาก AI อาจมีข้อผิดพลาด',
     ai_chat_input_placeholder: 'ถาม ค้นหา หรืออธิบาย...',
+    ai_chat_queued_message: 'ข้อความนี้จะถูกส่งหลังจากที่ ${1} เสร็จสิ้น',
     send: 'ส่ง',
     actions: 'การดำเนินการ',
     ai_chat_suggested_questions_title: 'คำถามที่แนะนำ',
diff --git a/packages/gitbook/src/intl/translations/tr.ts b/packages/gitbook/src/intl/translations/tr.ts
index c70c509d7..1bbdee843 100644
--- a/packages/gitbook/src/intl/translations/tr.ts
+++ b/packages/gitbook/src/intl/translations/tr.ts
@@ -133,6 +133,7 @@ export const tr: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Konuşmanızdaki mesajlar',
     ai_chat_context_disclaimer: 'AI yanıtları hata içerebilir.',
     ai_chat_input_placeholder: 'Sor, ara veya açıkla...',
+    ai_chat_queued_message: 'Bu mesaj, ${1} yanıtını tamamladıktan sonra gönderilecek',
     send: 'Gönder',
     actions: 'Eylemler',
     ai_chat_suggested_questions_title: 'Önerilen sorular',
diff --git a/packages/gitbook/src/intl/translations/uk.ts b/packages/gitbook/src/intl/translations/uk.ts
index 8837ec1a8..47fa90e13 100644
--- a/packages/gitbook/src/intl/translations/uk.ts
+++ b/packages/gitbook/src/intl/translations/uk.ts
@@ -133,6 +133,7 @@ export const uk: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Повідомлення у вашій розмові',
     ai_chat_context_disclaimer: 'Відповіді AI можуть містити помилки.',
     ai_chat_input_placeholder: 'Запитайте, знайдіть або поясніть...',
+    ai_chat_queued_message: 'Це повідомлення буде надіслано, коли ${1} завершить',
     send: 'Надіслати',
     actions: 'Дії',
     ai_chat_suggested_questions_title: 'Запропоновані запитання',
diff --git a/packages/gitbook/src/intl/translations/vi.ts b/packages/gitbook/src/intl/translations/vi.ts
index 3c4d81025..25743f5b8 100644
--- a/packages/gitbook/src/intl/translations/vi.ts
+++ b/packages/gitbook/src/intl/translations/vi.ts
@@ -133,6 +133,7 @@ export const vi: TranslationLanguage = {
     ai_chat_context_previous_messages: 'Tin nhắn trong cuộc trò chuyện của bạn',
     ai_chat_context_disclaimer: 'Câu trả lời AI có thể chứa lỗi.',
     ai_chat_input_placeholder: 'Hỏi, tìm kiếm hoặc giải thích...',
+    ai_chat_queued_message: 'Tin nhắn này sẽ được gửi sau khi ${1} hoàn tất',
     send: 'Gửi',
     actions: 'Hành động',
     ai_chat_suggested_questions_title: 'Câu hỏi gợi ý',
diff --git a/packages/gitbook/src/intl/translations/yue.ts b/packages/gitbook/src/intl/translations/yue.ts
index c3d487d01..f29835688 100644
--- a/packages/gitbook/src/intl/translations/yue.ts
+++ b/packages/gitbook/src/intl/translations/yue.ts
@@ -130,6 +130,7 @@ export const yue: TranslationLanguage = {
     ai_chat_context_previous_messages: '你對話入面嘅訊息',
     ai_chat_context_disclaimer: 'AI 回答可能有錯。',
     ai_chat_input_placeholder: '發問、搜尋或說明...',
+    ai_chat_queued_message: '呢個訊息會喺 ${1} 完成後發送',
     send: '傳送',
     actions: '動作',
     ai_chat_suggested_questions_title: '建議問題',
diff --git a/packages/gitbook/src/intl/translations/zh-tw.ts b/packages/gitbook/src/intl/translations/zh-tw.ts
index dce5dbab8..058a5584b 100644
--- a/packages/gitbook/src/intl/translations/zh-tw.ts
+++ b/packages/gitbook/src/intl/translations/zh-tw.ts
@@ -130,6 +130,7 @@ export const zh_tw: TranslationLanguage = {
     ai_chat_context_previous_messages: '您對話中的訊息',
     ai_chat_context_disclaimer: 'AI 回答可能包含錯誤。',
     ai_chat_input_placeholder: '提問、搜尋或說明...',
+    ai_chat_queued_message: '這則訊息將在 ${1} 完成後傳送',
     send: '傳送',
     actions: '動作',
     ai_chat_suggested_questions_title: '建議問題',
diff --git a/packages/gitbook/src/intl/translations/zh.ts b/packages/gitbook/src/intl/translations/zh.ts
index 510a048a0..497bdbb92 100644
--- a/packages/gitbook/src/intl/translations/zh.ts
+++ b/packages/gitbook/src/intl/translations/zh.ts
@@ -131,6 +131,7 @@ export const zh: TranslationLanguage = {
     ai_chat_context_previous_messages: '您对话中的消息',
     ai_chat_context_disclaimer: '人工智能的回答可能包含错误。',
     ai_chat_input_placeholder: '询问、搜索或解释...',
+    ai_chat_queued_message: '此消息将在 ${1} 完成后发送',
     send: '发送',
     actions: '操作',
     ai_chat_suggested_questions_title: '建议的问题',

From cb9275457500ac22be2502a44ce9ed107597283d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Greg=20Berg=C3=A9?= <berge.greg@gmail.com>
Date: Fri, 10 Jul 2026 11:24:33 +0200
Subject: [PATCH 27/46] Add a navigate action to integration block webframes
 (#4362)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/webframe-navigate.md               |  6 ++
 .../ContentKitWithAdaptiveVisitorContext.tsx  | 28 ------
 .../ContentKitWithClientContext.tsx           | 70 ++++++++++++++
 .../Integration/IntegrationBlock.tsx          | 94 +++++++++++++------
 .../DocumentView/Integration/adaptive.test.ts | 40 ++++++++
 .../DocumentView/Integration/adaptive.ts      | 12 +--
 .../react-contentkit/src/ElementWebframe.tsx  | 31 ++++--
 packages/react-contentkit/src/context.ts      | 11 +++
 8 files changed, 221 insertions(+), 71 deletions(-)
 create mode 100644 .changeset/webframe-navigate.md
 delete mode 100644 packages/gitbook/src/components/DocumentView/Integration/ContentKitWithAdaptiveVisitorContext.tsx
 create mode 100644 packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx
 create mode 100644 packages/gitbook/src/components/DocumentView/Integration/adaptive.test.ts

diff --git a/.changeset/webframe-navigate.md b/.changeset/webframe-navigate.md
new file mode 100644
index 000000000..52baed3b1
--- /dev/null
+++ b/.changeset/webframe-navigate.md
@@ -0,0 +1,6 @@
+---
+"@gitbook/react-contentkit": patch
+"gitbook": patch
+---
+
+Let integration block webframes navigate the reader to another page in the site by posting a `@webframe.navigate` action with a `path` (and optional `anchor`). Resolved client-side against the site base path, so navigation stays in-site and drives the standard navigation progress bar.
diff --git a/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithAdaptiveVisitorContext.tsx b/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithAdaptiveVisitorContext.tsx
deleted file mode 100644
index 3d174632d..000000000
--- a/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithAdaptiveVisitorContext.tsx
+++ /dev/null
@@ -1,28 +0,0 @@
-'use client';
-
-import { useAdaptiveVisitor } from '@/components/Adaptive';
-import { ContentKit, type ContentKitClientContextData } from '@gitbook/react-contentkit/client';
-import React from 'react';
-
-type ContentKitProps<RenderContext> = React.ComponentProps<typeof ContentKit<RenderContext>>;
-
-/**
- * ContentKit wrapper for integration blocks that need client-only adaptive context.
- */
-export function ContentKitWithAdaptiveVisitorContext<RenderContext>(
-    props: ContentKitProps<RenderContext>
-) {
-    const getAdaptiveVisitorClaims = useAdaptiveVisitor();
-    const visitorClaims = getAdaptiveVisitorClaims();
-
-    const clientContext = React.useMemo<ContentKitClientContextData>(
-        () => ({
-            getVisitorContext: () => ({
-                visitor: visitorClaims?.visitor ?? null,
-            }),
-        }),
-        [visitorClaims]
-    );
-
-    return <ContentKit {...props} clientContext={clientContext} />;
-}
diff --git a/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx b/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx
new file mode 100644
index 000000000..47d6104cf
--- /dev/null
+++ b/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx
@@ -0,0 +1,70 @@
+'use client';
+
+import { useAdaptiveVisitor } from '@/components/Adaptive';
+import { NavigationStatusContext } from '@/components/hooks';
+import { type GitBookLinker, createLinker } from '@/lib/links';
+import { ContentKit, type ContentKitClientContextData } from '@gitbook/react-contentkit/client';
+import { useRouter } from 'next/navigation';
+import React from 'react';
+
+type ContentKitProps<RenderContext> = React.ComponentProps<typeof ContentKit<RenderContext>>;
+
+/** Serializable inputs to rebuild the tested linker on the client (functions can't cross the RSC boundary). */
+export type WebframeLinkerData = Pick<
+    Parameters<typeof createLinker>[0],
+    'host' | 'protocol' | 'siteBasePath' | 'spaceBasePath'
+>;
+
+/**
+ * ContentKit wrapper for integration blocks that expose client-only capabilities to webframes:
+ * navigation to other pages, and adaptive visitor claims (only when the integration is allowed to
+ * access them).
+ */
+export function ContentKitWithClientContext<RenderContext>(
+    props: ContentKitProps<RenderContext> & {
+        /** Whether visitor claims may be exposed to the webframe (integration scope gated). */
+        canAccessVisitorClaims: boolean;
+        /** Data to rebuild the site linker, used to resolve webframe navigation requests. */
+        linkerData: WebframeLinkerData;
+    }
+) {
+    const { canAccessVisitorClaims, linkerData, ...contentKitProps } = props;
+
+    const router = useRouter();
+    const { onNavigationClick } = React.useContext(NavigationStatusContext);
+    const getAdaptiveVisitorClaims = useAdaptiveVisitor();
+
+    // Rebuild the (tested) linker on the client so navigation resolves paths exactly like the rest
+    // of the app, instead of duplicating the join logic here.
+    const linker = React.useMemo<GitBookLinker>(() => createLinker(linkerData), [linkerData]);
+
+    // Navigate to an in-site href, driving the same navigation progress bar as a regular link so
+    // the reader gets feedback while the destination page loads.
+    const navigateTo = React.useCallback(
+        (href: string) => {
+            onNavigationClick(href);
+            router.push(href);
+        },
+        [onNavigationClick, router]
+    );
+    // Read during render (Suspense) only when the integration is allowed visitor claims, so that
+    // webframes that don't use visitor claims don't suspend on the visitor-claims fetch.
+    const visitorClaims = canAccessVisitorClaims ? getAdaptiveVisitorClaims() : null;
+
+    const clientContext = React.useMemo<ContentKitClientContextData>(
+        () => ({
+            getVisitorContext: canAccessVisitorClaims
+                ? () => ({ visitor: visitorClaims?.visitor ?? null })
+                : undefined,
+            navigate: ({ path, anchor }) => {
+                // Resolve the requested path relative to the site root so a webframe can navigate
+                // to any section or space within the site (and nowhere outside it).
+                const suffix = anchor ? `#${anchor}` : '';
+                navigateTo(linker.toPathInSite(path) + suffix);
+            },
+        }),
+        [canAccessVisitorClaims, visitorClaims, linker, navigateTo]
+    );
+
+    return <ContentKit {...contentKitProps} clientContext={clientContext} />;
+}
diff --git a/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx b/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
index 8904145fd..1443cc2c2 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
+++ b/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
@@ -5,8 +5,12 @@ import { ContentKit, ContentKitOutput } from '@gitbook/react-contentkit';
 
 import type { BlockProps } from '../Block';
 import './contentkit.css';
-import { ContentKitWithAdaptiveVisitorContext } from './ContentKitWithAdaptiveVisitorContext';
-import { shouldRenderIntegrationBlockWithAdaptiveVisitorContext } from './adaptive';
+import type { GitBookLinker } from '@/lib/links';
+import {
+    ContentKitWithClientContext,
+    type WebframeLinkerData,
+} from './ContentKitWithClientContext';
+import { integrationBlockContainsWebframe } from './adaptive';
 import { contentKitServerContext } from './contentkit';
 import { fetchSafeIntegrationUI } from './render';
 import { renderIntegrationUi } from './server-actions';
@@ -70,34 +74,70 @@ export async function IntegrationBlock(props: BlockProps<DocumentBlockIntegratio
         return null;
     }
 
-    const ContentKitComponent = shouldRenderIntegrationBlockWithAdaptiveVisitorContext(
-        initialOutput
-    )
-        ? ContentKitWithAdaptiveVisitorContext
-        : ContentKit;
+    const containsWebframe = integrationBlockContainsWebframe(initialOutput);
+    const canAccessVisitorClaims = initialOutput.canAccessVisitorClaims === true;
+
+    // Any webframe uses the client-context wrapper: it enables navigation to other pages, plus
+    // visitor claims when the integration is allowed them.
+    const useClientContext = containsWebframe;
+
+    const contentKitProps = {
+        renderContext: {
+            integrationName: block.data.integration,
+        },
+        security: {
+            // Trust both the integrations host and the (cookieless) content host that
+            // serves rendered WebFrames. `ElementWebframe` gates inbound and outbound
+            // postMessage on this list, so a WebFrame served from the content host would
+            // break (no resize/ready/actions) if the content host weren't trusted.
+            // The hosts are identical until a distinct content origin is configured.
+            firstPartyDomains: [
+                ...new Set([GITBOOK_INTEGRATIONS_HOST, GITBOOK_INTEGRATIONS_CONTENT_HOST]),
+            ],
+        },
+        initialInput,
+        initialOutput,
+        render: renderIntegrationUi,
+    };
 
     return (
         <div className={tcls(style)}>
-            <ContentKitComponent
-                renderContext={{
-                    integrationName: block.data.integration,
-                }}
-                security={{
-                    // Trust both the integrations host and the (cookieless) content host that
-                    // serves rendered WebFrames. `ElementWebframe` gates inbound and outbound
-                    // postMessage on this list, so a WebFrame served from the content host would
-                    // break (no resize/ready/actions) if the content host weren't trusted.
-                    // The hosts are identical until a distinct content origin is configured.
-                    firstPartyDomains: [
-                        ...new Set([GITBOOK_INTEGRATIONS_HOST, GITBOOK_INTEGRATIONS_CONTENT_HOST]),
-                    ],
-                }}
-                initialInput={initialInput}
-                initialOutput={initialOutput}
-                render={renderIntegrationUi}
-            >
-                <ContentKitOutput output={initialOutput} context={contentKitServerContext} />
-            </ContentKitComponent>
+            {useClientContext ? (
+                <ContentKitWithClientContext
+                    {...contentKitProps}
+                    canAccessVisitorClaims={canAccessVisitorClaims}
+                    linkerData={getWebframeLinkerData(context.contentContext.linker)}
+                >
+                    <ContentKitOutput output={initialOutput} context={contentKitServerContext} />
+                </ContentKitWithClientContext>
+            ) : (
+                <ContentKit {...contentKitProps}>
+                    <ContentKitOutput output={initialOutput} context={contentKitServerContext} />
+                </ContentKit>
+            )}
         </div>
     );
 }
+
+/**
+ * Extract the serializable data needed to rebuild the site linker on the client, so webframe
+ * navigation resolves paths through the same (tested) linker as the rest of the app.
+ */
+function getWebframeLinkerData(linker: GitBookLinker): WebframeLinkerData {
+    const data: WebframeLinkerData = {
+        siteBasePath: linker.siteBasePath,
+        spaceBasePath: linker.spaceBasePath,
+    };
+
+    // `host`/`protocol` are only used to build absolute URLs, which webframe navigation never does.
+    // Carry them along when available so the rebuilt linker is complete (and avoids a dev warning).
+    try {
+        const url = new URL(linker.toAbsoluteURL('/'));
+        data.host = url.host;
+        data.protocol = url.protocol;
+    } catch {
+        // No usable host (e.g. tests): the linker still resolves in-site paths without it.
+    }
+
+    return data;
+}
diff --git a/packages/gitbook/src/components/DocumentView/Integration/adaptive.test.ts b/packages/gitbook/src/components/DocumentView/Integration/adaptive.test.ts
new file mode 100644
index 000000000..11dbae41f
--- /dev/null
+++ b/packages/gitbook/src/components/DocumentView/Integration/adaptive.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'bun:test';
+import type { ContentKitRenderOutput, ContentKitWebFrame } from '@gitbook/api';
+
+import { integrationBlockContainsWebframe } from './adaptive';
+
+const webframe: ContentKitWebFrame = {
+    type: 'webframe',
+    source: { url: 'https://integrations.gitbook.com/frame' },
+};
+
+function elementOutput(element: unknown): ContentKitRenderOutput {
+    return {
+        type: 'element',
+        element,
+        state: {},
+        props: {},
+    } as ContentKitRenderOutput;
+}
+
+describe('integrationBlockContainsWebframe', () => {
+    it('returns false for a completed output', () => {
+        expect(integrationBlockContainsWebframe({ type: 'complete' })).toBe(false);
+    });
+
+    it('returns false when there is no webframe in the tree', () => {
+        const output = elementOutput({
+            type: 'block',
+            children: [{ type: 'text', text: 'hello' }],
+        } as never);
+        expect(integrationBlockContainsWebframe(output)).toBe(false);
+    });
+
+    it('returns true when a webframe is nested in the tree', () => {
+        const output = elementOutput({
+            type: 'block',
+            children: [{ type: 'vstack', children: [webframe] }],
+        } as never);
+        expect(integrationBlockContainsWebframe(output)).toBe(true);
+    });
+});
diff --git a/packages/gitbook/src/components/DocumentView/Integration/adaptive.ts b/packages/gitbook/src/components/DocumentView/Integration/adaptive.ts
index 162f0f631..9adeb2686 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/adaptive.ts
+++ b/packages/gitbook/src/components/DocumentView/Integration/adaptive.ts
@@ -8,19 +8,15 @@ import type {
 type ContentKitElement = ContentKitRootElement | ContentKitDescendantElement | ContentKitStepper;
 
 /**
- * Decide whether an integration block should expose Adaptive visitor context to webframes.
+ * Whether an integration block's output contains a webframe that can consume client-only context
+ * (navigation and/or visitor claims).
  */
-export function shouldRenderIntegrationBlockWithAdaptiveVisitorContext(
-    output: ContentKitRenderOutput
-) {
+export function integrationBlockContainsWebframe(output: ContentKitRenderOutput): boolean {
     if (output.type === 'complete') {
         return false;
     }
 
-    return (
-        output.canAccessVisitorClaims === true &&
-        doesContentKitElementContainWebframe(output.element)
-    );
+    return doesContentKitElementContainWebframe(output.element);
 }
 
 /**
diff --git a/packages/react-contentkit/src/ElementWebframe.tsx b/packages/react-contentkit/src/ElementWebframe.tsx
index 26cd8f490..9ff9f58de 100644
--- a/packages/react-contentkit/src/ElementWebframe.tsx
+++ b/packages/react-contentkit/src/ElementWebframe.tsx
@@ -127,6 +127,19 @@ export function ElementWebframe(props: ContentKitClientElementProps<ContentKitWe
                             })(),
                         }));
                         break;
+                    case '@webframe.navigate':
+                        // Let the host navigate to another page. The destination is addressed by
+                        // `path`; the host resolves it within the current site and gates it.
+                        if (typeof message.action.path === 'string') {
+                            renderer.clientContext?.navigate?.({
+                                path: message.action.path,
+                                anchor:
+                                    typeof message.action.anchor === 'string'
+                                        ? message.action.anchor
+                                        : undefined,
+                            });
+                        }
+                        break;
                     default:
                         renderer.update({
                             action: message.action,
@@ -146,7 +159,7 @@ export function ElementWebframe(props: ContentKitClientElementProps<ContentKitWe
         };
     }, [renderer, sendMessage]);
 
-    // Send data and client-only visitor context as state to the webframe.
+    // Send data and client-only context (visitor claims) as state to the webframe.
     React.useEffect(() => {
         const abort = { cancelled: false };
         sendWebframeState({
@@ -218,14 +231,14 @@ function resolveWebframeState(
 }
 
 /**
- * Read optional client-only visitor context.
+ * Resolve the optional client-only contexts (visitor claims) to merge into the webframe state.
  */
-async function resolveVisitorContext(clientContext: ContentKitClientContextData | undefined) {
-    return await clientContext?.getVisitorContext?.();
+async function resolveClientContexts(clientContext: ContentKitClientContextData | undefined) {
+    return await Promise.all([clientContext?.getVisitorContext?.()]);
 }
 
 /**
- * Send the combined webframe state once visitor context has been resolved.
+ * Send the combined webframe state once client-only contexts have been resolved.
  */
 async function sendWebframeState(args: {
     elementData: ContentKitWebFrame['data'];
@@ -236,14 +249,16 @@ async function sendWebframeState(args: {
 }) {
     const { elementData, rendererState, clientContext, sendMessage, abort } = args;
     const state = resolveWebframeState(elementData, rendererState);
-    const visitorContext = await resolveVisitorContext(clientContext);
+    const clientContexts = await resolveClientContexts(clientContext);
 
     if (abort.cancelled) {
         return;
     }
 
-    if (typeof visitorContext !== 'undefined') {
-        Object.assign(state, visitorContext);
+    for (const context of clientContexts) {
+        if (context) {
+            Object.assign(state, context);
+        }
     }
 
     if (Object.keys(state).length > 0) {
diff --git a/packages/react-contentkit/src/context.ts b/packages/react-contentkit/src/context.ts
index c1dadf5dc..fcff8f10a 100644
--- a/packages/react-contentkit/src/context.ts
+++ b/packages/react-contentkit/src/context.ts
@@ -18,11 +18,22 @@ export type ContentKitRenderUpdate = Partial<
 >;
 
 export type ContentKitClientContextData = {
+    /**
+     * Client-only visitor claims, merged into the webframe state.
+     * Gated by the integration's visitor-claims scope.
+     */
     getVisitorContext?: () =>
         | Record<string, unknown>
         | null
         | undefined
         | Promise<Record<string, unknown> | null | undefined>;
+
+    /**
+     * Navigate the host page to another page, in response to a webframe `@webframe.navigate`
+     * action. The destination is addressed by `path` (resolved against the site base path); the
+     * host restricts navigation to destinations within the current site.
+     */
+    navigate?: (target: { path: string; anchor?: string }) => void;
 };
 
 export interface ContentKitClientContextType {

From a9a52fee727b72e1163dcd37efd9d6705f3153f7 Mon Sep 17 00:00:00 2001
From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com>
Date: Fri, 10 Jul 2026 13:25:26 +0200
Subject: [PATCH 28/46] RND-11356: remove redundant GBO best-section
 re-selection (#4375)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Zeno Kapitein <zeno@gitbook.io>
---
 .changeset/rnd-11356-remove-gbo-bestsection.md        |  5 +++++
 .../[siteURL]/[siteData]/~gitbook/mcp/handler.ts      |  7 ++++---
 .../[siteURL]/[siteData]/~gitbook/search/route.ts     |  6 +++---
 packages/gitbook/src/lib/search.ts                    | 11 -----------
 4 files changed, 12 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/rnd-11356-remove-gbo-bestsection.md
 delete mode 100644 packages/gitbook/src/lib/search.ts

diff --git a/.changeset/rnd-11356-remove-gbo-bestsection.md b/.changeset/rnd-11356-remove-gbo-bestsection.md
new file mode 100644
index 000000000..d0adb74b5
--- /dev/null
+++ b/.changeset/rnd-11356-remove-gbo-bestsection.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Remove GBO's redundant re-selection of the best-scoring search section. The search API now returns a single highest-scoring section per page (and orders sections highest-score-first), so GBO no longer needs its own `getBestScoredResult` helper to pick the best section for the search and MCP previews. No user-visible change.
diff --git a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
index fa319c0f2..1e98525cd 100644
--- a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
+++ b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/handler.ts
@@ -11,7 +11,6 @@ import { getExposableError, throwIfDataError } from '@/lib/data';
 import { fromPageMarkdown, getMarkdownForPageInSpace, toPageMarkdown } from '@/lib/markdownPage';
 import { resolvePagePath } from '@/lib/pages';
 import { joinPathWithBaseURL } from '@/lib/paths';
-import { getBestScoredResult } from '@/lib/search';
 import { findSiteSpaceBy, findSiteSpaceByUrl } from '@/lib/sites';
 import { trackServerInsightsEvents } from '@/lib/tracking';
 import { waitUntil } from '@/lib/waitUntil';
@@ -135,8 +134,10 @@ export async function handleMcpRequest(
                                     )
                                 );
 
-                                const body = getBestScoredResult(
-                                    (pageResult.sections ?? []).filter((section) => section.body)
+                                // The search API returns sections ordered highest-score-first, so
+                                // the first section with a body is the best-scoring preview.
+                                const body = (pageResult.sections ?? []).find(
+                                    (section) => section.body
                                 )?.body;
 
                                 return {
diff --git a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/search/route.ts b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/search/route.ts
index e55e729d7..92f36e83b 100644
--- a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/search/route.ts
+++ b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/search/route.ts
@@ -8,7 +8,6 @@ import { throwIfDataError } from '@/lib/data';
 import { toEmbeddableLinkForPublishedContent } from '@/lib/embeddable-linker';
 import { getSiteURLDataFromMiddleware } from '@/lib/middleware';
 import { joinPathWithBaseURL } from '@/lib/paths';
-import { getBestScoredResult } from '@/lib/search';
 import { getServerActionBaseContext } from '@/lib/server-actions';
 import { findSiteSpaceBy, getLocalizedTitle } from '@/lib/sites';
 import type {
@@ -187,8 +186,9 @@ function transformSitePageResult(args: {
                 };
             }) ?? [];
 
-    // Find the best-scoring section to use as a body preview on the page result.
-    const bestSection = getBestScoredResult(pageSections);
+    // The search API returns each page's sections ordered highest-score-first and caps them at one
+    // per page, so the first section is the best-scoring one to use as a body preview.
+    const bestSection = pageSections[0];
     if (bestSection) {
         page.bestSection = {
             href: bestSection.href,
diff --git a/packages/gitbook/src/lib/search.ts b/packages/gitbook/src/lib/search.ts
deleted file mode 100644
index 14acd8e24..000000000
--- a/packages/gitbook/src/lib/search.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-/**
- * Return the highest-scoring item in the list, or undefined when empty.
- */
-export function getBestScoredResult<T extends { score: number }>(
-    items: readonly T[]
-): T | undefined {
-    return items.reduce<T | undefined>(
-        (best, item) => (best === undefined || item.score > best.score ? item : best),
-        undefined
-    );
-}

From e73b182925cd17d0af43a9635fe6f7dcac7f4af5 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Fri, 10 Jul 2026 13:51:48 +0200
Subject: [PATCH 29/46] Declare embed standalone bundle as a Turbo build output
 (RND-11876) (#4386)

Co-authored-by: Claude <noreply@anthropic.com>
---
 .changeset/rnd-11876-embed-standalone-turbo-output.md | 5 +++++
 packages/embed/turbo.json                             | 8 ++++++++
 2 files changed, 13 insertions(+)
 create mode 100644 .changeset/rnd-11876-embed-standalone-turbo-output.md
 create mode 100644 packages/embed/turbo.json

diff --git a/.changeset/rnd-11876-embed-standalone-turbo-output.md b/.changeset/rnd-11876-embed-standalone-turbo-output.md
new file mode 100644
index 000000000..14f556179
--- /dev/null
+++ b/.changeset/rnd-11876-embed-standalone-turbo-output.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix the docs embed widget shipping a stale script: declare the embed package's `standalone/` bundle as a Turbo build output. Because it wasn't declared, changes confined to the standalone widget (which compiles to `standalone/` but not `dist/`) didn't invalidate the downstream `generate` cache that copies it into the app, so the deployed widget could lag the source — e.g. the `clipboard-write` permission on the widget iframe never reached production, breaking the copy button in the Assistant embed.
diff --git a/packages/embed/turbo.json b/packages/embed/turbo.json
new file mode 100644
index 000000000..91a6fd634
--- /dev/null
+++ b/packages/embed/turbo.json
@@ -0,0 +1,8 @@
+{
+    "extends": ["//"],
+    "tasks": {
+        "build": {
+            "outputs": ["dist/**", "standalone/**"]
+        }
+    }
+}

From 47ac3e2c81ff9b2a352726fde6de528a4ecfd3e7 Mon Sep 17 00:00:00 2001
From: spastorelli <spastorelli@users.noreply.github.com>
Date: Fri, 10 Jul 2026 15:24:33 +0200
Subject: [PATCH 30/46] Only advertise OAuth PRM doc for the auth MCP endpoint
 on non-VA sites (#4387)

---
 .../gitbook/src/lib/oauth-protected.test.ts   | 29 +++++++++++++++++++
 packages/gitbook/src/lib/oauth-protected.ts   | 23 ++++++++++++++-
 packages/gitbook/src/middleware.ts            |  8 +++--
 3 files changed, 56 insertions(+), 4 deletions(-)

diff --git a/packages/gitbook/src/lib/oauth-protected.test.ts b/packages/gitbook/src/lib/oauth-protected.test.ts
index c3bad7c0e..c043902a1 100644
--- a/packages/gitbook/src/lib/oauth-protected.test.ts
+++ b/packages/gitbook/src/lib/oauth-protected.test.ts
@@ -5,6 +5,7 @@ import {
     createOAuthProtectedResourceUnauthResponse,
     handleUnauthedOAuthProtectedResourceRequest,
     isOAuthProtectedResourceMetadataRequest,
+    isOAuthProtectedResourceMetadataRequestForAuthEndpoint,
     isOAuthProtectedResourceRequest,
 } from './oauth-protected';
 
@@ -250,4 +251,32 @@ describe('OAuth protected resources flow', () => {
             expect(isOAuthProtectedResourceMetadataRequest(url)).toBe(expected);
         });
     });
+
+    describe('isOAuthProtectedResourceMetadataRequestForAuthEndpoint', () => {
+        it.each([
+            {
+                scenario: 'matches metadata doc for the authenticated resource',
+                input: 'https://docs.acme.org/.well-known/oauth-protected-resource/~gitbook/mcp/auth',
+                expected: true,
+            },
+            {
+                scenario: 'does not match metadata doc for the public base resource',
+                input: 'https://docs.acme.org/.well-known/oauth-protected-resource/~gitbook/mcp',
+                expected: false,
+            },
+            {
+                scenario: 'does not match the resource itself',
+                input: 'https://docs.acme.org/~gitbook/mcp/auth',
+                expected: false,
+            },
+            {
+                scenario: 'does not match a non-protected path',
+                input: 'https://docs.acme.org/.well-known/oauth-protected-resource/~gitbook/other',
+                expected: false,
+            },
+        ])('$scenario', ({ input, expected }) => {
+            const url = new URL(input);
+            expect(isOAuthProtectedResourceMetadataRequestForAuthEndpoint(url)).toBe(expected);
+        });
+    });
 });
diff --git a/packages/gitbook/src/lib/oauth-protected.ts b/packages/gitbook/src/lib/oauth-protected.ts
index cff9519cc..148799a35 100644
--- a/packages/gitbook/src/lib/oauth-protected.ts
+++ b/packages/gitbook/src/lib/oauth-protected.ts
@@ -7,6 +7,13 @@ type OAuthProtectedResource = {
     endpoint: string;
     /** Authentication realm for this resource */
     realm?: string;
+    /**
+     * Whether this resource requires authentication regardless of visitor auth.
+     * The base `~gitbook/mcp` endpoint is only protected when the site enforces
+     * visitor auth; `~gitbook/mcp/auth` always advertises auth so clients can opt
+     * into adaptive content on non-VA sites.
+     */
+    authRequired?: boolean;
 };
 
 /**
@@ -18,7 +25,7 @@ const OAUTH_PROTECTED_RESOURCE_METADATA_PATH = '/.well-known/oauth-protected-res
  * List of OAuth protected resources.
  */
 const OAUTH_PROTECTED_RESOURCES: OAuthProtectedResource[] = [
-    { endpoint: '/~gitbook/mcp/auth', realm: 'mcp' },
+    { endpoint: '/~gitbook/mcp/auth', realm: 'mcp', authRequired: true },
     { endpoint: '/~gitbook/mcp', realm: 'mcp' },
 ];
 
@@ -138,6 +145,20 @@ export function isOAuthProtectedResourceMetadataRequest(
     return Boolean(getMatchedProtectedMetadataEndpoint(siteRequestURL));
 }
 
+/**
+ * Check if a metadata request targets a resource that requires authentication
+ * regardless of visitor auth (e.g. `~gitbook/mcp/auth`).
+ *
+ * On non-VA sites the base `~gitbook/mcp` endpoint is public, so we must not
+ * advertise a PRM document for it: clients that discover PRM proactively would
+ * otherwise start an OAuth flow against an endpoint that never issues a challenge.
+ */
+export function isOAuthProtectedResourceMetadataRequestForAuthEndpoint(
+    siteRequestURL: URL | NextRequest['nextUrl']
+) {
+    return Boolean(getMatchedProtectedMetadataEndpoint(siteRequestURL)?.authRequired);
+}
+
 /**
  * Return the matched protected endpoint entry for a metadata doc request (if any).
  */
diff --git a/packages/gitbook/src/middleware.ts b/packages/gitbook/src/middleware.ts
index 38071e2be..d5faa030d 100644
--- a/packages/gitbook/src/middleware.ts
+++ b/packages/gitbook/src/middleware.ts
@@ -27,7 +27,7 @@ import { MiddlewareHeaders } from '@/lib/middleware';
 import {
     createOAuthProtectedResourceMetadataResponse,
     handleUnauthedOAuthProtectedResourceRequest,
-    isOAuthProtectedResourceMetadataRequest,
+    isOAuthProtectedResourceMetadataRequestForAuthEndpoint,
     isOAuthProtectedResourceRequest,
 } from '@/lib/oauth-protected';
 import { removeLeadingSlash, removeTrailingSlash } from '@/lib/paths';
@@ -299,8 +299,10 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
         }
 
         // Handles OAuth protected resource metadata for non-VA adaptive content sites.
-        // If the requested URL resolved directly to a site, synthesize the metadata response immediately.
-        if (isOAuthProtectedResourceMetadataRequest(siteRequestURL)) {
+        // Only the `~gitbook/mcp/auth` endpoint advertises auth here; the base `~gitbook/mcp`
+        // endpoint stays public so clients doing proactive PRM discovery don't start an OAuth
+        // flow against an endpoint that never issues a challenge.
+        if (isOAuthProtectedResourceMetadataRequestForAuthEndpoint(siteRequestURL)) {
             return createOAuthProtectedResourceMetadataResponse({
                 siteRequestURL,
                 siteId: siteURLData.site,

From 39156ee9c346b34e28f34b8c8530abef67d3ce89 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Mon, 13 Jul 2026 20:03:52 +0200
Subject: [PATCH 31/46] Support button sizes in the button block (#4394)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/inline-button-size.md                     |  5 +++++
 bun.lock                                             |  4 ++--
 package.json                                         |  2 +-
 .../components/DocumentView/InlineActionButton.tsx   | 10 +++++++++-
 .../src/components/DocumentView/InlineButton.tsx     | 12 +++++++++++-
 5 files changed, 28 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/inline-button-size.md

diff --git a/.changeset/inline-button-size.md b/.changeset/inline-button-size.md
new file mode 100644
index 000000000..7edd4cbb0
--- /dev/null
+++ b/.changeset/inline-button-size.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Button blocks now respect the `size` option, so you can render small, medium, or large buttons.
diff --git a/bun.lock b/bun.lock
index d03076122..1b8096a86 100644
--- a/bun.lock
+++ b/bun.lock
@@ -360,7 +360,7 @@
     "react-dom": "catalog:",
   },
   "catalog": {
-    "@gitbook/api": "0.187.0",
+    "@gitbook/api": "0.188.0",
     "@scalar/api-client-react": "^1.3.46",
     "@tsconfig/node20": "^20.1.6",
     "@tsconfig/strictest": "^2.0.6",
@@ -756,7 +756,7 @@
 
     "@fortawesome/fontawesome-svg-core": ["@fortawesome/fontawesome-svg-core@7.2.0", "", { "dependencies": { "@fortawesome/fontawesome-common-types": "7.2.0" } }, "sha512-6639htZMjEkwskf3J+e6/iar+4cTNM9qhoWuRfj9F3eJD6r7iCzV1SWnQr2Mdv0QT0suuqU8BoJCZUyCtP9R4Q=="],
 
-    "@gitbook/api": ["@gitbook/api@0.187.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-ec2TuMm19ycPzFZXUt2D7xSNjbF3vh9Ft3zTgG4Td4UkVuNiB+zpRYmnduqzE0XsiMEwwKLEj/HWMXe+QK4Piw=="],
+    "@gitbook/api": ["@gitbook/api@0.188.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-kZHpDM3XJdf1oZKhxYk3OZsjNHR4ZJrF47JgUxintnEvsW1yS8UvZlq6+dxgalL1k9wGmz3XXhiNv+p7p6egsA=="],
 
     "@gitbook/browser-types": ["@gitbook/browser-types@workspace:packages/browser-types"],
 
diff --git a/package.json b/package.json
index 3f1872296..3f12d5960 100644
--- a/package.json
+++ b/package.json
@@ -43,7 +43,7 @@
         "catalog": {
             "@tsconfig/strictest": "^2.0.6",
             "@tsconfig/node20": "^20.1.6",
-            "@gitbook/api": "0.187.0",
+            "@gitbook/api": "0.188.0",
             "@scalar/api-client-react": "^1.3.46",
             "@types/react": "^19.0.0",
             "@types/react-dom": "^19.0.0",
diff --git a/packages/gitbook/src/components/DocumentView/InlineActionButton.tsx b/packages/gitbook/src/components/DocumentView/InlineActionButton.tsx
index 065f6abe1..704d2486c 100644
--- a/packages/gitbook/src/components/DocumentView/InlineActionButton.tsx
+++ b/packages/gitbook/src/components/DocumentView/InlineActionButton.tsx
@@ -4,6 +4,14 @@ import { useAI, useAIChatController, useAIChatState } from '../AI';
 import { useSetSearchState } from '../Search';
 import { Button, type ButtonProps, Input } from '../primitives';
 
+// The Input primitive has no `xsmall`; otherwise it shares the button's size scale.
+const INPUT_SIZE_MAP: Record<NonNullable<ButtonProps['size']>, 'small' | 'medium' | 'large'> = {
+    xsmall: 'small',
+    small: 'small',
+    medium: 'medium',
+    large: 'large',
+};
+
 export function InlineActionButton(
     props: { action: 'ask' | 'search'; query?: string } & { buttonProps: ButtonProps } // TODO: Type this properly: Pick<api.DocumentInlineButton, 'action' | 'query'> & { buttonProps: ButtonProps }
 ) {
@@ -42,7 +50,7 @@ export function InlineActionButton(
             <Input
                 inline
                 label={buttonProps.label as string}
-                sizing="medium"
+                sizing={INPUT_SIZE_MAP[buttonProps.size ?? 'medium']}
                 className="inline-flex max-w-full grow"
                 submitButton={{
                     label: tString(language, action === 'ask' ? 'send' : 'search'),
diff --git a/packages/gitbook/src/components/DocumentView/InlineButton.tsx b/packages/gitbook/src/components/DocumentView/InlineButton.tsx
index b8479d223..27f552f90 100644
--- a/packages/gitbook/src/components/DocumentView/InlineButton.tsx
+++ b/packages/gitbook/src/components/DocumentView/InlineButton.tsx
@@ -9,6 +9,16 @@ import type { InlineProps } from './Inline';
 import { InlineActionButton } from './InlineActionButton';
 import { NotFoundRefHoverCard } from './NotFoundRefHoverCard';
 
+// Editor button sizes render one step smaller here; the editor default (`large`) keeps the previous `medium`.
+const BUTTON_SIZE_MAP: Record<
+    NonNullable<api.DocumentInlineButton['data']['size']>,
+    ButtonProps['size']
+> = {
+    small: 'xsmall',
+    medium: 'small',
+    large: 'medium',
+};
+
 export function InlineButton(props: InlineProps<api.DocumentInlineButton>) {
     const { inline, context } = props;
 
@@ -16,7 +26,7 @@ export function InlineButton(props: InlineProps<api.DocumentInlineButton>) {
         label: inline.data.label,
         variant: inline.data.kind,
         icon: inline.data.icon as IconName | undefined,
-        size: 'medium',
+        size: BUTTON_SIZE_MAP[inline.data.size ?? 'large'],
     };
 
     const ButtonImplementation = () => {

From a69a307de2c6d90e3bae8afa13f3a773494f81e9 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Mon, 13 Jul 2026 20:37:08 +0200
Subject: [PATCH 32/46] Take a near-neutral extreme tint as the exact site
 background (#4392)

---
 .changeset/exact-light-tint-background.md     |  6 ++
 packages/colors/package.json                  |  1 +
 packages/colors/src/transformations.test.ts   | 69 +++++++++++++++++++
 packages/colors/src/transformations.ts        | 68 +++++++++++++++---
 .../RootLayout/CustomizationRootLayout.tsx    | 12 +++-
 5 files changed, 144 insertions(+), 12 deletions(-)
 create mode 100644 .changeset/exact-light-tint-background.md
 create mode 100644 packages/colors/src/transformations.test.ts

diff --git a/.changeset/exact-light-tint-background.md b/.changeset/exact-light-tint-background.md
new file mode 100644
index 000000000..1154980f2
--- /dev/null
+++ b/.changeset/exact-light-tint-background.md
@@ -0,0 +1,6 @@
+---
+"@gitbook/colors": patch
+"gitbook": patch
+---
+
+A near-white tint color (e.g. a warm `#F5F3EF`) is now taken as the exact page background, mirroring the existing behavior for near-black tints. The tint's exact lightness, hue and chroma are preserved, and the color is anchored to whichever scale step the active theme renders as the background — so it matches exactly on `muted` (which uses the second step) as well as `clean`. This applies only to near-neutral tints that are light enough to read as a background; saturated or merely light-ish colors keep their normal accent scale. The `bold` theme is unaffected: it already uses the tint for the header and stays intentionally two-tone.
diff --git a/packages/colors/package.json b/packages/colors/package.json
index d0f0b54cb..6bf6d0660 100644
--- a/packages/colors/package.json
+++ b/packages/colors/package.json
@@ -17,6 +17,7 @@
     "scripts": {
         "build": "tsdown",
         "typecheck": "tsc --noEmit",
+        "unit": "bun test",
         "dev": "bun run build -- --watch ./src",
         "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
diff --git a/packages/colors/src/transformations.test.ts b/packages/colors/src/transformations.test.ts
new file mode 100644
index 000000000..949a39f8d
--- /dev/null
+++ b/packages/colors/src/transformations.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'bun:test';
+
+import { colorScale } from './transformations';
+
+describe('colorScale exact base', () => {
+    it('takes a very light tint as the exact background on step 1 (clean/bold)', () => {
+        const scale = colorScale('#F5F3EF', { baseStep: 1 });
+        expect(scale[0]).toBe('#F5F3EF');
+    });
+
+    it('anchors a very light tint to step 2 when the theme uses the subtle step (muted)', () => {
+        const scale = colorScale('#F5F3EF', { baseStep: 2 });
+        expect(scale[1]).toBe('#F5F3EF');
+        // Step 1 sits just above the exact base, toward white.
+        expect(scale[0]).not.toBe('#F5F3EF');
+        expect(scale[0]).not.toBe('#ffffff');
+    });
+
+    it('takes a darker-than-dark tint as the exact background, preserving hue and chroma', () => {
+        const scale = colorScale('#0B0F19', { darkMode: true, baseStep: 1 });
+        expect(scale[0]).toBe('#0B0F19');
+    });
+
+    it('does not trigger for a normal mid-lightness tint', () => {
+        const scale = colorScale('#787878', { baseStep: 2 });
+        // The default white background is kept; the tint only colors the scale.
+        expect(scale[0]).toBe('#ffffff');
+        expect(scale[1]).not.toBe('#787878');
+    });
+
+    it('does not trigger for a saturated light color, keeping the normal accent ramp', () => {
+        // Light enough (L≈0.93) to pass the lightness bound, but too chromatic to read as a
+        // background — emitting it verbatim would leave a vivid step 1 above a near-gray scale.
+        const scale = colorScale('#FFEB3B', { baseStep: 1 });
+        expect(scale[0]).toBe('#ffffff');
+        expect(scale[0]).not.toBe('#FFEB3B');
+    });
+
+    it('respects a custom light background instead of overriding it with the tint', () => {
+        // The color is darker than the requested background, so it is not the extreme end and the
+        // supplied base must be preserved rather than overwritten.
+        const scale = colorScale('#eeeeee', { baseStep: 1, background: '#f8f8f8' });
+        expect(scale[0]).not.toBe('#eeeeee');
+    });
+
+    it('anchors an exact base even when a neutral mix is supplied (tint === primary)', () => {
+        // getTintMixColor blends neutral into the tint when it equals the primary color; that must
+        // not darken a near-white tint out of the exact-base path.
+        const scale = colorScale('#F5F3EF', {
+            baseStep: 1,
+            mix: { color: '#787878', ratio: 0.4 },
+        });
+        expect(scale[0]).toBe('#F5F3EF');
+    });
+
+    it('does not trigger for a light accent color below the near-white threshold', () => {
+        // #D8DEEC (light blue-gray, L≈0.90) is a UI accent, not a background, so it must not anchor.
+        const scale = colorScale('#D8DEEC', { baseStep: 1 });
+        expect(scale[0]).toBe('#ffffff');
+        expect(scale[0]).not.toBe('#D8DEEC');
+    });
+
+    it('never anchors when no baseStep is given (accent scales and the bold theme)', () => {
+        // A scale that does not define the page background opts out of the exact base entirely.
+        const scale = colorScale('#F5F3EF', {});
+        expect(scale[0]).toBe('#ffffff');
+        expect(scale[0]).not.toBe('#F5F3EF');
+    });
+});
diff --git a/packages/colors/src/transformations.ts b/packages/colors/src/transformations.ts
index d7950792c..b4da6ad05 100644
--- a/packages/colors/src/transformations.ts
+++ b/packages/colors/src/transformations.ts
@@ -82,6 +82,22 @@ export const colorMixMapping = {
     dark: [0, 0.03, 0.08, 0.1, 0.13, 0.15, 0.2, 0.25, 0.5, 0.55, 0.75, 1],
 };
 
+/**
+ * Light mode has no equivalent to the dark base bound (nothing is lighter than white), so a tint
+ * at or above this lightness is treated as an explicit, near-white background (e.g. a warm `#F5F3EF`
+ * at L≈0.96). Kept high so light UI accent colors (around L≈0.90) aren't mistaken for backgrounds.
+ */
+const EXACT_BASE_LIGHT_THRESHOLD = 0.95;
+
+/**
+ * Only a near-neutral tint reads as a background. A saturated color would keep the exact hue at the
+ * anchored step while the rest of the low scale stays ~gray, so those keep the normal accent ramp.
+ */
+const EXACT_BASE_NEUTRAL_CHROMA = 0.05;
+
+/** Lightness of the default white light background (≈0.99999, not exactly 1). */
+const LIGHT_BASE_L = rgbToOklch(hexToRgbArray(LIGHT_BASE)).L;
+
 /**
  * Convert a hex color to an RGB color.
  */
@@ -159,6 +175,14 @@ export type ColorScaleOptions = {
     /** Define a custom foreground color to use. If left undefined, the global `light`/`dark` values (in `colors.ts`) will be used. */
     foreground?: string;
 
+    /**
+     * The 1-indexed scale step this scale renders as the page background (1 = `tint-base` for
+     * `clean`, 2 = `tint-subtle` for `muted`). When set, an extreme near-neutral tint is taken as
+     * the exact background, anchored to this step so it matches exactly. Omit for scales that don't
+     * define the page background (accents, or the two-tone `bold` theme) — they never anchor.
+     */
+    baseStep?: number;
+
     mix?: {
         /** If set to a hex code, this color will be additionally mixed into the generated scale according to `mix.ratio`. */
         color: string;
@@ -179,6 +203,7 @@ export function colorScale(
         darkMode = false,
         background = darkMode ? DARK_BASE : LIGHT_BASE,
         foreground = darkMode ? LIGHT_BASE : DARK_BASE,
+        baseStep,
         mix,
     }: ColorScaleOptions = {}
 ) {
@@ -188,31 +213,51 @@ export function colorScale(
     const backgroundColor = rgbToOklch(hexToRgbArray(background));
     let mapping = darkMode ? colorMixMapping.dark : colorMixMapping.light;
 
-    if (mixColor && mix?.ratio && mix.ratio > 0) {
-        // If defined, we mix in a (tiny) bit of the mix color with the base color.
+    // A near-neutral tint at the extreme end of the scale is taken as the exact page background
+    // rather than tinting pure black/white with it — letting brands set an exact background such as
+    // a warm `#F5F3EF`. Only scales that define the page background opt in (via `baseStep`). In light
+    // mode the base is pure white by default, so a near-white tint also qualifies (nothing is lighter
+    // than white); a custom, lower background is respected instead. Decided on the raw color so a
+    // neutral mix (below) can't darken a tint out of the exact base.
+    const isExtremeBase = darkMode
+        ? baseColor.L < backgroundColor.L
+        : backgroundColor.L >= LIGHT_BASE_L
+          ? baseColor.L > EXACT_BASE_LIGHT_THRESHOLD
+          : baseColor.L > backgroundColor.L;
+    const isExactBase =
+        baseStep !== undefined && isExtremeBase && baseColor.C < EXACT_BASE_NEUTRAL_CHROMA;
+    const exactBaseIndex = (baseStep ?? 1) - 1;
+
+    if (mixColor && mix?.ratio && mix.ratio > 0 && !isExactBase) {
+        // Mix a little of the mix color into the base — but not when the tint is the exact base,
+        // where it must stay true to the supplied color (and match `--header-background`).
         baseColor.L = mixColor.L * mix.ratio + baseColor.L * (1 - mix.ratio);
         baseColor.C = mixColor.C * mix.ratio + baseColor.C * (1 - mix.ratio);
         baseColor.H = mix.color === DEFAULT_TINT_COLOR ? baseColor.H : mixColor.H;
     }
 
-    if (
-        (darkMode && baseColor.L < backgroundColor.L) ||
-        (!darkMode && baseColor.L > backgroundColor.L)
-    ) {
-        // If the supplied color is outside of our lightness bounds, use the supplied color's lightness.
-        // This is mostly used to allow darker-than-dark backgrounds for brands that specifically want that look.
+    if (isExactBase) {
         const difference = (backgroundColor.L - baseColor.L) / backgroundColor.L;
-        backgroundColor.L = baseColor.L;
         // At the edges of the scale, the subtle lightness changes stop being perceptible. We need to amp up our mapping to still stand out.
         const amplifier = 1;
         mapping = mapping.map((step, index) =>
             index < 9 ? step + step * amplifier * difference : step
         );
+
+        // Anchor the supplied color to the step the theme renders as the background, solving the
+        // background lightness so neighbouring steps stay continuous with it.
+        const baseMix = mapping[exactBaseIndex]!;
+        backgroundColor.L = (baseColor.L - foregroundColor.L * baseMix) / (1 - baseMix);
     }
 
     const result = [];
 
     for (let index = 0; index < mapping.length; index++) {
+        if (isExactBase && index === exactBaseIndex) {
+            result.push(hex);
+            continue;
+        }
+
         const step = mapping[index]!;
         const targetL = foregroundColor.L * step + backgroundColor.L * (1 - step);
 
@@ -238,7 +283,10 @@ export function colorScale(
                 case 11:
                     return 0.1;
                 default:
-                    return index * 0.05;
+                    // When the tint is the exact base, hold the steps from the base toward the
+                    // accents at its chroma so the background stays tinted; steps lighter than the
+                    // base (e.g. cards in `muted`) keep desaturating toward white.
+                    return isExactBase && index >= exactBaseIndex ? 1 : index * 0.05;
             }
         })();
 
diff --git a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
index aa03e6638..ee6e74323 100644
--- a/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
+++ b/packages/gitbook/src/components/RootLayout/CustomizationRootLayout.tsx
@@ -2,6 +2,7 @@ import {
     CustomizationDefaultThemeMode,
     CustomizationSidebarBackgroundStyle,
     CustomizationSidebarListStyle,
+    CustomizationTheme,
     type CustomizationThemedColor,
     type CustomizationTint,
     type SiteCustomizationSettings,
@@ -79,6 +80,13 @@ export async function CustomizationRootLayout(props: {
     const tintColor = getTintColor(customization);
     const mixColor = getTintMixColor(customization.styling.primaryColor, tintColor);
     const sidebarStyles = getSidebarStyles(customization);
+    const theme = 'theme' in customization.styling ? customization.styling.theme : undefined;
+    // Which scale step the theme renders as the page background — the step an exact light/dark tint
+    // anchors to. `muted` uses tint-subtle (step 2), other themes tint-base (step 1). `bold` is
+    // intentionally two-tone and already uses the tint for the header, so it opts out entirely
+    // (undefined) and keeps a neutral page background.
+    const tintBaseStep =
+        theme === CustomizationTheme.Bold ? undefined : theme === CustomizationTheme.Muted ? 2 : 1;
     const { infoColor, successColor, warningColor, dangerColor } = getSemanticColors(customization);
     const fontData = getFontData(customization.styling.font, 'content');
     // Temporarily add a if here while the cache is being warmed up.
@@ -158,7 +166,7 @@ export async function CustomizationRootLayout(props: {
                 >{`
                     :root, .light, .dark [data-color-scheme$="light"], .dark [data-follow-color-scheme="true"]:has([data-color-scheme$="light"]) {
                         ${generateColorVariable('primary', customization.styling.primaryColor.light)}
-                        ${generateColorVariable('tint', tintColor ? tintColor.light : DEFAULT_TINT_COLOR, { mix: mixColor && { color: mixColor.color.light, ratio: mixColor.ratio.light } })}
+                        ${generateColorVariable('tint', tintColor ? tintColor.light : DEFAULT_TINT_COLOR, { baseStep: tintBaseStep, mix: mixColor && { color: mixColor.color.light, ratio: mixColor.ratio.light } })}
                         ${generateColorVariable('neutral', DEFAULT_TINT_COLOR)}
 
                         --header-background: ${
@@ -185,7 +193,7 @@ export async function CustomizationRootLayout(props: {
 
                     .dark, :root:not(.dark) [data-color-scheme^="dark"], :root:not(.dark) [data-follow-color-scheme="true"]:has([data-color-scheme^="dark"]) {
                         ${generateColorVariable('primary', customization.styling.primaryColor.dark, { darkMode: true })}
-                        ${generateColorVariable('tint', tintColor ? tintColor.dark : DEFAULT_TINT_COLOR, { darkMode: true, mix: mixColor && { color: mixColor?.color.dark, ratio: mixColor.ratio.dark } })}
+                        ${generateColorVariable('tint', tintColor ? tintColor.dark : DEFAULT_TINT_COLOR, { darkMode: true, baseStep: tintBaseStep, mix: mixColor && { color: mixColor?.color.dark, ratio: mixColor.ratio.dark } })}
                         ${generateColorVariable('neutral', DEFAULT_TINT_COLOR, { darkMode: true })}
 
                         --header-background: ${hexToRgb(customization.header.backgroundColor?.dark ?? tintColor?.dark ?? customization.styling.primaryColor.dark)};

From e77bf32d5188c6d32463ea9cc678fff312fe1ba3 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Tue, 14 Jul 2026 20:24:14 +0200
Subject: [PATCH 33/46] Update customer e2e test URL after redirect (#4398)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/gitbook/e2e/customers.spec.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/gitbook/e2e/customers.spec.ts b/packages/gitbook/e2e/customers.spec.ts
index afd5410e0..8e4d60707 100644
--- a/packages/gitbook/e2e/customers.spec.ts
+++ b/packages/gitbook/e2e/customers.spec.ts
@@ -218,8 +218,8 @@ const testCases: TestsCase[] = [
         tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {
-        name: 'docs.cherry-ai.com',
-        contentBaseURL: 'https://docs.cherry-ai.com',
+        name: 'docs.cherryai.com.cn',
+        contentBaseURL: 'https://docs.cherryai.com.cn',
         tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
     },
     {

From cf94386c166215a319f64fabda49099f48c89895 Mon Sep 17 00:00:00 2001
From: Steven H <steven@gitbook.io>
Date: Tue, 14 Jul 2026 20:08:09 +0100
Subject: [PATCH 34/46] fix an issue where certain keywords could cause an
 exception when rendering emojis (#4397)

---
 .changeset/whole-hands-report.md   | 5 +++++
 packages/gitbook/src/lib/emojis.ts | 4 +++-
 2 files changed, 8 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/whole-hands-report.md

diff --git a/.changeset/whole-hands-report.md b/.changeset/whole-hands-report.md
new file mode 100644
index 000000000..11ed011ec
--- /dev/null
+++ b/.changeset/whole-hands-report.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix an issue where certain keywords could cause an exception when rendering emojis
diff --git a/packages/gitbook/src/lib/emojis.ts b/packages/gitbook/src/lib/emojis.ts
index 7a9ce23ac..e97234dc3 100644
--- a/packages/gitbook/src/lib/emojis.ts
+++ b/packages/gitbook/src/lib/emojis.ts
@@ -9,8 +9,10 @@ export function getEmojiForCode(code: string): string {
     }
 
     code = code.toLowerCase();
-    const fullCode = emojiCodepoints[code] ?? code;
 
+    const fullCode =
+        // use hasOwn to prevent codes like "constructor" or "prototype" from being resolved to the emoji codepoints object prototype
+        (Object.hasOwn(emojiCodepoints, code) ? emojiCodepoints[code] : undefined) ?? code;
     const codePoints = fullCode.split('-').map((elt) => Number.parseInt(elt, 16));
 
     try {

From 88b1919a45e1123a462fe3e7e6c3959562df2748 Mon Sep 17 00:00:00 2001
From: Addison <42930383+addisonschultz@users.noreply.github.com>
Date: Wed, 15 Jul 2026 17:31:04 +0900
Subject: [PATCH 35/46] Add centered GitBook logo to README (#4401)

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md                    | 4 ++++
 assets/gitbook_icon_dark.svg | 3 +++
 2 files changed, 7 insertions(+)
 create mode 100644 assets/gitbook_icon_dark.svg

diff --git a/README.md b/README.md
index 767bd1cb1..36efc7079 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="./assets/gitbook_icon_dark.svg" alt="GitBook" width="48" />
+</p>
+
 <h1 align="center">GitBook</h1>
 
 <p align="center">
diff --git a/assets/gitbook_icon_dark.svg b/assets/gitbook_icon_dark.svg
new file mode 100644
index 000000000..b70471805
--- /dev/null
+++ b/assets/gitbook_icon_dark.svg
@@ -0,0 +1,3 @@
+<svg width="65" height="65" viewBox="0 0 65 65" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M27.3963 34.2195C30.5255 36.0255 32.09 36.9285 33.8082 36.93C35.5265 36.9315 37.0926 36.0313 40.2249 34.2308L60.1913 22.7534C61.0927 22.2353 61.6484 21.2749 61.6484 20.2352C61.6484 19.1955 61.0927 18.2351 60.1913 17.717L40.2177 6.23554C37.0888 4.43695 35.5243 3.53766 33.8078 3.53833C32.0912 3.539 30.5275 4.43951 27.4 6.24053L10.2292 16.1286C10.102 16.2019 10.0383 16.2385 9.97905 16.2732C4.11368 19.7068 0.489862 25.9754 0.441408 32.7717C0.440918 32.8404 0.440918 32.9138 0.440918 33.0607C0.440918 33.2074 0.440918 33.2807 0.441407 33.3494C0.489754 40.138 4.10549 46.4008 9.96041 49.837C10.0196 49.8718 10.0831 49.9085 10.2101 49.9818L20.9658 56.1918C27.2331 59.8104 30.3668 61.6197 33.808 61.6208C37.2493 61.622 40.3842 59.8148 46.6539 56.2005L58.008 49.6551C61.1474 47.8454 62.7171 46.9405 63.579 45.4487C64.4409 43.957 64.4409 42.1451 64.4409 38.5215V31.5212C64.4409 30.5159 63.8965 29.5895 63.0182 29.1004C62.1683 28.627 61.1325 28.6341 60.2891 29.1189L37.0074 42.5019C35.4453 43.3998 34.6643 43.8487 33.8072 43.849C32.9501 43.8493 32.1688 43.4008 30.6062 42.5038L14.8487 33.4586C14.0593 33.0055 13.6647 32.7789 13.3477 32.738C12.625 32.6448 11.9301 33.0497 11.6548 33.7244C11.534 34.0203 11.5365 34.4753 11.5414 35.3855C11.545 36.0555 11.5468 36.3905 11.6094 36.6987C11.7496 37.3887 12.1127 38.0136 12.6428 38.4771C12.8795 38.6842 13.1696 38.8516 13.7499 39.1866L30.5974 48.9103C32.164 49.8145 32.9473 50.2666 33.8075 50.2668C34.6677 50.267 35.4512 49.8154 37.0184 48.912L57.6684 37.0085C58.2037 36.7 58.4713 36.5457 58.672 36.6616C58.8727 36.7776 58.8727 37.0865 58.8727 37.7044V40.8796C58.8727 41.7855 58.8727 42.2385 58.6572 42.6114C58.4417 42.9844 58.0493 43.2106 57.2644 43.663L40.2322 53.4811C37.0966 55.2885 35.5288 56.1923 33.8078 56.1915C32.0869 56.1907 30.5199 55.2855 27.386 53.4752L11.4509 44.2701C11.4003 44.2409 11.375 44.2262 11.3514 44.2125C8.0102 42.26 5.94856 38.6882 5.92922 34.8185C5.92909 34.7911 5.92909 34.7619 5.92909 34.7035V31.7889C5.92909 29.6526 7.06686 27.678 8.9151 26.6067C10.5483 25.66 12.5628 25.6582 14.1977 26.6018L27.3963 34.2195Z" fill="#181C1F"/>
+</svg>

From bcd4d4e980c78fef1917e81583d696c854399a16 Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Wed, 15 Jul 2026 10:42:20 +0200
Subject: [PATCH 36/46] Remove MCP test that recorded real feedback in
 production (#4399)

---
 packages/gitbook/tests/mcp.test.ts | 29 -----------------------------
 1 file changed, 29 deletions(-)

diff --git a/packages/gitbook/tests/mcp.test.ts b/packages/gitbook/tests/mcp.test.ts
index 3f6cfcfa6..b233a60d3 100644
--- a/packages/gitbook/tests/mcp.test.ts
+++ b/packages/gitbook/tests/mcp.test.ts
@@ -55,35 +55,6 @@ it(
     { timeout: 10_000 }
 );
 
-it(
-    'should record agent feedback through MCP',
-    async () => {
-        const client = new Client({
-            name: 'test',
-            version: '1.0.0',
-        });
-
-        await client.connect(
-            new StreamableHTTPClientTransport(
-                new URL(getContentTestURL('https://gitbook.com/docs/~gitbook/mcp/auth'))
-            )
-        );
-
-        const response = await client.callTool({
-            name: 'sendFeedback',
-            arguments: {
-                category: 'content-gap',
-                content: 'The authentication section does not explain how to rotate API tokens.',
-            },
-        });
-
-        expect(response.isError).toBeFalsy();
-        // @ts-expect-error - response.content is of type unknown
-        expect(response.content[0]?.text).toContain('Feedback recorded');
-    },
-    { timeout: 10_000 }
-);
-
 it(
     'should get a page from another site space through MCP',
     async () => {

From 3d376845d7a9c013856869633bbb5eb39c00c527 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Wed, 15 Jul 2026 16:17:00 +0200
Subject: [PATCH 37/46] Add a carousel layout for cards blocks (#4393)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/cards-carousel-layout.md           |   5 +
 bun.lock                                      |   4 +-
 package.json                                  |   2 +-
 .../DocumentView/Table/ViewCards.tsx          | 142 ++++++++++++++++++
 .../src/components/PageAside/PageAside.tsx    |   9 +-
 packages/gitbook/src/lib/pages.test.ts        |   6 +
 6 files changed, 164 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/cards-carousel-layout.md

diff --git a/.changeset/cards-carousel-layout.md b/.changeset/cards-carousel-layout.md
new file mode 100644
index 000000000..fe7f4bd7e
--- /dev/null
+++ b/.changeset/cards-carousel-layout.md
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Add a carousel layout option to cards blocks, rendering them as a horizontally-scrolling, scroll-snapping row instead of a wrapping grid.
diff --git a/bun.lock b/bun.lock
index 1b8096a86..30b3d0904 100644
--- a/bun.lock
+++ b/bun.lock
@@ -360,7 +360,7 @@
     "react-dom": "catalog:",
   },
   "catalog": {
-    "@gitbook/api": "0.188.0",
+    "@gitbook/api": "0.189.0",
     "@scalar/api-client-react": "^1.3.46",
     "@tsconfig/node20": "^20.1.6",
     "@tsconfig/strictest": "^2.0.6",
@@ -756,7 +756,7 @@
 
     "@fortawesome/fontawesome-svg-core": ["@fortawesome/fontawesome-svg-core@7.2.0", "", { "dependencies": { "@fortawesome/fontawesome-common-types": "7.2.0" } }, "sha512-6639htZMjEkwskf3J+e6/iar+4cTNM9qhoWuRfj9F3eJD6r7iCzV1SWnQr2Mdv0QT0suuqU8BoJCZUyCtP9R4Q=="],
 
-    "@gitbook/api": ["@gitbook/api@0.188.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-kZHpDM3XJdf1oZKhxYk3OZsjNHR4ZJrF47JgUxintnEvsW1yS8UvZlq6+dxgalL1k9wGmz3XXhiNv+p7p6egsA=="],
+    "@gitbook/api": ["@gitbook/api@0.189.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-QezuW8dMScSTJ+2IL/GGixkhGEsMRFRoO/W2r80pKRjoWyI9Ebai9oZsoN/pbRZz3cTnwa7hpRDtzaqHeeOAdQ=="],
 
     "@gitbook/browser-types": ["@gitbook/browser-types@workspace:packages/browser-types"],
 
diff --git a/package.json b/package.json
index 3f12d5960..491e101b6 100644
--- a/package.json
+++ b/package.json
@@ -43,7 +43,7 @@
         "catalog": {
             "@tsconfig/strictest": "^2.0.6",
             "@tsconfig/node20": "^20.1.6",
-            "@gitbook/api": "0.188.0",
+            "@gitbook/api": "0.189.0",
             "@scalar/api-client-react": "^1.3.46",
             "@types/react": "^19.0.0",
             "@types/react-dom": "^19.0.0",
diff --git a/packages/gitbook/src/components/DocumentView/Table/ViewCards.tsx b/packages/gitbook/src/components/DocumentView/Table/ViewCards.tsx
index f86eecd3e..5c8dd4c68 100644
--- a/packages/gitbook/src/components/DocumentView/Table/ViewCards.tsx
+++ b/packages/gitbook/src/components/DocumentView/Table/ViewCards.tsx
@@ -1,5 +1,6 @@
 import type { DocumentTableViewCards } from '@gitbook/api';
 
+import { ScrollContainer } from '@/components/primitives/ScrollContainer';
 import { tcls } from '@/lib/tailwind';
 
 import { RecordCard } from './RecordCard';
@@ -7,6 +8,20 @@ import type { TableViewProps } from './Table';
 import { TableSearchRecord } from './TableSearch';
 
 export function ViewCards(props: TableViewProps<DocumentTableViewCards>) {
+    // `wrap` defaults to `true` (a wrapping grid); only an explicit `false` opts into the
+    // horizontally-scrolling carousel row. Fall back to the grid in print mode: a PDF can't
+    // scroll, so carousel overflow would be silently clipped.
+    if (props.view.wrap === false && props.context.mode !== 'print') {
+        return <CardsCarousel {...props} />;
+    }
+
+    return <CardsGrid {...props} />;
+}
+
+/**
+ * The default layout: cards wrap into a responsive grid.
+ */
+function CardsGrid(props: TableViewProps<DocumentTableViewCards>) {
     const { block, view, records, style } = props;
 
     return (
@@ -35,3 +50,130 @@ export function ViewCards(props: TableViewProps<DocumentTableViewCards>) {
         </div>
     );
 }
+
+/**
+ * The carousel layout: cards lay out in a single horizontally-scrolling row that
+ * snaps to the leftmost card. Reuses ScrollContainer for the scroll buttons.
+ *
+ * Rather than fading the edges, the row breaks out of the content column so it can
+ * scroll to the page edges. Negative margins on the outer wrapper pull it out; matching
+ * padding + scroll-padding on the scroller keep the first/last cards aligned with the
+ * body text at rest and snapping to that edge, while cards bleed to the edge mid-scroll.
+ * See `bleedVars` below for how far each side reaches.
+ */
+function CardsCarousel(props: TableViewProps<DocumentTableViewCards>) {
+    const { view, records } = props;
+
+    // Cards need a fixed width so the row overflows and scrolls; mirror the grid's
+    // medium/large sizing.
+    const cardWidth =
+        view.cardSize === 'large'
+            ? 'w-[90%] @sm:w-[calc(45%-0.5rem)] @5xl:w-[calc(50%-0.5rem)]'
+            : 'w-[90%] @sm:w-[calc(45%-0.5rem)] @xl:w-[calc(30%-0.66rem)] @5xl:w-[calc(33.33%-0.66rem)]';
+
+    // Break the row out of the content column so it bleeds to the page edges instead of
+    // fading. `--cards-bleed-l/r` are the distances to pull each side out by; they drive the
+    // negative margins (on the wrapper) and the matching padding + scroll-padding (on the
+    // scroller), so the first/last cards stay aligned with the body text at rest while cards
+    // bleed to the edge mid-scroll. Kept as literals here since it's a single block.
+    //
+    // The bleed only makes sense on the default layout, where the 48rem column leaves wide
+    // empty margins to reclaim. The wide layout (max-w-6xl) already fills the usable width,
+    // so from `lg` we suppress the bleed entirely — otherwise the page gutter would push the
+    // row past where every other block ends, jutting into the window frame.
+    //
+    // On the default layout:
+    // - Left is capped at the page gutter (1/1.5/2rem) so it never slides under the TOC.
+    // - Right reaches the viewport edge from `lg`. The 48rem column is centred in the space
+    //   beside the TOC, so the gap to the viewport edge is `50vw` minus half the column
+    //   (24rem), minus half the TOC (10.5rem of the 21rem `w-72`+`mr-12`) when one is shown.
+    //   `html` clips horizontal overflow, so a small overshoot is harmless.
+    // - Right collapses to 0 once an outline occupies that column (shown from `xl`), so
+    //   cards never slide under it.
+    const bleedVars = tcls(
+        '[--cards-bleed-l:1rem]',
+        'sm:[--cards-bleed-l:1.5rem]',
+        'md:[--cards-bleed-l:2rem]',
+        'layout-default:md:max-lg:[--cards-bleed-l:max(calc(50vw-24.5rem),2rem)]',
+        'lg:[--cards-bleed-l:max(calc(50vw-34rem),3rem)]',
+        'xl:[--cards-bleed-l:3rem]',
+
+        '[--cards-bleed-r:1rem]',
+        'sm:[--cards-bleed-r:1.5rem]',
+        'md:[--cards-bleed-r:2rem]',
+        'layout-default:md:max-lg:[--cards-bleed-r:max(calc(50vw-24.5rem),2rem)]',
+        'layout-default:lg:[--cards-bleed-r:max(calc(50vw-35rem),3rem)]',
+        'layout-default:xl:[--cards-bleed-r:3rem]',
+
+        'hover:layout-default:no-sidebar:lg:max-xl:[--cards-bleed-l:max(calc(50vw-24.5rem),2rem)]',
+        'hover:layout-default:no-sidebar:lg:max-xl:[--cards-bleed-r:max(calc(50vw-24.5rem),2rem)]',
+
+        // Default centered
+        'hover:layout-default:no-sidebar:xl:[--cards-bleed-l:max(calc(50vw-22.5rem),2rem)]',
+        'hover:layout-default:xl:[--cards-bleed-r:max(calc(50vw-26.5rem),19rem)]',
+
+        // Full width, no outline
+        'hover:layout-wide:page-no-outline:2xl:[--cards-bleed-r:max(calc(50vw-43.5rem),0rem)]',
+
+        // Full width centered
+        'layout-wide:no-sidebar:page-no-outline:2xl:[--cards-bleed-l:max(calc(50vw-36.5rem),0rem)]',
+        'layout-wide:no-sidebar:page-no-outline:2xl:[--cards-bleed-r:max(calc(50vw-36.5rem),0rem)]'
+    );
+
+    return (
+        <ScrollContainer
+            orientation="horizontal"
+            className={tcls(
+                bleedVars,
+                'ml-[calc(var(--cards-bleed-l)*-1)]',
+                'mr-[calc(var(--cards-bleed-r)*-1)]',
+                'xl:transition-[margin]',
+                'hover:z-11'
+            )}
+            // `py-1` keeps the card ring/shadow from being clipped by the scroll overflow;
+            // `snap-mandatory` + the scroll-padding snap each card to the content edge.
+            contentClassName={tcls(
+                'gap-4',
+                'pt-px',
+                '-mt-px',
+                'pb-6',
+                '-mb-6',
+                'pl-[var(--cards-bleed-l)]',
+                'pr-[var(--cards-bleed-r)]',
+                'scroll-pl-[var(--cards-bleed-l)]',
+                'scroll-pr-[var(--cards-bleed-r)]',
+                'snap-x',
+                'snap-mandatory',
+                'xl:transition-[padding]'
+            )}
+            leading={{
+                fade: true,
+                button: { size: 'small', className: 'ml-[calc(var(--cards-bleed-l)-1rem)]' },
+            }}
+            trailing={{
+                fade: true,
+                button: { size: 'small', className: 'mr-[calc(var(--cards-bleed-r)-1rem)]' },
+            }}
+        >
+            {records.map((record) => {
+                return (
+                    <TableSearchRecord
+                        key={record[0]}
+                        recordId={record[0]}
+                        // `grid grid-cols-1` stretches the card to fill the fixed-width,
+                        // equal-height track; `snap-start` aligns it to the left edge.
+                        visibleClassName={tcls(
+                            'grid',
+                            'grid-cols-1',
+                            'shrink-0',
+                            'snap-start',
+                            cardWidth
+                        )}
+                    >
+                        <RecordCard {...props} record={record} />
+                    </TableSearchRecord>
+                );
+            })}
+        </ScrollContainer>
+    );
+}
diff --git a/packages/gitbook/src/components/PageAside/PageAside.tsx b/packages/gitbook/src/components/PageAside/PageAside.tsx
index c2a20787c..6c5ba7c73 100644
--- a/packages/gitbook/src/components/PageAside/PageAside.tsx
+++ b/packages/gitbook/src/components/PageAside/PageAside.tsx
@@ -77,6 +77,7 @@ export async function PageAside(props: {
                 'break-anywhere', // To prevent long words in headings from breaking the layout
 
                 'lg:z-10',
+                'lg:hover:z-12',
                 'layout-default:xl:not-chat-open:pr-0',
                 'layout-default:xl:not-chat-open:pl-8',
                 'layout-default:xl:not-chat-open:flex!',
@@ -98,7 +99,13 @@ export async function PageAside(props: {
                 'page-api-block:page-has-outline:min-[96rem]:border-l-0',
                 'page-api-block:page-has-outline:min-[96rem]:pl-8',
 
-                'hydrated:site-background', // Only add a background once the element is positioned correctly to prevent overlapping the page cover
+                // Only add a background once the element is positioned correctly, to prevent
+                // overlapping the page cover. Kept opaque wherever the outline is a toggleable
+                // overlay (below xl in any layout, and xl–3xl in wide layout, where it opens as
+                // a desktop SideSheet), but dropped for the permanent outline column so a bleeding
+                // cards carousel can scroll behind it.
+                'max-xl:hydrated:site-background',
+                'layout-wide:max-3xl:hydrated:site-background',
                 'text-tint',
                 'contrast-more:text-tint-strong'
             )}
diff --git a/packages/gitbook/src/lib/pages.test.ts b/packages/gitbook/src/lib/pages.test.ts
index e1be6faee..8cc358d1c 100644
--- a/packages/gitbook/src/lib/pages.test.ts
+++ b/packages/gitbook/src/lib/pages.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'bun:test';
 import {
     type RevisionPage,
+    RevisionPageLayoutOptionsCoverMask,
     RevisionPageLayoutOptionsCoverSize,
     RevisionPageLayoutOptionsWidth,
 } from '@gitbook/api';
@@ -77,6 +78,7 @@ describe('resolveFirstDocument', () => {
                         layout: {
                             cover: true,
                             coverSize: RevisionPageLayoutOptionsCoverSize.Full,
+                            coverMask: RevisionPageLayoutOptionsCoverMask.None,
                             title: true,
                             description: true,
                             tableOfContents: true,
@@ -130,6 +132,7 @@ describe('resolveFirstDocument', () => {
                 layout: {
                     cover: true,
                     coverSize: RevisionPageLayoutOptionsCoverSize.Full,
+                    coverMask: RevisionPageLayoutOptionsCoverMask.None,
                     title: true,
                     description: true,
                     tableOfContents: true,
@@ -176,6 +179,7 @@ describe('resolvePagePath', () => {
                 layout: {
                     cover: true,
                     coverSize: RevisionPageLayoutOptionsCoverSize.Full,
+                    coverMask: RevisionPageLayoutOptionsCoverMask.None,
                     title: true,
                     description: true,
                     tableOfContents: true,
@@ -252,6 +256,7 @@ describe('resolvePagePath', () => {
                         layout: {
                             cover: true,
                             coverSize: RevisionPageLayoutOptionsCoverSize.Full,
+                            coverMask: RevisionPageLayoutOptionsCoverMask.None,
                             title: true,
                             description: true,
                             tableOfContents: true,
@@ -370,6 +375,7 @@ function createDocumentPage(id: string, path: string, hidden = false): RevisionP
         layout: {
             cover: true,
             coverSize: RevisionPageLayoutOptionsCoverSize.Full,
+            coverMask: RevisionPageLayoutOptionsCoverMask.None,
             title: true,
             description: true,
             tableOfContents: true,

From c41cf9c12a7963c58ad771f5f72dd45967198b3c Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Wed, 15 Jul 2026 18:02:53 +0200
Subject: [PATCH 38/46] Add cover image background mode and mask (#4213)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
---
 .changeset/hot-views-judge.md                 |   5 +
 .../components/DocumentView/DocumentView.tsx  |   8 +
 .../src/components/DocumentView/Heading.tsx   |   3 +
 .../src/components/DocumentView/Paragraph.tsx |  12 +-
 .../components/PageActions/PageActions.tsx    |   5 +-
 .../src/components/PageAside/PageAside.tsx    |   3 +-
 .../PageAside/ScrollSectionsList.tsx          |   1 +
 .../src/components/PageBody/PageBody.tsx      |  77 ++-
 .../src/components/PageBody/PageCover.tsx     | 143 +++--
 .../components/PageBody/PageCoverImage.tsx    |  13 +-
 .../src/components/PageBody/PageHeader.tsx    |  28 +-
 .../src/components/RootLayout/globals.css     | 603 ++++++++++--------
 .../components/SitePage/PageClientLayout.tsx  |  76 +++
 .../src/components/SitePage/SitePage.tsx      |  15 +-
 .../src/components/primitives/Button.tsx      |   2 +-
 packages/gitbook/tailwind.config.ts           |   8 +
 16 files changed, 627 insertions(+), 375 deletions(-)
 create mode 100644 .changeset/hot-views-judge.md

diff --git a/.changeset/hot-views-judge.md b/.changeset/hot-views-judge.md
new file mode 100644
index 000000000..384096100
--- /dev/null
+++ b/.changeset/hot-views-judge.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add cover image background mode and masks
diff --git a/packages/gitbook/src/components/DocumentView/DocumentView.tsx b/packages/gitbook/src/components/DocumentView/DocumentView.tsx
index 9d5f45eac..629afba5f 100644
--- a/packages/gitbook/src/components/DocumentView/DocumentView.tsx
+++ b/packages/gitbook/src/components/DocumentView/DocumentView.tsx
@@ -36,6 +36,14 @@ export interface DocumentContext {
      * @default false
      */
     withLinkPreviews?: boolean;
+
+    /**
+     * True when this document is the main page body — the only place a background page cover is
+     * shown behind the content. Cover-aware text styling (contrast over the cover) is scoped to it
+     * so auxiliary documents (search answers, AI chat, PDF export) don't inherit the cover colors.
+     * @default false
+     */
+    isPageBody?: boolean;
 }
 
 export interface DocumentContextProps {
diff --git a/packages/gitbook/src/components/DocumentView/Heading.tsx b/packages/gitbook/src/components/DocumentView/Heading.tsx
index 8977997b9..b074ba617 100644
--- a/packages/gitbook/src/components/DocumentView/Heading.tsx
+++ b/packages/gitbook/src/components/DocumentView/Heading.tsx
@@ -59,6 +59,9 @@ export async function Heading(props: BlockProps<DocumentBlockHeading>) {
                     'justify-self-start',
                     'max-w-full',
                     'break-words',
+                    // Cover-aware contrast text applies only to the page body, not to documents
+                    // rendered in overlays (search answers, AI chat) on a background-cover page.
+                    context.isPageBody && 'page-cover-background:text-contrast-cover',
                     getTextAlignment(block.data.align),
                     textStyle.lineHeight
                 )}
diff --git a/packages/gitbook/src/components/DocumentView/Paragraph.tsx b/packages/gitbook/src/components/DocumentView/Paragraph.tsx
index b58c2988a..1212bbd36 100644
--- a/packages/gitbook/src/components/DocumentView/Paragraph.tsx
+++ b/packages/gitbook/src/components/DocumentView/Paragraph.tsx
@@ -18,7 +18,17 @@ export function Paragraph(props: BlockProps<DocumentBlockParagraph>) {
         'has-[.button,input]:flex has-[.button,input]:flex-wrap has-[.button,input]:gap-2 has-[.button,input]:items-center';
 
     const paragraph = (
-        <p className={tcls(inlineButtonStyle, style, getTextAlignment(block.data?.align))}>
+        <p
+            className={tcls(
+                // Cover-aware contrast text applies only to the page body, not to documents
+                // rendered in overlays (search answers, AI chat) on a background-cover page.
+                context.isPageBody &&
+                    'page-cover-background:[&:not(:has(.button,input))]:text-contrast-cover',
+                inlineButtonStyle,
+                style,
+                getTextAlignment(block.data?.align)
+            )}
+        >
             <Inlines {...contextProps} nodes={block.nodes} ancestorInlines={[]} />
         </p>
     );
diff --git a/packages/gitbook/src/components/PageActions/PageActions.tsx b/packages/gitbook/src/components/PageActions/PageActions.tsx
index 209c35e05..38b6ff31b 100644
--- a/packages/gitbook/src/components/PageActions/PageActions.tsx
+++ b/packages/gitbook/src/components/PageActions/PageActions.tsx
@@ -475,7 +475,10 @@ function PageActionWrapper(props: {
                 variant="secondary"
                 label={label ?? shortLabel}
                 aria-label={shortLabel}
-                className="bg-tint-base"
+                // `relative z-20` keeps the button above the breadcrumbs, whose container can sit on
+                // top of it over a page cover. `disabled:bg-tint-base` preserves the background while
+                // busy — the `secondary` variant would otherwise reset it via `disabled:bg-transparent`.
+                className="relative z-20 bg-tint-base disabled:bg-tint-base"
                 onClick={onClick}
                 href={href}
                 target={href ? target : undefined}
diff --git a/packages/gitbook/src/components/PageAside/PageAside.tsx b/packages/gitbook/src/components/PageAside/PageAside.tsx
index 6c5ba7c73..1982e9e03 100644
--- a/packages/gitbook/src/components/PageAside/PageAside.tsx
+++ b/packages/gitbook/src/components/PageAside/PageAside.tsx
@@ -107,7 +107,8 @@ export async function PageAside(props: {
                 'max-xl:hydrated:site-background',
                 'layout-wide:max-3xl:hydrated:site-background',
                 'text-tint',
-                'contrast-more:text-tint-strong'
+                'contrast-more:text-tint-strong',
+                'xl:page-cover-background:text-contrast-cover'
             )}
         >
             <div className="flex h-full w-full shrink-0 flex-col overflow-hidden">
diff --git a/packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx b/packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx
index 417383bea..d782b549f 100644
--- a/packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx
+++ b/packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx
@@ -107,6 +107,7 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
                             'sidebar-list-line:border-l-2',
                             'border-transparent',
                             'sidebar-list-line:-left-px',
+                            'xl:page-cover-background:text-contrast-cover',
 
                             // The method badge no longer has a right margin, so lay the row out with a gap
                             section.tag && ['flex', 'items-baseline', 'gap-2'],
diff --git a/packages/gitbook/src/components/PageBody/PageBody.tsx b/packages/gitbook/src/components/PageBody/PageBody.tsx
index 84574ad53..0171823e0 100644
--- a/packages/gitbook/src/components/PageBody/PageBody.tsx
+++ b/packages/gitbook/src/components/PageBody/PageBody.tsx
@@ -93,6 +93,9 @@ export async function PageBody(props: {
                     'py-8',
                     'layout-wide:no-sidebar:lg:max-xl:pb-20', // Add padding to prevent overlap of minimised trademark
                     '@container',
+                    // Flex column so the growing content wrapper below fills the page: the footer
+                    // navigation settles at the bottom, and a full-page cover shows behind the content.
+                    'flex flex-col',
                     CONTENT_STYLE,
                     pageHasToc ? 'page-has-toc' : 'page-no-toc',
                     wideLayout ? 'layout-wide' : 'layout-default'
@@ -104,37 +107,44 @@ export async function PageBody(props: {
                     <PageCover as="hero" page={page} cover={page.cover} context={context} />
                 ) : null}
 
-                <PageHeader
-                    context={context}
-                    page={page}
-                    ancestors={ancestors}
-                    withRSSFeed={contentHasUpdates}
-                    hasAPIBlocks={hasAPIBlocks}
-                />
-                {document && !isNodeEmpty(document) ? (
-                    <OptionalSuspense
-                        staticRoute={staticRoute}
-                        fallback={<DocumentViewSkeleton document={document} blockStyle="" />}
-                    >
-                        <SuspenseLoadedHint />
-                        <div className="contents" data-content-ref-root="">
-                            <DocumentView
-                                document={document}
-                                style="flex flex-col [&>*+*]:mt-5"
-                                context={{
-                                    mode: 'default',
-                                    contentContext: {
-                                        ...context,
-                                        page,
-                                    },
-                                    withLinkPreviews,
-                                }}
-                            />
-                        </div>
-                    </OptionalSuspense>
-                ) : (
-                    <PageBodyBlankslate page={page} context={context} />
-                )}
+                {/* Grows to fill the page (so the footer navigation below settles at the bottom) and
+                    stays a plain block — this gives the floated, sticky API page-actions a tall
+                    containing block to travel within while letting the breadcrumbs wrap around them
+                    (see PageHeader). */}
+                <div className="min-w-0 grow">
+                    <PageHeader
+                        context={context}
+                        page={page}
+                        ancestors={ancestors}
+                        withRSSFeed={contentHasUpdates}
+                        hasAPIBlocks={hasAPIBlocks}
+                    />
+                    {document && !isNodeEmpty(document) ? (
+                        <OptionalSuspense
+                            staticRoute={staticRoute}
+                            fallback={<DocumentViewSkeleton document={document} blockStyle="" />}
+                        >
+                            <SuspenseLoadedHint />
+                            <div className="contents" data-content-ref-root="">
+                                <DocumentView
+                                    document={document}
+                                    style="flex flex-col [&>*+*]:mt-5"
+                                    context={{
+                                        mode: 'default',
+                                        contentContext: {
+                                            ...context,
+                                            page,
+                                        },
+                                        withLinkPreviews,
+                                        isPageBody: true,
+                                    }}
+                                />
+                            </div>
+                        </OptionalSuspense>
+                    ) : (
+                        <PageBodyBlankslate page={page} context={context} />
+                    )}
+                </div>
 
                 {page.layout.pagination && customization.pagination.enabled ? (
                     <PageFooterNavigation context={context} page={page} />
@@ -176,10 +186,7 @@ export async function PageBody(props: {
     );
 }
 
-function LLMsTxtPageDirective(props: {
-    context: GitBookSiteContext;
-    page: RevisionPageDocument;
-}) {
+function LLMsTxtPageDirective(props: { context: GitBookSiteContext; page: RevisionPageDocument }) {
     const { context, page } = props;
 
     return (
diff --git a/packages/gitbook/src/components/PageBody/PageCover.tsx b/packages/gitbook/src/components/PageBody/PageCover.tsx
index 7e14b125a..c5ff63cdb 100644
--- a/packages/gitbook/src/components/PageBody/PageCover.tsx
+++ b/packages/gitbook/src/components/PageBody/PageCover.tsx
@@ -1,5 +1,9 @@
 import type { GitBookSiteContext } from '@/lib/context';
-import type { RevisionPageDocument, RevisionPageDocumentCover } from '@gitbook/api';
+import {
+    CustomizationHeaderPreset,
+    type RevisionPageDocument,
+    type RevisionPageDocumentCover,
+} from '@gitbook/api';
 import type { StaticImageData } from 'next/image';
 
 import { getImageAttributes } from '@/components/utils';
@@ -13,18 +17,38 @@ import { getCoverHeight } from './coverHeight';
 import defaultPageCoverSVG from './default-page-cover.svg';
 
 const defaultPageCover = defaultPageCoverSVG as StaticImageData;
+const DEFAULT_RESPONSIVE_COVER_CUTOFF = '56.25%';
 
 /**
  * Cover for the page.
  */
 export async function PageCover(props: {
-    as: 'hero' | 'full';
+    as: 'hero' | 'full' | 'background';
     page: RevisionPageDocument;
     cover: RevisionPageDocumentCover;
     context: GitBookSiteContext;
 }) {
-    const { as, cover, context } = props;
+    const { as, page, cover, context } = props;
     const height = getCoverHeight(cover);
+    const mask = page.layout.coverMask === 'radial' ? 'radial' : 'none';
+
+    const initialCoverCutoff = () => {
+        if (!height) {
+            return DEFAULT_RESPONSIVE_COVER_CUTOFF;
+        }
+
+        let total = height;
+        if (context.customization.announcement?.enabled) {
+            total += 68;
+        }
+        if (context.customization.header.preset !== CustomizationHeaderPreset.None) {
+            total += 64;
+        }
+        if (context.visibleSections && context.visibleSections.list.length > 1) {
+            total += 45;
+        }
+        return `${total}px`;
+    };
 
     const [resolved, resolvedDark] = await Promise.all([
         cover.ref ? resolveContentRef(cover.ref, context) : null,
@@ -79,56 +103,73 @@ export async function PageCover(props: {
     assert(light, 'Light image should be defined');
 
     return (
-        <div
-            data-gb-page-cover
-            data-full={String(as === 'full')}
-            className={tcls(
-                'overflow-hidden',
-                // Negative margin to balance the container padding
-                '-mx-4',
+        <>
+            <style>{`:root { --cover-height: ${initialCoverCutoff()}; }`}</style>
+            <div
+                data-gb-page-cover
+                data-cover-text-color={cover.textColor}
+                data-cover-text-color-dark={cover.textColorDark}
+                data-cover-type={as}
+                data-full={String(as === 'full')}
+                className={tcls(
+                    'overflow-hidden',
+                    // Negative margin to balance the container padding
+                    '-mx-4',
 
-                // Full-width cover: extend to edges, disregard TOC where possible
-                as === 'full'
-                    ? [
-                          'sm:-mx-6',
-                          'md:-mx-8',
-                          'lg:-ml-12',
+                    // Full-width cover: extend to edges, disregard TOC where possible
+                    as === 'full' || as === 'background'
+                        ? [
+                              'sm:-mx-6',
+                              'md:-mx-8',
+                              'lg:-ml-12',
 
-                          // Extend the full-width cover
-                          'layout-default:page-no-toc:lg:-ml-92', // Extend into the left sidebar if there's no TOC...
-                          'layout-wide:2xl:-mr-[clamp(2rem,calc((100vw-90rem)/2+2rem),18rem)]', // ...and to the right if there's no outline.
-                          'layout-wide:page-no-toc:2xl:-mx-[max(calc((100vw-90rem)/2+2rem),2rem)]', // Span full width if the page content is centered.
-                          'layout-wide:has-sidebar:page-no-toc:lg:-ml-[max(calc((100vw-90rem)/2+23rem),23rem)]', // If there's still a sidebar, we have to factor it in too.
+                              // Extend the full-width cover
+                              'layout-default:page-no-toc:lg:-ml-92', // Extend into the left sidebar if there's no TOC...
+                              'layout-wide:2xl:-mr-[clamp(2rem,calc((100vw-90rem)/2+2rem),18rem)]', // ...and to the right if there's no outline.
+                              'layout-wide:page-no-toc:2xl:-mx-[max(calc((100vw-90rem)/2+2rem),2rem)]', // Span full width if the page content is centered.
+                              'layout-wide:has-sidebar:page-no-toc:lg:-ml-[max(calc((100vw-90rem)/2+23rem),23rem)]', // If there's still a sidebar, we have to factor it in too.
 
-                          // Corner rounding: we round once the page is wide enough to have space around the cover.
-                          'layout-default:2xl:rounded-corners:rounded-b-xl',
-                          'layout-default:2xl:circular-corners:rounded-b-3xl',
-                          'layout-wide:3xl:circular-corners:rounded-b-3xl',
-                          'layout-wide:3xl:rounded-corners:rounded-b-xl',
-                          // Round the bottom left corner once the sidebar is shown next to it
-                          'has-sidebar:lg:rounded-corners:rounded-bl-xl',
-                          'has-sidebar:lg:circular-corners:rounded-bl-3xl',
-                      ]
-                    : [
-                          // Regular cover: size regularly along with other content
-                          CONTENT_STYLE,
-                          'max-sm:-mx-4',
-                          'sm:rounded-corners:rounded-xl',
-                          'sm:circular-corners:rounded-3xl',
-                          'mb-8',
-                          'max-sm:w-screen',
-                          'max-sm:-mt-8',
-                      ]
-            )}
-        >
-            <PageCoverImage
-                imgs={{
-                    light,
-                    dark,
-                }}
-                y={cover.yPos}
-                height={height}
-            />
-        </div>
+                              // Corner rounding: we round once the page is wide enough to have space around the cover.
+                              'layout-default:2xl:rounded-corners:rounded-b-xl',
+                              'layout-default:2xl:circular-corners:rounded-b-3xl',
+                              'layout-wide:3xl:circular-corners:rounded-b-3xl',
+                              'layout-wide:3xl:rounded-corners:rounded-b-xl',
+                              // Round the bottom left corner once the sidebar is shown next to it
+                              'has-sidebar:lg:rounded-corners:rounded-bl-xl',
+                              'has-sidebar:lg:circular-corners:rounded-bl-3xl',
+                          ]
+                        : null,
+
+                    as === 'hero'
+                        ? [
+                              // Regular cover: size regularly along with other content
+                              CONTENT_STYLE,
+                              'max-sm:-mx-4',
+                              'sm:rounded-corners:rounded-xl',
+                              'sm:circular-corners:rounded-3xl',
+                              'mb-8',
+                              'max-sm:w-screen',
+                              'max-sm:-mt-8',
+                          ]
+                        : null,
+
+                    as === 'background'
+                        ? [
+                              '-z-1 absolute inset-x-0 contrast-more:opacity-5 *:contrast-more:blur-md',
+                          ]
+                        : null
+                )}
+            >
+                <PageCoverImage
+                    imgs={{
+                        light,
+                        dark,
+                    }}
+                    y={cover.yPos}
+                    height={height}
+                    mask={mask}
+                />
+            </div>
+        </>
     );
 }
diff --git a/packages/gitbook/src/components/PageBody/PageCoverImage.tsx b/packages/gitbook/src/components/PageBody/PageCoverImage.tsx
index eb2190b74..ae2d18c4b 100644
--- a/packages/gitbook/src/components/PageBody/PageCoverImage.tsx
+++ b/packages/gitbook/src/components/PageBody/PageCoverImage.tsx
@@ -24,10 +24,11 @@ interface PageCoverImageProps {
     y: number;
     // Only if the `height` was customized by the user (and thus defined), we use it to set the cover's height and skip the default behaviour of fixed aspect-ratio.
     height: number | undefined;
+    mask?: 'none' | 'radial';
 }
 
 export function PageCoverImage(props: PageCoverImageProps) {
-    const { imgs, y, height } = props;
+    const { imgs, y, height, mask } = props;
     const { containerRef, objectPositionY, isLoading } = useCoverPosition(imgs, y);
 
     if (isLoading) {
@@ -53,6 +54,11 @@ export function PageCoverImage(props: PageCoverImageProps) {
                         : `${PAGE_COVER_SIZE.width}/${PAGE_COVER_SIZE.height}`,
                     objectPosition: `50% ${objectPositionY}%`,
                     height, // if no height is passed, no height will be set.
+                    maskComposite: 'intersect',
+                    maskImage:
+                        mask === 'radial'
+                            ? 'radial-gradient(200% 200% at 50% -100%, black 70%, rgba(0,0,0,0.85) 77.5%, rgba(0,0,0,0.6) 85%, rgba(0,0,0,0.1) 96.25%, transparent 100%), linear-gradient(to left, black 60%, rgba(0,0,0,0.8) 75%, rgba(0,0,0,0.1) 95%, transparent 100%), linear-gradient(to right, black 60%, rgba(0,0,0,0.8) 75%, rgba(0,0,0,0.1) 95%, transparent 100%)'
+                            : undefined,
                 }}
             />
             {imgs.dark && (
@@ -69,6 +75,11 @@ export function PageCoverImage(props: PageCoverImageProps) {
                             : `${PAGE_COVER_SIZE.width}/${PAGE_COVER_SIZE.height}`,
                         objectPosition: `50% ${objectPositionY}%`,
                         height, // if no height is passed, no height will be set.
+                        maskComposite: 'intersect',
+                        maskImage:
+                            mask === 'radial'
+                                ? 'radial-gradient(200% 200% at 50% -100%, black 70%, rgba(0,0,0,0.85) 77.5%, rgba(0,0,0,0.6) 85%, rgba(0,0,0,0.1) 96.25%, transparent 100%), linear-gradient(to left, black 60%, rgba(0,0,0,0.8) 75%, rgba(0,0,0,0.1) 95%, transparent 100%), linear-gradient(to right, black 60%, rgba(0,0,0,0.8) 75%, rgba(0,0,0,0.1) 95%, transparent 100%)'
+                                : undefined,
                     }}
                 />
             )}
diff --git a/packages/gitbook/src/components/PageBody/PageHeader.tsx b/packages/gitbook/src/components/PageBody/PageHeader.tsx
index a449be4b3..d4d3f5818 100644
--- a/packages/gitbook/src/components/PageBody/PageHeader.tsx
+++ b/packages/gitbook/src/components/PageBody/PageHeader.tsx
@@ -148,11 +148,14 @@ export async function PageHeader(props: {
             className={tcls(
                 'float-right ml-4 flex gap-2',
                 showBreadcrumbs ? '-mb-1 -mt-1.5' : '-mt-3 xs:mt-2',
-                // On desktop API pages (where this <div> is rendered as a sibling of <header>, see
-                // below) keep the actions pinned below the site header while scrolling long
-                // operations. The offset tracks the header height (banner, cover…) via the same
-                // --toc-top-offset the outline and code samples use. Hidden while the outline drawer
-                // is open (drawer widths only) so it doesn't overlap the sheet.
+                // On desktop API pages these actions are pulled out of <header> (rendered as its
+                // preceding sibling, see below) so their sticky containing block is the tall,
+                // growing content wrapper in <main> — a plain block — rather than the short header.
+                // There they keep the base `float-right`, so the breadcrumbs wrap around them at any
+                // width, while pinning below the site header when scrolling long operations. The
+                // offset tracks the header height (banner, cover…) via the same --toc-top-offset the
+                // outline and code samples use. Hidden while the outline drawer is open (drawer
+                // widths only) so it doesn't overlap the sheet.
                 hasAPIBlocks && [
                     'page-api-block:lg:sticky',
                     'page-api-block:lg:top-[calc(var(--toc-top-offset,4rem)+1rem)]',
@@ -185,7 +188,7 @@ export async function PageHeader(props: {
                 // content spans the full width with no navigation column, so the crumbs sit stranded.
                 <nav
                     aria-label="Breadcrumb"
-                    className="layout-wide:page-no-toc:hidden text-tint text-xs leading-relaxed"
+                    className="layout-wide:page-no-toc:hidden page-cover-background:text-contrast-cover text-tint text-xs leading-relaxed page-cover-background:opacity-9"
                 >
                     <ol className="inline">
                         {contextCrumbs.map((crumb, index) => (
@@ -238,7 +241,8 @@ export async function PageHeader(props: {
                         'grow',
                         'text-pretty',
                         'clear-right',
-                        'xs:clear-none'
+                        'xs:clear-none',
+                        'page-cover-background:text-contrast-cover'
                     )}
                 >
                     <PageIcon page={page} style={['text-tint-subtle ', 'shrink-0']} />
@@ -246,7 +250,15 @@ export async function PageHeader(props: {
                 </h1>
             ) : null}
             {page.description && page.layout.description ? (
-                <p className={tcls(CONTENT_STYLE_REDUCED, 'text-lg', 'text-tint', 'clear-both')}>
+                <p
+                    className={tcls(
+                        CONTENT_STYLE_REDUCED,
+                        'text-lg',
+                        'page-cover-background:text-contrast-cover',
+                        'text-tint contrast-more:text-tint-strong',
+                        'clear-both'
+                    )}
+                >
                     {page.description}
                 </p>
             ) : null}
diff --git a/packages/gitbook/src/components/RootLayout/globals.css b/packages/gitbook/src/components/RootLayout/globals.css
index 198997846..06a2f9d2c 100644
--- a/packages/gitbook/src/components/RootLayout/globals.css
+++ b/packages/gitbook/src/components/RootLayout/globals.css
@@ -2,8 +2,7 @@
 
 @config '../../../tailwind.config.ts';
 
-@import './prose.css';
-
+@import "./prose.css";
 
 /*
   The default border color has changed to `currentcolor` in Tailwind CSS v4,
@@ -14,37 +13,37 @@
   color utility to any element that depends on these defaults.
 */
 @layer base {
-    *,
-    ::after,
-    ::before,
-    ::backdrop,
-    ::file-selector-button {
-        border-color: var(--color-gray-200, currentcolor);
-    }
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-gray-200, currentcolor);
+  }
 }
 
 @utility no-scrollbar {
-    &::-webkit-scrollbar {
-        display: none;
-    }
-    scrollbar-width: none;
-    -ms-overflow-style: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+  scrollbar-width: none;
+  -ms-overflow-style: none;
 }
 
 @utility hide-scrollbar {
-    /* Hide scrollbar by default */
-    scrollbar-color: transparent transparent;
-    transition: scrollbar-color 0.2s ease-in-out;
+  /* Hide scrollbar by default */
+  scrollbar-color: transparent transparent;
+  transition: scrollbar-color 0.2s ease-in-out;
 
-    &:hover {
-        /* Show scrollbar on hover */
-        scrollbar-color: unset;
-    }
+  &:hover {
+    /* Show scrollbar on hover */
+    scrollbar-color: unset;
+  }
 
-    @media (prefers-contrast: more) {
-        /* Always show scrollbar in high contrast mode */
-        scrollbar-color: unset;
-    }
+  @media (prefers-contrast: more) {
+    /* Always show scrollbar in high contrast mode */
+    scrollbar-color: unset;
+  }
 }
 
 /*
@@ -55,137 +54,147 @@
   wrapper from React, so let pointer events pass through it for these tooltips only.
 */
 [data-radix-popper-content-wrapper]:has([data-non-interactive]) {
-    pointer-events: none;
+  pointer-events: none;
 }
 
 @utility linear-mask-gradient {
-    mask-image: linear-gradient(to bottom, rgba(0, 0, 0, 1) 96px, rgba(0, 0, 0, 0));
-    mask-image: linear-gradient(to bottom, rgba(0, 0, 0, 1) 96px, rgba(0, 0, 0, 0));
+  mask-image: linear-gradient(
+    to bottom,
+    rgba(0, 0, 0, 1) 96px,
+    rgba(0, 0, 0, 0)
+  );
+  mask-image: linear-gradient(
+    to bottom,
+    rgba(0, 0, 0, 1) 96px,
+    rgba(0, 0, 0, 0)
+  );
 }
 
 @utility linear-mask-util {
-    mask-image: linear-gradient(to bottom, white, white);
-    mask-image: linear-gradient(to bottom, white, white);
+  mask-image: linear-gradient(to bottom, white, white);
+  mask-image: linear-gradient(to bottom, white, white);
 }
 
 @utility grid-area-1-1 {
-    grid-area: 1 / 1;
-    grid-area: 1 / 1;
+  grid-area: 1 / 1;
+  grid-area: 1 / 1;
 }
 
 @utility gutter-stable {
-    scrollbar-gutter: stable;
+  scrollbar-gutter: stable;
 }
 
 @utility triangle {
-    position: relative;
-    background-color: orange;
-    text-align: left;
-    transform: rotate(-60deg) skewX(-30deg) scale(1, 0.866);
-    &:before {
-        content: "";
-        position: absolute;
-        background-color: inherit;
-    }
-    &:after {
-        content: "";
-        position: absolute;
-        background-color: inherit;
-    }
+  position: relative;
+  background-color: orange;
+  text-align: left;
+  transform: rotate(-60deg) skewX(-30deg) scale(1, 0.866);
+  &:before {
+    content: "";
+    position: absolute;
+    background-color: inherit;
+  }
+  &:after {
+    content: "";
+    position: absolute;
+    background-color: inherit;
+  }
+  width: inherit;
+  height: inherit;
+  border-top-right-radius: 30%;
+  &:before {
     width: inherit;
     height: inherit;
     border-top-right-radius: 30%;
-    &:before {
-        width: inherit;
-        height: inherit;
-        border-top-right-radius: 30%;
-    }
-    &:after {
-        width: inherit;
-        height: inherit;
-        border-top-right-radius: 30%;
-    }
-
-    &:before {
-        transform: rotate(-135deg) skewX(-45deg) scale(1.414, 0.707) translate(0, -50%);
-    }
-    &:after {
-        transform: rotate(135deg) skewY(-45deg) scale(0.707, 1.414) translate(50%);
-    }
-    position: relative;
-    background-color: orange;
-    text-align: left;
-    transform: rotate(-60deg) skewX(-30deg) scale(1, 0.866);
-    &:before {
-        content: "";
-        position: absolute;
-        background-color: inherit;
-    }
-    &:after {
-        content: "";
-        position: absolute;
-        background-color: inherit;
-    }
+  }
+  &:after {
     width: inherit;
     height: inherit;
     border-top-right-radius: 30%;
-    &:before {
-        width: inherit;
-        height: inherit;
-        border-top-right-radius: 30%;
-    }
-    &:after {
-        width: inherit;
-        height: inherit;
-        border-top-right-radius: 30%;
-    }
+  }
 
-    &:before {
-        transform: rotate(-135deg) skewX(-45deg) scale(1.414, 0.707) translate(0, -50%);
-    }
-    &:after {
-        transform: rotate(135deg) skewY(-45deg) scale(0.707, 1.414) translate(50%);
-    }
+  &:before {
+    transform: rotate(-135deg) skewX(-45deg) scale(1.414, 0.707)
+      translate(0, -50%);
+  }
+  &:after {
+    transform: rotate(135deg) skewY(-45deg) scale(0.707, 1.414) translate(50%);
+  }
+  position: relative;
+  background-color: orange;
+  text-align: left;
+  transform: rotate(-60deg) skewX(-30deg) scale(1, 0.866);
+  &:before {
+    content: "";
+    position: absolute;
+    background-color: inherit;
+  }
+  &:after {
+    content: "";
+    position: absolute;
+    background-color: inherit;
+  }
+  width: inherit;
+  height: inherit;
+  border-top-right-radius: 30%;
+  &:before {
+    width: inherit;
+    height: inherit;
+    border-top-right-radius: 30%;
+  }
+  &:after {
+    width: inherit;
+    height: inherit;
+    border-top-right-radius: 30%;
+  }
+
+  &:before {
+    transform: rotate(-135deg) skewX(-45deg) scale(1.414, 0.707)
+      translate(0, -50%);
+  }
+  &:after {
+    transform: rotate(135deg) skewY(-45deg) scale(0.707, 1.414) translate(50%);
+  }
 }
 
 @utility break-anywhere {
+  word-break: break-word;
+  @supports (overflow-wrap: anywhere) {
     word-break: break-word;
-    @supports (overflow-wrap: anywhere) {
-        word-break: break-word;
-        overflow-wrap: anywhere;
-    }
+    overflow-wrap: anywhere;
+  }
+  word-break: break-word;
+  @supports (overflow-wrap: anywhere) {
     word-break: break-word;
-    @supports (overflow-wrap: anywhere) {
-        word-break: break-word;
-        overflow-wrap: anywhere;
-    }
+    overflow-wrap: anywhere;
+  }
 }
 
 @utility bg-gradient-primary {
-    @apply bg-linear-to-bl from-primary-4 to-tint-base to-60% bg-fixed;
-    @apply bg-linear-to-bl from-primary-4 to-tint-base to-60% bg-fixed;
+  @apply bg-linear-to-bl from-primary-4 to-tint-base to-60% bg-fixed;
+  @apply bg-linear-to-bl from-primary-4 to-tint-base to-60% bg-fixed;
 }
 
 @utility bg-gradient-tint {
-    @apply bg-linear-to-bl from-tint-4 to-tint-base to-60% bg-fixed;
-    @apply bg-linear-to-bl from-tint-4 to-tint-base to-60% bg-fixed;
+  @apply bg-linear-to-bl from-tint-4 to-tint-base to-60% bg-fixed;
+  @apply bg-linear-to-bl from-tint-4 to-tint-base to-60% bg-fixed;
 }
 
 @utility site-background {
-    @apply [html.sidebar-filled.theme-bold.tint_&]:bg-tint-subtle;
-    @apply bg-tint-base;
-    @apply theme-muted:bg-tint-subtle;
+  @apply [html.sidebar-filled.theme-bold.tint_&]:bg-tint-subtle;
+  @apply bg-tint-base;
+  @apply theme-muted:bg-tint-subtle;
 
-    @apply theme-gradient:bg-gradient-primary;
-    @apply theme-gradient-tint:bg-gradient-tint;
+  @apply theme-gradient:bg-gradient-primary;
+  @apply theme-gradient-tint:bg-gradient-tint;
 }
 
 @utility elevate-link {
-    & a[href]:not(.link-overlay),
-    & [data-annotation] {
-        position: relative;
-        z-index: 20;
-    }
+  & a[href]:not(.link-overlay),
+  & [data-annotation] {
+    position: relative;
+    z-index: 20;
+  }
 }
 
 /*
@@ -197,141 +206,190 @@
   color utility to any element that depends on these defaults.
 */
 @layer base {
-    *,
-    ::after,
-    ::before,
-    ::backdrop,
-    ::file-selector-button {
-        border-color: var(--color-gray-200, currentcolor);
-    }
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-gray-200, currentcolor);
+  }
 }
 
 @layer base {
-    :root {
-        @apply leading-relaxed;
-        interpolate-size: allow-keywords; /* Opt-in for modern browsers to interpolate "auto" values in transitions/animations. */
-        overflow-x: hidden; /* We never want horizontal scroll of the whole page, it looks buggy and we should never have overflow anyway */
-        --ai-chat-width: 24rem; /* Default AI chat panel width (= AI_CHAT_DEFAULT_WIDTH 384px); overridden client-side from local storage. */
-    }
-    
-    /* Modern browsers with `scrollbar-*` support */
-    @supports (scrollbar-color: auto) {
-        * {
-            scrollbar-color: theme("colors.tint.7") transparent;
-            scrollbar-width: thin;
-        }
+  :root {
+    @apply leading-relaxed;
+    interpolate-size: allow-keywords; /* Opt-in for modern browsers to interpolate "auto" values in transitions/animations. */
+    overflow-x: hidden; /* We never want horizontal scroll of the whole page, it looks buggy and we should never have overflow anyway */
+    --ai-chat-width: 24rem; /* Default AI chat panel width (= AI_CHAT_DEFAULT_WIDTH 384px); overridden client-side from local storage. */
+    --cover-height: 0px;
+    --cover-text-top: rgb(var(--tint-12));
+    --cover-text-bottom: rgb(var(--tint-12));
+  }
 
-        @media (prefers-contrast: more) {
-            * {
-                scrollbar-color: theme("colors.tint.11") transparent;
-                scrollbar-width: auto;
-            }
-        }
-    }
-    
-    /* Otherwise, use `::-webkit-scrollbar-*` pseudo-elements */
-    @supports selector(::-webkit-scrollbar) {
-        ::-webkit-scrollbar {
-            background: transparent;
-            max-width: 8px;
-            max-height: 6px;
-        }
+  :root:not(.dark):has(
+      [data-gb-page-cover][data-cover-type="background"][data-cover-text-color="white"]
+    ),
+  :root.dark:has(
+      [data-gb-page-cover][data-cover-type="background"][data-cover-text-color-dark="black"]
+    ) {
+    --cover-text-top: rgb(var(--contrast-tint-12));
+  }
 
-        ::-webkit-scrollbar-thumb {
-            background: theme("colors.tint.7");
-            border-radius: 8px;
-            transition: background 0.2s ease-in-out;
-        }
-
-        ::-webkit-scrollbar-thumb:hover {
-            background: theme("colors.tint.8");
-        }
-
-        @media (prefers-contrast: more) {
-            ::-webkit-scrollbar-thumb {
-                background: theme("colors.tint.11");
-            }
-
-            ::-webkit-scrollbar-thumb:hover {
-                background: theme("colors.tint.12");
-            }
-        }
+  /* Modern browsers with `scrollbar-*` support */
+  @supports (scrollbar-color: auto) {
+    * {
+      scrollbar-color: theme("colors.tint.7") transparent;
+      scrollbar-width: thin;
     }
 
-
-    body {
-        @apply text-tint-strong antialiased;
-    }
-    html {
+    @media (prefers-contrast: more) {
+      * {
+        scrollbar-color: theme("colors.tint.11") transparent;
         scrollbar-width: auto;
+      }
     }
-    h1 {
-        @apply tracking-[-0.025em] text-tint-strong text-balance;
-    }
-    h2,
-    h3,
-    h4,
-    h5,
-    h6 {
-        @apply tracking-[-0.0125em] text-tint-strong;
+  }
+
+  /* Otherwise, use `::-webkit-scrollbar-*` pseudo-elements */
+  @supports selector(::-webkit-scrollbar) {
+    ::-webkit-scrollbar {
+      background: transparent;
+      max-width: 8px;
+      max-height: 6px;
     }
 
-    a,
-    button,
-    input,
-    textarea {
-        @apply focus-visible:outline-2 focus-visible:outline-primary;
+    ::-webkit-scrollbar-thumb {
+      background: theme("colors.tint.7");
+      border-radius: 8px;
+      transition: background 0.2s ease-in-out;
     }
 
-    button:not(:disabled),
-    [role="button"]:not(:disabled) {
-        cursor: pointer;
+    ::-webkit-scrollbar-thumb:hover {
+      background: theme("colors.tint.8");
     }
 
-    code,
-    pre {
-        /* Don't apply antialiased to `code` and `pre` elements */
-        @apply subpixel-antialiased;
+    @media (prefers-contrast: more) {
+      ::-webkit-scrollbar-thumb {
+        background: theme("colors.tint.11");
+      }
+
+      ::-webkit-scrollbar-thumb:hover {
+        background: theme("colors.tint.12");
+      }
     }
+  }
+
+  body {
+    @apply text-tint-strong antialiased;
+  }
+  html {
+    scrollbar-width: auto;
+  }
+  h1 {
+    @apply tracking-[-0.025em] text-tint-strong text-balance;
+  }
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    @apply tracking-[-0.0125em] text-tint-strong;
+  }
+
+  a,
+  button,
+  input,
+  textarea {
+    @apply focus-visible:outline-2 focus-visible:outline-primary;
+  }
+
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
+
+  code,
+  pre {
+    /* Don't apply antialiased to `code` and `pre` elements */
+    @apply subpixel-antialiased;
+  }
+}
+
+@utility contrast-cover {
+  background-clip: border-box;
+  background-image: linear-gradient(
+    to bottom,
+    var(--cover-text-top) 0,
+    var(--cover-text-top) var(--cover-height),
+    var(--cover-text-bottom) var(--cover-height),
+    var(--cover-text-bottom) 100vh
+  );
+  background-repeat: no-repeat;
+  background-size: 100% 100vh;
+  background-attachment: fixed;
+}
+
+@utility text-contrast-cover {
+  color: transparent;
+  -webkit-text-fill-color: transparent;
+  background-image: linear-gradient(
+    to bottom,
+    var(--cover-text-top) 0,
+    var(--cover-text-top) var(--cover-height),
+    var(--cover-text-bottom) var(--cover-height),
+    var(--cover-text-bottom) 100vh
+  );
+  background-repeat: no-repeat;
+  background-size: 100% 100vh;
+  background-attachment: fixed;
+  background-clip: text;
+  -webkit-background-clip: text;
+
+  @media (prefers-contrast: more) {
+    color: var(--cover-text-bottom);
+    -webkit-text-fill-color: var(--cover-text-bottom);
+    background-image: none;
+  }
 }
 
 html {
-    color-scheme: light;
+  color-scheme: light;
 
-    /** Ensure PDF export and print correctly displays the background colors */
-    print-color-adjust: exact;
-    -webkit-print-color-adjust: exact;
+  /** Ensure PDF export and print correctly displays the background colors */
+  print-color-adjust: exact;
+  -webkit-print-color-adjust: exact;
 }
 html.dark {
-    color-scheme: dark light;
+  color-scheme: dark light;
 }
 
 /** While the AI chat panel is being resized, suppress transitions */
 html[data-ai-chat-resizing="true"] {
-    cursor: col-resize;
-    user-select: none;
+  cursor: col-resize;
+  user-select: none;
 }
 html[data-ai-chat-resizing="true"] * {
-    transition-duration: 0s !important;
+  transition-duration: 0s !important;
 }
 
 html.announcement-hidden [data-gb-announcement-banner] {
-    @apply hidden;
+  @apply hidden;
 }
 
 html.font-Lato {
-    /* Lato's default ligatures impact readability, so we turn them off */
-    font-variant-ligatures: no-common-ligatures;
+  /* Lato's default ligatures impact readability, so we turn them off */
+  font-variant-ligatures: no-common-ligatures;
 }
 
 /* Code blocks */
 /* Shiki themes can define font styling (style, weight, decoration) via CSS variables.
  * These variables are prefixed with --shiki-{mode}-{property} and allow themes to customize
  * typography beyond just colors. We apply them here so code blocks respect theme font styling. */
-.shiki, .shiki span {
-    font-style: var(--shiki-light-font-style) !important;
-    font-weight: var(--shiki-light-font-weight) !important;
-    text-decoration: var(--shiki-light-text-decoration) !important;
+.shiki,
+.shiki span {
+  font-style: var(--shiki-light-font-style) !important;
+  font-weight: var(--shiki-light-font-weight) !important;
+  text-decoration: var(--shiki-light-text-decoration) !important;
 }
 
 html.dark .shiki,
@@ -342,29 +400,29 @@ html.dark .shiki span {
 }
 
 .highlight-line {
-    @apply min-w-min text-tint-strong table-row bg-tint-subtle theme-muted:bg-tint-base theme-bold-tint:bg-tint-base relative hover:invert-5 hover:z-1 rounded-sm;
-    @apply only:hover:ring-transparent;
-    @apply [counter-increment:line];
+  @apply min-w-min text-tint-strong table-row bg-tint-subtle theme-muted:bg-tint-base theme-bold-tint:bg-tint-base relative hover:invert-5 hover:z-1 rounded-sm;
+  @apply only:hover:ring-transparent;
+  @apply [counter-increment:line];
 
-    &.highlighted {
-        /* Use `invert-` to get a dynamic color that contrasts with the background, regardless of the codeblock's theme. */
-        @apply bg-tint-base invert-10 hover:invert-15;
-        @apply first:rounded-t-md first:*:mt-1;
-        @apply last:rounded-b-md last:*:mb-1;
-        @apply rounded-none;
-    }
+  &.highlighted {
+    /* Use `invert-` to get a dynamic color that contrasts with the background, regardless of the codeblock's theme. */
+    @apply bg-tint-base invert-10 hover:invert-15;
+    @apply first:rounded-t-md first:*:mt-1;
+    @apply last:rounded-b-md last:*:mb-1;
+    @apply rounded-none;
+  }
 
-    &:not(.highlighted) + .highlighted {
-        @apply rounded-t-md *:mt-1;
-    }
+  &:not(.highlighted) + .highlighted {
+    @apply rounded-t-md *:mt-1;
+  }
 
-    &.highlighted:has(+ :not(.highlighted)) {
-        @apply rounded-b-md *:mb-1;
-    }
+  &.highlighted:has(+ :not(.highlighted)) {
+    @apply rounded-b-md *:mb-1;
+  }
 
-    &:not(.highlighted) + .highlighted:has(+ :not(.highlighted)) {
-        @apply rounded-md;
-    }
+  &:not(.highlighted) + .highlighted:has(+ :not(.highlighted)) {
+    @apply rounded-md;
+  }
 }
 
 /*
@@ -381,70 +439,70 @@ html.dark .shiki span {
  * otherwise muddy the tint.
  */
 .highlight-line.diff-added {
-    background-color: #e1f8ec !important; /* gbx --green-3 (light) */
-    @apply rounded-md;
+  background-color: #e1f8ec !important; /* gbx --green-3 (light) */
+  @apply rounded-md;
 }
 .highlight-line.diff-deleted {
-    background-color: #ffeae6 !important; /* gbx --red-3 (light) */
-    @apply rounded-md;
+  background-color: #ffeae6 !important; /* gbx --red-3 (light) */
+  @apply rounded-md;
 }
 .highlight-line.diff-added.highlighted {
-    background-color: #baebd3 !important; /* gbx --green-5 (light) */
-    filter: none !important;
+  background-color: #baebd3 !important; /* gbx --green-5 (light) */
+  filter: none !important;
 }
 .highlight-line.diff-deleted.highlighted {
-    background-color: #ffcac0 !important; /* gbx --red-5 (light) */
-    filter: none !important;
+  background-color: #ffcac0 !important; /* gbx --red-5 (light) */
+  filter: none !important;
 }
 
 html.dark .highlight-line.diff-added {
-    background-color: #113023 !important; /* gbx --green-3 (dark) */
+  background-color: #113023 !important; /* gbx --green-3 (dark) */
 }
 html.dark .highlight-line.diff-deleted {
-    background-color: #411510 !important; /* gbx --red-3 (dark) */
+  background-color: #411510 !important; /* gbx --red-3 (dark) */
 }
 html.dark .highlight-line.diff-added.highlighted {
-    background-color: #064b34 !important; /* gbx --green-5 (dark) */
-    filter: none !important;
+  background-color: #064b34 !important; /* gbx --green-5 (dark) */
+  filter: none !important;
 }
 html.dark .highlight-line.diff-deleted.highlighted {
-    background-color: #67100a !important; /* gbx --red-5 (dark) */
-    filter: none !important;
+  background-color: #67100a !important; /* gbx --red-5 (dark) */
+  filter: none !important;
 }
 
 .highlight-line-number {
-    @apply table-cell whitespace-nowrap w-0 text-sm text-tint pl-4 pr-2 text-right bg-tint-subtle theme-muted:bg-tint-base theme-bold-tint:bg-tint-base sticky -left-2;
-    @apply before:content-[counter(line)] not-contrast-more:before:opacity-6;
+  @apply table-cell whitespace-nowrap w-0 text-sm text-tint pl-4 pr-2 text-right bg-tint-subtle theme-muted:bg-tint-base theme-bold-tint:bg-tint-base sticky -left-2;
+  @apply before:content-[counter(line)] not-contrast-more:before:opacity-6;
 
-    .highlighted & {
-        @apply bg-tint-base
-    }
+  .highlighted & {
+    @apply bg-tint-base;
+  }
 }
 
 /* Diff line gutter (line numbers) — same tint as the line itself. */
 .diff-added > .highlight-line-number {
-    background-color: #e1f8ec !important;
+  background-color: #e1f8ec !important;
 }
 .diff-deleted > .highlight-line-number {
-    background-color: #ffeae6 !important;
+  background-color: #ffeae6 !important;
 }
 .diff-added.highlighted > .highlight-line-number {
-    background-color: #baebd3 !important;
+  background-color: #baebd3 !important;
 }
 .diff-deleted.highlighted > .highlight-line-number {
-    background-color: #ffcac0 !important;
+  background-color: #ffcac0 !important;
 }
 html.dark .diff-added > .highlight-line-number {
-    background-color: #113023 !important;
+  background-color: #113023 !important;
 }
 html.dark .diff-deleted > .highlight-line-number {
-    background-color: #411510 !important;
+  background-color: #411510 !important;
 }
 html.dark .diff-added.highlighted > .highlight-line-number {
-    background-color: #064b34 !important;
+  background-color: #064b34 !important;
 }
 html.dark .diff-deleted.highlighted > .highlight-line-number {
-    background-color: #67100a !important;
+  background-color: #67100a !important;
 }
 
 /*
@@ -455,32 +513,31 @@ html.dark .diff-deleted.highlighted > .highlight-line-number {
  */
 .highlight-line.diff-added .highlight-line-content::before,
 .highlight-line.diff-deleted .highlight-line-content::before {
-    display: inline-block;
-    width: 1ch;
-    margin-right: 0.5ch;
-    font-weight: 600;
-    user-select: none;
+  display: inline-block;
+  width: 1ch;
+  margin-right: 0.5ch;
+  font-weight: 600;
+  user-select: none;
 }
 .highlight-line.diff-added .highlight-line-content::before {
-    content: "+";
-    color: #247758; /* gbx --green-11 light */
+  content: "+";
+  color: #247758; /* gbx --green-11 light */
 }
 .highlight-line.diff-deleted .highlight-line-content::before {
-    content: "\2212"; /* U+2212 minus sign — visually clearer than a hyphen */
-    color: #de0000; /* gbx --red-11 light */
+  content: "\2212"; /* U+2212 minus sign — visually clearer than a hyphen */
+  color: #de0000; /* gbx --red-11 light */
 }
 html.dark .highlight-line.diff-added .highlight-line-content::before {
-    color: #6ecea5; /* gbx --green-11 dark */
+  color: #6ecea5; /* gbx --green-11 dark */
 }
 html.dark .highlight-line.diff-deleted .highlight-line-content::before {
-    color: #ff9080; /* gbx --red-11 dark */
+  color: #ff9080; /* gbx --red-11 dark */
 }
 
-
 .highlight-line-content {
-    @apply table-cell text-sm px-4;
+  @apply table-cell text-sm px-4;
 
-    .highlight-line-number + & {
-        @apply pl-2;
-    }
+  .highlight-line-number + & {
+    @apply pl-2;
+  }
 }
diff --git a/packages/gitbook/src/components/SitePage/PageClientLayout.tsx b/packages/gitbook/src/components/SitePage/PageClientLayout.tsx
index 9b9ed2e59..8808433ca 100644
--- a/packages/gitbook/src/components/SitePage/PageClientLayout.tsx
+++ b/packages/gitbook/src/components/SitePage/PageClientLayout.tsx
@@ -24,6 +24,7 @@ export function PageClientLayout({
     useRegisterPageMetadata({ pageMetaLinks });
 
     useStripFallbackQueryParam();
+    useSetCoverHeight();
     return null;
 }
 
@@ -60,3 +61,78 @@ function useRegisterPageMetadata(metadata: {
         currentPageMetadataStore.setState({ metaLinks: pageMetaLinks });
     }, [pageMetaLinks]);
 }
+
+/**
+ * Expose the visible bottom edge of the page cover as a viewport-relative CSS variable.
+ */
+function useSetCoverHeight() {
+    React.useEffect(() => {
+        const root = document.documentElement;
+        let animationFrame: number | null = null;
+
+        const updateCoverHeight = () => {
+            const pageCover = document.querySelector<HTMLElement>('[data-gb-page-cover]');
+            const isBackgroundCover = pageCover?.dataset.coverType === 'background';
+
+            if (!isBackgroundCover) {
+                root.style.setProperty('--cover-height', '0px');
+                return;
+            }
+
+            if (!pageCover) {
+                return;
+            }
+
+            const bottom = pageCover.getBoundingClientRect().bottom;
+            const height = Math.max(Math.min(bottom, window.innerHeight), 0);
+
+            root.style.setProperty('--cover-height', `${height}px`);
+        };
+
+        const scheduleUpdate = () => {
+            if (animationFrame !== null) {
+                return;
+            }
+
+            animationFrame = requestAnimationFrame(() => {
+                animationFrame = null;
+                updateCoverHeight();
+            });
+        };
+
+        scheduleUpdate();
+
+        window.addEventListener('scroll', scheduleUpdate, { passive: true });
+        window.addEventListener('resize', scheduleUpdate, { passive: true });
+
+        const pageCover = document.querySelector<HTMLElement>('[data-gb-page-cover]');
+        const resizeObserver =
+            pageCover && typeof ResizeObserver !== 'undefined'
+                ? new ResizeObserver(() => {
+                      scheduleUpdate();
+                  })
+                : null;
+
+        if (pageCover && resizeObserver) {
+            resizeObserver.observe(pageCover);
+        }
+
+        // Dismissing the announcement banner only toggles a class on <html> (see
+        // dismissAnnouncement) — no scroll/resize event and no cover resize — yet it shifts the
+        // cover up. Watch <html> class changes so the cover height is recomputed in that case too.
+        const classObserver =
+            typeof MutationObserver !== 'undefined' ? new MutationObserver(scheduleUpdate) : null;
+        classObserver?.observe(root, { attributes: true, attributeFilter: ['class'] });
+
+        return () => {
+            if (animationFrame !== null) {
+                cancelAnimationFrame(animationFrame);
+            }
+
+            resizeObserver?.disconnect();
+            classObserver?.disconnect();
+            window.removeEventListener('scroll', scheduleUpdate);
+            window.removeEventListener('resize', scheduleUpdate);
+        };
+    }, []);
+}
diff --git a/packages/gitbook/src/components/SitePage/SitePage.tsx b/packages/gitbook/src/components/SitePage/SitePage.tsx
index 684115f3b..02b3083f6 100644
--- a/packages/gitbook/src/components/SitePage/SitePage.tsx
+++ b/packages/gitbook/src/components/SitePage/SitePage.tsx
@@ -81,9 +81,18 @@ export async function SitePage(props: SitePageProps & { staticRoute: boolean })
         <>
             {/* Using `contents` makes the children of this div according to its parent — which keeps them in a single flex row with the TOC by default.
             If there's a page cover, we use `flex flex-col` to lay out the PageCover above the PageBody + PageAside instead. */}
-            <div className={withFullPageCover && page.cover ? 'flex grow flex-col' : 'contents'}>
+            <div
+                className={
+                    withFullPageCover && page.cover ? 'relative flex grow flex-col' : 'contents'
+                }
+            >
                 {withFullPageCover && page.cover ? (
-                    <PageCover as="full" page={page} cover={page.cover} context={context} />
+                    <PageCover
+                        as={page.layout.coverSize === 'background' ? 'background' : 'full'}
+                        page={page}
+                        cover={page.cover}
+                        context={context}
+                    />
                 ) : null}
 
                 <div
@@ -272,7 +281,7 @@ export async function getSitePageData(props: SitePageProps) {
     const withFullPageCover = !!(
         page.cover &&
         page.layout.cover &&
-        page.layout.coverSize === 'full'
+        (page.layout.coverSize === 'full' || page.layout.coverSize === 'background')
     );
     const withPageFeedback = customization.feedback.enabled;
 
diff --git a/packages/gitbook/src/components/primitives/Button.tsx b/packages/gitbook/src/components/primitives/Button.tsx
index ebe422e30..bc6817659 100644
--- a/packages/gitbook/src/components/primitives/Button.tsx
+++ b/packages/gitbook/src/components/primitives/Button.tsx
@@ -58,7 +58,7 @@ export const variantClasses = {
     ],
     secondary: [
         'bg-tint',
-        'depth-flat:bg-transparent',
+        'depth-flat:bg-tint-base',
         'text-tint',
         'hover:bg-tint-hover',
         'hover:not-disabled:depth-flat:bg-tint-hover',
diff --git a/packages/gitbook/tailwind.config.ts b/packages/gitbook/tailwind.config.ts
index 270e50a5a..96ce36691 100644
--- a/packages/gitbook/tailwind.config.ts
+++ b/packages/gitbook/tailwind.config.ts
@@ -770,6 +770,14 @@ const config: Config = {
              */
             addVariant('page-api-block', 'body:has(.openapi-block) &');
 
+            /**
+             * Variant for the page cover type
+             */
+            addVariant(
+                'page-cover-background',
+                'body:has([data-gb-page-cover][data-cover-type="background"]) &'
+            );
+
             /**
              * Variant when the page is displayed in print mode.
              */

From 1b571aeaa972752c1f41555b8567d9ed6d7ecb51 Mon Sep 17 00:00:00 2001
From: conico974 <nicodorseuil@yahoo.fr>
Date: Thu, 16 Jul 2026 14:21:01 +0200
Subject: [PATCH 39/46] Fix scroll behavior for navigation (#4406)

---
 packages/gitbook/src/components/hooks/useScrollPage.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/gitbook/src/components/hooks/useScrollPage.ts b/packages/gitbook/src/components/hooks/useScrollPage.ts
index a2751b317..bb5363639 100644
--- a/packages/gitbook/src/components/hooks/useScrollPage.ts
+++ b/packages/gitbook/src/components/hooks/useScrollPage.ts
@@ -85,7 +85,9 @@ function scrollToHash(hash: string) {
     if (element) {
         element.scrollIntoView({
             block: 'start',
-            behavior: 'smooth',
+            // Looks like there is a bug when using smooth scroll on navigation between pages.
+            // The browser does not scroll, probably some kind of browser optimization.
+            behavior: 'instant',
         });
         return true;
     }

From 703e654a37bcfe1d83d318786039733e696c9546 Mon Sep 17 00:00:00 2001
From: Utku Ufuk <utkuufuk@gmail.com>
Date: Thu, 16 Jul 2026 15:23:30 +0300
Subject: [PATCH 40/46] Split the default-scope site search into two parallel
 API requests (#4395)

---
 .changeset/split-site-search-requests.md      |   5 +
 .../Search/reciprocalRankFusion.test.ts       |   4 +-
 .../components/Search/reciprocalRankFusion.ts |   2 +-
 .../src/components/Search/search-types.ts     |   7 +-
 .../src/components/Search/useSearchResults.ts | 203 +++++++++++++-----
 packages/gitbook/src/lib/data/api.ts          |  13 +-
 packages/gitbook/src/lib/data/types.ts        |   7 +-
 7 files changed, 187 insertions(+), 54 deletions(-)
 create mode 100644 .changeset/split-site-search-requests.md

diff --git a/.changeset/split-site-search-requests.md b/.changeset/split-site-search-requests.md
new file mode 100644
index 000000000..53238f16f
--- /dev/null
+++ b/.changeset/split-site-search-requests.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Split the default-scope site search into two parallel API requests — one restricted to the current site space and one for the other site spaces — rendering each result set as soon as its response arrives. All results are ranked together by score, with the current site space scores boosted.
diff --git a/packages/gitbook/src/components/Search/reciprocalRankFusion.test.ts b/packages/gitbook/src/components/Search/reciprocalRankFusion.test.ts
index 3beb39767..00e61ffb1 100644
--- a/packages/gitbook/src/components/Search/reciprocalRankFusion.test.ts
+++ b/packages/gitbook/src/components/Search/reciprocalRankFusion.test.ts
@@ -14,7 +14,7 @@ function localPage(id: string, title = id): LocalPageResult {
     };
 }
 
-function remotePage(id: string, title = id): OrderedComputedResult {
+function remotePage(id: string, title = id, score = 0): OrderedComputedResult {
     return {
         type: 'page',
         id: `remote-${id}`,
@@ -22,7 +22,7 @@ function remotePage(id: string, title = id): OrderedComputedResult {
         spaceId: 'space',
         title,
         href: `/${id}`,
-        score: 0,
+        score,
         breadcrumbs: [{ label: 'Remote' }],
     };
 }
diff --git a/packages/gitbook/src/components/Search/reciprocalRankFusion.ts b/packages/gitbook/src/components/Search/reciprocalRankFusion.ts
index a610627ce..1ba9fab7c 100644
--- a/packages/gitbook/src/components/Search/reciprocalRankFusion.ts
+++ b/packages/gitbook/src/components/Search/reciprocalRankFusion.ts
@@ -133,7 +133,7 @@ function mergePinnedRemoteResult(
 
 /**
  * Merge local (FlexSearch) and remote (API) search results using
- * Reciprocal Rank Fusion (RRF), while preserving the API order for the first
+ * Reciprocal Rank Fusion (RRF), while preserving the order of the first
  * three remote results.
  *
  * RRF formula: score(d) = Σ_i  1 / (k + rank_i(d))
diff --git a/packages/gitbook/src/components/Search/search-types.ts b/packages/gitbook/src/components/Search/search-types.ts
index 32af60a7d..b1751edcf 100644
--- a/packages/gitbook/src/components/Search/search-types.ts
+++ b/packages/gitbook/src/components/Search/search-types.ts
@@ -37,7 +37,12 @@ export type ComputedRecordResult = BaseComputedResult & {
 
 export type SearchSiteContentScope =
     | { mode: 'all' }
-    | { mode: 'current'; siteSpaceId: string }
+    | {
+          mode: 'current';
+          siteSpaceId: string;
+          /** Restrict the search to the current site space alone, or to the other site spaces in the scope. */
+          restrictTo?: 'currentSiteSpace' | 'otherSiteSpaces';
+      }
     | { mode: 'specific'; siteSpaceIds: string[] };
 
 export interface SearchSiteContentRequest {
diff --git a/packages/gitbook/src/components/Search/useSearchResults.ts b/packages/gitbook/src/components/Search/useSearchResults.ts
index dace56f30..f98f590a6 100644
--- a/packages/gitbook/src/components/Search/useSearchResults.ts
+++ b/packages/gitbook/src/components/Search/useSearchResults.ts
@@ -8,7 +8,7 @@ import {
     createRecommendedQuestionResult,
     getEmptySearchResults,
 } from './empty-search-results';
-import type { OrderedComputedResult } from './search-types';
+import type { OrderedComputedResult, SearchSiteContentScope } from './search-types';
 import { streamRecommendedQuestions } from './server-actions';
 
 import { useAI } from '@/components/AI';
@@ -28,6 +28,9 @@ export type ResultType =
 
 export type { LocalPageResult, MergedPageResult };
 
+// Score multiplier for current site space results when combined with those from other site spaces
+const CURRENT_SITE_SPACE_SCORE_MULTIPLIER = 2;
+
 // Small helper extracted for unit testing of scope → local filter mapping
 // computeFilterSiteSpaceIds is imported from './filter' for testability
 
@@ -87,9 +90,10 @@ export function useSearchResults(props: {
 
     const [remoteState, setRemoteState] = React.useState<{
         results: OrderedComputedResult[];
+        otherSpacesResults: OrderedComputedResult[];
         fetching: boolean;
         error: boolean;
-    }>({ results: [], fetching: false, error: false });
+    }>({ results: [], otherSpacesResults: [], fetching: false, error: false });
 
     // Track the current in-flight fetch so it can be aborted imperatively
     // when the user navigates away before the request completes.
@@ -105,7 +109,12 @@ export function useSearchResults(props: {
         }
         if (!query) {
             if (!withAI) {
-                setRemoteState({ results: [], fetching: false, error: false });
+                setRemoteState({
+                    results: [],
+                    otherSpacesResults: [],
+                    fetching: false,
+                    error: false,
+                });
                 return;
             }
 
@@ -116,11 +125,21 @@ export function useSearchResults(props: {
                     `Cached recommended questions should be set for site-space ${siteSpaceId}`
                 );
                 // Recommended questions are stored as ResultType[] already
-                setRemoteState({ results: [], fetching: false, error: false });
+                setRemoteState({
+                    results: [],
+                    otherSpacesResults: [],
+                    fetching: false,
+                    error: false,
+                });
                 return;
             }
 
-            setRemoteState({ results: [], fetching: false, error: false });
+            setRemoteState({
+                results: [],
+                otherSpacesResults: [],
+                fetching: false,
+                error: false,
+            });
 
             let cancelled = false;
 
@@ -133,7 +152,12 @@ export function useSearchResults(props: {
                 suggestions.forEach((question) => {
                     questions.add(question);
                 });
-                setRemoteState({ results: [], fetching: false, error: false });
+                setRemoteState({
+                    results: [],
+                    otherSpacesResults: [],
+                    fetching: false,
+                    error: false,
+                });
                 return;
             }
 
@@ -159,7 +183,12 @@ export function useSearchResults(props: {
 
                     if (!cancelled) {
                         // Recommended questions are handled via a separate path below
-                        setRemoteState({ results: [], fetching: false, error: false });
+                        setRemoteState({
+                            results: [],
+                            otherSpacesResults: [],
+                            fetching: false,
+                            error: false,
+                        });
                     }
                 }
             }, 100);
@@ -171,67 +200,121 @@ export function useSearchResults(props: {
         }
         setRemoteState({
             results: [],
+            otherSpacesResults: [],
             fetching: true,
             error: false,
         });
         let cancelled = false;
         const abortController = new AbortController();
         const timeout = setTimeout(async () => {
-            try {
-                const results = await (() => {
-                    const fetchSearch = (
-                        scope: Parameters<typeof fetchSearchResults>[1]
-                    ): Promise<OrderedComputedResult[]> =>
-                        fetchSearchResults(
-                            searchURL,
-                            scope,
-                            query,
-                            abortController.signal,
-                            asEmbeddable
-                        );
+            const fetchSearch = (
+                scope: Parameters<typeof fetchSearchResults>[1]
+            ): Promise<OrderedComputedResult[]> =>
+                fetchSearchResults(searchURL, scope, query, abortController.signal, asEmbeddable);
 
+            try {
+                // Each scope resolves to a primary search request and, for the default scope
+                // on a multi-section site, a secondary request for the other site spaces
+                const { resultsPromise, otherSpacesResultsPromise } = ((): {
+                    resultsPromise: Promise<OrderedComputedResult[]>;
+                    otherSpacesResultsPromise?: Promise<OrderedComputedResult[]>;
+                } => {
                     switch (scope) {
                         case 'all':
                             // Search all content on the site
-                            return fetchSearch({ mode: 'all' });
+                            return { resultsPromise: fetchSearch({ mode: 'all' }) };
                         case 'default':
-                            // Search the current section's variant + matched/default variant for other sections
-                            return fetchSearch({ mode: 'current', siteSpaceId });
+                            // Search the current section's variant + matched/default variant for other sections.
+                            // Without sections, the scope resolves to the current site space alone, so a
+                            // second request restricted to the other site spaces would be redundant.
+                            if (!withSections) {
+                                return {
+                                    resultsPromise: fetchSearch({ mode: 'current', siteSpaceId }),
+                                };
+                            }
+
+                            // Split into two parallel requests so the (smaller, faster) current site
+                            // space results can be shown while the other site spaces are still being searched.
+                            return {
+                                resultsPromise: fetchSearch({
+                                    mode: 'current',
+                                    siteSpaceId,
+                                    restrictTo: 'currentSiteSpace',
+                                }),
+                                otherSpacesResultsPromise: fetchSearch({
+                                    mode: 'current',
+                                    siteSpaceId,
+                                    restrictTo: 'otherSiteSpaces',
+                                }),
+                            };
                         case 'extended':
                             // Search all variants of the current section
-                            return fetchSearch({ mode: 'specific', siteSpaceIds });
+                            return {
+                                resultsPromise: fetchSearch({ mode: 'specific', siteSpaceIds }),
+                            };
                         case 'current':
                             // Search only the current section's current variant
-                            return fetchSearch({ mode: 'specific', siteSpaceIds: [siteSpaceId] });
+                            return {
+                                resultsPromise: fetchSearch({
+                                    mode: 'specific',
+                                    siteSpaceIds: [siteSpaceId],
+                                }),
+                            };
                         default:
                             assertNever(scope);
                     }
                 })();
 
+                // Render each result set as soon as its response arrives; a failed
+                // request reports an error without discarding the other result set.
+                let tracked = false;
+                const onResults =
+                    (key: 'results' | 'otherSpacesResults') =>
+                    (results: OrderedComputedResult[]) => {
+                        if (cancelled) {
+                            return;
+                        }
+
+                        if (!results) {
+                            // Can happen when the route cannot be found and returns the page's html.
+                            setRemoteState((prev) => ({ ...prev, error: true }));
+                            return;
+                        }
+
+                        setRemoteState((prev) => ({ ...prev, [key]: results }));
+
+                        if (!tracked) {
+                            tracked = true;
+                            trackEvent({ type: 'search_type_query', query });
+                        }
+                    };
+                const onError = () => {
+                    if (cancelled) {
+                        return;
+                    }
+                    setRemoteState((prev) => ({ ...prev, error: true }));
+                };
+
+                await Promise.all([
+                    resultsPromise.then(onResults('results'), onError),
+                    otherSpacesResultsPromise?.then(onResults('otherSpacesResults'), onError),
+                ]);
+
                 if (cancelled) {
                     return;
                 }
-
-                if (!results) {
-                    // One time when this one returns undefined is when it cannot find the server action and returns the html from the page.
-                    // In that case, we want to avoid being stuck in a loading state, but it is an error.
-                    // We could potentially try to force reload the page here, but i'm not 100% sure it would be a better experience.
-                    setRemoteState({ results: [], fetching: false, error: true });
-                    return;
-                }
-
-                setRemoteState({ results, fetching: false, error: false });
-
-                trackEvent({
-                    type: 'search_type_query',
-                    query,
-                });
+                setRemoteState((prev) => ({ ...prev, fetching: false }));
             } catch {
                 // If there is an error, we need to catch it to avoid infinite loading state.
                 if (cancelled) {
                     return;
                 }
-                setRemoteState({ results: [], fetching: false, error: true });
+                setRemoteState({
+                    results: [],
+                    otherSpacesResults: [],
+                    fetching: false,
+                    error: true,
+                });
             }
         }, 200);
 
@@ -258,6 +341,7 @@ export function useSearchResults(props: {
         suggestions,
         searchURL,
         asEmbeddable,
+        withSections,
     ]);
 
     const abort = React.useCallback(() => {
@@ -284,10 +368,23 @@ export function useSearchResults(props: {
             });
         }
 
-        const merged = reciprocalRankFusion(localResults, remoteState.results, query);
-
-        return merged;
-    }, [localResults, remoteState.results, query, withAI, siteSpaceId, suggestions, recentQueries]);
+        return reciprocalRankFusion(
+            localResults,
+            remoteState.otherSpacesResults.length > 0
+                ? combineRemoteResults(remoteState.results, remoteState.otherSpacesResults)
+                : remoteState.results,
+            query
+        );
+    }, [
+        localResults,
+        remoteState.results,
+        remoteState.otherSpacesResults,
+        query,
+        withAI,
+        siteSpaceId,
+        suggestions,
+        recentQueries,
+    ]);
 
     return {
         results,
@@ -302,10 +399,7 @@ export function useSearchResults(props: {
  */
 async function fetchSearchResults(
     searchURL: string,
-    scope:
-        | { mode: 'all' }
-        | { mode: 'current'; siteSpaceId: string }
-        | { mode: 'specific'; siteSpaceIds: string[] },
+    scope: SearchSiteContentScope,
     query: string,
     signal?: AbortSignal,
     asEmbeddable?: boolean
@@ -327,3 +421,16 @@ async function fetchSearchResults(
 
     return response.json() as Promise<OrderedComputedResult[]>;
 }
+
+function combineRemoteResults(
+    remoteResultsCurrentSpace: OrderedComputedResult[],
+    remoteResultsOtherSpaces: OrderedComputedResult[]
+): OrderedComputedResult[] {
+    return [
+        ...remoteResultsCurrentSpace.map((result) => ({
+            ...result,
+            score: result.score * CURRENT_SITE_SPACE_SCORE_MULTIPLIER,
+        })),
+        ...remoteResultsOtherSpaces,
+    ].sort((a, b) => b.score - a.score);
+}
diff --git a/packages/gitbook/src/lib/data/api.ts b/packages/gitbook/src/lib/data/api.ts
index fa5704904..36276df24 100644
--- a/packages/gitbook/src/lib/data/api.ts
+++ b/packages/gitbook/src/lib/data/api.ts
@@ -5,6 +5,7 @@ import {
     GitBookAPI,
     type HttpResponse,
     type RenderIntegrationUI,
+    type SiteSearchScope,
 } from '@gitbook/api';
 import { getCacheTag, getComputedContentSourceCacheTags } from '@gitbook/cache-tags';
 import { parse as parseCacheControl } from '@tusbar/cache-control';
@@ -785,7 +786,17 @@ const searchSiteContent = cache(
                         siteId,
                         {
                             query,
-                            ...scope,
+                            ...(scope.mode === 'current' && scope.restrictTo
+                                ? {
+                                      // `restrictTo` only exists in the newer `scope` request shape,
+                                      // and the published @gitbook/api types don't include it yet.
+                                      scope: {
+                                          mode: 'default',
+                                          currentSiteSpace: scope.siteSpaceId,
+                                          restrictTo: scope.restrictTo,
+                                      } as SiteSearchScope,
+                                  }
+                                : scope),
                         },
                         {},
                         {
diff --git a/packages/gitbook/src/lib/data/types.ts b/packages/gitbook/src/lib/data/types.ts
index 878479f98..94fd768e2 100644
--- a/packages/gitbook/src/lib/data/types.ts
+++ b/packages/gitbook/src/lib/data/types.ts
@@ -178,7 +178,12 @@ export interface GitBookDataFetcher {
         query: string;
         scope:
             | { mode: 'all' }
-            | { mode: 'current'; siteSpaceId: string }
+            | {
+                  mode: 'current';
+                  siteSpaceId: string;
+                  /** Restrict the search to the current site space alone, or to the other site spaces in the scope. */
+                  restrictTo?: 'currentSiteSpace' | 'otherSiteSpaces';
+              }
             | { mode: 'specific'; siteSpaceIds: string[] };
         /** Cache bust to ensure the search results are fresh when the space is updated. */
         cacheBust?: string;

From bf6a7af72b0121c87aa34e13f9abfe49787e7e0b Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Thu, 16 Jul 2026 21:53:24 +0200
Subject: [PATCH 41/46] Defer search index loading until search is opened
 (#4407)

---
 .../src/components/Search/SearchContainer.tsx | 20 ++++-
 .../src/components/Search/site-index.ts       | 79 +++++++++++++++++++
 .../Search/useLocalSearchResults.tsx          | 71 +++++++++--------
 .../components/Search/useSearchController.tsx |  1 +
 .../src/components/Search/useSearchResults.ts |  6 +-
 .../src/components/SiteLayout/SiteLayout.tsx  |  5 +-
 .../components/SitePage/SitePageNotFound.tsx  | 24 ++----
 7 files changed, 149 insertions(+), 57 deletions(-)
 create mode 100644 packages/gitbook/src/components/Search/site-index.ts

diff --git a/packages/gitbook/src/components/Search/SearchContainer.tsx b/packages/gitbook/src/components/Search/SearchContainer.tsx
index 452eff295..57ddb214b 100644
--- a/packages/gitbook/src/components/Search/SearchContainer.tsx
+++ b/packages/gitbook/src/components/Search/SearchContainer.tsx
@@ -3,6 +3,7 @@
 import { t, useLanguage } from '@/intl/client';
 import { tcls } from '@/lib/tailwind';
 import { CustomizationSearchStyle } from '@gitbook/api';
+import dynamic from 'next/dynamic';
 import React, { useRef } from 'react';
 import { useHotkeys } from 'react-hotkeys-hook';
 import { AIChatButton } from '../AIChat';
@@ -10,13 +11,16 @@ import { useIsMobile } from '../hooks/useIsMobile';
 import { Button, Popover } from '../primitives';
 import { KeyboardShortcut } from '../primitives/KeyboardShortcut';
 import { SideSheet } from '../primitives/SideSheet';
-import { SearchFrame } from './SearchFrame';
 import { SearchInput } from './SearchInput';
 import { SearchLiveResultsAnnouncer } from './SearchLiveResultsAnnouncer';
 import { SearchScopeControl } from './SearchScopeControl';
 import type { SearchBaseProps } from './search-props';
 import { useSearchController } from './useSearchController';
 
+const SearchFrame = dynamic(() => import('./SearchFrame').then((mod) => mod.SearchFrame), {
+    ssr: false,
+});
+
 interface SearchContainerProps extends SearchBaseProps {
     style: CustomizationSearchStyle;
     className?: string;
@@ -113,8 +117,20 @@ export function SearchContainer({
         cursor !== null && cursor < results.length ? `${resultsId}-${cursor}` : undefined;
     const isSearchOpen = Boolean(visible && (state?.open ?? false));
     const shouldFillHeight = Boolean(query || showAsk);
+
+    // The SideSheet always renders its children (it hides them with CSS, unlike the desktop
+    // Popover which mounts its content on open). Mounting the frame only after the first open
+    // keeps the dynamic SearchFrame chunk off the mobile startup path, while leaving it mounted
+    // afterwards so the sheet's exit animation isn't cut short.
+    const [wasSearchOpened, setWasSearchOpened] = React.useState(false);
+    React.useEffect(() => {
+        if (isSearchOpen) {
+            setWasSearchOpened(true);
+        }
+    }, [isSearchOpen]);
+
     const shouldShowSearchFrame = usesSideSheet
-        ? Boolean(state?.open || state?.query || withAI)
+        ? Boolean(state?.open || state?.query || wasSearchOpened)
         : Boolean(state?.query || withAI);
     const scopeControlNode =
         searchProps.withVariants || searchProps.withSections ? (
diff --git a/packages/gitbook/src/components/Search/site-index.ts b/packages/gitbook/src/components/Search/site-index.ts
new file mode 100644
index 000000000..39fe0445c
--- /dev/null
+++ b/packages/gitbook/src/components/Search/site-index.ts
@@ -0,0 +1,79 @@
+'use client';
+
+/**
+ * Client-side access to the `~gitbook/site-index` JSON, shared by every consumer
+ * (instant search in `useLocalSearchResults`, related pages on the 404 page).
+ *
+ * Loading strategy: the download starts as early as possible (server-rendered
+ * preload hint in `SiteLayout`, deduped here at first call) and is kept as raw
+ * text so the multi-MB `JSON.parse` — main-thread work — is only paid when a
+ * consumer actually needs the pages.
+ */
+
+export interface SiteIndexBreadcrumb {
+    label: string;
+    icon?: string;
+    emoji?: string;
+}
+
+/** Raw entry from the `~gitbook/site-index` JSON response */
+export interface SiteIndexPage {
+    id: string;
+    title: string;
+    pathname: string;
+    siteSpaceId: string;
+    /** BCP-47 language code emitted by the index route, absent when no language is set. */
+    lang?: string;
+    icon?: string;
+    emoji?: string;
+    description?: string;
+    breadcrumbs?: SiteIndexBreadcrumb[];
+}
+
+let siteIndexText: Promise<string> | null = null;
+
+/**
+ * Start (or reuse) the single-flight download of the raw index. Errors clear the
+ * cache so the next consumer retries.
+ */
+export function prefetchSiteIndex(indexURL: string): void {
+    fetchSiteIndexText(indexURL).catch(() => {
+        // Ignored: consumers surface errors when they actually read the index.
+    });
+}
+
+/**
+ * Get the parsed index pages. Parses per call (cheap for the rare second
+ * consumer) so the parsed object graph is never retained at module scope.
+ */
+export async function fetchSiteIndex(
+    indexURL: string
+): Promise<{ version: 1; pages: SiteIndexPage[] }> {
+    return JSON.parse(await fetchSiteIndexText(indexURL));
+}
+
+/**
+ * Drop the cached raw text (several MB for large sites) once a consumer has
+ * turned it into a longer-lived form. Purely a memory release: a later consumer
+ * re-fetches, hitting the HTTP cache.
+ */
+export function releaseSiteIndex(): void {
+    siteIndexText = null;
+}
+
+function fetchSiteIndexText(indexURL: string): Promise<string> {
+    if (!siteIndexText) {
+        siteIndexText = fetch(indexURL).then((response) => {
+            if (!response.ok) {
+                throw new Error(`Failed to fetch search index: ${response.status}`);
+            }
+            return response.text();
+        });
+
+        siteIndexText.catch(() => {
+            siteIndexText = null;
+        });
+    }
+
+    return siteIndexText;
+}
diff --git a/packages/gitbook/src/components/Search/useLocalSearchResults.tsx b/packages/gitbook/src/components/Search/useLocalSearchResults.tsx
index 78b1525e9..dc7a2d817 100644
--- a/packages/gitbook/src/components/Search/useLocalSearchResults.tsx
+++ b/packages/gitbook/src/components/Search/useLocalSearchResults.tsx
@@ -1,27 +1,14 @@
 'use client';
 
-import { Document, type DocumentValue } from 'flexsearch';
+import type { Document, DocumentValue } from 'flexsearch';
 import React from 'react';
-
-interface Breadcrumb {
-    label: string;
-    icon?: string;
-    emoji?: string;
-}
-
-/** Raw entry from the `~gitbook/index` JSON response */
-interface RawIndexPage {
-    id: string;
-    title: string;
-    pathname: string;
-    siteSpaceId: string;
-    /** BCP-47 language code emitted by the index route, absent when no language is set. */
-    lang?: string;
-    icon?: string;
-    emoji?: string;
-    description?: string;
-    breadcrumbs?: Breadcrumb[];
-}
+import {
+    type SiteIndexBreadcrumb,
+    type SiteIndexPage,
+    fetchSiteIndex,
+    prefetchSiteIndex,
+    releaseSiteIndex,
+} from './site-index';
 
 /** FlexSearch-compatible document type — satisfies DocumentData via explicit index signature */
 interface IndexPage {
@@ -41,7 +28,7 @@ export interface LocalPageResult {
     icon?: string;
     emoji?: string;
     description?: string;
-    breadcrumbs?: Breadcrumb[];
+    breadcrumbs?: SiteIndexBreadcrumb[];
 }
 
 type LocalSearchState = {
@@ -58,13 +45,16 @@ const cachedIndexes = new Map<string, Document<IndexPage>>();
 // Keyed by page id, shared across all language groups.
 const cachedPageData = new Map<
     string,
-    { pathname: string; icon?: string; emoji?: string; breadcrumbs?: Breadcrumb[] }
+    { pathname: string; icon?: string; emoji?: string; breadcrumbs?: SiteIndexBreadcrumb[] }
 >();
 
 let pendingFetch: Promise<Map<string, Document<IndexPage>>> | null = null;
 
-function buildLangIndex(pages: RawIndexPage[]): Document<IndexPage> {
-    const index = new Document<IndexPage>({
+function buildLangIndex(
+    DocumentCtor: typeof import('flexsearch').Document,
+    pages: SiteIndexPage[]
+): Document<IndexPage> {
+    const index = new DocumentCtor<IndexPage>({
         document: {
             id: 'id',
             index: ['title', 'description'],
@@ -110,15 +100,14 @@ async function getOrBuildIndexes(indexURL: string): Promise<Map<string, Document
     }
 
     pendingFetch = (async () => {
-        const response = await fetch(indexURL);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch search index: ${response.status}`);
-        }
-
-        const data: { version: 1; pages: RawIndexPage[] } = await response.json();
+        // FlexSearch stays in an on-demand chunk instead of the main client bundle, it's only needed once the user actually searches.
+        const [{ Document }, data] = await Promise.all([
+            import('flexsearch'),
+            fetchSiteIndex(indexURL),
+        ]);
 
         // Group pages by their `lang` value (empty string for pages without one)
-        const pagesByLang = new Map<string, RawIndexPage[]>();
+        const pagesByLang = new Map<string, SiteIndexPage[]>();
         for (const page of data.pages) {
             const key = page.lang ?? '';
             const bucket = pagesByLang.get(key);
@@ -131,9 +120,11 @@ async function getOrBuildIndexes(indexURL: string): Promise<Map<string, Document
 
         // Build one FlexSearch Document per language group
         for (const [lang, pages] of pagesByLang) {
-            cachedIndexes.set(lang, buildLangIndex(pages));
+            cachedIndexes.set(lang, buildLangIndex(Document, pages));
         }
 
+        releaseSiteIndex();
+
         return cachedIndexes;
     })();
 
@@ -156,8 +147,10 @@ export function useLocalSearchResults(props: {
      * are returned. Uses FlexSearch native tag filtering. Omit for no filtering (all spaces). */
     filterSiteSpaceIds?: string[];
     disabled?: boolean;
+    /** Whether the search surface is open. */
+    open: boolean;
 }): LocalSearchState {
-    const { query, indexURL, lang, filterSiteSpaceIds, disabled = false } = props;
+    const { query, indexURL, lang, filterSiteSpaceIds, disabled = false, open } = props;
 
     const [state, setState] = React.useState<LocalSearchState>({
         results: [],
@@ -168,6 +161,8 @@ export function useLocalSearchResults(props: {
     // Track whether the indexes are loaded so the search effect re-runs after load
     const [indexReady, setIndexReady] = React.useState(cachedIndexes.size > 0);
 
+    const active = open || Boolean(query);
+
     // Load the indexes once
     React.useEffect(() => {
         if (cachedIndexes.size > 0) {
@@ -175,6 +170,12 @@ export function useLocalSearchResults(props: {
             return;
         }
 
+        prefetchSiteIndex(indexURL);
+
+        if (!active) {
+            return;
+        }
+
         let cancelled = false;
         setState((prev) => ({ ...prev, fetching: true, error: false }));
 
@@ -194,7 +195,7 @@ export function useLocalSearchResults(props: {
         return () => {
             cancelled = true;
         };
-    }, [indexURL]);
+    }, [indexURL, active]);
 
     // Perform instant local search whenever query, lang, or index readiness changes
     React.useEffect(() => {
diff --git a/packages/gitbook/src/components/Search/useSearchController.tsx b/packages/gitbook/src/components/Search/useSearchController.tsx
index bdfb257d1..567987125 100644
--- a/packages/gitbook/src/components/Search/useSearchController.tsx
+++ b/packages/gitbook/src/components/Search/useSearchController.tsx
@@ -200,6 +200,7 @@ export function useSearchController(props: SearchBaseProps) {
     const { results, fetching, error, abort } = useSearchResults({
         asEmbeddable,
         disabled: !(state?.query || withAI),
+        open: Boolean(state?.open),
         query: normalizedQuery,
         siteSpaceId: siteSpace.id,
         siteSpaceIds,
diff --git a/packages/gitbook/src/components/Search/useSearchResults.ts b/packages/gitbook/src/components/Search/useSearchResults.ts
index f98f590a6..9513b2459 100644
--- a/packages/gitbook/src/components/Search/useSearchResults.ts
+++ b/packages/gitbook/src/components/Search/useSearchResults.ts
@@ -45,6 +45,8 @@ const cachedRecommendedQuestions: Map<string, RecommendedQuestionResult[]> = new
 export function useSearchResults(props: {
     asEmbeddable?: boolean;
     disabled: boolean;
+    /** Whether the search surface is open. Gates building the local search index. */
+    open: boolean;
     query: string;
     siteSpaceId: string;
     siteSpaceIds: string[];
@@ -52,7 +54,7 @@ export function useSearchResults(props: {
     suggestions?: string[];
     /** URL for the search API route (e.g. from linker.toPathInSpace('~gitbook/search')). */
     searchURL: string;
-    /** URL for the local index JSON (e.g. from linker.toPathInSite('~gitbook/index')). */
+    /** URL for the local index JSON (e.g. from linker.toPathInSite('~gitbook/site-index')). */
     indexURL: string;
     /** BCP-47 language code of the current site space, used to filter local search results. */
     lang?: string;
@@ -62,6 +64,7 @@ export function useSearchResults(props: {
     const {
         asEmbeddable,
         disabled,
+        open,
         query,
         siteSpaceId,
         siteSpaceIds,
@@ -85,6 +88,7 @@ export function useSearchResults(props: {
         indexURL,
         lang,
         disabled,
+        open,
         filterSiteSpaceIds,
     });
 
diff --git a/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx b/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
index 23b6c6aa0..a63ac8e6d 100644
--- a/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
+++ b/packages/gitbook/src/components/SiteLayout/SiteLayout.tsx
@@ -39,10 +39,13 @@ export async function SiteLayout(props: {
         ReactDOM.preconnect(GITBOOK_ASSETS_URL);
     }
 
-    // We also preload the site index
+    // Start the search-index download from the HTML itself. `crossOrigin` must match the
+    // client `fetch()` (cors + same-origin credentials) or the preload is ignored and the
+    // index downloads twice — the omission was exactly that bug before.
     ReactDOM.preload(`${context.linker.siteBasePath}~gitbook/site-index`, {
         as: 'fetch',
         type: 'application/json',
+        crossOrigin: 'anonymous',
     });
 
     scripts.forEach(({ script }) => {
diff --git a/packages/gitbook/src/components/SitePage/SitePageNotFound.tsx b/packages/gitbook/src/components/SitePage/SitePageNotFound.tsx
index 6f0f01b16..7e90bd4a5 100644
--- a/packages/gitbook/src/components/SitePage/SitePageNotFound.tsx
+++ b/packages/gitbook/src/components/SitePage/SitePageNotFound.tsx
@@ -11,6 +11,7 @@ import { useEffect, useState } from 'react';
 import { useAI } from '../AI';
 import { PreservePageLayout } from '../PageBody/PreservePageLayout';
 import { useSetSearchState } from '../Search';
+import { fetchSiteIndex } from '../Search/site-index';
 import { SiteAuthLoginButton } from '../SiteAuth/SiteAuthLoginLink';
 import {
     useSiteAdaptiveAuthLoginHref,
@@ -229,34 +230,21 @@ function NotFoundSuggestions(props: { suggestions: RelatedPage[] | null }) {
     ) : null;
 }
 
-/** Minimal shape of an entry in the `~gitbook/site-index` response. */
-type IndexPage = {
-    id: string;
-    title: string;
-    pathname: string;
-    siteSpaceId: string;
-    icon?: string;
-    emoji?: string;
-};
-
 /**
  * Return the pages whose path is closest to the one that 404'd.
  *
  * Rather than asking the server (which would mean an extra request per 404), this reuses the
- * search index served at `~gitbook/site-index` — already preloaded and CDN-cached on every page —
- * so it's a cache hit, not an origin request. The ranking is a lighter, client-side cousin of
- * `getSimilarPages` (which the Markdown 404 runs server-side from the full page tree).
+ * search index served at `~gitbook/site-index` — preloaded on every page and shared with
+ * instant search via the module cache in `site-index.ts`, so at most one request is made.
+ * The ranking is a lighter, client-side cousin of `getSimilarPages` (which the Markdown 404
+ * runs server-side from the full page tree).
  */
 async function getRelatedPages(
     indexURL: string,
     requestedPath: string,
     siteSpaceId: string | null
 ): Promise<RelatedPage[]> {
-    const response = await fetch(indexURL);
-    if (!response.ok) {
-        return [];
-    }
-    const { pages } = (await response.json()) as { pages: IndexPage[] };
+    const { pages } = await fetchSiteIndex(indexURL);
 
     return pages
         .filter((page) => !siteSpaceId || page.siteSpaceId === siteSpaceId)

From 6083a888458443875a8652075ebf3d05bc1a40c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Greg=20Berg=C3=A9?= <berge.greg@gmail.com>
Date: Fri, 17 Jul 2026 12:06:38 +0200
Subject: [PATCH 42/46] Expose the current page context to integration block
 webframes (#4411)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/webframe-page-context.md           |  6 +++
 packages/gitbook/e2e/customers.spec.ts        |  5 --
 .../ContentKitWithClientContext.tsx           | 12 +++--
 .../Integration/IntegrationBlock.tsx          | 10 ++--
 .../DocumentView/Integration/adaptive.test.ts | 48 ++++++++++++++++++-
 .../DocumentView/Integration/adaptive.ts      | 38 ++++++++++++++-
 .../react-contentkit/src/ElementWebframe.tsx  | 10 ++--
 packages/react-contentkit/src/context.ts      | 19 ++++++++
 8 files changed, 131 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/webframe-page-context.md

diff --git a/.changeset/webframe-page-context.md b/.changeset/webframe-page-context.md
new file mode 100644
index 000000000..041df33bc
--- /dev/null
+++ b/.changeset/webframe-page-context.md
@@ -0,0 +1,6 @@
+---
+"@gitbook/react-contentkit": patch
+"gitbook": patch
+---
+
+Expose the current page (`id`, `path`, `title`) to integration block webframes through the client-only webframe `state.page`, alongside adaptive visitor claims.
diff --git a/packages/gitbook/e2e/customers.spec.ts b/packages/gitbook/e2e/customers.spec.ts
index 8e4d60707..8ccdcda75 100644
--- a/packages/gitbook/e2e/customers.spec.ts
+++ b/packages/gitbook/e2e/customers.spec.ts
@@ -282,11 +282,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://vimeo.com',
         tests: [{ name: 'Home', url: '/legal' }],
     },
-    {
-        name: 'help.platipomiru.com',
-        contentBaseURL: 'https://help.platipomiru.com',
-        tests: [{ name: 'Home', url: '/' }],
-    },
     {
         name: 'help.aikido.dev',
         contentBaseURL: 'https://help.aikido.dev',
diff --git a/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx b/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx
index 47d6104cf..c044638d8 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx
+++ b/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx
@@ -6,6 +6,7 @@ import { type GitBookLinker, createLinker } from '@/lib/links';
 import { ContentKit, type ContentKitClientContextData } from '@gitbook/react-contentkit/client';
 import { useRouter } from 'next/navigation';
 import React from 'react';
+import type { WebframePageContext } from './adaptive';
 
 type ContentKitProps<RenderContext> = React.ComponentProps<typeof ContentKit<RenderContext>>;
 
@@ -17,18 +18,20 @@ export type WebframeLinkerData = Pick<
 
 /**
  * ContentKit wrapper for integration blocks that expose client-only capabilities to webframes:
- * navigation to other pages, and adaptive visitor claims (only when the integration is allowed to
- * access them).
+ * the current page, navigation to other pages, and adaptive visitor claims (only when the
+ * integration is allowed to access them).
  */
 export function ContentKitWithClientContext<RenderContext>(
     props: ContentKitProps<RenderContext> & {
         /** Whether visitor claims may be exposed to the webframe (integration scope gated). */
         canAccessVisitorClaims: boolean;
+        /** Current page to inject into the webframe, or `null` when unknown. */
+        page: WebframePageContext | null;
         /** Data to rebuild the site linker, used to resolve webframe navigation requests. */
         linkerData: WebframeLinkerData;
     }
 ) {
-    const { canAccessVisitorClaims, linkerData, ...contentKitProps } = props;
+    const { canAccessVisitorClaims, page, linkerData, ...contentKitProps } = props;
 
     const router = useRouter();
     const { onNavigationClick } = React.useContext(NavigationStatusContext);
@@ -56,6 +59,7 @@ export function ContentKitWithClientContext<RenderContext>(
             getVisitorContext: canAccessVisitorClaims
                 ? () => ({ visitor: visitorClaims?.visitor ?? null })
                 : undefined,
+            getPageContext: page ? () => ({ page }) : undefined,
             navigate: ({ path, anchor }) => {
                 // Resolve the requested path relative to the site root so a webframe can navigate
                 // to any section or space within the site (and nowhere outside it).
@@ -63,7 +67,7 @@ export function ContentKitWithClientContext<RenderContext>(
                 navigateTo(linker.toPathInSite(path) + suffix);
             },
         }),
-        [canAccessVisitorClaims, visitorClaims, linker, navigateTo]
+        [canAccessVisitorClaims, visitorClaims, page, linker, navigateTo]
     );
 
     return <ContentKit {...contentKitProps} clientContext={clientContext} />;
diff --git a/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx b/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
index 1443cc2c2..1d599549c 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
+++ b/packages/gitbook/src/components/DocumentView/Integration/IntegrationBlock.tsx
@@ -10,7 +10,7 @@ import {
     ContentKitWithClientContext,
     type WebframeLinkerData,
 } from './ContentKitWithClientContext';
-import { integrationBlockContainsWebframe } from './adaptive';
+import { getWebframePageContext, integrationBlockContainsWebframe } from './adaptive';
 import { contentKitServerContext } from './contentkit';
 import { fetchSafeIntegrationUI } from './render';
 import { renderIntegrationUi } from './server-actions';
@@ -77,8 +77,11 @@ export async function IntegrationBlock(props: BlockProps<DocumentBlockIntegratio
     const containsWebframe = integrationBlockContainsWebframe(initialOutput);
     const canAccessVisitorClaims = initialOutput.canAccessVisitorClaims === true;
 
-    // Any webframe uses the client-context wrapper: it enables navigation to other pages, plus
-    // visitor claims when the integration is allowed them.
+    // The current page (path/id/title) is non-sensitive, so it is always exposed to webframes.
+    const page = getWebframePageContext(context.contentContext);
+
+    // Any webframe uses the client-context wrapper: it enables navigation to other pages and
+    // exposes the current page, plus visitor claims when the integration is allowed them.
     const useClientContext = containsWebframe;
 
     const contentKitProps = {
@@ -106,6 +109,7 @@ export async function IntegrationBlock(props: BlockProps<DocumentBlockIntegratio
                 <ContentKitWithClientContext
                     {...contentKitProps}
                     canAccessVisitorClaims={canAccessVisitorClaims}
+                    page={page}
                     linkerData={getWebframeLinkerData(context.contentContext.linker)}
                 >
                     <ContentKitOutput output={initialOutput} context={contentKitServerContext} />
diff --git a/packages/gitbook/src/components/DocumentView/Integration/adaptive.test.ts b/packages/gitbook/src/components/DocumentView/Integration/adaptive.test.ts
index 11dbae41f..20108b89e 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/adaptive.test.ts
+++ b/packages/gitbook/src/components/DocumentView/Integration/adaptive.test.ts
@@ -1,7 +1,9 @@
 import { describe, expect, it } from 'bun:test';
 import type { ContentKitRenderOutput, ContentKitWebFrame } from '@gitbook/api';
 
-import { integrationBlockContainsWebframe } from './adaptive';
+import type { GitBookAnyContext } from '@/lib/context';
+import { createLinker } from '@/lib/links';
+import { getWebframePageContext, integrationBlockContainsWebframe } from './adaptive';
 
 const webframe: ContentKitWebFrame = {
     type: 'webframe',
@@ -38,3 +40,47 @@ describe('integrationBlockContainsWebframe', () => {
         expect(integrationBlockContainsWebframe(output)).toBe(true);
     });
 });
+
+describe('getWebframePageContext', () => {
+    it('returns null when the context has no page', () => {
+        const context = { space: { id: 'space-1' } } as unknown as GitBookAnyContext;
+        expect(getWebframePageContext(context)).toBeNull();
+    });
+
+    it('resolves the page path relative to the site root, including the section slug', () => {
+        const context = {
+            page: {
+                id: 'page-1',
+                path: 'guides/getting-started',
+                title: 'Getting started',
+                slug: 'getting-started',
+            },
+            // Site served at /docs, with the page's space mounted under the `api` section.
+            linker: createLinker({ siteBasePath: '/docs/', spaceBasePath: '/docs/api/' }),
+        } as unknown as GitBookAnyContext;
+
+        expect(getWebframePageContext(context)).toEqual({
+            id: 'page-1',
+            path: 'api/guides/getting-started',
+            title: 'Getting started',
+        });
+    });
+
+    it('leaves the path unprefixed when the space is served at the site root', () => {
+        const context = {
+            page: {
+                id: 'page-2',
+                path: 'guides/getting-started',
+                title: 'Getting started',
+                slug: 'getting-started',
+            },
+            linker: createLinker({ siteBasePath: '/', spaceBasePath: '/' }),
+        } as unknown as GitBookAnyContext;
+
+        expect(getWebframePageContext(context)).toEqual({
+            id: 'page-2',
+            path: 'guides/getting-started',
+            title: 'Getting started',
+        });
+    });
+});
diff --git a/packages/gitbook/src/components/DocumentView/Integration/adaptive.ts b/packages/gitbook/src/components/DocumentView/Integration/adaptive.ts
index 9adeb2686..77c5732a7 100644
--- a/packages/gitbook/src/components/DocumentView/Integration/adaptive.ts
+++ b/packages/gitbook/src/components/DocumentView/Integration/adaptive.ts
@@ -1,3 +1,4 @@
+import type { GitBookAnyContext } from '@/lib/context';
 import type {
     ContentKitDescendantElement,
     ContentKitRenderOutput,
@@ -7,9 +8,19 @@ import type {
 
 type ContentKitElement = ContentKitRootElement | ContentKitDescendantElement | ContentKitStepper;
 
+/**
+ * Current page exposed to a webframe through the client-only webframe state.
+ */
+export type WebframePageContext = {
+    id: string;
+    /** Path of the page relative to the site root (includes the section and variant). */
+    path: string;
+    title: string;
+};
+
 /**
  * Whether an integration block's output contains a webframe that can consume client-only context
- * (navigation and/or visitor claims).
+ * (navigation, visitor claims and/or the current page).
  */
 export function integrationBlockContainsWebframe(output: ContentKitRenderOutput): boolean {
     if (output.type === 'complete') {
@@ -19,6 +30,31 @@ export function integrationBlockContainsWebframe(output: ContentKitRenderOutput)
     return doesContentKitElementContainWebframe(output.element);
 }
 
+/**
+ * Extract the current page to expose to a webframe, or `null` when it is unknown
+ * (e.g. a non-page context, or reusable content resolved from another source).
+ *
+ * The exposed `path` is resolved relative to the site root — so it carries the section and
+ * variant, unlike the space-relative `page.path` — matching how `@webframe.navigate` resolves a
+ * path. A webframe can pass `page.path` straight back to the navigate action.
+ */
+export function getWebframePageContext(
+    contentContext: GitBookAnyContext
+): WebframePageContext | null {
+    if (!('page' in contentContext) || !contentContext.page) {
+        return null;
+    }
+
+    const { linker } = contentContext;
+    const { id, path, title } = contentContext.page;
+
+    return {
+        id,
+        path: linker.toRelativePathInSite(linker.toPathInSpace(path)),
+        title,
+    };
+}
+
 /**
  * Check whether a ContentKit element tree contains a webframe element.
  */
diff --git a/packages/react-contentkit/src/ElementWebframe.tsx b/packages/react-contentkit/src/ElementWebframe.tsx
index 9ff9f58de..0f4a3a423 100644
--- a/packages/react-contentkit/src/ElementWebframe.tsx
+++ b/packages/react-contentkit/src/ElementWebframe.tsx
@@ -159,7 +159,7 @@ export function ElementWebframe(props: ContentKitClientElementProps<ContentKitWe
         };
     }, [renderer, sendMessage]);
 
-    // Send data and client-only context (visitor claims) as state to the webframe.
+    // Send data and client-only context (visitor claims, current page) as state to the webframe.
     React.useEffect(() => {
         const abort = { cancelled: false };
         sendWebframeState({
@@ -231,10 +231,14 @@ function resolveWebframeState(
 }
 
 /**
- * Resolve the optional client-only contexts (visitor claims) to merge into the webframe state.
+ * Resolve the optional client-only contexts (visitor claims, current page)
+ * to merge into the webframe state.
  */
 async function resolveClientContexts(clientContext: ContentKitClientContextData | undefined) {
-    return await Promise.all([clientContext?.getVisitorContext?.()]);
+    return await Promise.all([
+        clientContext?.getVisitorContext?.(),
+        clientContext?.getPageContext?.(),
+    ]);
 }
 
 /**
diff --git a/packages/react-contentkit/src/context.ts b/packages/react-contentkit/src/context.ts
index fcff8f10a..c50a1abd6 100644
--- a/packages/react-contentkit/src/context.ts
+++ b/packages/react-contentkit/src/context.ts
@@ -17,6 +17,16 @@ export type ContentKitRenderUpdate = Partial<
     Pick<RequestRenderIntegrationUI, 'action' | 'props' | 'state'>
 >;
 
+/**
+ * The current page exposed to a webframe through the client-only webframe state.
+ */
+export type ContentKitWebframePage = {
+    id: string;
+    /** Path of the page relative to the site root. */
+    path: string;
+    title: string;
+};
+
 export type ContentKitClientContextData = {
     /**
      * Client-only visitor claims, merged into the webframe state.
@@ -28,6 +38,15 @@ export type ContentKitClientContextData = {
         | undefined
         | Promise<Record<string, unknown> | null | undefined>;
 
+    /**
+     * Client-only current-page context, merged into the webframe state.
+     */
+    getPageContext?: () =>
+        | { page: ContentKitWebframePage }
+        | null
+        | undefined
+        | Promise<{ page: ContentKitWebframePage } | null | undefined>;
+
     /**
      * Navigate the host page to another page, in response to a webframe `@webframe.navigate`
      * action. The destination is addressed by `path` (resolved against the site base path); the

From 4d7c01587e7f9cc428ee1b0ba3c4449e8c7f3dd2 Mon Sep 17 00:00:00 2001
From: spastorelli <spastorelli@users.noreply.github.com>
Date: Fri, 17 Jul 2026 15:58:27 +0200
Subject: [PATCH 43/46] Add Sites OAuth consent screen (#4405)

---
 .../composite/deploy-cloudflare/action.yaml   |   3 +
 .github/composite/deploy-vercel/action.yaml   |   3 +
 .../oauth2/v1/[siteId]/authorize/layout.tsx   |  20 ++
 .../oauth2/v1/[siteId]/authorize/page.tsx     |  67 ++++++
 .../SiteOAuthConsent/ConsentForm.tsx          |  93 ++++++++
 .../SiteOAuthConsent/ConsentScreen.tsx        | 203 ++++++++++++++++++
 .../components/SiteOAuthConsent/actions.ts    |  39 ++++
 .../src/components/SiteOAuthConsent/index.ts  |   1 +
 packages/gitbook/src/lib/env/globals.ts       |   8 +
 packages/gitbook/src/lib/site-oauth/flag.ts   |  32 +++
 packages/gitbook/src/lib/site-oauth/index.ts  | 136 ++++++++++++
 packages/gitbook/src/middleware.ts            |  38 +++-
 12 files changed, 639 insertions(+), 4 deletions(-)
 create mode 100644 packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/oauth2/v1/[siteId]/authorize/layout.tsx
 create mode 100644 packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/oauth2/v1/[siteId]/authorize/page.tsx
 create mode 100644 packages/gitbook/src/components/SiteOAuthConsent/ConsentForm.tsx
 create mode 100644 packages/gitbook/src/components/SiteOAuthConsent/ConsentScreen.tsx
 create mode 100644 packages/gitbook/src/components/SiteOAuthConsent/actions.ts
 create mode 100644 packages/gitbook/src/components/SiteOAuthConsent/index.ts
 create mode 100644 packages/gitbook/src/lib/site-oauth/flag.ts
 create mode 100644 packages/gitbook/src/lib/site-oauth/index.ts

diff --git a/.github/composite/deploy-cloudflare/action.yaml b/.github/composite/deploy-cloudflare/action.yaml
index f8b7181a5..ae38528b4 100644
--- a/.github/composite/deploy-cloudflare/action.yaml
+++ b/.github/composite/deploy-cloudflare/action.yaml
@@ -53,6 +53,7 @@ runs:
             GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
             GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
             GITBOOK_OAUTH_SERVER_URL: ${{ inputs.opItem }}/GITBOOK_OAUTH_SERVER_URL
+            GITBOOK_SITE_OAUTH_SIGNING_SECRET: ${{ inputs.opItem }}/GITBOOK_SITE_OAUTH_SIGNING_SECRET
             GITBOOK_PREVIEW_BASE_URL: ${{ inputs.opItem }}/GITBOOK_PREVIEW_BASE_URL
             GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
             GITBOOK_INTEGRATIONS_CONTENT_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_CONTENT_HOST
@@ -68,6 +69,8 @@ runs:
             GITBOOK_RUNTIME: cloudflare
             GITBOOK_BLOCK_SEARCH_INDEXATION: ${{ inputs.environment == 'preview' && 'true' || '' }}
             GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE: ${{ inputs.environment == 'preview' && 'true' || '' }}
+            # Enable the sites OAuth consent screen everywhere but production, matching the OAuth server default.
+            GITBOOK_SITE_OAUTH_CONSENT_ENABLED: ${{ inputs.environment != 'production' && 'true' || 'false' }}
           shell: bash
 
         - name: Upload the DO worker
diff --git a/.github/composite/deploy-vercel/action.yaml b/.github/composite/deploy-vercel/action.yaml
index b796c5a59..d6171290a 100644
--- a/.github/composite/deploy-vercel/action.yaml
+++ b/.github/composite/deploy-vercel/action.yaml
@@ -55,6 +55,7 @@ runs:
             GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
             GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
             GITBOOK_OAUTH_SERVER_URL: ${{ inputs.opItem }}/GITBOOK_OAUTH_SERVER_URL
+            GITBOOK_SITE_OAUTH_SIGNING_SECRET: ${{ inputs.opItem }}/GITBOOK_SITE_OAUTH_SIGNING_SECRET
             GITBOOK_PREVIEW_BASE_URL: ${{ inputs.opItem }}/GITBOOK_PREVIEW_BASE_URL
             GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
             GITBOOK_INTEGRATIONS_CONTENT_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_CONTENT_HOST
@@ -84,6 +85,8 @@ runs:
             VERCEL_PROJECT_ID: ${{ inputs.vercelProject }}
             GITBOOK_RUNTIME: vercel
             GITBOOK_HEAD_SHA: ${{ inputs.headSha }}
+            # Enable the sites OAuth consent screen everywhere but production, matching the OAuth server default.
+            GITBOOK_SITE_OAUTH_CONSENT_ENABLED: ${{ inputs.environment != 'production' && 'true' || 'false' }}
         - name: Deploy Project Artifacts to Vercel
           id: deploy
           shell: bash
diff --git a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/oauth2/v1/[siteId]/authorize/layout.tsx b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/oauth2/v1/[siteId]/authorize/layout.tsx
new file mode 100644
index 000000000..7e6161251
--- /dev/null
+++ b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/oauth2/v1/[siteId]/authorize/layout.tsx
@@ -0,0 +1,20 @@
+import { type RouteLayoutParams, getDynamicSiteContext } from '@/app/utils';
+import { CustomizationRootLayout } from '@/components/RootLayout/CustomizationRootLayout';
+import { getThemeFromMiddleware } from '@/lib/middleware';
+
+/**
+ * Layout for the sites OAuth consent screen.
+ */
+export default async function Layout({
+    params,
+    children,
+}: React.PropsWithChildren<{ params: Promise<RouteLayoutParams> }>) {
+    const { context } = await getDynamicSiteContext(await params);
+    const forcedTheme = await getThemeFromMiddleware();
+
+    return (
+        <CustomizationRootLayout context={context} forcedTheme={forcedTheme}>
+            {children}
+        </CustomizationRootLayout>
+    );
+}
diff --git a/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/oauth2/v1/[siteId]/authorize/page.tsx b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/oauth2/v1/[siteId]/authorize/page.tsx
new file mode 100644
index 000000000..218f4afe7
--- /dev/null
+++ b/packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/oauth2/v1/[siteId]/authorize/page.tsx
@@ -0,0 +1,67 @@
+import { cookies, headers } from 'next/headers';
+import { notFound } from 'next/navigation';
+
+import {
+    type RouteLayoutParams,
+    getDynamicSiteContext,
+    getSiteURLDataFromParams,
+} from '@/app/utils';
+import { ConsentError, ConsentScreen } from '@/components/SiteOAuthConsent';
+import { withLeadingSlash, withTrailingSlash } from '@/lib/paths';
+import {
+    SiteOAuthConsentError,
+    isSitesOAuthConsentEnabled,
+    startSiteOAuthConsent,
+} from '@/lib/site-oauth';
+import { getVisitorToken } from '@/lib/visitors';
+
+// The consent screen depends on the request (visitor, one-time interaction) and must never be cached.
+export const dynamic = 'force-dynamic';
+
+type PageParams = RouteLayoutParams & { siteId: string };
+
+/**
+ * Render the sites OAuth consent screen for a post-login authorize resume.
+ */
+export default async function Page(props: {
+    params: Promise<PageParams>;
+    searchParams: Promise<{ gb_oauth_state?: string }>;
+}) {
+    if (!isSitesOAuthConsentEnabled()) {
+        notFound();
+    }
+
+    const params = await props.params;
+    const searchParams = await props.searchParams;
+    const { siteId } = params;
+
+    const { context } = await getDynamicSiteContext(params);
+    const siteBasePath = withTrailingSlash(
+        withLeadingSlash(getSiteURLDataFromParams(params).siteBasePath)
+    );
+    const authorizeURL = new URL(
+        `${siteBasePath}~gitbook/oauth2/v1/${siteId}/authorize`,
+        context.linker.toAbsoluteURL('/')
+    );
+    const visitorToken = getVisitorToken({
+        cookies: (await cookies()).getAll(),
+        headers: await headers(),
+        url: authorizeURL,
+    });
+    const jwtToken = visitorToken?.token;
+    const interactionId = searchParams.gb_oauth_state;
+
+    if (!interactionId || !jwtToken) {
+        return <ConsentError />;
+    }
+
+    try {
+        const consent = await startSiteOAuthConsent({ siteId, interactionId, jwtToken });
+        return <ConsentScreen siteId={siteId} siteTitle={context.site.title} consent={consent} />;
+    } catch (error) {
+        if (error instanceof SiteOAuthConsentError) {
+            return <ConsentError />;
+        }
+        throw error;
+    }
+}
diff --git a/packages/gitbook/src/components/SiteOAuthConsent/ConsentForm.tsx b/packages/gitbook/src/components/SiteOAuthConsent/ConsentForm.tsx
new file mode 100644
index 000000000..d0f1d6c0d
--- /dev/null
+++ b/packages/gitbook/src/components/SiteOAuthConsent/ConsentForm.tsx
@@ -0,0 +1,93 @@
+'use client';
+
+import { useState, useTransition } from 'react';
+
+import { Button } from '@/components/primitives/Button';
+import { Checkbox } from '@/components/primitives/Checkbox';
+import { tcls } from '@/lib/tailwind';
+
+import { type SubmitConsentInput, submitSiteOAuthConsent } from './actions';
+
+/**
+ * Site's OAuth consent form to present to the user the client's information requesting access to the site's MCP.
+ */
+export function ConsentForm(props: {
+    siteId: string;
+    consentSessionId: string;
+    /** Whether the OAuth server recognizes the client as verified. */
+    verified: boolean;
+}) {
+    const { siteId, consentSessionId, verified } = props;
+    const [isPending, startTransition] = useTransition();
+    const [error, setError] = useState<string>();
+    const [trusted, setTrusted] = useState(false);
+
+    // Unverified clients can only be approved once the visitor explicitly acknowledges they trust
+    // the app. The OAuth server re-checks this, so it can't be bypassed by tampering with the client.
+    const canApprove = verified || trusted;
+
+    const decide = (decision: SubmitConsentInput['decision']) => {
+        setError(undefined);
+        startTransition(async () => {
+            const result = await submitSiteOAuthConsent({
+                siteId,
+                consentSessionId,
+                decision,
+                trusted,
+            });
+            if ('redirectURL' in result) {
+                // Full-page navigation to the client's (external) redirect URI.
+                window.location.href = result.redirectURL;
+            } else {
+                setError(result.error);
+            }
+        });
+    };
+
+    return (
+        <div className="flex flex-col gap-3">
+            {error ? (
+                <p role="alert" className="text-danger-strong text-sm">
+                    {error}
+                </p>
+            ) : null}
+
+            <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-3">
+                {verified ? (
+                    <span />
+                ) : (
+                    <label
+                        htmlFor="site-oauth-trusted"
+                        className="flex items-center gap-2 text-sm text-tint"
+                    >
+                        <Checkbox
+                            id="site-oauth-trusted"
+                            checked={trusted}
+                            onCheckedChange={(value) => setTrusted(value === true)}
+                        />
+                        <span>I recognize and trust this client</span>
+                    </label>
+                )}
+
+                <div className={tcls('ms-auto flex gap-2')}>
+                    <Button
+                        variant="secondary"
+                        icon="xmark"
+                        disabled={isPending}
+                        onClick={() => decide('deny')}
+                    >
+                        Deny
+                    </Button>
+                    <Button
+                        variant="primary"
+                        icon="check"
+                        disabled={isPending || !canApprove}
+                        onClick={() => decide('approve')}
+                    >
+                        Approve
+                    </Button>
+                </div>
+            </div>
+        </div>
+    );
+}
diff --git a/packages/gitbook/src/components/SiteOAuthConsent/ConsentScreen.tsx b/packages/gitbook/src/components/SiteOAuthConsent/ConsentScreen.tsx
new file mode 100644
index 000000000..3d1ee9bbd
--- /dev/null
+++ b/packages/gitbook/src/components/SiteOAuthConsent/ConsentScreen.tsx
@@ -0,0 +1,203 @@
+import { Icon } from '@gitbook/icons';
+
+import { StyledLink } from '@/components/primitives/StyledLink';
+import type { SiteOAuthConsentStart } from '@/lib/site-oauth';
+import { tcls } from '@/lib/tailwind';
+
+import { ConsentForm } from './ConsentForm';
+
+/**
+ * Consent screen shown to a visitor when an MCP client requests authorization to a published site.
+ */
+export function ConsentScreen(props: {
+    siteId: string;
+    siteTitle: string;
+    consent: SiteOAuthConsentStart;
+}) {
+    const { siteId, siteTitle, consent } = props;
+    const { client, redirectUri, consentSessionId } = consent;
+    const redirectParts = parseRedirectURI(redirectUri);
+
+    return (
+        <ConsentCard>
+            <div className="flex flex-col gap-6 p-6 sm:p-8">
+                {/* Client identity */}
+                <div className="flex items-start gap-3">
+                    {client.logoUri ? (
+                        <img
+                            src={client.logoUri}
+                            alt=""
+                            className="size-10 shrink-0 rounded-corners:rounded-lg straight-corners:rounded-none object-contain"
+                            referrerPolicy="no-referrer"
+                        />
+                    ) : (
+                        <span className="flex size-10 shrink-0 items-center justify-center rounded-corners:rounded-lg straight-corners:rounded-none bg-tint-subtle text-tint">
+                            <Icon icon="key" className="size-5" />
+                        </span>
+                    )}
+
+                    <div className="flex min-w-0 flex-col gap-0.5">
+                        <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
+                            <h1 className="font-semibold text-tint-strong">{client.name}</h1>
+                            <ClientTrustBadge verified={client.verified} />
+                        </div>
+                        {client.uri ? (
+                            <StyledLink
+                                href={client.uri}
+                                className="inline-flex w-fit items-center gap-1 text-sm text-tint"
+                            >
+                                Website
+                                <Icon icon="arrow-up-right" className="size-3" />
+                            </StyledLink>
+                        ) : null}
+                    </div>
+                </div>
+
+                {/* Request statement — toned down, with the client and site names emphasized. */}
+                <p className="text-base text-tint leading-snug">
+                    <span className="font-semibold text-tint-strong">{client.name}</span> wants to
+                    access <span className="font-semibold text-tint-strong">{siteTitle} MCP</span>{' '}
+                    on your behalf.
+                </p>
+
+                {/* Redirect URI, shown in full with the destination host emphasized. */}
+                <div className="flex flex-col gap-2">
+                    <span className="text-sm text-tint">
+                        After approving, an authorization code will be sent to:
+                    </span>
+                    <div
+                        className={tcls(
+                            'flex items-center gap-2.5',
+                            'rounded-corners:rounded-md straight-corners:rounded-none',
+                            'border border-tint-subtle bg-tint-subtle px-3 py-2'
+                        )}
+                    >
+                        <Icon icon="link" className="size-4 shrink-0 text-tint" />
+                        <code className="break-all font-mono text-sm">
+                            {redirectParts ? (
+                                <>
+                                    <span className="text-tint">{redirectParts.prefix}</span>
+                                    <span className="font-semibold text-tint-strong">
+                                        {redirectParts.host}
+                                    </span>
+                                    <span className="text-tint">{redirectParts.rest}</span>
+                                </>
+                            ) : (
+                                <span className="text-tint-strong">{redirectUri}</span>
+                            )}
+                        </code>
+                    </div>
+                </div>
+
+                {client.verified ? null : (
+                    <div
+                        className={tcls(
+                            'flex gap-3',
+                            'rounded-corners:rounded-md straight-corners:rounded-none',
+                            'bg-warning p-3 text-sm text-warning-strong'
+                        )}
+                    >
+                        <Icon icon="triangle-exclamation" className="mt-0.5 size-4 shrink-0" />
+                        <div className="flex flex-col gap-1">
+                            <span className="font-semibold">
+                                GitBook has not verified this client
+                            </span>
+                            <span>
+                                Only approve if you recognize this application and trust it with
+                                access to {siteTitle}.
+                            </span>
+                        </div>
+                    </div>
+                )}
+            </div>
+
+            {/* Footer: trust acknowledgement + decision */}
+            <div className="border-tint-subtle border-t p-4 sm:px-8">
+                <ConsentForm
+                    siteId={siteId}
+                    consentSessionId={consentSessionId}
+                    verified={client.verified}
+                />
+            </div>
+        </ConsentCard>
+    );
+}
+
+/**
+ * Centered, branded card shell shared by the consent screen and its error state.
+ */
+function ConsentCard(props: { children: React.ReactNode }) {
+    return (
+        <main className="flex min-h-screen items-center justify-center bg-tint-subtle p-4">
+            <div
+                className={tcls(
+                    'w-full max-w-lg',
+                    'flex flex-col',
+                    'rounded-corners:rounded-lg straight-corners:rounded-none',
+                    'border border-tint-subtle bg-tint-base',
+                    'shadow-lg'
+                )}
+            >
+                {props.children}
+            </div>
+        </main>
+    );
+}
+
+/**
+ * Error state shown when the consent flow cannot be started (e.g. a refreshed or expired link).
+ */
+export function ConsentError(props: { title?: string; message?: string }) {
+    const {
+        title = 'This authorization link has expired',
+        message = 'Please start the sign-in again from the application.',
+    } = props;
+
+    return (
+        <ConsentCard>
+            <div className="flex flex-col items-center gap-4 p-6 text-center sm:p-8">
+                <span className="flex size-12 items-center justify-center rounded-corners:rounded-full straight-corners:rounded-none bg-danger text-danger-strong">
+                    <Icon icon="circle-exclamation" className="size-6" />
+                </span>
+                <h1 className="font-semibold text-lg text-tint-strong">{title}</h1>
+                <p className="text-tint">{message}</p>
+            </div>
+        </ConsentCard>
+    );
+}
+
+/**
+ * Split a redirect URI so the destination host (the trust-relevant part) can be emphasized while
+ * the scheme and path are shown muted. Returns null if the URI can't be parsed.
+ */
+function parseRedirectURI(uri: string): { prefix: string; host: string; rest: string } | null {
+    try {
+        const url = new URL(uri);
+        return {
+            prefix: `${url.protocol}//`,
+            host: url.host,
+            rest: `${url.pathname}${url.search}${url.hash}`,
+        };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Inline verified/unverified indicator shown next to the client name.
+ */
+function ClientTrustBadge(props: { verified: boolean }) {
+    const { verified } = props;
+
+    return (
+        <span
+            className={tcls(
+                'inline-flex items-center gap-1 font-medium text-xs',
+                verified ? 'text-success-strong' : 'text-warning-strong'
+            )}
+        >
+            <Icon icon={verified ? 'circle-check' : 'triangle-exclamation'} className="size-3" />
+            {verified ? 'Verified' : 'Unverified'}
+        </span>
+    );
+}
diff --git a/packages/gitbook/src/components/SiteOAuthConsent/actions.ts b/packages/gitbook/src/components/SiteOAuthConsent/actions.ts
new file mode 100644
index 000000000..4ed6d96e7
--- /dev/null
+++ b/packages/gitbook/src/components/SiteOAuthConsent/actions.ts
@@ -0,0 +1,39 @@
+'use server';
+
+import { type SiteOAuthConsentDecision, submitSiteOAuthConsentDecision } from '@/lib/site-oauth';
+
+export type SubmitConsentInput = {
+    siteId: string;
+    consentSessionId: string;
+    decision: SiteOAuthConsentDecision;
+    trusted: boolean;
+};
+
+export type SubmitConsentResult = { redirectURL: string } | { error: string };
+
+/**
+ * Server action to submit the consent decision to the sites OAuth server's `consent/decision` endpoint.
+ */
+export async function submitSiteOAuthConsent(
+    input: SubmitConsentInput
+): Promise<SubmitConsentResult> {
+    const { siteId, consentSessionId, decision, trusted } = input;
+
+    if (!siteId || !consentSessionId || (decision !== 'approve' && decision !== 'deny')) {
+        return { error: 'Invalid request. Please start again from the application.' };
+    }
+
+    try {
+        const { redirectURL } = await submitSiteOAuthConsentDecision({
+            siteId,
+            consentSessionId,
+            decision,
+            trusted,
+        });
+        return { redirectURL };
+    } catch (_error) {
+        return {
+            error: 'We could not complete the authorization. The request may have expired — please start again from the application.',
+        };
+    }
+}
diff --git a/packages/gitbook/src/components/SiteOAuthConsent/index.ts b/packages/gitbook/src/components/SiteOAuthConsent/index.ts
new file mode 100644
index 000000000..f7aaddeef
--- /dev/null
+++ b/packages/gitbook/src/components/SiteOAuthConsent/index.ts
@@ -0,0 +1 @@
+export { ConsentScreen, ConsentError } from './ConsentScreen';
diff --git a/packages/gitbook/src/lib/env/globals.ts b/packages/gitbook/src/lib/env/globals.ts
index 92970e753..b7d97778b 100644
--- a/packages/gitbook/src/lib/env/globals.ts
+++ b/packages/gitbook/src/lib/env/globals.ts
@@ -132,6 +132,14 @@ export const GITBOOK_ICONS_TOKEN = process.env.GITBOOK_ICONS_TOKEN;
  */
 export const GITBOOK_SECRET = process.env.GITBOOK_SECRET ?? null;
 
+/**
+ * Shared secret used to sign server-to-server requests to the sites OAuth server consent endpoints.
+ * This must match the sites OAuth provider signing secret (`functionsConfig.sitesOAuth.signingSecret`
+ * in gitbook-x); it is a dedicated secret and must not be confused with `GITBOOK_SECRET`.
+ */
+export const GITBOOK_SITE_OAUTH_SIGNING_SECRET =
+    process.env.GITBOOK_SITE_OAUTH_SIGNING_SECRET ?? null;
+
 function enforceEnum<T extends string>(key: string, value: string, enumValues: T[]): T {
     if (!enumValues.includes(value as T)) {
         throw new Error(
diff --git a/packages/gitbook/src/lib/site-oauth/flag.ts b/packages/gitbook/src/lib/site-oauth/flag.ts
new file mode 100644
index 000000000..25acf282a
--- /dev/null
+++ b/packages/gitbook/src/lib/site-oauth/flag.ts
@@ -0,0 +1,32 @@
+/**
+ * Whether GBO should render the sites OAuth consent screen (instead of forwarding the post-login
+ * resume to the OAuth server). This must be coordinated with the OAuth server so GBO renders consent
+ * exactly when the server expects it.
+ *
+ * Kept in its own module (free of `node:crypto`/`server-only`) so it can be imported from the edge
+ * middleware. It is never imported into a client bundle.
+ */
+export function isSitesOAuthConsentEnabled(): boolean {
+    const override = process.env.GITBOOK_SITE_OAUTH_CONSENT_ENABLED;
+    if (override !== undefined) {
+        return override === 'true';
+    }
+    return process.env.NODE_ENV === 'development';
+}
+
+/**
+ * Interaction id the OAuth server puts on the post-login resume URL. Its presence marks a resume
+ * that GBO should render consent for (rather than forward to the OAuth server).
+ */
+export const SITE_OAUTH_STATE_PARAM = 'gb_oauth_state';
+
+/**
+ * Whether GBO should render the consent screen for a request hitting the
+ * `~gitbook/oauth2/v1/:siteId/authorize` forwarder, rather than forwarding it to the OAuth server.
+ *
+ * Render only when consent is enabled AND this is a post-login resume (carries the interaction id);
+ * everything else forwards, preserving the legacy behavior.
+ */
+export function shouldRenderSiteOAuthConsent(searchParams: URLSearchParams): boolean {
+    return isSitesOAuthConsentEnabled() && searchParams.has(SITE_OAUTH_STATE_PARAM);
+}
diff --git a/packages/gitbook/src/lib/site-oauth/index.ts b/packages/gitbook/src/lib/site-oauth/index.ts
new file mode 100644
index 000000000..426916794
--- /dev/null
+++ b/packages/gitbook/src/lib/site-oauth/index.ts
@@ -0,0 +1,136 @@
+import 'server-only';
+
+import { createHmac } from 'node:crypto';
+
+import { GITBOOK_OAUTH_SERVER_URL, GITBOOK_SITE_OAUTH_SIGNING_SECRET } from '@/lib/env';
+
+export {
+    SITE_OAUTH_STATE_PARAM,
+    isSitesOAuthConsentEnabled,
+    shouldRenderSiteOAuthConsent,
+} from './flag';
+
+/**
+ * Details about the OAuth client requesting authorization, as returned by the OAuth server. The
+ * `name` and `uri` are client-supplied and must be treated as untrusted when rendered.
+ */
+export type SiteOAuthConsentClient = {
+    name: string;
+    uri?: string;
+    logoUri?: string;
+    verified: boolean;
+    verifiedName?: string;
+};
+
+/**
+ * Result of a successful `consent/start` call: everything GBO needs to render the consent screen.
+ */
+export type SiteOAuthConsentStart = {
+    consentSessionId: string;
+    client: SiteOAuthConsentClient;
+    scopes: string[];
+    redirectUri: string;
+};
+
+/**
+ * A visitor's decision on a consent request.
+ */
+export type SiteOAuthConsentDecision = 'approve' | 'deny';
+
+/**
+ * Error thrown when a server-to-server call to the OAuth server consent endpoint fails. It carries
+ * the upstream HTTP status so callers can distinguish an expired/consumed session (400) from an
+ * authentication problem (401).
+ */
+export class SiteOAuthConsentError extends Error {
+    readonly status: number;
+
+    constructor(message: string, status: number) {
+        super(message);
+        this.name = 'SiteOAuthConsentError';
+        this.status = status;
+    }
+}
+
+/**
+ * Start a consent session with the OAuth server for a post-login authorize resume.
+ *
+ * This is single-use: it consumes the pending interaction session on the OAuth server, so it must be
+ * called exactly once per consent render.
+ */
+export async function startSiteOAuthConsent(args: {
+    siteId: string;
+    interactionId: string;
+    jwtToken: string;
+}): Promise<SiteOAuthConsentStart> {
+    const { siteId, interactionId, jwtToken } = args;
+    return postToConsentEndpoint<SiteOAuthConsentStart>(siteId, 'consent/start', {
+        interactionId,
+        jwtToken,
+    });
+}
+
+/**
+ * Submit the visitor's decision to the OAuth server and get back the absolute URL to send the
+ * visitor's browser to (the client's redirect URI with an auth code on approve, or an access_denied
+ * redirect on deny).
+ */
+export async function submitSiteOAuthConsentDecision(args: {
+    siteId: string;
+    consentSessionId: string;
+    decision: SiteOAuthConsentDecision;
+    trusted: boolean;
+}): Promise<{ redirectURL: string }> {
+    const { siteId, consentSessionId, decision, trusted } = args;
+    return postToConsentEndpoint<{ redirectURL: string }>(siteId, 'consent/decision', {
+        consentSessionId,
+        decision,
+        // Only forward the trust acknowledgement when the visitor actually gave it; the server
+        // re-checks and rejects an unverified client approved without it.
+        ...(trusted ? { trusted: true } : {}),
+    });
+}
+
+/**
+ * Sign and POST a JSON body to a site OAuth server consent endpoint, returning the parsed response.
+ *
+ * The shared-secret signature matches the OAuth server's schem and is sent as the
+ * `x-gitbook-signature` / `x-gitbook-timestamp` headers.
+ */
+async function postToConsentEndpoint<T>(
+    siteId: string,
+    endpoint: 'consent/start' | 'consent/decision',
+    body: unknown
+): Promise<T> {
+    if (!GITBOOK_SITE_OAUTH_SIGNING_SECRET) {
+        throw new SiteOAuthConsentError('Missing sites OAuth signing secret', 500);
+    }
+
+    const rawBody = JSON.stringify(body);
+    const timestamp = Math.floor(Date.now() / 1000);
+    const signature = createHmac('sha256', GITBOOK_SITE_OAUTH_SIGNING_SECRET)
+        .update(`${siteId}:${timestamp}:${rawBody}`)
+        .digest('hex');
+
+    const url = new URL(GITBOOK_OAUTH_SERVER_URL);
+    url.pathname += `/${encodeURIComponent(siteId)}/${endpoint}`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            'x-gitbook-signature': signature,
+            'x-gitbook-timestamp': String(timestamp),
+        },
+        body: rawBody,
+        cache: 'no-store',
+    });
+
+    if (!response.ok) {
+        throw new SiteOAuthConsentError(
+            `OAuth server ${endpoint} responded with ${response.status}`,
+            response.status
+        );
+    }
+
+    return (await response.json()) as T;
+}
diff --git a/packages/gitbook/src/middleware.ts b/packages/gitbook/src/middleware.ts
index d5faa030d..d2edaee43 100644
--- a/packages/gitbook/src/middleware.ts
+++ b/packages/gitbook/src/middleware.ts
@@ -36,6 +36,7 @@ import {
     getPreviewRequestIdentifier,
     isPreviewRequest,
 } from '@/lib/preview';
+import { shouldRenderSiteOAuthConsent } from '@/lib/site-oauth/flag';
 import {
     type ResponseCookies,
     getPathScopedCookieName,
@@ -194,10 +195,19 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
 
     if (siteOAuthAuthorizeMatch) {
         const siteId = siteOAuthAuthorizeMatch.pathname.groups.siteId;
-        const siteOAuthAuthorizeURL = new URL(oauthServerURL);
-        siteOAuthAuthorizeURL.pathname += `/${siteId}/authorize`;
-        siteOAuthAuthorizeURL.search = siteOAuthAuthorizeMatch.search.input.replace('?', '');
-        return NextResponse.redirect(siteOAuthAuthorizeURL.toString());
+
+        // When the consent flow is enabled, GBO renders the consent screen for the post-login resume
+        // (recognized by the `gb_oauth_state` interaction id the OAuth server puts on the resume URL)
+        // instead of forwarding. We fall through to the normal site routing, which rewrites the
+        // request to the `~gitbook/oauth2/v1/[siteId]/authorize` route that renders consent.
+        //
+        // Otherwise we forward to the OAuth server exactly as before (legacy path).
+        if (!shouldRenderSiteOAuthConsent(siteRequestURL.searchParams)) {
+            const siteOAuthAuthorizeURL = new URL(oauthServerURL);
+            siteOAuthAuthorizeURL.pathname += `/${siteId}/authorize`;
+            siteOAuthAuthorizeURL.search = siteOAuthAuthorizeMatch.search.input.replace('?', '');
+            return NextResponse.redirect(siteOAuthAuthorizeURL.toString());
+        }
     }
 
     //
@@ -541,6 +551,21 @@ async function serveSiteRoutes(requestURL: URL, request: NextRequest) {
             response.headers.set('cache-control', 'public, max-age=0, must-revalidate');
         }
 
+        // The sites OAuth consent screen carries a security decision: lock it down so it can't be
+        // framed, cached, or leak the client's redirect URI via the Referer header.
+        if (pathname.match(/^~gitbook\/oauth2\/v1\/[^/]+\/authorize$/)) {
+            response.headers.set(
+                'content-security-policy',
+                getContentSecurityPolicy().replace(
+                    /frame-ancestors[^;]*;/,
+                    "frame-ancestors 'none';"
+                )
+            );
+            response.headers.set('x-frame-options', 'DENY');
+            response.headers.set('referrer-policy', 'no-referrer');
+            response.headers.set('cache-control', 'no-store');
+        }
+
         return writeResponseCookies(response, cookies);
     };
 
@@ -731,6 +756,11 @@ function encodePathInSiteContent(
         return { pathname };
     }
 
+    // The sites OAuth consent screen is rendered dynamically per request (client details, visitor).
+    if (pathname.match(/^~gitbook\/oauth2\/v1\/[^/]+\/authorize$/)) {
+        return { pathname, routeType: 'dynamic' };
+    }
+
     // If the pathname is a RSS feed (/.../rss.xml), we rewrite it to ~gitbook/rss/:pathname
     const rssMatch = pathname.match(RSS_PATH_REGEX);
     if (rssMatch) {

From 0dee4155a2a70f36f5dd445bb0a11cd3e1734537 Mon Sep 17 00:00:00 2001
From: spastorelli <spastorelli@users.noreply.github.com>
Date: Fri, 17 Jul 2026 17:16:46 +0200
Subject: [PATCH 44/46] Add consent flow env vars to next config (#4413)

---
 packages/gitbook/next.config.mjs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/gitbook/next.config.mjs b/packages/gitbook/next.config.mjs
index 992281a11..e093cfd77 100644
--- a/packages/gitbook/next.config.mjs
+++ b/packages/gitbook/next.config.mjs
@@ -46,6 +46,8 @@ const nextConfig = {
         GITBOOK_API_URL: process.env.GITBOOK_API_URL,
         GITBOOK_APP_URL: process.env.GITBOOK_APP_URL,
         GITBOOK_OAUTH_SERVER_URL: process.env.GITBOOK_OAUTH_SERVER_URL,
+        GITBOOK_SITE_OAUTH_SIGNING_SECRET: process.env.GITBOOK_SITE_OAUTH_SIGNING_SECRET,
+        GITBOOK_SITE_OAUTH_CONSENT_ENABLED: process.env.GITBOOK_SITE_OAUTH_CONSENT_ENABLED,
         GITBOOK_PREVIEW_BASE_URL: process.env.GITBOOK_PREVIEW_BASE_URL,
         GITBOOK_INTEGRATIONS_HOST: process.env.GITBOOK_INTEGRATIONS_HOST,
         GITBOOK_INTEGRATIONS_CONTENT_HOST: process.env.GITBOOK_INTEGRATIONS_CONTENT_HOST,

From 484cc11627fb279fff99244b1897d74df630d6e5 Mon Sep 17 00:00:00 2001
From: Tomek <tomasz@gitbook.io>
Date: Mon, 20 Jul 2026 10:47:04 +0200
Subject: [PATCH 45/46] Fix ScrollContainer scroll buttons not reflecting
 overflow immediately (#4414)

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
---
 .changeset/scroll-container-overflow-state.md |   5 +
 .../src/components/hooks/useScrollOverflow.ts | 104 ++++++++++++++++++
 .../components/primitives/ScrollContainer.tsx |  45 +-------
 3 files changed, 111 insertions(+), 43 deletions(-)
 create mode 100644 .changeset/scroll-container-overflow-state.md
 create mode 100644 packages/gitbook/src/components/hooks/useScrollOverflow.ts

diff --git a/.changeset/scroll-container-overflow-state.md b/.changeset/scroll-container-overflow-state.md
new file mode 100644
index 000000000..eda768fcd
--- /dev/null
+++ b/.changeset/scroll-container-overflow-state.md
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix ScrollContainer scroll buttons not reflecting content overflow immediately or after dynamic content changes (e.g. search results).
diff --git a/packages/gitbook/src/components/hooks/useScrollOverflow.ts b/packages/gitbook/src/components/hooks/useScrollOverflow.ts
new file mode 100644
index 000000000..48664255d
--- /dev/null
+++ b/packages/gitbook/src/components/hooks/useScrollOverflow.ts
@@ -0,0 +1,104 @@
+'use client';
+
+import * as React from 'react';
+import { useScrollListener } from './useScrollListener';
+
+/**
+ * Track the scroll position and overflow amount of a scrollable container,
+ * keeping them in sync with scroll events, resizes, and content changes.
+ */
+export function useScrollOverflow(
+    orientation: 'horizontal' | 'vertical',
+    containerRef: React.RefObject<HTMLElement | null>
+) {
+    const [scrollPosition, setScrollPosition] = React.useState(0);
+    const [scrollSize, setScrollSize] = React.useState(0);
+
+    const measure = React.useCallback(() => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+
+        const scrollDimension =
+            orientation === 'horizontal' ? container.scrollWidth : container.scrollHeight;
+        const clientDimension =
+            orientation === 'horizontal' ? container.clientWidth : container.clientHeight;
+
+        setScrollSize(Math.max(scrollDimension - clientDimension - 1, 0));
+        setScrollPosition(
+            orientation === 'horizontal' ? container.scrollLeft : container.scrollTop
+        );
+    }, [orientation, containerRef]);
+
+    useScrollListener(measure, containerRef);
+
+    // Measure synchronously on mount (and when the container/orientation changes), so
+    // initial overflow is detected without waiting for a resize/scroll event. Subsequent
+    // content changes are picked up by the observers below instead of re-measuring on
+    // every render.
+    React.useLayoutEffect(() => {
+        measure();
+    }, [measure]);
+
+    React.useEffect(() => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+
+        // Children can overflow (or stop overflowing) without the container itself
+        // changing size, so we observe the direct children in addition to the container,
+        // and re-register observers as children are added/removed.
+        let frame: number | null = null;
+        const scheduleMeasure = () => {
+            if (frame !== null) {
+                return;
+            }
+            frame = requestAnimationFrame(() => {
+                frame = null;
+                measure();
+            });
+        };
+
+        const ro = new ResizeObserver(scheduleMeasure);
+        ro.observe(container);
+        for (const child of Array.from(container.children)) {
+            ro.observe(child);
+        }
+
+        const mo = new MutationObserver((mutations) => {
+            for (const mutation of mutations) {
+                // Only re-register direct children with the resize observer; descendants
+                // deeper in the tree are covered by their parent's resize/mutation handling.
+                if (mutation.target !== container) {
+                    continue;
+                }
+                for (const node of Array.from(mutation.addedNodes)) {
+                    if (node instanceof Element) {
+                        ro.observe(node);
+                    }
+                }
+                for (const node of Array.from(mutation.removedNodes)) {
+                    if (node instanceof Element) {
+                        ro.unobserve(node);
+                    }
+                }
+            }
+            scheduleMeasure();
+        });
+        // Also watch descendants (subtree/characterData) so text/content changes deeper in
+        // the tree that grow or shrink scrollHeight/scrollWidth still trigger a re-measure.
+        mo.observe(container, { childList: true, subtree: true, characterData: true });
+
+        return () => {
+            if (frame !== null) {
+                cancelAnimationFrame(frame);
+            }
+            ro.disconnect();
+            mo.disconnect();
+        };
+    }, [measure, containerRef]);
+
+    return { scrollPosition, scrollSize };
+}
diff --git a/packages/gitbook/src/components/primitives/ScrollContainer.tsx b/packages/gitbook/src/components/primitives/ScrollContainer.tsx
index 8c70b2d03..1bc07addb 100644
--- a/packages/gitbook/src/components/primitives/ScrollContainer.tsx
+++ b/packages/gitbook/src/components/primitives/ScrollContainer.tsx
@@ -3,7 +3,7 @@
 import { tString, useLanguage } from '@/intl/client';
 import { tcls } from '@/lib/tailwind';
 import * as React from 'react';
-import { useScrollListener } from '../hooks/useScrollListener';
+import { useScrollOverflow } from '../hooks/useScrollOverflow';
 import { Button, type ButtonProps } from './Button';
 
 /**
@@ -56,50 +56,9 @@ export function ScrollContainer(props: ScrollContainerProps) {
 
     const containerRef = React.useRef<HTMLDivElement>(null);
 
-    const [scrollPosition, setScrollPosition] = React.useState(0);
-    const [scrollSize, setScrollSize] = React.useState(0);
-
     const language = useLanguage();
 
-    useScrollListener(() => {
-        const container = containerRef.current;
-        if (!container) {
-            return;
-        }
-
-        setScrollSize(
-            orientation === 'horizontal'
-                ? container.scrollWidth - container.clientWidth - 1
-                : container.scrollHeight - container.clientHeight - 1
-        );
-
-        setScrollPosition(
-            orientation === 'horizontal' ? container.scrollLeft : container.scrollTop
-        );
-    }, containerRef);
-
-    React.useEffect(() => {
-        const container = containerRef.current;
-        if (!container) {
-            return;
-        }
-
-        // Update max scroll position using resize observer
-        const ro = new ResizeObserver((entries) => {
-            const [entry] = entries;
-            if (entry) {
-                setScrollSize(
-                    orientation === 'horizontal'
-                        ? entry.target.scrollWidth - entry.target.clientWidth - 1
-                        : entry.target.scrollHeight - entry.target.clientHeight - 1
-                );
-            }
-        });
-
-        ro.observe(container);
-
-        return () => ro.disconnect();
-    }, [orientation]);
+    const { scrollPosition, scrollSize } = useScrollOverflow(orientation, containerRef);
 
     React.useEffect(() => {
         const container = containerRef.current;

From 03bbacf3199eaf434aea189db1217ae92d5b86f0 Mon Sep 17 00:00:00 2001
From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com>
Date: Mon, 20 Jul 2026 12:53:28 +0200
Subject: [PATCH 46/46] Add missing link reference to OpenAPI models (#4416)

---
 .changeset/few-parts-lead.md                  |  7 +++++
 .../DocumentView/OpenAPI/context.tsx          |  1 +
 .../components/DocumentView/OpenAPI/style.css | 26 +++++++++++++++-
 packages/openapi-parser/src/schemas.test.ts   | 18 +++++++++++
 packages/openapi-parser/src/schemas.ts        | 13 ++++++++
 .../react-openapi/src/OpenAPIDisclosure.tsx   | 30 +++++++++++++++++--
 packages/react-openapi/src/context.ts         |  1 +
 .../src/schemas/OpenAPISchemaItem.tsx         | 29 ++++++++++++++++--
 .../src/schemas/OpenAPISchemas.tsx            |  6 +++-
 packages/react-openapi/src/translations/de.ts |  1 +
 packages/react-openapi/src/translations/en.ts |  1 +
 packages/react-openapi/src/translations/es.ts |  1 +
 packages/react-openapi/src/translations/fr.ts |  1 +
 packages/react-openapi/src/translations/ja.ts |  1 +
 packages/react-openapi/src/translations/nl.ts |  1 +
 packages/react-openapi/src/translations/no.ts |  1 +
 .../react-openapi/src/translations/pt-br.ts   |  1 +
 packages/react-openapi/src/translations/zh.ts |  1 +
 18 files changed, 134 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/few-parts-lead.md
 create mode 100644 packages/openapi-parser/src/schemas.test.ts

diff --git a/.changeset/few-parts-lead.md b/.changeset/few-parts-lead.md
new file mode 100644
index 000000000..12eb6e774
--- /dev/null
+++ b/.changeset/few-parts-lead.md
@@ -0,0 +1,7 @@
+---
+"@gitbook/openapi-parser": patch
+"@gitbook/react-openapi": patch
+"gitbook": patch
+---
+
+Add missing link reference to OpenAPI models
diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx b/packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx
index 110eef2dd..90c962d22 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/context.tsx
@@ -52,6 +52,7 @@ export function getOpenAPIContext(args: {
             check: <Icon icon="check" />,
             lock: <Icon icon="lock" />,
             mcp: <Icon icon="mcp" />,
+            hashtag: <Icon icon="hashtag" />,
         },
         renderCodeBlock: (codeProps) => (
             <PlainCodeBlock
diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
index f7caf8370..bcf55daf0 100644
--- a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
+++ b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
@@ -865,6 +865,30 @@ body:has(.openapi-select-popover) {
     @apply border-t border-x last:border-b border-tint-subtle !ring-0 rounded-corners:first:!rounded-t-xl rounded-corners:last:!rounded-b-xl circular-corners:first:!rounded-t-2xl circular-corners:last:!rounded-b-2xl straight-corners:first:!rounded-t-xs straight-corners:last:!rounded-b-xs !rounded-none;
 }
 
+/* Model name + its hover hash-link, inline. Carries the anchor id / deep-link scroll target. */
+.openapi-schemas-model-title {
+    @apply flex items-center gap-2 min-w-0;
+    /* Offset by the trigger's p-5 so a deep-link lands the model's top edge, not its title, below the header. */
+    scroll-margin-top: calc(var(--content-scroll-margin) + 1.25rem);
+}
+
+.openapi-schemas-model-title-name {
+    @apply min-w-0 truncate;
+}
+
+.openapi-schemas-anchor-link {
+    @apply shrink-0 flex items-center opacity-0 transition-opacity;
+}
+
+.openapi-schemas-disclosure:hover .openapi-schemas-anchor-link,
+.openapi-schemas-anchor-link:focus-visible {
+    @apply opacity-100;
+}
+
+.openapi-schemas-anchor-link svg {
+    @apply size-3 text-tint-subtle hover:text-tint-strong;
+}
+
 .openapi-schemas-disclosure > .openapi-disclosure-trigger {
     @apply flex items-center font-mono transition-all font-normal text-tint-strong !text-sm hover:bg-tint-subtle dark:hover:bg-tint-hover relative flex-1 gap-2.5 p-5 truncate -outline-offset-1;
 }
@@ -965,7 +989,7 @@ body:has(.openapi-select-popover) {
     }
 }
 
-.openapi-disclosure-trigger[aria-expanded="true"] svg {
+.openapi-disclosure-trigger[aria-expanded="true"] .openapi-disclosure-trigger-label svg {
     @apply rotate-45;
 }
 
diff --git a/packages/openapi-parser/src/schemas.test.ts b/packages/openapi-parser/src/schemas.test.ts
new file mode 100644
index 000000000..dbd771ddb
--- /dev/null
+++ b/packages/openapi-parser/src/schemas.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'bun:test';
+import { getOpenAPISchemaAnchorId } from './schemas';
+
+describe('getOpenAPISchemaAnchorId', () => {
+    it('lowercases a simple name', () => {
+        expect(getOpenAPISchemaAnchorId('User')).toBe('user');
+    });
+
+    it('replaces non-alphanumeric runs with a single dash', () => {
+        expect(getOpenAPISchemaAnchorId('Pet Store')).toBe('pet-store');
+        expect(getOpenAPISchemaAnchorId('User.Profile_v2')).toBe('user-profile-v2');
+    });
+
+    it('trims leading and trailing dashes', () => {
+        expect(getOpenAPISchemaAnchorId('#User#')).toBe('user');
+        expect(getOpenAPISchemaAnchorId('  spaced  ')).toBe('spaced');
+    });
+});
diff --git a/packages/openapi-parser/src/schemas.ts b/packages/openapi-parser/src/schemas.ts
index b753cceee..33c22827c 100644
--- a/packages/openapi-parser/src/schemas.ts
+++ b/packages/openapi-parser/src/schemas.ts
@@ -2,6 +2,19 @@ import type { OpenAPIV3, OpenAPIV3_1 } from '@scalar/openapi-types';
 import { shouldIgnoreEntity } from './helpers/shouldIgnoreEntity';
 import type { OpenAPISchema } from './types';
 
+/**
+ * Build a stable, readable anchor id for a model/schema name (e.g. `User` -> `user`).
+ * Shared between the rendered disclosure and the page's table of contents so their ids match.
+ * Names are usually unique within a spec; a page heading could in theory slug to the same value.
+ */
+export function getOpenAPISchemaAnchorId(name: string): string {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '');
+}
+
 /**
  * Extract selected schemas from the OpenAPI document.
  */
diff --git a/packages/react-openapi/src/OpenAPIDisclosure.tsx b/packages/react-openapi/src/OpenAPIDisclosure.tsx
index 41b640ac1..fc5ff7fb2 100644
--- a/packages/react-openapi/src/OpenAPIDisclosure.tsx
+++ b/packages/react-openapi/src/OpenAPIDisclosure.tsx
@@ -1,7 +1,7 @@
 'use client';
 import clsx from 'classnames';
 import type React from 'react';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { Button, Disclosure, DisclosurePanel } from 'react-aria-components';
 
 /**
@@ -14,10 +14,36 @@ export function OpenAPIDisclosure(props: {
     label: string | ((isExpanded: boolean) => string);
     className?: string;
     defaultExpanded?: boolean;
+    /**
+     * Anchor id used as a deep-link target. When set, the disclosure expands and scrolls the
+     * element carrying this id into view once the URL hash matches it.
+     */
+    id?: string;
 }): React.JSX.Element {
-    const { icon, header, label, children, className, defaultExpanded = false } = props;
+    const { icon, header, label, children, className, defaultExpanded = false, id } = props;
     const [isExpanded, setIsExpanded] = useState(defaultExpanded);
 
+    // Expand and scroll into view when the URL hash points to this disclosure.
+    useEffect(() => {
+        if (!id) {
+            return;
+        }
+
+        const openFromHash = () => {
+            if (window.location.hash.slice(1) !== id) {
+                return;
+            }
+            setIsExpanded(true);
+            requestAnimationFrame(() => {
+                document.getElementById(id)?.scrollIntoView({ block: 'start' });
+            });
+        };
+
+        openFromHash();
+        window.addEventListener('hashchange', openFromHash);
+        return () => window.removeEventListener('hashchange', openFromHash);
+    }, [id]);
+
     return (
         <Disclosure
             className={clsx('openapi-disclosure', className)}
diff --git a/packages/react-openapi/src/context.ts b/packages/react-openapi/src/context.ts
index cfb07eadc..e21258836 100644
--- a/packages/react-openapi/src/context.ts
+++ b/packages/react-openapi/src/context.ts
@@ -17,6 +17,7 @@ export interface OpenAPIClientContext {
         check: React.ReactNode;
         lock: React.ReactNode;
         mcp: React.ReactNode;
+        hashtag: React.ReactNode;
     };
 
     /**
diff --git a/packages/react-openapi/src/schemas/OpenAPISchemaItem.tsx b/packages/react-openapi/src/schemas/OpenAPISchemaItem.tsx
index e21f877e4..a91fdf7a2 100644
--- a/packages/react-openapi/src/schemas/OpenAPISchemaItem.tsx
+++ b/packages/react-openapi/src/schemas/OpenAPISchemaItem.tsx
@@ -8,20 +8,45 @@ import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
 import { Section } from '../StaticSection';
 import type { OpenAPIClientContext } from '../context';
 import { getDisclosureLabel } from '../getDisclosureLabel';
+import { tString } from '../translate';
 
 export function OpenAPISchemaItem(props: {
+    id?: string;
     name: string;
     schema: OpenAPIV3.SchemaObject;
     context: OpenAPIClientContext;
 }) {
-    const { schema, context, name } = props;
+    const { schema, context, name, id } = props;
 
     return (
         <OpenAPIDisclosure
             className="openapi-schemas-disclosure"
             key={name}
+            id={id}
             icon={context.icons.plus}
-            header={name}
+            header={
+                id ? (
+                    <span id={id} className="openapi-schemas-model-title">
+                        <span className="openapi-schemas-model-title-name">{name}</span>
+                        <a
+                            href={`#${id}`}
+                            className="openapi-schemas-anchor-link"
+                            aria-label={tString(context.translation, 'direct_link_to_model', name)}
+                            // Keep the click from toggling the disclosure or scrolling; just set the URL.
+                            onPointerDown={(e) => e.stopPropagation()}
+                            onClick={(e) => {
+                                e.preventDefault();
+                                e.stopPropagation();
+                                window.history.pushState(null, '', `#${id}`);
+                            }}
+                        >
+                            {context.icons.hashtag}
+                        </a>
+                    </span>
+                ) : (
+                    name
+                )
+            }
             label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
             defaultExpanded={context.expandAllModelSections}
         >
diff --git a/packages/react-openapi/src/schemas/OpenAPISchemas.tsx b/packages/react-openapi/src/schemas/OpenAPISchemas.tsx
index 5d71e2022..045b172ba 100644
--- a/packages/react-openapi/src/schemas/OpenAPISchemas.tsx
+++ b/packages/react-openapi/src/schemas/OpenAPISchemas.tsx
@@ -1,3 +1,4 @@
+import { getOpenAPISchemaAnchorId } from '@gitbook/openapi-parser';
 import clsx from 'classnames';
 import { OpenAPIExample } from '../OpenAPIExample';
 import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
@@ -41,7 +42,9 @@ export function OpenAPISchemas(props: {
         const title = `The ${firstSchema.name} object`;
         return (
             <div className={clsx('openapi-schemas openapi-schemas-single', className)}>
-                <div className="openapi-summary" id={context.id}>
+                {/* The heading rendered below already carries the anchor id; a second id here would
+                    win the fragment target and scroll to the wrong margin. */}
+                <div className="openapi-summary">
                     {context.renderHeading({
                         title,
                         deprecated: Boolean(firstSchema.schema.deprecated),
@@ -88,6 +91,7 @@ export function OpenAPISchemas(props: {
                 return (
                     <OpenAPISchemaItem
                         key={name}
+                        id={getOpenAPISchemaAnchorId(name)}
                         name={name}
                         context={clientContext}
                         schema={schema}
diff --git a/packages/react-openapi/src/translations/de.ts b/packages/react-openapi/src/translations/de.ts
index a4238288d..1fd8611c8 100644
--- a/packages/react-openapi/src/translations/de.ts
+++ b/packages/react-openapi/src/translations/de.ts
@@ -45,4 +45,5 @@ export const de = {
     or: 'oder',
     and: 'und',
     possible_values: 'Mögliche Werte',
+    direct_link_to_model: 'Direktlink zu ${1}',
 };
diff --git a/packages/react-openapi/src/translations/en.ts b/packages/react-openapi/src/translations/en.ts
index e50d7cdaa..2bcfcd6ff 100644
--- a/packages/react-openapi/src/translations/en.ts
+++ b/packages/react-openapi/src/translations/en.ts
@@ -45,4 +45,5 @@ export const en = {
     properties: 'Properties',
     or: 'or',
     and: 'and',
+    direct_link_to_model: 'Direct link to ${1}',
 };
diff --git a/packages/react-openapi/src/translations/es.ts b/packages/react-openapi/src/translations/es.ts
index 21f61d010..210f00587 100644
--- a/packages/react-openapi/src/translations/es.ts
+++ b/packages/react-openapi/src/translations/es.ts
@@ -45,4 +45,5 @@ export const es = {
     or: 'o',
     and: 'y',
     possible_values: 'Valores posibles',
+    direct_link_to_model: 'Enlace directo a ${1}',
 };
diff --git a/packages/react-openapi/src/translations/fr.ts b/packages/react-openapi/src/translations/fr.ts
index aa2078905..7739f8966 100644
--- a/packages/react-openapi/src/translations/fr.ts
+++ b/packages/react-openapi/src/translations/fr.ts
@@ -45,4 +45,5 @@ export const fr = {
     or: 'ou',
     and: 'et',
     possible_values: 'Valeurs possibles',
+    direct_link_to_model: 'Lien direct vers ${1}',
 };
diff --git a/packages/react-openapi/src/translations/ja.ts b/packages/react-openapi/src/translations/ja.ts
index 4806663e6..80ffc2aa1 100644
--- a/packages/react-openapi/src/translations/ja.ts
+++ b/packages/react-openapi/src/translations/ja.ts
@@ -45,4 +45,5 @@ export const ja = {
     or: 'または',
     and: 'および',
     possible_values: '可能な値',
+    direct_link_to_model: '${1} への直接リンク',
 };
diff --git a/packages/react-openapi/src/translations/nl.ts b/packages/react-openapi/src/translations/nl.ts
index 3c58e1313..1ec738ef7 100644
--- a/packages/react-openapi/src/translations/nl.ts
+++ b/packages/react-openapi/src/translations/nl.ts
@@ -45,4 +45,5 @@ export const nl = {
     or: 'of',
     and: 'en',
     possible_values: 'Mogelijke waarden',
+    direct_link_to_model: 'Directe link naar ${1}',
 };
diff --git a/packages/react-openapi/src/translations/no.ts b/packages/react-openapi/src/translations/no.ts
index ed6c096e2..9aa8e2cc9 100644
--- a/packages/react-openapi/src/translations/no.ts
+++ b/packages/react-openapi/src/translations/no.ts
@@ -45,4 +45,5 @@ export const no = {
     or: 'eller',
     and: 'og',
     possible_values: 'Mulige verdier',
+    direct_link_to_model: 'Direktelenke til ${1}',
 };
diff --git a/packages/react-openapi/src/translations/pt-br.ts b/packages/react-openapi/src/translations/pt-br.ts
index 58cc8bf37..fa8eba81b 100644
--- a/packages/react-openapi/src/translations/pt-br.ts
+++ b/packages/react-openapi/src/translations/pt-br.ts
@@ -45,4 +45,5 @@ export const pt_br = {
     or: 'ou',
     and: 'e',
     possible_values: 'Valores possíveis',
+    direct_link_to_model: 'Link direto para ${1}',
 };
diff --git a/packages/react-openapi/src/translations/zh.ts b/packages/react-openapi/src/translations/zh.ts
index 4fb1bc88b..e04f6bd92 100644
--- a/packages/react-openapi/src/translations/zh.ts
+++ b/packages/react-openapi/src/translations/zh.ts
@@ -45,4 +45,5 @@ export const zh = {
     or: '或',
     and: '和',
     possible_values: '可能的值',
+    direct_link_to_model: '${1} 的直接链接',
 };