Add buttons to hide toolbar

Co-authored-by: Nicolas Dorseuil <nicolas@gitbook.io>

.changeset/calm-ties-burn.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix missing geo data in site insights because of incorrect proxying of events.

.changeset/cool-falcons-report.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add stable scroll gutter to search container

.changeset/cuddly-eels-live.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix robots.txt preventing favicon from being indexed.

.changeset/dry-melons-joke.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Make search accessible

.changeset/fair-bulldogs-double.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Improve default site icon

.changeset/few-elephants-carry.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Use sitespace title instead of space title in search

.changeset/fluffy-clouds-tap.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Support nested site section groups

.changeset/late-mangos-draw.md

@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Show a toolbar for authenticated users with access to the current site.

.changeset/little-months-exercise.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add support for inline expressions rendering with visitor data on GBO side

.changeset/mean-hornets-sip.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Update to column width sizing

.changeset/modern-experts-smoke.md

@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Expose a hook useVisitorSession to access the current user/visitor

.changeset/selfish-ravens-drop.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Expose "Best match" when site has translations

.changeset/shaggy-clocks-rule.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Improve screen reader accessibility for hints

.changeset/sharp-buses-wash.md

@@ -0,0 +1,5 @@
+---
+"@gitbook/react-openapi": minor
+---
+
+Fix OpenAPISecurities and code sample not using operation security requirements

.changeset/shiny-onions-guess.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix crash for card cover defined without objectFit

.changeset/slimy-points-talk.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add scrollcontainer component

.changeset/spicy-boats-change.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Refactor section tabs

.changeset/twelve-bears-clean.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix OpenAPI response dropdown & vertical overflow

.changeset/two-coats-trade.md

@@ -0,0 +1,5 @@
+---
+"@gitbook/react-openapi": patch
+---
+
+Fix OpenAPI response showing as JSON instead of YAML when it should

.changeset/wicked-hornets-crash.md

@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Scope search across sections and variants

package.json

@@ -34,7 +34,7 @@
     "workspaces": {
         "packages": ["packages/*"],
         "catalog": {
-            "@gitbook/api": "^0.141.0",
+            "@gitbook/api": "^0.142.0",
             "bidc": "^0.0.2"
         }
     },

packages/gitbook/e2e/customers.spec.ts

@@ -62,11 +62,11 @@ 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.spicychat.ai',
+    //     contentBaseURL: 'https://docs.spicychat.ai',
+    //     tests: [{ name: 'Home', url: '/' }],
+    // },
     {
         name: 'docs.portainer.io',
         contentBaseURL: 'https://docs.portainer.io',

packages/gitbook/openNext/customWorkers/middleware.js

@@ -26,8 +26,10 @@ export default class extends WorkerEntrypoint {
     async fetch(request) {
         return runWithCloudflareRequestContext(request, this.env, this.ctx, async () => {
             const startTime = Date.now();
+            const middlewareRequest = new Request(request.url, request);
+            middlewareRequest.headers.set('x-open-next-continent', request.cf?.continent || '');
             // - `Request`s are handled by the Next server
-            const reqOrResp = await middlewareHandler(request, this.env, this.ctx);
+            const reqOrResp = await middlewareHandler(middlewareRequest, this.env, this.ctx);
             if (reqOrResp instanceof Response) {
                 const duration = Date.now() - startTime;
                 const logMessage = formatLog(

packages/gitbook/openNext/incrementalCache.ts

@@ -7,6 +7,8 @@ import type {
 } from '@opennextjs/aws/types/overrides.js';
 import { getCloudflareContext } from '@opennextjs/cloudflare';
 
+import { withRegionalCache } from '@opennextjs/cloudflare/overrides/incremental-cache/regional-cache';
+
 import type { DurableObjectNamespace, Rpc } from '@cloudflare/workers-types';
 
 export const BINDING_NAME = 'NEXT_INC_CACHE_R2_BUCKET';
@@ -18,15 +20,12 @@ export type KeyOptions = {
 
 /**
  *
- * It is very similar to the `R2IncrementalCache` in the `@opennextjs/cloudflare` package, but it allow us to trace
- * the cache operations. It also integrates both R2 and Cache API in a single class.
- * Having our own, will allow us to customize it in the future if needed.
+ * It is very similar to the `R2IncrementalCache` in the `@opennextjs/cloudflare` package, but it has an additional
+ * R2WriteBuffer Durable Object to handle writes to R2. Given how we set up cache, we often end up writing to the same key too fast.
  */
 class GitbookIncrementalCache implements IncrementalCache {
     name = 'GitbookIncrementalCache';
 
-    protected localCache: Cache | undefined;
-
     async get<CacheType extends CacheEntryType = 'cache'>(
         key: string,
         cacheType?: CacheType
@@ -34,7 +33,6 @@ class GitbookIncrementalCache implements IncrementalCache {
         const cacheKey = this.getR2Key(key, cacheType);
 
         const r2 = getCloudflareContext().env[BINDING_NAME];
-        const localCache = await this.getCacheInstance();
         if (!r2) throw new Error('No R2 bucket');
         if (process.env.SHOULD_BYPASS_CACHE === 'true') {
             // We are in a local middleware environment, we should bypass the cache
@@ -42,27 +40,17 @@ class GitbookIncrementalCache implements IncrementalCache {
             return null;
         }
         try {
-            // Check local cache first if available
-            const localCacheEntry = await localCache.match(this.getCacheUrlKey(cacheKey));
-            if (localCacheEntry) {
-                const result = (await localCacheEntry.json()) as WithLastModified<
-                    CacheValue<CacheType>
-                >;
-                return this.returnNullOn404({
-                    ...result,
-                    // Because we use tag cache and also invalidate them every time,
-                    // if we get a cache hit, we don't need to check the tag cache as we already know it's not been revalidated
-                    // this should improve performance even further, and reduce costs
-                    shouldBypassTagCache: true,
-                });
-            }
-
             const r2Object = await r2.get(cacheKey);
             if (!r2Object) return null;
 
+            const json = (await r2Object.json()) as CacheValue<CacheType>;
+            const lastModified = r2Object.uploaded.getTime();
+
+            if (!json) return null;
+
             return this.returnNullOn404({
-                value: await r2Object.json(),
-                lastModified: r2Object.uploaded.getTime(),
+                value: json,
+                lastModified,
             });
         } catch (e) {
             console.error('Failed to get from cache', e);
@@ -89,39 +77,8 @@ class GitbookIncrementalCache implements IncrementalCache {
     ): Promise<void> {
         const cacheKey = this.getR2Key(key, cacheType);
 
-        const localCache = await this.getCacheInstance();
-
         try {
             await this.writeToR2(cacheKey, JSON.stringify(value));
-
-            //TODO: Check if there is any places where we don't have tags
-            // Ideally we should always have tags, but in case we don't, we need to decide how to handle it
-            // For now we default to a build ID tag, which allow us to invalidate the cache in case something is wrong in this deployment
-            const tags = this.getTagsFromCacheEntry(value) ?? [
-                `build_id/${process.env.NEXT_BUILD_ID}`,
-            ];
-
-            // We consider R2 as the source of truth, so we update the local cache
-            // only after a successful R2 write
-            await localCache.put(
-                this.getCacheUrlKey(cacheKey),
-                new Response(
-                    JSON.stringify({
-                        value,
-                        // Note: `Date.now()` returns the time of the last IO rather than the actual time.
-                        //       See https://developers.cloudflare.com/workers/reference/security-model/
-                        lastModified: Date.now(),
-                    }),
-                    {
-                        headers: {
-                            // Cache-Control default to 30 minutes, will be overridden by `revalidate`
-                            // In theory we should always get the `revalidate` value
-                            'cache-control': `max-age=${value.revalidate ?? 60 * 30}`,
-                            'cache-tag': tags.join(','),
-                        },
-                    }
-                )
-            );
         } catch (e) {
             console.error('Failed to set to cache', e);
         }
@@ -131,14 +88,10 @@ class GitbookIncrementalCache implements IncrementalCache {
         const cacheKey = this.getR2Key(key);
 
         const r2 = getCloudflareContext().env[BINDING_NAME];
-        const localCache = await this.getCacheInstance();
         if (!r2) throw new Error('No R2 bucket');
 
         try {
             await r2.delete(cacheKey);
-
-            // Here again R2 is the source of truth, so we delete from local cache first
-            await localCache.delete(this.getCacheUrlKey(cacheKey));
         } catch (e) {
             console.error('Failed to delete from cache', e);
         }
@@ -168,12 +121,6 @@ class GitbookIncrementalCache implements IncrementalCache {
         }
     }
 
-    async getCacheInstance(): Promise<Cache> {
-        if (this.localCache) return this.localCache;
-        this.localCache = await caches.open('incremental-cache');
-        return this.localCache;
-    }
-
     // Utility function to generate keys for R2/Cache API
     getR2Key(initialKey: string, cacheType: CacheEntryType = 'cache'): string {
         let key = initialKey;
@@ -189,28 +136,13 @@ class GitbookIncrementalCache implements IncrementalCache {
             '/'
         );
     }
-
-    getCacheUrlKey(cacheKey: string): string {
-        return `http://cache.local/${cacheKey}`;
-    }
-
-    getTagsFromCacheEntry<CacheType extends CacheEntryType>(
-        entry: CacheValue<CacheType>
-    ): string[] | undefined {
-        if ('tags' in entry && entry.tags) {
-            return entry.tags;
-        }
-
-        if ('meta' in entry && entry.meta && 'headers' in entry.meta && entry.meta.headers) {
-            const rawTags = entry.meta.headers['x-next-cache-tags'];
-            if (typeof rawTags === 'string') {
-                return rawTags.split(',');
-            }
-        }
-        if ('value' in entry) {
-            return entry.tags;
-        }
-    }
 }
 
-export default new GitbookIncrementalCache();
+export default withRegionalCache(new GitbookIncrementalCache(), {
+    mode: 'long-lived',
+    // We can do it because we use our own logic to invalidate the cache
+    bypassTagCacheOnCacheHit: true,
+    defaultLongLivedTtlSec: 60 * 60 * 24 /* 24 hours */,
+    // We don't want to update the cache entry on every cache hit
+    shouldLazilyUpdateOnCacheHit: false,
+});

packages/gitbook/package.json

@@ -4,6 +4,7 @@
     "private": true,
     "dependencies": {
         "@gitbook/api": "catalog:",
+        "@gitbook/expr": "workspace:*",
         "@gitbook/browser-types": "workspace:*",
         "@gitbook/cache-tags": "workspace:*",
         "@gitbook/colors": "workspace:*",
@@ -14,7 +15,8 @@
         "@gitbook/react-contentkit": "workspace:*",
         "@gitbook/react-math": "workspace:*",
         "@gitbook/react-openapi": "workspace:*",
-        "@opennextjs/cloudflare": "^1.7.1",
+        "@modelcontextprotocol/sdk": "^1.17.5",
+        "@opennextjs/cloudflare": "^1.8.3",
         "@radix-ui/react-checkbox": "^1.0.4",
         "@radix-ui/react-dropdown-menu": "^2.1.12",
         "@radix-ui/react-hover-card": "^1.1.15",
@@ -39,6 +41,7 @@
         "jwt-decode": "^4.0.0",
         "katex": "^0.16.9",
         "mathjax": "^3.2.2",
+        "mcp-handler": "^1.0.2",
         "mdast-util-from-markdown": "^2.0.2",
         "mdast-util-frontmatter": "^2.0.1",
         "mdast-util-gfm": "^3.1.0",
@@ -46,6 +49,7 @@
         "memoizee": "^0.4.17",
         "micromark-extension-frontmatter": "^2.0.0",
         "micromark-extension-gfm": "^3.0.0",
+        "motion": "^12.23.12",
         "next": "15.4.0",
         "next-themes": "^0.2.1",
         "nuqs": "^2.2.3",
@@ -71,10 +75,8 @@
         "url-join": "^5.0.0",
         "usehooks-ts": "^3.1.0",
         "warn-once": "^0.1.1",
-        "zustand": "^5.0.3",
-        "mcp-handler": "^1.0.2",
-        "@modelcontextprotocol/sdk": "^1.17.5",
-        "zod": "^3"
+        "zod": "^3",
+        "zustand": "^5.0.3"
     },
     "devDependencies": {
         "@argos-ci/playwright": "^5.0.9",

packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/demo/route.ts

@@ -16,9 +16,107 @@ export async function GET(
     return new Response(
         `
 <html>
-    <head></head>
-    <body></body>
+    <head>
+        <meta name="color-scheme" content="light dark">
+    </head>
+    <body>
+        <svg style="position: absolute; bottom: 6rem; right: 4rem;" width="719" height="644" viewBox="0 0 719 644" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <rect opacity="0.1" x="0.566895" y="208" width="529.567" height="228" rx="16" fill="#A4A7B0"/>
+            <g opacity="0.2">
+                <line x1="141.567" y1="472" x2="4.56689" y2="472" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="416.067" y1="472" x2="165.567" y2="472" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="526.567" y1="472" x2="440.067" y2="472" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="194.567" y1="496" x2="4.56689" y2="496" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="324.067" y1="496" x2="218.567" y2="496" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="473.567" y1="496" x2="348.067" y2="496" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="231.901" y1="520" x2="4.56689" y2="520" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="291.186" y1="520" x2="255.901" y2="520" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="442.058" y1="520" x2="315.186" y2="520" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="526.567" y1="520" x2="466.058" y2="520" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="141.567" y1="544" x2="4.56689" y2="544" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="348.191" y1="544" x2="165.567" y2="544" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="184.017" y1="592" x2="4.56689" y2="592" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="312.848" y1="592" x2="208.017" y2="592" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="386.574" y1="592" x2="336.848" y2="592" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="448.401" y1="592" x2="410.574" y2="592" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="126.633" y1="616" x2="4.56689" y2="616" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="401.133" y1="616" x2="150.633" y2="616" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="526.567" y1="616" x2="425.133" y2="616" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="179.457" y1="640" x2="4.56689" y2="640" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="329.569" y1="640" x2="203.457" y2="640" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="141.567" y1="4" x2="4.56689" y2="4" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="416.067" y1="4" x2="165.567" y2="4" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="526.567" y1="4" x2="440.067" y2="4" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="194.567" y1="28" x2="4.56689" y2="28" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="324.067" y1="28" x2="218.567" y2="28" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="473.567" y1="28" x2="348.067" y2="28" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="231.901" y1="52" x2="4.56689" y2="52" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="291.186" y1="52" x2="255.901" y2="52" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="442.058" y1="52" x2="315.186" y2="52" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="526.567" y1="52" x2="466.058" y2="52" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="141.567" y1="76" x2="4.56689" y2="76" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="348.191" y1="76" x2="165.567" y2="76" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="184.017" y1="124" x2="4.56689" y2="124" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="312.848" y1="124" x2="208.017" y2="124" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="386.574" y1="124" x2="336.848" y2="124" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="448.401" y1="124" x2="410.574" y2="124" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="126.633" y1="148" x2="4.56689" y2="148" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="401.133" y1="148" x2="150.633" y2="148" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="526.567" y1="148" x2="425.133" y2="148" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="179.457" y1="172" x2="4.56689" y2="172" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="329.569" y1="172" x2="203.457" y2="172" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+                <rect x="563" y="208" width="156" height="256" rx="16" fill="#A4A7B0" opacity="0.05"/>
+            <g opacity="0.2">
+                <line x1="682.214" y1="228" x2="583" y2="228" stroke="#656973" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="638.472" y1="252" x2="583" y2="252" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="681.396" y1="252" x2="654.472" y2="252" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="617.989" y1="276" x2="583" y2="276" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="699" y1="276" x2="633.989" y2="276" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="603.168" y1="300" x2="583" y2="300" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="657.873" y1="300" x2="619.168" y2="300" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="637" y1="324" x2="583" y2="324" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="688.836" y1="324" x2="653" y2="324" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="657.474" y1="372" x2="583" y2="372" stroke="#656973" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="633" y1="396" x2="583" y2="396" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="699" y1="396" x2="649" y2="396" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="585.416" y1="420" x2="583" y2="420" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="621.731" y1="420" x2="601.416" y2="420" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="699" y1="420" x2="637.731" y2="420" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+            <g opacity="0.2">
+                <line x1="619.471" y1="444" x2="583" y2="444" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+                <line x1="658.186" y1="444" x2="635.471" y2="444" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
+            </g>
+        </svg>
+    </body>
     <script src="${context.linker.toAbsoluteURL(context.linker.toPathInSite('~gitbook/embed/script.js'))}"></script>
+    <script>
+    window.GitBook('configure', {
+        suggestions: [
+            'Help me get started',
+            'What can I ask you?',
+            'Show me tips and tricks',
+        ],
+    });
+        window.GitBook('open');
+    </script>
 </html>
 `,
         {

packages/gitbook/src/components/AI/useAI.tsx

@@ -137,7 +137,7 @@ export function useAI(): AIContext {
                     setSearchState((prev) => ({
                         ask: null, // Reset ask as we assume the assistant will handle it
                         query: prev?.query ?? null,
-                        global: prev?.global ?? false,
+                        scope: prev?.scope ?? 'default',
                         open: false,
                     }));
                     assistant.open(query);

packages/gitbook/src/components/AI/useAIChat.tsx

@@ -146,7 +146,7 @@ export function AIChatProvider(props: {
         setSearchState((prev) => ({
             ask: prev?.ask ?? initialQuery ?? '',
             query: prev?.query ?? null,
-            global: prev?.global ?? false,
+            scope: prev?.scope ?? 'default',
             open: false, // Close search popover when opening chat
         }));
     }, [setSearchState]);
@@ -159,7 +159,7 @@ export function AIChatProvider(props: {
         setSearchState((prev) => ({
             ask: null,
             query: prev?.query ?? null,
-            global: prev?.global ?? false,
+            scope: prev?.scope ?? 'default',
             open: false,
         }));
     }, [setSearchState]);
@@ -374,7 +374,7 @@ export function AIChatProvider(props: {
                 setSearchState((prev) => ({
                     ask: input.message,
                     query: prev?.query ?? null,
-                    global: prev?.global ?? false,
+                    scope: prev?.scope ?? 'default',
                     open: false,
                 }));
             }
@@ -435,7 +435,7 @@ export function AIChatProvider(props: {
         setSearchState((prev) => ({
             ask: '',
             query: prev?.query ?? null,
-            global: prev?.global ?? false,
+            scope: prev?.scope ?? 'default',
             open: false,
         }));
     }, [setSearchState]);

packages/gitbook/src/components/AIChat/AIChatInput.tsx

@@ -140,7 +140,7 @@ export function AIChatInput(props: {
                             <span className="leading-none">
                                 {t(language, 'ai_chat_context_title')}
                             </span>
-                            <Icon icon="question-circle" className="size-3" />
+                            <Icon icon="question-circle" className="size-3 shrink-0" />
                         </div>
                     </HoverCardTrigger>
                 </HoverCardRoot>

packages/gitbook/src/components/Adaptive/AdaptiveVisitorContextProvider.tsx

@@ -4,19 +4,14 @@ import type { GitBookSiteContext } from '@/lib/context';
 import { OpenAPIPrefillContextProvider } from '@gitbook/react-openapi';
 import * as React from 'react';
 import { createContext, useContext } from 'react';
-
-export type AdaptiveVisitorClaimsData = {
-    visitor: {
-        claims: Record<string, unknown> & { unsigned: Record<string, unknown> };
-    };
-};
+import type { AdaptiveVisitorClaims } from './types';
 
 /**
  * In-memory cache of visitor claim readers keyed by contextId.
  */
 const adaptiveVisitorReaderCache = new Map<
     string,
-    ReturnType<typeof createResourceReader<AdaptiveVisitorClaimsData | null>>
+    ReturnType<typeof createResourceReader<AdaptiveVisitorClaims | null>>
 >();
 
 function createResourceReader<T>(promise: Promise<T>) {
@@ -52,7 +47,7 @@ function getAdaptiveVisitorClaimsReader(url: string, contextId: string) {
                 if (!res.ok) {
                     return null;
                 }
-                return await res.json<AdaptiveVisitorClaimsData>();
+                return await res.json<AdaptiveVisitorClaims>();
             } catch {
                 return null;
             }
@@ -64,7 +59,7 @@ function getAdaptiveVisitorClaimsReader(url: string, contextId: string) {
     return reader;
 }
 
-export type AdaptiveVisitorContextValue = () => AdaptiveVisitorClaimsData | null;
+export type AdaptiveVisitorContextValue = () => AdaptiveVisitorClaims | null;
 
 const AdaptiveVisitorContext = createContext<AdaptiveVisitorContextValue>(() => null);
 

packages/gitbook/src/components/Adaptive/index.ts

@@ -1 +1,3 @@
+export * from './types';
+export * from './utils';
 export * from './AdaptiveVisitorContextProvider';

packages/gitbook/src/components/Adaptive/types.ts

@@ -0,0 +1,9 @@
+export type AdaptiveVisitorClaimsData = Record<string, unknown> & {
+    unsigned: Record<string, unknown>;
+};
+
+export type AdaptiveVisitorClaims = {
+    visitor: {
+        claims: AdaptiveVisitorClaimsData;
+    };
+};

packages/gitbook/src/components/Adaptive/utils.ts

@@ -0,0 +1,28 @@
+import type { Variables } from '@gitbook/api';
+import type { AdaptiveVisitorClaims } from './types';
+
+/**
+ * Return an evaluation context to evaluate expressions.
+ */
+export function createExpressionEvaluationContext(args: {
+    visitorClaims: AdaptiveVisitorClaims | null;
+    variables: {
+        space?: Variables;
+        page?: Variables;
+    };
+}) {
+    const { visitorClaims, variables } = args;
+    return {
+        ...(visitorClaims ? visitorClaims : {}),
+        space: {
+            vars: variables.space ?? {},
+        },
+        ...(variables.page
+            ? {
+                  page: {
+                      vars: variables.page ?? {},
+                  },
+              }
+            : {}),
+    };
+}

packages/gitbook/src/components/AdminToolbar/AdminToolbar.tsx

@@ -1,143 +1,63 @@
 import type { GitBookSiteContext } from '@/lib/context';
-import { Icon } from '@gitbook/icons';
-import React from 'react';
+import { AdminToolbarClient } from './AdminToolbarClient';
+import type { AdminToolbarContext } from './types';
 
-import { tcls } from '@/lib/tailwind';
-import { DateRelative } from '../primitives';
-import { IframeWrapper } from './IframeWrapper';
-import { RefreshChangeRequestButton } from './RefreshChangeRequestButton';
-import { Toolbar, ToolbarBody, ToolbarButton, ToolbarButtonGroups } from './Toolbar';
-
-interface AdminToolbarProps {
+export interface AdminToolbarProps {
     context: GitBookSiteContext;
 }
 
-function ToolbarLayout(props: { children: React.ReactNode }) {
-    return (
-        <div
-            className={tcls(
-                'fixed',
-                'bottom-5',
-                'left-1/2',
-                'z-50',
-                'transform',
-                '-translate-x-1/2',
-                'rounded-full',
-
-                'bg-tint-12/9',
-                'dark:bg-tint-1/9',
-
-                'shadow-lg',
-                'min-h-10',
-                'min-w-40',
-                'p-2',
-                'max-w-md',
-                'border-tint-12/1',
-                'backdrop-blur-md'
-            )}
-        >
-            <React.Suspense fallback={null}>{props.children}</React.Suspense>
-        </div>
-    );
-}
-
 /**
- * Toolbar with information for the content admin when previewing a revision or change-request.
+ * Server component that determines what type of toolbar to show and passes data to client component
  */
 export async function AdminToolbar(props: AdminToolbarProps) {
     const { context } = props;
 
-    if (context.changeRequest) {
-        return (
-            <IframeWrapper>
-                <ChangeRequestToolbar context={context} />
-            </IframeWrapper>
-        );
-    }
+    // Create a minimal context to avoid serializing and passing too many data to the client
+    const minimalContext: AdminToolbarContext = {
+        organizationId: context.organizationId,
+        revisionId: context.revisionId,
+        space: {
+            id: context.space.id,
+            revision: context.space.revision,
+            urls: {
+                app: context.space.urls.app,
+            },
+        },
+        changeRequest: context.changeRequest
+            ? {
+                  id: context.changeRequest.id,
+                  number: context.changeRequest.number,
+                  subject: context.changeRequest.subject,
+                  revision: context.changeRequest.revision,
+                  updatedAt: context.changeRequest.updatedAt,
+                  createdBy: {
+                      displayName: context.changeRequest.createdBy.displayName,
+                  },
+                  urls: {
+                      app: context.changeRequest.urls.app,
+                  },
+              }
+            : null,
+        revision: {
+            createdAt: context.revision.createdAt,
+            urls: {
+                app: context.revision.urls.app,
+            },
+            git: context.revision.git
+                ? {
+                      url: context.revision.git.url,
+                  }
+                : null,
+        },
+        site: {
+            id: context.site.id,
+            title: context.site.title,
+            urls: {
+                app: context.site.urls.app,
+                published: context.site.urls.published,
+            },
+        },
+    };
 
-    if (context.revisionId !== context.space.revision) {
-        return (
-            <IframeWrapper>
-                <RevisionToolbar context={context} />
-            </IframeWrapper>
-        );
-    }
-
-    return null;
-}
-
-async function ChangeRequestToolbar(props: { context: GitBookSiteContext }) {
-    const { context } = props;
-    const { space, changeRequest } = context;
-
-    if (!changeRequest) {
-        return null;
-    }
-
-    return (
-        <ToolbarLayout>
-            <Toolbar>
-                <ToolbarButton title="Open in application" href={changeRequest.urls.app}>
-                    <Icon icon="code-branch" className="size-4" />
-                </ToolbarButton>
-                <ToolbarBody>
-                    <p>
-                        #{changeRequest.number}: {changeRequest.subject ?? 'No subject'}
-                    </p>
-                    <p className="text-tint-2 text-xs dark:text-tint-11">
-                        Change request updated <DateRelative value={changeRequest.updatedAt} />
-                    </p>
-                </ToolbarBody>
-                <ToolbarButtonGroups>
-                    <ToolbarButton title="Open in application" href={changeRequest.urls.app}>
-                        <Icon icon="arrow-up-right-from-square" className="size-4" />
-                    </ToolbarButton>
-                    <RefreshChangeRequestButton
-                        spaceId={space.id}
-                        changeRequestId={changeRequest.id}
-                        revisionId={changeRequest.revision}
-                        updatedAt={new Date(changeRequest.updatedAt).getTime()}
-                    />
-                </ToolbarButtonGroups>
-            </Toolbar>
-        </ToolbarLayout>
-    );
-}
-
-async function RevisionToolbar(props: { context: GitBookSiteContext }) {
-    const { context } = props;
-    const { revision } = context;
-
-    return (
-        <ToolbarLayout>
-            <Toolbar>
-                <ToolbarButton title="Open in application" href={revision.urls.app}>
-                    <Icon icon="code-commit" className="size-4" />
-                </ToolbarButton>
-                <ToolbarBody>
-                    <p>
-                        Revision created <DateRelative value={revision.createdAt} />
-                    </p>
-                    {revision.git ? (
-                        <p className="text-tint-2 text-xs dark:text-tint-11">
-                            {revision.git.message}
-                        </p>
-                    ) : null}
-                </ToolbarBody>
-                <ToolbarButtonGroups>
-                    <ToolbarButton title="Open in application" href={revision.urls.app}>
-                        <Icon icon="arrow-up-right-from-square" className="size-4" />
-                    </ToolbarButton>
-                    {revision.git?.url ? (
-                        <ToolbarButton title="Open git commit" href={revision.git.url}>
-                            <Icon
-                                icon={revision.git.url.includes('github.com') ? 'github' : 'gitlab'}
-                                className="size-4"
-                            />
-                        </ToolbarButton>
-                    ) : null}
-                </ToolbarButtonGroups>
-            </Toolbar>
-        </ToolbarLayout>
-    );
+    return <AdminToolbarClient context={minimalContext} />;
 }

packages/gitbook/src/components/AdminToolbar/AdminToolbarClient.tsx

@@ -0,0 +1,407 @@
+'use client';
+import { Icon } from '@gitbook/icons';
+import { MotionConfig } from 'motion/react';
+import React from 'react';
+import { useCheckForContentUpdate } from '../AutoRefreshContent';
+import { useVisitorSession } from '../Insights';
+import { useCurrentPagePath } from '../hooks';
+import { DateRelative, Tooltip } from '../primitives';
+import { HideToolbarButton } from './HideToolbarButton';
+import { IframeWrapper } from './IframeWrapper';
+import { RefreshContentButton } from './RefreshContentButton';
+import {
+    Toolbar,
+    ToolbarBody,
+    ToolbarButton,
+    ToolbarButtonGroup,
+    type ToolbarButtonProps,
+    ToolbarSeparator,
+    ToolbarSubtitle,
+    ToolbarTitle,
+} from './Toolbar';
+import { ToolbarControlsProvider } from './ToolbarControlsContext';
+import type { AdminToolbarClientProps, AdminToolbarContext } from './types';
+
+export function AdminToolbarClient(props: AdminToolbarClientProps) {
+    const { context, onPersistentClose, onSessionClose, onToggleMinify } = props;
+    const [minified, setMinified] = React.useState(true);
+    const visitorSession = useVisitorSession();
+    const [sessionClosed, setSessionClosed] = React.useState(false);
+    const [shouldHide, setShouldHide] = React.useState(false);
+
+    React.useEffect(() => {
+        const STORAGE_KEY = 'gitbook_toolbar_closed';
+
+        try {
+            const hidden = !!localStorage.getItem(STORAGE_KEY);
+            setShouldHide(hidden);
+        } catch {
+            setShouldHide(false);
+        }
+    }, []);
+
+    const handleSessionClose = React.useCallback(() => {
+        setSessionClosed(true);
+        onSessionClose?.();
+    }, [onSessionClose]);
+
+    const handlePersistentClose = React.useCallback(() => {
+        try {
+            localStorage.setItem('gitbook_toolbar_closed', '1');
+        } catch {
+            console.error('Failed to close toolbar using local storage');
+        }
+        setSessionClosed(true);
+        onPersistentClose?.();
+    }, [onPersistentClose]);
+
+    const handleMinifiedChange = React.useCallback(
+        (value: boolean) => {
+            setMinified(value);
+            onToggleMinify?.();
+        },
+        [onToggleMinify]
+    );
+
+    const toolbarControls = React.useMemo(
+        () => ({
+            minimize: () => handleMinifiedChange(true),
+            closeSession: handleSessionClose,
+            closePersistent: handlePersistentClose,
+        }),
+        [handleMinifiedChange, handleSessionClose, handlePersistentClose]
+    );
+
+    if (shouldHide || sessionClosed) {
+        return null;
+    }
+
+    // If there is a change request, show the change request toolbar
+    if (context.changeRequest) {
+        return (
+            <ToolbarControlsProvider value={toolbarControls}>
+                <IframeWrapper>
+                    <MotionConfig reducedMotion="user">
+                        <ChangeRequestToolbar
+                            context={context}
+                            minified={minified}
+                            onMinifiedChange={handleMinifiedChange}
+                        />
+                    </MotionConfig>
+                </IframeWrapper>
+            </ToolbarControlsProvider>
+        );
+    }
+
+    // If the revision is not the current revision, the user is looking at a previous version of the site, so show the revision toolbar
+    if (context.revisionId !== context.space.revision) {
+        return (
+            <ToolbarControlsProvider value={toolbarControls}>
+                <IframeWrapper>
+                    <MotionConfig reducedMotion="user">
+                        <RevisionToolbar
+                            context={context}
+                            minified={minified}
+                            onMinifiedChange={handleMinifiedChange}
+                        />
+                    </MotionConfig>
+                </IframeWrapper>
+            </ToolbarControlsProvider>
+        );
+    }
+
+    // If the user is authenticated and part of the organization owning this site, show the authenticated user toolbar
+    if (visitorSession?.organizationId === context.organizationId) {
+        return (
+            <ToolbarControlsProvider value={toolbarControls}>
+                <IframeWrapper>
+                    <MotionConfig reducedMotion="user">
+                        <AuthenticatedUserToolbar
+                            context={context}
+                            minified={minified}
+                            onMinifiedChange={handleMinifiedChange}
+                        />
+                    </MotionConfig>
+                </IframeWrapper>
+            </ToolbarControlsProvider>
+        );
+    }
+}
+
+interface ToolbarViewProps {
+    context: AdminToolbarContext;
+    minified: boolean;
+    onMinifiedChange: (value: boolean) => void;
+}
+
+function ChangeRequestToolbar(props: ToolbarViewProps) {
+    const { context, minified, onMinifiedChange } = props;
+    const { changeRequest, site } = context;
+    if (!changeRequest) {
+        throw new Error('Change request is not set');
+    }
+
+    const author = changeRequest.createdBy.displayName;
+
+    const { refreshForUpdates, updated } = useCheckForContentUpdate({
+        revisionId: changeRequest.revision,
+    });
+
+    return (
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange}>
+            <ToolbarBody>
+                <ToolbarTitle
+                    prefix={`Change #${changeRequest.number}:`}
+                    suffix={`${changeRequest.subject || 'Untitled'}`}
+                />
+                <ToolbarSubtitle
+                    subtitle={
+                        <>
+                            <DateRelative value={changeRequest.updatedAt} /> by {author}
+                        </>
+                    }
+                />
+            </ToolbarBody>
+
+            <ToolbarSeparator />
+
+            <ToolbarActions>
+                {/* Refresh to retrieve latest changes */}
+                {updated ? <RefreshContentButton refreshForUpdates={refreshForUpdates} /> : null}
+
+                {/* Edit in GitBook */}
+                <EditPageButton href={changeRequest.urls.app} siteId={site.id} />
+
+                {/* Comment in app */}
+                <ToolbarButton
+                    title="Comment in a GitBook"
+                    href={getToolbarHref({
+                        href: `${changeRequest.urls.app}~/comments`,
+                        siteId: site.id,
+                        buttonId: 'comment',
+                    })}
+                    icon="comment"
+                />
+
+                {/* Open production site */}
+                {site.urls.published ? (
+                    <ToolbarButton
+                        title="Open production site"
+                        href={getToolbarHref({
+                            href: site.urls.published,
+                            siteId: site.id,
+                            buttonId: 'production-site',
+                        })}
+                        icon="globe"
+                    />
+                ) : null}
+
+                {/* Open CR in GitBook */}
+                <ToolbarButton
+                    title="View change request in GitBook"
+                    href={getToolbarHref({
+                        href: changeRequest.urls.app,
+                        siteId: site.id,
+                        buttonId: 'change-request',
+                    })}
+                    icon="code-pull-request"
+                />
+            </ToolbarActions>
+        </Toolbar>
+    );
+}
+
+function RevisionToolbar(props: ToolbarViewProps) {
+    const { context, minified, onMinifiedChange } = props;
+    const { revision, site } = context;
+    if (!revision) {
+        throw new Error('Revision is not set');
+    }
+
+    const gitURL = revision.git?.url;
+    const isGitHub = gitURL?.includes('github.com');
+    const gitProvider = isGitHub ? 'GitHub' : 'GitLab';
+
+    return (
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange}>
+            <Tooltip label="Site preview">
+                <ToolbarBody>
+                    <ToolbarTitle prefix="Site version" suffix={context.site.title} />
+                    <ToolbarSubtitle
+                        subtitle={
+                            <>
+                                Created <DateRelative value={revision.createdAt} />
+                            </>
+                        }
+                    />
+                </ToolbarBody>
+            </Tooltip>
+            <ToolbarSeparator />
+            <ToolbarActions>
+                {/* Open commit in Git client */}
+                <ToolbarButton
+                    title={
+                        gitURL ? (
+                            `Open commit in ${gitProvider}`
+                        ) : (
+                            <div className="flex items-center gap-2">
+                                Setup GitSync to edit using Git{' '}
+                                <div className="flex items-center gap-1 text-neutral-8 text-xs hover:text-neutral-6 hover:underline dark:text-neutral-3">
+                                    <a
+                                        href="https://gitbook.com/docs/getting-started/git-sync"
+                                        target="_blank"
+                                        rel="noopener noreferrer"
+                                        className=""
+                                        onClick={(e) => e.stopPropagation()}
+                                    >
+                                        Learn more
+                                    </a>
+                                    <Icon icon="arrow-up-right" className="size-3" />
+                                </div>
+                            </div>
+                        )
+                    }
+                    href={gitURL}
+                    disabled={!gitURL}
+                    icon={gitURL ? (isGitHub ? 'github' : 'gitlab') : 'github'}
+                />
+                {site.urls.published ? (
+                    <ToolbarButton
+                        title="Open production site"
+                        href={getToolbarHref({
+                            href: site.urls.published,
+                            siteId: site.id,
+                            buttonId: 'production-site',
+                        })}
+                        icon="globe"
+                    />
+                ) : null}
+                <ToolbarButton
+                    title="View this revision in GitBook"
+                    href={getToolbarHref({
+                        href: revision.urls.app,
+                        siteId: site.id,
+                        buttonId: 'revision',
+                    })}
+                    icon="code-commit"
+                />
+            </ToolbarActions>
+        </Toolbar>
+    );
+}
+
+function AuthenticatedUserToolbar(props: ToolbarViewProps) {
+    const { context, minified, onMinifiedChange } = props;
+    const { revision, space, site } = context;
+    const { refreshForUpdates, updated } = useCheckForContentUpdate({
+        revisionId: space.revision,
+    });
+
+    return (
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange}>
+            <Tooltip label="Site preview">
+                <ToolbarBody>
+                    <ToolbarTitle suffix={context.site.title} />
+                    <ToolbarSubtitle
+                        subtitle={
+                            <>
+                                Updated <DateRelative value={revision.createdAt} />
+                            </>
+                        }
+                    />
+                </ToolbarBody>
+            </Tooltip>
+            <ToolbarSeparator />
+            <ToolbarActions>
+                {/* Refresh to retrieve latest changes */}
+                {updated ? <RefreshContentButton refreshForUpdates={refreshForUpdates} /> : null}
+
+                {/* Edit in GitBook */}
+                <EditPageButton href={space.urls.app} siteId={site.id} />
+
+                {/* Open site in GitBook */}
+                <ToolbarButton
+                    title="Open site in GitBook"
+                    href={getToolbarHref({
+                        href: site.urls.app,
+                        siteId: site.id,
+                        buttonId: 'site',
+                    })}
+                    icon="gears"
+                />
+
+                {/* Customize in GitBook */}
+                <ToolbarButton
+                    title="Customize in GitBook"
+                    href={getToolbarHref({
+                        href: `${site.urls.app}/customization/general`,
+                        siteId: site.id,
+                        buttonId: 'customize',
+                    })}
+                    icon="palette"
+                />
+
+                {/* Open insights in GitBook */}
+                <ToolbarButton
+                    title="Open insights in GitBook"
+                    href={getToolbarHref({
+                        href: `${site.urls.app}/insights`,
+                        siteId: site.id,
+                        buttonId: 'insights',
+                    })}
+                    icon="chart-simple"
+                />
+            </ToolbarActions>
+        </Toolbar>
+    );
+}
+
+function ToolbarActions(props: { children: React.ReactNode }) {
+    const { children } = props;
+
+    return (
+        <ToolbarButtonGroup>
+            {children}
+            <HideToolbarButton />
+        </ToolbarButtonGroup>
+    );
+}
+
+function EditPageButton(props: {
+    href: string;
+    siteId: string;
+    motionValues?: ToolbarButtonProps['motionValues'];
+}) {
+    const { href, motionValues, siteId } = props;
+    const pagePath = useCurrentPagePath();
+
+    return (
+        <ToolbarButton
+            title="Edit in GitBook"
+            href={getToolbarHref({
+                href: `${href}${pagePath.startsWith('/') ? pagePath.slice(1) : pagePath}`,
+                siteId,
+                buttonId: 'edit',
+            })}
+            icon="pencil"
+            motionValues={motionValues}
+        />
+    );
+}
+
+/**
+ * Append utm parameters to a URL to track usage of the toolbar.
+ */
+function getToolbarHref({
+    href,
+    siteId,
+    buttonId,
+}: { href: string; siteId: string; buttonId: string }) {
+    const url = new URL(href);
+    url.searchParams.set('utm_source', 'content');
+    url.searchParams.set('utm_medium', 'toolbar');
+    url.searchParams.set('utm_campaign', siteId);
+    url.searchParams.set('utm_content', buttonId);
+
+    return url.toString();
+}

packages/gitbook/src/components/AdminToolbar/AnimatedLogo.module.css

@@ -0,0 +1,179 @@
+.svgLogo {
+  --logo-fill: var(--color-neutral-900);
+  --seg-A-color: #2782c4;
+  --seg-B-color: #43b7f2;
+  --seg-C-color: #8be2ff;
+  --trace-color: #dedfe3;
+
+
+  --T: 2s;
+  shape-rendering: geometricPrecision;
+  vector-effect: non-scaling-stroke;
+}
+
+:global(html.dark) .svgLogo {
+  --logo-fill: var(--color-neutral-100);
+  --trace-color: #46474c;
+}
+
+/* Base segment animation */
+.seg {
+  opacity: 0;
+  animation: segFade var(--T) ease both 0.06s, segAMove var(--T) linear,
+    segALen var(--T) linear;
+    animation-delay: 0.06s;
+  animation-fill-mode: forwards;
+}
+
+.segA {
+  animation-name: segFade, segAMove, segALen;
+}
+
+.segB {
+  animation-name: segFade, segBMove, segBLen;
+}
+
+.segC {
+  animation-name: segFade, segCMove, segCLen;
+}
+
+.trace {
+  animation: traceFill var(--T) ease both 0.06s;
+  animation-fill-mode: forwards;
+}
+
+@keyframes traceFill {
+  0% {
+    fill: transparent;
+    stroke:var(--trace-color);
+  }
+  95% {
+    fill: transparent;
+    stroke:var(--trace-color);
+  }
+  100% {
+    fill: var(--logo-fill);
+    stroke:none;
+  }
+}
+
+
+/* Segment A animation */
+@keyframes segAMove {
+  0% {
+    stroke-dashoffset: 0;
+    stroke: var(--seg-A-color);
+  }
+  50% {
+    stroke-dashoffset: -0.5;
+    stroke: var(--seg-A-color);
+  }
+  95% {
+    stroke-dashoffset: -1;
+  }
+  100% {
+    stroke-dashoffset: 0;
+    stroke: none;
+  }
+}
+
+@keyframes segALen {
+  0% {
+    stroke-dasharray: 0.18 0.82;
+  }
+  95% {
+    stroke-dasharray: 0.22 0.78;
+  }
+  100% {
+    stroke-dasharray: 1;
+  }
+}
+
+/* Segment B animation */
+@keyframes segBMove {
+  0% {
+    stroke-dashoffset: -0.18;
+    stroke: var(--seg-B-color);
+  }
+  50% {
+    stroke-dashoffset: -0.72;
+    stroke: var(--seg-B-color);
+  }
+  95% {
+    stroke-dashoffset: -1.18;
+    stroke: var(--seg-B-color);
+  }
+  100% {
+    stroke-dashoffset: 0;
+    stroke: none;
+  }
+}
+
+@keyframes segBLen {
+  0%,
+  50%,
+  95% {
+    stroke-dasharray: 0.2 0.8;
+  }
+  100% {
+    stroke-dasharray: 1;
+  }
+}
+
+/* Segment C animation */
+@keyframes segCMove {
+  0% {
+    stroke-dashoffset: -0.38;
+    stroke: var(--seg-C-color);
+  }
+  50% {
+    stroke-dashoffset: -0.92;
+    stroke: var(--seg-C-color);
+  }
+  95% {
+    stroke-dashoffset: -1.38;
+    stroke: var(--seg-C-color);
+  }
+  100% {
+    stroke-dashoffset: 0;
+    stroke: none;
+  }
+}
+
+@keyframes segCLen {
+  0% {
+    stroke-dasharray: 0.22 0.78;
+  }
+  95% {
+    stroke-dasharray: 0.18 0.82;
+  }
+  100% {
+    stroke-dasharray: 1;
+  }
+}
+
+/* Segment fade animation - stays visible at end */
+@keyframes segFade {
+  0% {
+    opacity: 0;
+  }
+  10% {
+    opacity: 1;
+  }
+  100% {
+    opacity: 1;
+  }
+}
+
+/* Reduced motion support */
+@media (prefers-reduced-motion: reduce) {
+  .seg {
+    animation: none;
+    opacity: 0;
+  }
+  .trace {
+    animation: none;
+    fill: var(--logo-fill);
+    stroke:none;
+  }
+}

packages/gitbook/src/components/AdminToolbar/AnimatedLogo.tsx

@@ -0,0 +1,62 @@
+import { tcls } from '@/lib/tailwind';
+import type React from 'react';
+import styles from './AnimatedLogo.module.css';
+
+export const AnimatedLogo: React.FC = () => {
+    return (
+        <svg
+            className={styles.svgLogo}
+            width="28"
+            height="28"
+            viewBox="0 0 28 28"
+            aria-hidden="true"
+        >
+            {/* Background trace */}
+            <path
+                d={dPath}
+                transform="translate(14,14) scale(0.4)"
+                strokeWidth={3}
+                pathLength={1}
+                strokeLinecap="round"
+                className={styles.trace}
+            />
+            {/* Three individual paths to create the 'chasing' segmented stroke effect */}
+            <path
+                className={tcls(styles.seg, styles.segA)}
+                d={dPath}
+                transform="translate(14,14) scale(0.4)"
+                fill="none"
+                strokeWidth={3}
+                pathLength={1}
+                strokeLinecap="round"
+                strokeDasharray="0.18 0.82"
+                strokeDashoffset={0}
+            />
+            <path
+                className={tcls(styles.seg, styles.segB)}
+                d={dPath}
+                transform="translate(14,14) scale(0.4)"
+                fill="none"
+                strokeWidth={3}
+                pathLength={1}
+                strokeLinecap="round"
+                strokeDasharray="0.20 0.80"
+                strokeDashoffset={-0.18}
+            />
+            <path
+                className={tcls(styles.seg, styles.segC)}
+                d={dPath}
+                transform="translate(14,14) scale(0.4)"
+                fill="none"
+                strokeWidth={3}
+                pathLength={1}
+                strokeLinecap="round"
+                strokeDasharray="0.22 0.78"
+                strokeDashoffset={-0.38}
+            />
+        </svg>
+    );
+};
+
+const dPath =
+    'M-5.07306 1.64898C-1.92626 3.46518 -0.352865 4.37328 1.37504 4.37477C3.10303 4.37628 4.67794 3.47098 7.82794 1.66027C7.82794 1.66027 27.9071 -9.88183 27.9071 -9.88183C28.8136 -10.4029 29.3724 -11.3687 29.3724 -12.4143C29.3724 -13.4598 28.8136 -14.4257 27.9071 -14.9467C27.9071 -14.9467 7.82063 -26.4931 7.82063 -26.4931C4.67414 -28.3018 3.10083 -29.2062 1.37453 -29.2055C-0.351665 -29.2048 -1.92427 -28.2992 -5.06947 -26.488C-5.06947 -26.488 -22.3372 -16.5441 -22.3372 -16.5441C-22.4651 -16.4704 -22.5291 -16.4336 -22.5888 -16.3986C-28.4872 -12.9457 -32.1315 -6.64173 -32.1802 0.192975C-32.1807 0.262075 -32.1807 0.335975 -32.1807 0.483575C-32.1807 0.631075 -32.1807 0.704875 -32.1802 0.773875C-32.1316 7.60087 -28.4955 13.899 -22.6075 17.3547C-22.548 17.3897 -22.4841 17.4266 -22.3564 17.5003C-22.3564 17.5003 -11.5399 23.7454 -11.5399 23.7454C-5.23716 27.3844 -2.08587 29.2039 1.37484 29.2051C4.83554 29.2062 7.98813 27.3889 14.2932 23.7541C14.2932 23.7541 25.7115 17.1718 25.7115 17.1718C28.8686 15.3518 30.4471 14.4418 31.3139 12.9416C32.1807 11.4414 32.1807 9.61938 32.1807 5.97517C32.1807 5.97517 32.1807 -1.06463 32.1807 -1.06463C32.1807 -2.07553 31.6332 -3.00723 30.75 -3.49913C29.8953 -3.97513 28.8536 -3.96802 28.0054 -3.48053C28.0054 -3.48053 4.59224 9.97808 4.59224 9.97808C3.02144 10.8811 2.23593 11.3326 1.37404 11.3329C0.512135 11.3331 -0.273565 10.8821 -1.84506 9.98007C-1.84506 9.98007 -17.6916 0.883775 -17.6916 0.883775C-18.4854 0.428075 -18.8823 0.200275 -19.2011 0.159175C-19.9279 0.065375 -20.6267 0.472475 -20.9036 1.15108C-21.025 1.44858 -21.0225 1.90628 -21.0176 2.82148C-21.014 3.49528 -21.0122 3.83218 -20.9492 4.14208C-20.8082 4.83607 -20.4431 5.46448 -19.91 5.93068C-19.672 6.13888 -19.3802 6.30727 -18.7966 6.64407C-18.7966 6.64407 -1.85397 16.4227 -1.85397 16.4227C-0.278465 17.332 0.509335 17.7867 1.37434 17.7869C2.23934 17.7872 3.02734 17.3329 4.60333 16.4245C4.60333 16.4245 25.3699 4.45377 25.3699 4.45377C25.9083 4.14348 26.1774 3.98828 26.3792 4.10488C26.5811 4.22148 26.5811 4.53218 26.5811 5.15357C26.5811 5.15357 26.5811 8.34667 26.5811 8.34667C26.5811 9.25768 26.5811 9.71317 26.3643 10.0883C26.1476 10.4634 25.753 10.6908 24.9637 11.1458C24.9637 11.1458 7.83524 21.0193 7.83524 21.0193C4.68194 22.837 3.10533 23.7458 1.37463 23.7451C-0.356065 23.7443 -1.93186 22.834 -5.08347 21.0134C-5.08347 21.0134 -21.1086 11.7563 -21.1086 11.7563C-21.1595 11.7269 -21.1849 11.7122 -21.2087 11.6984C-24.5687 9.73487 -26.642 6.14287 -26.6614 2.25128C-26.6616 2.22378 -26.6616 2.19438 -26.6616 2.13567C-26.6616 2.13567 -26.6616 -0.795425 -26.6616 -0.795425C-26.6616 -2.94372 -25.5174 -4.92953 -23.6587 -6.00682C-22.0163 -6.95883 -19.9905 -6.96072 -18.3463 -6.01183C-18.3463 -6.01183 -5.07306 1.64898 -5.07306 1.64898Z';

packages/gitbook/src/components/AdminToolbar/HideToolbarButton.tsx

@@ -0,0 +1,238 @@
+'use client';
+import { tcls } from '@/lib/tailwind';
+import { Icon, type IconName, IconStyle } from '@gitbook/icons';
+import { motion } from 'motion/react';
+import React, { useRef } from 'react';
+import { useOnClickOutside } from 'usehooks-ts';
+import { ToolbarButton, type ToolbarButtonProps } from './Toolbar';
+import styles from './Toolbar.module.css';
+import { useToolbarControls } from './ToolbarControlsContext';
+
+const ARC_DURATION_SECONDS = 0.4;
+const ARC_STAGGER_MS = 80;
+const BASE_ROTATION_DEG = 95;
+const ROTATION_STEP_DEG = 18;
+
+interface HideToolbarButtonProps {
+    motionValues?: ToolbarButtonProps['motionValues'];
+}
+
+/**
+ * Hide menu trigger. Expands a macOS Dock-like submenu with 3 labeled actions.
+ */
+export function HideToolbarButton(props: HideToolbarButtonProps) {
+    const { motionValues } = props;
+    const [open, setOpen] = React.useState(false);
+    const controls = useToolbarControls();
+
+    const ref = useRef<HTMLDivElement>(null);
+    const buttonRef = useRef<HTMLDivElement>(null);
+
+    const handleClickOutsideArcMenu = (event: Event) => {
+        // Don't close the arc if we are clicking  clicking on the button itself
+        if (buttonRef.current?.contains(event.target as Node)) {
+            return;
+        }
+        setOpen(false);
+    };
+    useOnClickOutside(ref, handleClickOutsideArcMenu);
+
+    // Close arc menu on scroll
+    React.useEffect(() => {
+        if (!open) return;
+
+        const handleScroll = () => setOpen(false);
+        window.addEventListener('scroll', handleScroll, { passive: true });
+
+        return () => window.removeEventListener('scroll', handleScroll);
+    }, [open]);
+
+    const items = React.useMemo(
+        () =>
+            [
+                controls?.minimize
+                    ? {
+                          id: 'minimize',
+                          icon: 'minus',
+                          label: 'Minimize',
+                          onClick: controls.minimize,
+                      }
+                    : null,
+                controls?.closeSession
+                    ? {
+                          id: 'session-close',
+                          icon: 'xmark',
+                          label: 'Close for one session',
+                          onClick: controls.closeSession,
+                      }
+                    : null,
+                controls?.closePersistent
+                    ? {
+                          id: 'persistent-close',
+                          icon: 'ban',
+                          label: "Don't show again",
+                          onClick: controls.closePersistent,
+                      }
+                    : null,
+            ].filter(Boolean) as Array<ArcMenuItem>,
+        [controls]
+    );
+
+    const sharedMotionStyle = motionValues
+        ? {
+              x: motionValues.x,
+          }
+        : undefined;
+
+    return (
+        <ToolbarButton
+            ref={buttonRef}
+            title={open ? 'Hide options' : 'Hide toolbar'}
+            onClick={() => {
+                setOpen((v) => !v);
+            }}
+            motionValues={motionValues}
+            icon="eye-slash"
+        >
+            {/* Expanding arc menu */}
+            {open && (
+                <motion.div
+                    className={tcls('pointer-events-none absolute inset-0', styles.arcMenu)}
+                    style={sharedMotionStyle as React.CSSProperties | undefined}
+                >
+                    <div
+                        className={tcls(
+                            'pointer-events-none absolute left-0 overflow-visible',
+                            styles.arcMenuPath
+                        )}
+                        ref={ref}
+                    >
+                        {items.map((item, index) => (
+                            <ArcToolbarButton
+                                index={index}
+                                staggerIndex={items.length - 1 - index}
+                                key={item.icon}
+                                {...item}
+                                onClick={() => {
+                                    setOpen(false);
+                                    item.onClick?.();
+                                }}
+                            />
+                        ))}
+                    </div>
+                </motion.div>
+            )}
+        </ToolbarButton>
+    );
+}
+
+type ArcMenuItem = {
+    id: string;
+    icon: IconName;
+    label: string;
+    description: string;
+    onClick?: () => void;
+};
+
+type ArcToolbarButtonProps = Pick<ArcMenuItem, 'label' | 'icon' | 'onClick'> & {
+    index: number;
+    staggerIndex?: number;
+    disabled?: boolean;
+    className?: string;
+    iconClassName?: string;
+};
+
+export function ArcToolbarButton(props: ArcToolbarButtonProps) {
+    const {
+        index,
+        staggerIndex = index,
+        label,
+        disabled,
+        className,
+        onClick = () => {},
+        icon,
+        iconClassName,
+    } = props;
+
+    const targetOffset = `calc(var(--start-distance) + ${index} * var(--spread-distance))`;
+
+    // Calculate rotation based on position along the arc
+    const calculateRotation = () => {
+        return BASE_ROTATION_DEG - index * ROTATION_STEP_DEG;
+    };
+
+    const itemRotation = calculateRotation();
+
+    return (
+        <div className="pointer-events-none">
+            <button
+                type="button"
+                onClick={() => {
+                    onClick();
+                }}
+                style={
+                    {
+                        '--target-offset-distance': targetOffset,
+                        '--arc-duration': `${ARC_DURATION_SECONDS}s`,
+                        '--arc-delay': `${(staggerIndex ?? 0) * ARC_STAGGER_MS}ms`,
+                        '--rotation-offset': `${itemRotation}deg`,
+                        offsetPath: 'border-box',
+                        offsetDistance: targetOffset,
+                        offsetAnchor: '0% 40%',
+                        offsetRotate: `auto ${itemRotation}deg`,
+                    } as React.CSSProperties
+                }
+                className={tcls(
+                    'group',
+                    'absolute',
+                    'top-0',
+                    'left-0',
+                    'w-40',
+                    'opacity-0',
+                    'pointer-events-auto',
+                    'flex',
+                    'items-center',
+                    'gap-2',
+                    styles.arcMenuItem,
+                    className
+                )}
+            >
+                <div
+                    className={tcls(
+                        'flex shrink-0 items-center justify-center gap-1',
+                        'h-8 w-8 rounded-full border',
+                        'truncate text-sm',
+                        'cursor-pointer transition-colors',
+                        'group-hover:-rotate-5 group-hover:scale-105',
+                        disabled ? 'cursor-not-allowed opacity-50' : '',
+                        'text-tint-1 dark:text-tint-12',
+                        'bg-[linear-gradient(110deg,rgba(51,53,57,1)_0%,rgba(50,52,56,1)_100%)]',
+                        'dark:[background:linear-gradient(110deg,rgba(255,255,255,1)_0%,rgba(240,246,248,1)_100%)]',
+                        'border border-solid dark:border-[rgb(255_255_255_/_40%)]'
+                    )}
+                    style={{
+                        background: 'linear-gradient(rgb(51, 53, 57), rgb(50, 52, 56))',
+                        border: '1px solid rgba(0, 0, 0, 0.06)',
+                        boxShadow: 'rgba(255, 255, 255, 0.15) 0px 1px 1px 0px inset',
+                    }}
+                >
+                    <Icon
+                        icon={icon as IconName}
+                        iconStyle={IconStyle.Solid}
+                        className={tcls('size-4 shrink-0 group-hover:scale-110', iconClassName)}
+                    />
+                </div>
+                <span
+                    className={tcls(
+                        'whitespace-nowrap rounded-lg px-3 py-1 font-normal text-sm transition-transform',
+                        'group-hover:rotate-2 group-hover:scale-105',
+                        'text-neutral-1 dark:text-neutral-12',
+                        'bg-[linear-gradient(110deg,rgba(51,53,57,1)_0%,rgba(50,52,56,1)_100%)]'
+                    )}
+                >
+                    {label}
+                </span>
+            </button>
+        </div>
+    );
+}

packages/gitbook/src/components/AdminToolbar/RefreshChangeRequestButton.tsx

@@ -1,70 +0,0 @@
-'use client';
-import { Icon } from '@gitbook/icons';
-import React from 'react';
-
-import { useCheckForContentUpdate } from '@/components/AutoRefreshContent';
-import { tcls } from '@/lib/tailwind';
-
-import { ToolbarButton } from './Toolbar';
-
-// We don't show the button if the content has been updated 30s ago or less.
-const minInterval = 1000 * 30; // 5 minutes
-
-/**
- * Button to refresh the page if the content has been updated.
- */
-export function RefreshChangeRequestButton(props: {
-    spaceId: string;
-    changeRequestId: string;
-    revisionId: string;
-    updatedAt: number;
-}) {
-    const { updatedAt } = props;
-
-    const [visible, setVisible] = React.useState(false);
-    const [loading, setLoading] = React.useState(false);
-    const checkForUpdates = useCheckForContentUpdate(props);
-
-    const refresh = React.useCallback(async () => {
-        setLoading(true);
-        try {
-            await checkForUpdates();
-        } finally {
-            setLoading(false);
-            setVisible(false);
-        }
-    }, [checkForUpdates]);
-
-    // Show the button if the content has been updated more than 30s ago.
-    React.useEffect(() => {
-        if (updatedAt < Date.now() - minInterval) {
-            setVisible(true);
-        }
-    }, [updatedAt]);
-
-    // 30sec after being hidden, we show the button again
-    React.useEffect(() => {
-        if (!visible) {
-            const timeout = setTimeout(() => {
-                setVisible(true);
-            }, minInterval);
-            return () => clearTimeout(timeout);
-        }
-    }, [visible]);
-
-    if (!visible) {
-        return null;
-    }
-
-    return (
-        <ToolbarButton
-            title="Refresh"
-            onClick={(event) => {
-                event.preventDefault();
-                refresh();
-            }}
-        >
-            <Icon icon="rotate" className={tcls('size-4', loading ? 'animate-spin' : null)} />
-        </ToolbarButton>
-    );
-}

packages/gitbook/src/components/AdminToolbar/RefreshContentButton.tsx

@@ -0,0 +1,42 @@
+'use client';
+import React from 'react';
+
+import { ToolbarButton, type ToolbarButtonProps } from './Toolbar';
+
+/**
+ * Button to refresh the page if the content has been updated.
+ */
+export function RefreshContentButton(props: {
+    refreshForUpdates: () => Promise<void>;
+    motionValues?: ToolbarButtonProps['motionValues'];
+}) {
+    const { refreshForUpdates, motionValues } = props;
+
+    const [loading, setLoading] = React.useState(false);
+
+    const refresh = React.useCallback(async () => {
+        setLoading(true);
+        try {
+            await refreshForUpdates();
+        } finally {
+            setLoading(false);
+        }
+    }, [refreshForUpdates]);
+
+    return (
+        <ToolbarButton
+            title="Refresh for latest changes"
+            onClick={(event) => {
+                if (loading) {
+                    return;
+                }
+                event.preventDefault();
+                refresh();
+            }}
+            disabled={loading}
+            motionValues={motionValues}
+            icon="rotate"
+            iconClassName={loading ? 'animate-spin' : undefined}
+        />
+    );
+}

packages/gitbook/src/components/AdminToolbar/Toolbar.module.css

@@ -0,0 +1,40 @@
+.arcMenu {
+    --arc-width: 505px;
+    --arc-height: 400px;
+    --arc-radius: 34%;
+    --start-distance: -240px;
+    --spread-distance: 45px;
+}
+
+.arcMenuPath {
+    bottom: calc(var(--arc-height) / -2);
+    width: var(--arc-width);
+    height: var(--arc-height);
+    border-radius: var(--arc-radius);
+    transform: translate(0%, 0%);
+}
+
+.arcMenuItem {
+    animation-name: hide-toolbar-arc-enter;
+    animation-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
+    animation-fill-mode: forwards;
+    animation-duration: var(--arc-duration, 0.4s);
+    animation-delay: var(--arc-delay, 0s);
+    transform-origin: center left;
+    offset-path: border-box;
+    offset-anchor: 0% 0%;
+    offset-rotate: auto var(--rotation-offset, 0deg);
+}
+
+@keyframes hide-toolbar-arc-enter {
+    from {
+        offset-distance: var(--start-distance);
+        transform: scale(0.5);
+        opacity: 0;
+    }
+    to {
+        offset-distance: var(--target-offset-distance);
+        transform: scale(1);
+        opacity: 1;
+    }
+}

packages/gitbook/src/components/AdminToolbar/Toolbar.tsx

@@ -1,65 +1,309 @@
 'use client';
-
-import type * as React from 'react';
+import {
+    AnimatePresence,
+    type MotionValue,
+    motion,
+    useReducedMotion,
+    useSpring,
+} from 'motion/react';
+import React from 'react';
+import { AnimatedLogo } from './AnimatedLogo';
 
 import { tcls } from '@/lib/tailwind';
+import { Icon, type IconName, IconStyle } from '@gitbook/icons';
+import { Tooltip } from '../primitives';
+import { getCopyVariants, toolbarEasings } from './transitions';
+import { useMagnificationEffect } from './useMagnificationEffect';
 
-export function Toolbar(props: { children: React.ReactNode }) {
-    const { children } = props;
+const DURATION_LOGO_APPEARANCE = 2000;
+const DELAY_BETWEEN_LOGO_AND_CONTENT = 100;
+
+interface ToolbarProps {
+    children: React.ReactNode;
+    minified: boolean;
+    onMinifiedChange: (value: boolean) => void;
+}
+
+export function Toolbar(props: ToolbarProps) {
+    const { children, minified, onMinifiedChange } = props;
+    const [isReady, setIsReady] = React.useState(false);
+
+    // Wait for page to be ready, then show the toolbar
+    React.useEffect(() => {
+        const handleLoad = () => {
+            setIsReady(true);
+        };
+
+        if (document.readyState === 'complete') {
+            handleLoad();
+        } else {
+            window.addEventListener('load', handleLoad);
+            return () => window.removeEventListener('load', handleLoad);
+        }
+    }, []);
+
+    // After toolbar appears, wait then show the full content
+    React.useEffect(() => {
+        if (!isReady) {
+            return;
+        }
+
+        const expandAfterTimeout = setTimeout(() => {
+            onMinifiedChange(false);
+        }, DURATION_LOGO_APPEARANCE + DELAY_BETWEEN_LOGO_AND_CONTENT);
+
+        return () => clearTimeout(expandAfterTimeout);
+    }, [isReady, onMinifiedChange]);
+
+    // Don't render anything until page is ready
+    if (!isReady) {
+        return null;
+    }
 
     return (
-        <div
-            className={tcls(
-                'flex',
-                'flex-row',
-                'items-center',
-                'gap-4',
-                'text-sm',
-                'px-4',
-                'py-1',
-                'rounded-full',
-                'truncate',
-                'text-tint-1',
-                'dark:text-tint-12'
-            )}
-        >
-            {children}
-        </div>
+        <motion.div className="-translate-x-1/2 fixed bottom-5 left-1/2 z-40 w-auto max-w-xl transform px-4">
+            <AnimatePresence mode="wait">
+                <motion.div
+                    onClick={() => {
+                        if (minified) {
+                            onMinifiedChange(false);
+                        }
+                    }}
+                    layout
+                    transition={toolbarEasings.spring}
+                    className={tcls(
+                        minified ? 'cursor-pointer px-2' : 'pr-2 pl-3.5',
+                        'flex',
+                        'items-center',
+                        'justify-center',
+                        'min-h-11',
+                        'min-w-12',
+                        'h-12',
+                        'py-2',
+                        'backdrop-blur-sm',
+                        'origin-center',
+                        'border-[0.5px] border-neutral-5 border-solid dark:border-neutral-8',
+                        'bg-[linear-gradient(45deg,rgba(255,255,255,0)_0%,rgba(255,255,255,0.2)_100%)]'
+                    )}
+                    initial={{
+                        scale: 1,
+                        opacity: 1,
+                    }}
+                    animate={{
+                        scale: 1,
+                        opacity: 1,
+                    }}
+                    style={{
+                        borderRadius: '100px', // This is set on `style` so Framer Motion can correct for distortions
+                    }}
+                >
+                    {/* Logo with stroke segments animation in blue-tints */}
+                    <motion.div layout>
+                        <AnimatedLogo />
+                    </motion.div>
+
+                    {!minified ? children : null}
+                </motion.div>
+            </AnimatePresence>
+        </motion.div>
     );
 }
 
 export function ToolbarBody(props: { children: React.ReactNode }) {
-    return <div className="flex flex-col gap-1">{props.children}</div>;
+    return <div className="flex flex-col items-start px-3">{props.children}</div>;
 }
 
-export function ToolbarButtonGroups(props: { children: React.ReactNode }) {
-    return <div className="flex flex-row gap-2">{props.children}</div>;
-}
+export function ToolbarButtonGroup(props: { children: React.ReactNode }) {
+    const { children } = props;
+    const containerRef = React.useRef<HTMLDivElement>(null);
+
+    const buttonChildren = React.Children.toArray(children).filter((child) => !!child);
+    const { buttonMotionValues } = useMagnificationEffect({
+        childrenCount: buttonChildren.length,
+        containerRef,
+    });
 
-export function ToolbarButton(props: React.HTMLProps<HTMLAnchorElement>) {
-    const { children, ...rest } = props;
     return (
-        <a
-            {...rest}
-            className={tcls(
-                'flex',
-                'flex-col',
-                'items-center',
-                'justify-center',
-                'size-11',
-                'gap-1',
-                'text-sm',
-                'rounded-full',
-                'truncate',
-                'text-tint-1', // Equal to text-tint-strong in dark mode
-                'dark:text-tint-12', // Equal to text-tint-strong in dark mode
-                'hover:bg-tint-12',
-                'dark:hover:bg-tint-1',
-                'hover:shadow-lg',
-                'cursor-pointer'
-            )}
+        <motion.div
+            ref={containerRef}
+            variants={toolbarEasings.parent}
+            initial="hidden"
+            animate="show"
+            className="flex items-center gap-1 overflow-visible pr-2 pl-4"
         >
-            {children}
-        </a>
+            {buttonChildren.map((child, index) => {
+                const childEl = child as React.ReactElement;
+                const childKey = childEl.key ?? `toolbar-button-${index}`;
+                return (
+                    <ToolbarButtonWrapper
+                        key={childKey}
+                        child={childEl}
+                        rawMotionValues={buttonMotionValues[index]}
+                    />
+                );
+            })}
+        </motion.div>
+    );
+}
+
+export interface ToolbarButtonProps extends Omit<React.HTMLProps<HTMLAnchorElement>, 'title'> {
+    motionValues?: {
+        scale: MotionValue<number>;
+        x: MotionValue<number>;
+    };
+    icon: IconName;
+    iconClassName?: string;
+    title?: React.ReactNode;
+    children?: React.ReactNode;
+}
+
+export const ToolbarButton = React.forwardRef<HTMLDivElement, ToolbarButtonProps>((props, ref) => {
+    const {
+        title,
+        disabled,
+        motionValues,
+        className,
+        style,
+        href,
+        onClick,
+        icon,
+        iconClassName,
+        children,
+    } = props;
+    const reduceMotion = useReducedMotion();
+
+    return (
+        <motion.div variants={toolbarEasings.staggeringChild} className="relative" ref={ref}>
+            {children ? children : null}
+            <Tooltip label={title}>
+                <motion.a
+                    href={href}
+                    onClick={onClick}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    style={
+                        reduceMotion
+                            ? undefined
+                            : {
+                                  scale: motionValues?.scale,
+                                  x: motionValues?.x,
+                                  transformOrigin: 'bottom center',
+                                  zIndex: motionValues?.scale ? 10 : 'auto',
+                                  ...style,
+                                  background: 'linear-gradient(rgb(51, 53, 57), rgb(50, 52, 56))',
+                                  boxShadow: 'rgba(255, 255, 255, 0.15) 0px 1px 1px 0px inset',
+                                  border: '1px solid rgba(0, 0, 0, 0.06)',
+                              }
+                    }
+                    transition={{
+                        type: 'spring',
+                        stiffness: 400,
+                        damping: 30,
+                    }}
+                    className={tcls(
+                        'toolbar-button',
+                        className,
+                        'flex',
+                        'relative',
+                        'items-center',
+                        'justify-center',
+                        'gap-1',
+                        'text-sm',
+                        'rounded-full',
+                        'truncate',
+                        'text-tint-1',
+                        'dark:text-tint-12',
+                        'cursor-pointer',
+                        'transition-colors',
+                        'size-8',
+                        disabled ? 'cursor-not-allowed opacity-50' : ''
+                    )}
+                >
+                    <Icon
+                        icon={icon}
+                        iconStyle={IconStyle.Solid}
+                        className={tcls(
+                            'size-4 shrink-0 group-hover:scale-110 group-hover:text-tint-3',
+                            iconClassName
+                        )}
+                    />
+                </motion.a>
+            </Tooltip>
+        </motion.div>
+    );
+});
+
+ToolbarButton.displayName = 'ToolbarButton';
+
+function ToolbarButtonWrapper(props: {
+    child: React.ReactElement;
+    rawMotionValues?: { scale: MotionValue<number>; x: MotionValue<number> };
+}) {
+    const { child, rawMotionValues } = props;
+
+    // Convert the raw motion values to smooth spring easings
+    const springScale = useSpring(rawMotionValues?.scale.get() ?? 1, {
+        stiffness: 400,
+        damping: 30,
+    });
+    const springX = useSpring(rawMotionValues?.x.get() ?? 0, { stiffness: 400, damping: 30 });
+
+    // Sync springs with raw motion values
+    React.useEffect(() => {
+        if (!rawMotionValues) return;
+
+        const unsubScale = rawMotionValues.scale.on('change', (v) => springScale.set(v));
+        const unsubX = rawMotionValues.x.on('change', (v) => springX.set(v));
+
+        return () => {
+            unsubScale();
+            unsubX();
+        };
+    }, [rawMotionValues, springScale, springX]);
+
+    const motionValues = {
+        scale: springScale,
+        x: springX,
+    };
+
+    return React.cloneElement(child, {
+        motionValues,
+    });
+}
+
+export function ToolbarSeparator() {
+    return <div className="h-5 w-px bg-tint-1/3" />;
+}
+
+export function ToolbarTitle(props: { prefix?: string; suffix: string }) {
+    return (
+        <div className="flex items-center gap-1 text-xs ">
+            {props.prefix ? <ToolbarTitlePrefix title={props.prefix} /> : null}
+            <ToolbarTitleSuffix title={props.suffix} />
+        </div>
+    );
+}
+
+function ToolbarTitlePrefix(props: { title: string }) {
+    return (
+        <motion.span {...getCopyVariants(0)} className="truncate font-medium text-neutral-12">
+            {props.title}
+        </motion.span>
+    );
+}
+
+function ToolbarTitleSuffix(props: { title: string }) {
+    return (
+        <motion.span {...getCopyVariants(1)} className="max-w-[20ch] truncate text-neutral-12">
+            {props.title}
+        </motion.span>
+    );
+}
+
+export function ToolbarSubtitle(props: { subtitle: React.ReactNode }) {
+    return (
+        <motion.span {...getCopyVariants(1)} className="text-neutral-12/90 text-xxs">
+            {props.subtitle}
+        </motion.span>
     );
 }

packages/gitbook/src/components/AdminToolbar/ToolbarControlsContext.tsx

@@ -0,0 +1,21 @@
+'use client';
+import React from 'react';
+
+export interface ToolbarControlsContextValue {
+    minimize: () => void;
+    closeSession?: () => void;
+    closePersistent?: () => void;
+}
+
+const ToolbarControlsContext = React.createContext<ToolbarControlsContextValue | null>(null);
+
+export function ToolbarControlsProvider(
+    props: React.PropsWithChildren<{ value: ToolbarControlsContextValue | null }>
+) {
+    const { children, value } = props;
+    return <ToolbarControlsContext.Provider value={value}>{children}</ToolbarControlsContext.Provider>;
+}
+
+export function useToolbarControls() {
+    return React.useContext(ToolbarControlsContext);
+}

packages/gitbook/src/components/AdminToolbar/index.ts

@@ -1,2 +1,5 @@
 export * from './AdminToolbar';
+export * from './AdminToolbarClient';
 export * from './IframeWrapper';
+export * from './Toolbar';
+export * from './transitions';

packages/gitbook/src/components/AdminToolbar/transitions.ts

@@ -0,0 +1,73 @@
+import type { Transition } from 'motion/react';
+
+// Slight bounce but minimal overshoot esp. at the minimized state.
+const spring = {
+    type: 'spring' as const,
+    stiffness: 130,
+    damping: 19,
+    mass: 1,
+};
+
+const parent = {
+    hidden: { opacity: 0 },
+    show: {
+        opacity: 1,
+        transition: {
+            delayChildren: 0.4,
+            staggerChildren: 0.1,
+        },
+    },
+};
+
+const staggeringChild = {
+    hidden: {
+        opacity: 0,
+        scale: 0.7,
+    },
+    show: {
+        opacity: 1,
+        scale: 1,
+        transition: {
+            duration: 0.3,
+            type: 'spring',
+        } as Transition,
+    },
+};
+
+export const minifyButtonAnimation = {
+    initial: {
+        scale: 0.5,
+        opacity: 0,
+    },
+    animate: {
+        scale: 1,
+        opacity: 1,
+    },
+    exit: {
+        scale: 0.5,
+        opacity: 0,
+    },
+};
+
+export const getCopyVariants = (position: number) => {
+    return {
+        initial: {
+            opacity: 0,
+            x: -10,
+        },
+        animate: {
+            opacity: 1,
+            x: 0,
+        },
+        transition: {
+            duration: 0.1,
+            delay: position / 10 + 0.3,
+        } as Transition,
+    };
+};
+
+export const toolbarEasings = {
+    spring,
+    parent,
+    staggeringChild,
+};

packages/gitbook/src/components/AdminToolbar/types.ts

@@ -0,0 +1,60 @@
+/*
+ * Minimal types containing only the fields needed for AdminToolbar to restrict what gets serialized
+ */
+
+export type MinimalChangeRequest = {
+    id: string;
+    number: number;
+    subject: string | null;
+    revision: string;
+    updatedAt: string;
+    createdBy: {
+        displayName: string;
+    };
+    urls: {
+        app: string;
+    };
+};
+
+export type MinimalRevision = {
+    createdAt: string;
+    urls: {
+        app: string;
+    };
+    git?: {
+        url: string | undefined;
+    } | null;
+};
+
+export type MinimalSpace = {
+    id: string;
+    revision: string;
+    urls: {
+        app: string;
+    };
+};
+
+export type MinimalSite = {
+    id: string;
+    title: string;
+    urls: {
+        app: string;
+        published: string | undefined;
+    };
+};
+
+export type AdminToolbarContext = {
+    organizationId: string;
+    revisionId: string;
+    space: MinimalSpace;
+    changeRequest: MinimalChangeRequest | null;
+    revision: MinimalRevision;
+    site: MinimalSite;
+};
+
+export interface AdminToolbarClientProps {
+    context: AdminToolbarContext;
+    onSessionClose?: () => void;
+    onPersistentClose?: () => void;
+    onToggleMinify?: () => void;
+}

packages/gitbook/src/components/AdminToolbar/useMagnificationEffect.ts

@@ -0,0 +1,237 @@
+import { type MotionValue, motionValue } from 'motion/react';
+import React from 'react';
+
+interface MagnificationConfig {
+    /** Size of each button in pixels - used for spacing calculations */
+    buttonSize?: number;
+    /** Maximum scale factor for buttons when mouse is directly over them */
+    maxScale?: number;
+    /** Distance in pixels from mouse where buttons start scaling */
+    influenceRadius?: number;
+    /** Multiplier for spacing between buttons - higher values create more space */
+    spacingMultiplier?: number;
+    /** Controls scaling curve - higher values make scaling more dramatic near mouse */
+    scaleExponent?: number;
+    /** Padding around container for mouse detection in pixels */
+    padding?: number;
+}
+
+const defaultConfig: Required<MagnificationConfig> = {
+    buttonSize: 32, // Standard button size for 32px (size-8) buttons
+    maxScale: 1.25, // 25% scale increase - noticeable but not overwhelming
+    influenceRadius: 80, // ~2.5 button widths of influence
+    spacingMultiplier: 1.3, // Creates proportional spacing to scale increase
+    scaleExponent: 2.5, // Exponential curve for dramatic close-range scaling
+    padding: 10, // Small buffer zone around container edges
+};
+
+const resetMotionValues = (
+    motionValues: Array<{ scale: MotionValue<number>; x: MotionValue<number> }>
+) => {
+    motionValues.forEach(({ scale, x }) => {
+        scale.set(1);
+        x.set(0);
+    });
+};
+
+const captureButtonPositions = (buttons: HTMLElement[]) => {
+    // Reset transforms to get original positions
+    buttons.forEach((button) => {
+        button.style.transform = '';
+    });
+    return buttons.map((button) => {
+        const rect = button.getBoundingClientRect();
+        return {
+            left: rect.left,
+            width: rect.width,
+            top: rect.top,
+            height: rect.height,
+        };
+    });
+};
+
+const calculateScale = (
+    mouseX: number,
+    buttonCenterX: number,
+    containerRect: DOMRect,
+    config: Required<MagnificationConfig>
+) => {
+    // Calculate only X-axis distance from mouse to button center
+    const distance = Math.abs(mouseX - buttonCenterX);
+
+    if (distance > config.influenceRadius) return 1;
+
+    // Calculate distance from container edge (X-axis only)
+    const distanceFromEdgeX = Math.min(mouseX - containerRect.left, containerRect.right - mouseX);
+    const distanceFromEdge = distanceFromEdgeX;
+
+    // Define the "heart" zone - 8px from center (16x16px total area)
+    const heartZoneRadius = 8;
+
+    let baseScale: number;
+
+    if (distance <= heartZoneRadius) {
+        // Within the heart zone - always at max scale
+        baseScale = config.maxScale;
+    } else {
+        // Outside heart zone - scale from max to 1 based on distance
+        const outerRadius = config.influenceRadius - heartZoneRadius;
+        const outerDistance = distance - heartZoneRadius;
+        const progress = Math.min(outerDistance / outerRadius, 1);
+        const exponentialProgress = (1 - progress) ** config.scaleExponent;
+        baseScale = 1 + (config.maxScale - 1) * exponentialProgress;
+    }
+
+    // Only apply entry transition if we're very close to the edge (within 10px)
+    // This prevents the entry logic from interfering with normal scaling
+    if (distanceFromEdge < 10) {
+        const entryProgress = distanceFromEdge / 10;
+        return 1 + (baseScale - 1) * entryProgress;
+    }
+
+    return baseScale;
+};
+
+const calculateSpacing = (
+    buttonIndex: number,
+    buttonEffects: Array<{ scale: number; translateX: number }>,
+    positions: Array<{ left: number; width: number; top: number; height: number }>,
+    config: Required<MagnificationConfig>
+) => {
+    const currentPos = positions[buttonIndex];
+    if (!currentPos) return 0;
+
+    const buttonCenterX = currentPos.left + currentPos.width / 2;
+    let leftPush = 0;
+    let rightPush = 0;
+
+    buttonEffects.forEach((otherEffect, otherIndex) => {
+        if (otherIndex === buttonIndex) return;
+
+        const otherPos = positions[otherIndex];
+        if (!otherPos) return;
+
+        const otherCenterX = otherPos.left + otherPos.width / 2;
+        const distanceBetween = Math.abs(buttonCenterX - otherCenterX);
+
+        // Only apply influence if close enough
+        if (distanceBetween < config.influenceRadius * 1.5) {
+            const influenceStrength = Math.max(
+                0,
+                1 - distanceBetween / (config.influenceRadius * 1.5)
+            );
+            const extraSpace = (otherEffect.scale - 1) * config.buttonSize;
+            const pushAmount = (extraSpace / 2) * config.spacingMultiplier * influenceStrength;
+
+            if (otherCenterX < buttonCenterX) {
+                rightPush += pushAmount;
+            } else {
+                leftPush += pushAmount;
+            }
+        }
+    });
+
+    return rightPush - leftPush;
+};
+
+export function useMagnificationEffect(props: {
+    childrenCount: number;
+    containerRef: React.RefObject<HTMLElement>;
+    config?: MagnificationConfig;
+}) {
+    const { childrenCount, containerRef, config } = props;
+    const originalPositionsRef = React.useRef<
+        Array<{ left: number; width: number; top: number; height: number }>
+    >([]);
+
+    const finalConfig = React.useMemo(() => ({ ...defaultConfig, ...config }), [config]);
+
+    // Create basic motion values that will be consumed by springs in the components
+    const buttonMotionValues = React.useMemo(() => {
+        return Array.from({ length: childrenCount }, () => ({
+            scale: motionValue(1),
+            x: motionValue(0),
+        }));
+    }, [childrenCount]);
+
+    React.useEffect(() => {
+        const container = containerRef.current;
+        if (!container) return;
+
+        const buttons = Array.from(container.querySelectorAll('.toolbar-button')) as HTMLElement[];
+
+        if (buttons.length !== childrenCount) {
+            console.error(
+                `Button count (${buttons.length}) does not match children count (${childrenCount})`
+            );
+            return;
+        }
+
+        const handleMouseMove = (event: MouseEvent) => {
+            const buttons = Array.from(
+                container.querySelectorAll('.toolbar-button')
+            ) as HTMLElement[];
+
+            // Capture positions if needed
+            if (originalPositionsRef.current.length !== buttons.length) {
+                originalPositionsRef.current = captureButtonPositions(buttons);
+            }
+
+            const containerRect = container.getBoundingClientRect();
+            const { clientX: mouseX, clientY: mouseY } = event;
+
+            // Check if mouse is in range
+            const isInRange =
+                mouseX >= containerRect.left - finalConfig.padding &&
+                mouseX <= containerRect.right + finalConfig.padding &&
+                mouseY >= containerRect.top - finalConfig.padding &&
+                mouseY <= containerRect.bottom + finalConfig.padding;
+
+            if (!isInRange) {
+                resetMotionValues(buttonMotionValues);
+                return;
+            }
+
+            // Calculate scales for all buttons
+            const buttonEffects = buttons.map((_, index) => {
+                const pos = originalPositionsRef.current[index];
+                if (!pos) return { scale: 1, translateX: 0 };
+
+                const buttonCenterX = pos.left + pos.width / 2;
+                const scale = calculateScale(mouseX, buttonCenterX, containerRect, finalConfig);
+                return { scale, translateX: 0 };
+            });
+
+            // Calculate spacing for all buttons
+            buttonEffects.forEach((effect, index) => {
+                effect.translateX = calculateSpacing(
+                    index,
+                    buttonEffects,
+                    originalPositionsRef.current,
+                    finalConfig
+                );
+            });
+
+            // Update motion values - springs in components will animate to these values
+            buttonEffects.forEach((effect, index) => {
+                const motionValue = buttonMotionValues[index];
+                if (motionValue) {
+                    motionValue.scale.set(effect.scale);
+                    motionValue.x.set(effect.translateX);
+                }
+            });
+        };
+
+        const handleMouseLeave = () => resetMotionValues(buttonMotionValues);
+
+        container.addEventListener('mousemove', handleMouseMove);
+        container.addEventListener('mouseleave', handleMouseLeave);
+
+        return () => {
+            container.removeEventListener('mousemove', handleMouseMove);
+            container.removeEventListener('mouseleave', handleMouseLeave);
+        };
+    }, [finalConfig, containerRef, buttonMotionValues, childrenCount]);
+
+    return { buttonMotionValues };
+}

packages/gitbook/src/components/AutoRefreshContent/server-actions.ts

@@ -1,28 +1,43 @@
 'use server';
 
 import { getDataOrNull } from '@/lib/data';
+import { getSiteURLDataFromMiddleware } from '@/lib/middleware';
 import { getServerActionBaseContext } from '@/lib/server-actions';
 import { traceErrorOnly } from '@/lib/tracing';
 
 /**
- * Return true if a change-request has been updated.
+ * Return true if the content has been updated.
+ * It compares the revision ID displayed on the client side with the latest revision ID from the server/cache.
  */
 export async function hasContentBeenUpdated(props: {
-    spaceId: string;
-    changeRequestId: string;
     revisionId: string;
 }) {
     return traceErrorOnly('AutoRefreshContent.hasContentBeenUpdated', async () => {
         const context = await getServerActionBaseContext();
-        const changeRequest = await getDataOrNull(
-            context.dataFetcher.getChangeRequest({
-                spaceId: props.spaceId,
-                changeRequestId: props.changeRequestId,
+        const siteURLData = await getSiteURLDataFromMiddleware();
+
+        if (siteURLData.changeRequest) {
+            const changeRequest = await getDataOrNull(
+                context.dataFetcher.getChangeRequest({
+                    spaceId: siteURLData.space,
+                    changeRequestId: siteURLData.changeRequest,
+                })
+            );
+            if (!changeRequest) {
+                return false;
+            }
+            return changeRequest.revision !== props.revisionId;
+        }
+
+        const space = await getDataOrNull(
+            context.dataFetcher.getSpace({
+                spaceId: siteURLData.space,
+                shareKey: siteURLData.shareKey,
             })
         );
-        if (!changeRequest) {
+        if (!space) {
             return false;
         }
-        return changeRequest.revision !== props.revisionId;
+        return space.revision !== props.revisionId;
     });
 }

packages/gitbook/src/components/AutoRefreshContent/useCheckForContentUpdate.ts

@@ -5,20 +5,71 @@ import React from 'react';
 import { hasContentBeenUpdated } from './server-actions';
 
 /**
- * Return a callback to check if a change request has been updated and to refresh the page if it has.
+ * Return a callback to check if a content has been updated and to refresh the page if it has.
  */
 export function useCheckForContentUpdate(props: {
-    spaceId: string;
-    changeRequestId: string;
+    /**
+     * ID of the revision of the content currently being displayed.
+     */
     revisionId: string;
+    /**
+     * How long after page load to check for updates.
+     * @default 5min
+     */
+    checkAfterLoad?: number;
 }) {
-    const { spaceId, changeRequestId, revisionId } = props;
-
-    return React.useCallback(async () => {
-        const updated = await hasContentBeenUpdated({ spaceId, changeRequestId, revisionId });
+    const { revisionId, checkAfterLoad = 5 * 60 * 1000 } = props;
+    const [updated, setUpdated] = React.useState(false);
 
+    const checkForUpdates = React.useCallback(async () => {
         if (updated) {
+            // No need to check for updates if we already know the content has been updated
+            return true;
+        }
+
+        const result = await hasContentBeenUpdated({ revisionId });
+        setUpdated(result);
+        return result;
+    }, [revisionId, updated]);
+
+    const refreshForUpdates = React.useCallback(async () => {
+        if (await checkForUpdates()) {
             window.location.reload();
         }
-    }, [spaceId, changeRequestId, revisionId]);
+    }, [checkForUpdates]);
+
+    // Check for updates after the page has loaded
+    React.useEffect(() => {
+        const timeout = setTimeout(() => {
+            if (document.visibilityState === 'visible') {
+                // We check only if the tab is visible; otherwise we'll check when the tab is focus again
+                checkForUpdates();
+            }
+        }, checkAfterLoad);
+
+        return () => {
+            clearTimeout(timeout);
+        };
+    }, [checkForUpdates, checkAfterLoad]);
+
+    // Check for updates when the tab is becoming visible
+    React.useEffect(() => {
+        if (updated) {
+            // No need to check for updates if we already know the content has been updated
+            return;
+        }
+
+        const callback = () => {
+            if (document.visibilityState === 'visible') {
+                checkForUpdates();
+            }
+        };
+
+        document.addEventListener('visibilitychange', callback);
+        return () => {
+            document.removeEventListener('visibilitychange', callback);
+        };
+    }, [checkForUpdates, updated]);
+
+    return { refreshForUpdates, updated };
 }

packages/gitbook/src/components/DocumentView/CodeBlock/ClientCodeBlock.tsx

@@ -3,16 +3,19 @@
 import type { DocumentBlockCode } from '@gitbook/api';
 import { useEffect, useMemo, useRef, useState } from 'react';
 
+import { useAdaptiveVisitor } from '@/components/Adaptive';
 import { useInViewportListener } from '@/components/hooks/useInViewportListener';
 import { useScrollListener } from '@/components/hooks/useScrollListener';
 import { useDebounceCallback } from 'usehooks-ts';
 import type { BlockProps } from '../Block';
+import { type InlineExpressionVariables, useEvaluateInlineExpression } from '../InlineExpression';
 import { CodeBlockRenderer } from './CodeBlockRenderer';
 import type { HighlightLine, RenderedInline } from './highlight';
 import { plainHighlight } from './plain-highlight';
 
 type ClientBlockProps = Pick<BlockProps<DocumentBlockCode>, 'block' | 'style'> & {
     inlines: RenderedInline[];
+    inlineExprVariables: InlineExpressionVariables;
 };
 
 /**
@@ -20,11 +23,21 @@ type ClientBlockProps = Pick<BlockProps<DocumentBlockCode>, 'block' | 'style'> &
  * It allows us to defer some load to avoid blocking the rendering of the whole page with block highlighting.
  */
 export function ClientCodeBlock(props: ClientBlockProps) {
-    const { block, style, inlines } = props;
+    const { block, style, inlines, inlineExprVariables } = props;
     const blockRef = useRef<HTMLDivElement>(null);
     const isInViewportRef = useRef(false);
     const [isInViewport, setIsInViewport] = useState(false);
-    const plainLines = useMemo(() => plainHighlight(block, []), [block]);
+
+    const getAdaptiveVisitorClaims = useAdaptiveVisitor();
+    const visitorClaims = getAdaptiveVisitorClaims();
+    const evaluateInlineExpression = useEvaluateInlineExpression({
+        visitorClaims,
+        variables: inlineExprVariables,
+    });
+    const plainLines = useMemo(
+        () => plainHighlight(block, inlines, { evaluateInlineExpression }),
+        [block, inlines, evaluateInlineExpression]
+    );
     const [lines, setLines] = useState<null | HighlightLine[]>(null);
     const [highlighting, setHighlighting] = useState(false);
 
@@ -80,7 +93,7 @@ export function ClientCodeBlock(props: ClientBlockProps) {
             if (typeof window !== 'undefined') {
                 setHighlighting(true);
                 import('./highlight').then(({ highlight }) => {
-                    highlight(block, inlines).then((lines) => {
+                    highlight(block, inlines, { evaluateInlineExpression }).then((lines) => {
                         if (cancelled) {
                             return;
                         }
@@ -98,7 +111,7 @@ export function ClientCodeBlock(props: ClientBlockProps) {
 
         // Otherwise if the block is not in viewport, we reset to the plain lines
         setLines(null);
-    }, [isInViewport, block, inlines]);
+    }, [isInViewport, block, inlines, evaluateInlineExpression]);
 
     return (
         <CodeBlockRenderer

packages/gitbook/src/components/DocumentView/CodeBlock/CodeBlock.tsx

@@ -1,3 +1,5 @@
+import * as React from 'react';
+
 import type { DocumentBlockCode } from '@gitbook/api';
 
 import { getNodeFragmentByType } from '@/lib/document';
@@ -14,32 +16,64 @@ import { type RenderedInline, getInlines, highlight } from './highlight';
 export async function CodeBlock(props: BlockProps<DocumentBlockCode>) {
     const { block, document, style, isEstimatedOffscreen, context } = props;
     const inlines = getInlines(block);
-    const richInlines: RenderedInline[] = inlines.map((inline, index) => {
-        const body = (() => {
-            const fragment = getNodeFragmentByType(inline.inline, 'annotation-body');
-            if (!fragment) {
-                return null;
+
+    let hasInlineExpression = false;
+
+    const richInlines: RenderedInline[] = inlines
+        // Exclude inline expressions from rendered inline as they are rendered as code text once evaluated
+        // and so need to be treated as plain code tokens.
+        .filter((inline) => {
+            if (inline.inline.type === 'expression') {
+                hasInlineExpression = true;
+                return false;
             }
-            return (
-                <Blocks
-                    key={index}
-                    document={document}
-                    ancestorBlocks={[]}
-                    context={context}
-                    nodes={fragment.nodes}
-                    style="space-y-4"
-                />
-            );
-        })();
+            return true;
+        })
+        .map((inline, index) => {
+            const body = (() => {
+                const fragment = getNodeFragmentByType(inline.inline, 'annotation-body');
+                if (!fragment) {
+                    return null;
+                }
+                return (
+                    <Blocks
+                        key={index}
+                        document={document}
+                        ancestorBlocks={[]}
+                        context={context}
+                        nodes={fragment.nodes}
+                        style="space-y-4"
+                    />
+                );
+            })();
 
-        return { inline, body };
-    });
+            return { inline, body };
+        });
 
-    if (!isEstimatedOffscreen) {
+    if (!isEstimatedOffscreen && !hasInlineExpression) {
         // In v2, we render the code block server-side
         const lines = await highlight(block, richInlines);
         return <CodeBlockRenderer block={block} style={style} lines={lines} />;
     }
 
-    return <ClientCodeBlock block={block} style={style} inlines={richInlines} />;
+    const variables = context.contentContext
+        ? {
+              space: context.contentContext?.revision.variables,
+              page:
+                  'page' in context.contentContext
+                      ? context.contentContext.page.variables
+                      : undefined,
+          }
+        : {};
+
+    return (
+        <React.Suspense fallback={null}>
+            <ClientCodeBlock
+                block={block}
+                style={style}
+                inlines={richInlines}
+                inlineExprVariables={variables}
+            />
+        </React.Suspense>
+    );
 }

packages/gitbook/src/components/DocumentView/CodeBlock/CodeBlockRenderer.tsx

@@ -32,7 +32,7 @@ export const CodeBlockRenderer = forwardRef(function CodeBlockRenderer(
         <div
             ref={ref}
             aria-busy={ariaBusy}
-            className={tcls('group/codeblock grid grid-flow-col', style)}
+            className={tcls('group/codeblock grid shrink grid-flow-col overflow-hidden', style)}
         >
             <div className="flex items-center justify-start gap-2 text-sm [grid-area:1/1]">
                 {title ? (

packages/gitbook/src/components/DocumentView/CodeBlock/highlight.ts

@@ -64,7 +64,10 @@ export async function preloadHighlight(block: DocumentBlockCode) {
  */
 export async function highlight(
     block: DocumentBlockCode,
-    inlines: RenderedInline[]
+    inlines: RenderedInline[],
+    options?: {
+        evaluateInlineExpression?: (expr: string) => string;
+    }
 ): Promise<HighlightLine[]> {
     const langName = getBlockLang(block);
 
@@ -74,10 +77,10 @@ export async function highlight(
         // - TEMP : language is PowerShell or C++ and browser is Safari:
         //   RegExp#[Symbol.search] throws TypeError when `lastIndex` isn’t writable
         //   Fixed in upcoming Safari 18.6, remove when it'll be released - RND-7772
-        return plainHighlight(block, inlines);
+        return plainHighlight(block, inlines, options);
     }
 
-    const code = getPlainCodeBlock(block);
+    const code = getPlainCodeBlock(block, undefined, options);
 
     const highlighter = await getSingletonHighlighter({
         langs: [langName],
@@ -255,11 +258,17 @@ function matchTokenAndInlines(
     return result;
 }
 
-function getPlainCodeBlock(code: DocumentBlockCode, inlines?: InlineIndexed[]): string {
+function getPlainCodeBlock(
+    code: DocumentBlockCode,
+    inlines?: InlineIndexed[],
+    options?: {
+        evaluateInlineExpression?: (expr: string) => string;
+    }
+): string {
     let content = '';
 
     code.nodes.forEach((node, index) => {
-        const lineContent = getPlainCodeBlockLine(node, content.length, inlines);
+        const lineContent = getPlainCodeBlockLine(node, content.length, inlines, options);
         content += lineContent;
 
         if (index < code.nodes.length - 1) {
@@ -273,7 +282,10 @@ function getPlainCodeBlock(code: DocumentBlockCode, inlines?: InlineIndexed[]):
 function getPlainCodeBlockLine(
     parent: DocumentBlockCodeLine | DocumentInlineAnnotation,
     index: number,
-    inlines?: InlineIndexed[]
+    inlines?: InlineIndexed[],
+    options?: {
+        evaluateInlineExpression?: (expr: string) => string;
+    }
 ): string {
     let content = '';
 
@@ -284,7 +296,12 @@ function getPlainCodeBlockLine(
             switch (node.type) {
                 case 'annotation': {
                     const start = index + content.length;
-                    content += getPlainCodeBlockLine(node, index + content.length, inlines);
+                    content += getPlainCodeBlockLine(
+                        node,
+                        index + content.length,
+                        inlines,
+                        options
+                    );
                     const end = index + content.length;
 
                     if (inlines) {
@@ -297,6 +314,19 @@ function getPlainCodeBlockLine(
                     break;
                 }
                 case 'expression': {
+                    const start = index + content.length;
+                    const exprValue =
+                        options?.evaluateInlineExpression?.(node.data.expression) ?? '';
+                    content += exprValue;
+                    const end = start + exprValue.length;
+
+                    if (inlines) {
+                        inlines.push({
+                            inline: node,
+                            start,
+                            end,
+                        });
+                    }
                     break;
                 }
                 default: {

packages/gitbook/src/components/DocumentView/CodeBlock/plain-highlight.ts

@@ -9,9 +9,13 @@ import type { HighlightLine, HighlightToken, RenderedInline } from './highlight'
  */
 export function plainHighlight(
     block: DocumentBlockCode,
-    inlines: RenderedInline[]
+    inlines: RenderedInline[],
+    options?: {
+        evaluateInlineExpression?: (expr: string) => string;
+    }
 ): HighlightLine[] {
     const inlinesCopy = Array.from(inlines);
+
     return block.nodes.map((lineBlock) => {
         const tokens: HighlightToken[] = lineBlock.nodes.map((node) => {
             if (node.object === 'text') {
@@ -20,6 +24,14 @@ export function plainHighlight(
                     content: getNodeText(node),
                 };
             }
+
+            if (node.type === 'expression') {
+                return {
+                    type: 'plain',
+                    content: options?.evaluateInlineExpression?.(node.data.expression) ?? '',
+                };
+            }
+
             const inline = inlinesCopy.shift();
             return {
                 type: 'annotation',

packages/gitbook/src/components/DocumentView/Columns/Columns.tsx

@@ -1,17 +1,57 @@
 import { tcls } from '@/lib/tailwind';
 import { type DocumentBlockColumns, type Length, VerticalAlignment } from '@gitbook/api';
+import React from 'react';
 import type { BlockProps } from '../Block';
 import { Blocks } from '../Blocks';
 
 export function Columns(props: BlockProps<DocumentBlockColumns>) {
     const { block, style, ancestorBlocks, document, context } = props;
+
+    const columnWidths = React.useMemo(() => {
+        const widths = block.nodes.map((block) => {
+            const width = block.data.width;
+            return width ? getFractionalWidth(width) : 0;
+        });
+
+        const totalWidth = widths.reduce<number>((acc, width) => acc + width, 0);
+        // If not all columns widths are set, distribute the remaining widths as equally as we can
+        if (totalWidth < 1.0 && widths.some((width) => width === 0)) {
+            const unsetWidths = widths.filter((width) => width === 0);
+            let remainingWidth = 1.0 - totalWidth;
+            let unsetWidthsLength = unsetWidths.length;
+            widths.forEach((width, index) => {
+                if (width === 0) {
+                    const calculatedWidth =
+                        Math.round((remainingWidth / unsetWidthsLength) * COLUMN_DIVISIONS) /
+                        COLUMN_DIVISIONS;
+                    widths[index] = calculatedWidth; // Assign width to empty columns
+                    unsetWidthsLength--;
+                    remainingWidth -= calculatedWidth;
+                }
+            });
+        }
+        return widths;
+    }, [block.nodes]);
+
     return (
-        <div className={tcls('flex flex-col gap-x-8 md:flex-row', style)}>
-            {block.nodes.map((columnBlock) => {
+        <div
+            className={tcls(
+                'grid w-full grid-cols-1 gap-x-8 gap-y-4 md:grid-flow-col md:grid-cols-[repeat(var(--grid-slices),minmax(0,1fr))] md:grid-rows-1',
+                style
+            )}
+            style={{ '--grid-slices': COLUMN_DIVISIONS } as React.CSSProperties}
+        >
+            {block.nodes.map((columnBlock, index) => {
+                const columnWidth = columnWidths[index];
                 return (
                     <Column
                         key={columnBlock.key}
-                        width={columnBlock.data.width}
+                        width={
+                            columnBlock.data.width ??
+                            (columnWidth
+                                ? { value: columnWidth * 100, unit: '%' }
+                                : { value: 0, unit: '%' })
+                        }
                         verticalAlignment={columnBlock.data.verticalAlignment}
                     >
                         <Blocks
@@ -31,11 +71,11 @@ export function Columns(props: BlockProps<DocumentBlockColumns>) {
 
 export function Column(props: {
     children?: React.ReactNode;
-    width?: Length;
+    width: Length;
     verticalAlignment?: VerticalAlignment;
 }) {
     const { width, verticalAlignment } = props;
-    const { className, style } = transformLengthToCSS(width);
+    const { className, style } = transformLengthToCSS(width) ?? {};
     return (
         <div
             className={tcls(
@@ -53,41 +93,25 @@ export function Column(props: {
     );
 }
 
-function transformLengthToCSS(length: Length | undefined) {
-    if (!length) {
-        return { className: ['md:w-full'] }; // default to full width if no length is specified
-    }
+const COLUMN_DIVISIONS = 12;
 
+export function transformLengthToCSS(length: Length) {
     if (typeof length === 'number') {
-        return { style: undefined }; // not implemented yet with non-percentage lengths
+        return; // not implemented yet with non-percentage lengths
     }
-
     if (length.unit === '%') {
         return {
-            className: [
-                'md:shrink-0',
-                COLUMN_WIDTHS[Math.round(length.value * 0.01 * (COLUMN_WIDTHS.length - 1))],
-            ],
+            className: 'md:flex-shrink-0 md:[grid-column:var(--grid-col)]',
+            style: {
+                '--grid-col': `auto / span ${Math.round(length.value * 0.01 * COLUMN_DIVISIONS)}`,
+            } as React.CSSProperties,
         };
     }
-
-    return { style: undefined }; // not implemented yet with non-percentage lengths
 }
 
-// Tailwind CSS classes for column widths.
-// The index of the array corresponds to the percentage width of the column.
-const COLUMN_WIDTHS = [
-    'md:w-0',
-    'md:w-1/12',
-    'md:w-2/12',
-    'md:w-3/12',
-    'md:w-4/12',
-    'md:w-5/12',
-    'md:w-6/12',
-    'md:w-7/12',
-    'md:w-8/12',
-    'md:w-9/12',
-    'md:w-10/12',
-    'md:w-11/12',
-    'md:w-full',
-];
+function getFractionalWidth(length: Length) {
+    if (typeof length === 'number') {
+        return 0;
+    }
+    return length.value / 100;
+}

packages/gitbook/src/components/DocumentView/Hint.tsx

@@ -3,6 +3,8 @@ import { Icon, type IconName } from '@gitbook/icons';
 
 import { type ClassValue, tcls } from '@/lib/tailwind';
 
+import { getSpaceLanguage, tString } from '@/intl/server';
+import { languages } from '@/intl/translations';
 import { Block, type BlockProps } from './Block';
 import { Blocks } from './Blocks';
 import { getBlockTextStyle } from './spacing';
@@ -18,6 +20,12 @@ export function Hint({
     const firstLine = getBlockTextStyle(firstNode);
     const hasHeading = ['heading-1', 'heading-2', 'heading-3'].includes(firstNode.type);
 
+    const language = contextProps.context.contentContext
+        ? getSpaceLanguage(contextProps.context.contentContext)
+        : languages.en;
+
+    const label = tString(language, `hint_${block.data.style}`);
+
     return (
         <div
             className={tcls(
@@ -38,6 +46,8 @@ export function Hint({
 
                 style
             )}
+            aria-label={label}
+            role="note"
         >
             <div
                 className={tcls(

packages/gitbook/src/components/DocumentView/Inline.tsx

@@ -5,6 +5,7 @@ import { Annotation } from './Annotation/Annotation';
 import type { DocumentContextProps } from './DocumentView';
 import { Emoji } from './Emoji';
 import { InlineButton } from './InlineButton';
+import { InlineExpression } from './InlineExpression';
 import { InlineIcon } from './InlineIcon';
 import { InlineImage } from './InlineImage';
 import { InlineLink } from './InlineLink';
@@ -51,9 +52,7 @@ export function Inline<T extends DocumentInline>(props: InlineProps<T>) {
         case 'icon':
             return <InlineIcon {...contextProps} inline={inline} />;
         case 'expression':
-            // The GitBook API should take care of evaluating expressions.
-            // We should never need to render them.
-            return null;
+            return <InlineExpression {...contextProps} inline={inline} />;
         default:
             return nullIfNever(inline);
     }

packages/gitbook/src/components/DocumentView/InlineExpression/InlineExpression.tsx

@@ -0,0 +1,30 @@
+import * as React from 'react';
+
+import type { DocumentInlineExpression } from '@gitbook/api';
+import type { InlineProps } from '../Inline';
+import { InlineExpressionValue } from './InlineExpressionValue';
+
+/**
+ * Render an inline expression.
+ */
+export function InlineExpression(props: InlineProps<DocumentInlineExpression>) {
+    const { context, inline } = props;
+
+    const { data } = inline;
+
+    const variables = context.contentContext
+        ? {
+              space: context.contentContext?.revision.variables,
+              page:
+                  'page' in context.contentContext
+                      ? context.contentContext.page.variables
+                      : undefined,
+          }
+        : {};
+
+    return (
+        <React.Suspense fallback={null}>
+            <InlineExpressionValue expression={data.expression} variables={variables} />
+        </React.Suspense>
+    );
+}

packages/gitbook/src/components/DocumentView/InlineExpression/InlineExpressionValue.tsx

@@ -0,0 +1,26 @@
+'use client';
+import { useAdaptiveVisitor } from '@/components/Adaptive';
+import { useMemo } from 'react';
+import type { InlineExpressionVariables } from './types';
+import { useEvaluateInlineExpression } from './useEvaluateInlineExpression';
+
+export function InlineExpressionValue(props: {
+    expression: string;
+    variables: InlineExpressionVariables;
+}) {
+    const { expression, variables } = props;
+
+    const getAdaptiveVisitorClaims = useAdaptiveVisitor();
+    const visitorClaims = getAdaptiveVisitorClaims();
+    const evaluateInlineExpression = useEvaluateInlineExpression({
+        visitorClaims,
+        variables,
+    });
+
+    const result = useMemo(
+        () => evaluateInlineExpression(expression),
+        [expression, evaluateInlineExpression]
+    );
+
+    return <>{result}</>;
+}

packages/gitbook/src/components/DocumentView/InlineExpression/index.ts

@@ -0,0 +1,3 @@
+export * from './InlineExpression';
+export * from './types';
+export * from './useEvaluateInlineExpression';

packages/gitbook/src/components/DocumentView/InlineExpression/types.ts

@@ -0,0 +1,6 @@
+import type { Variables } from '@gitbook/api';
+
+export interface InlineExpressionVariables {
+    space?: Variables;
+    page?: Variables;
+}

packages/gitbook/src/components/DocumentView/InlineExpression/useEvaluateInlineExpression.ts

@@ -0,0 +1,42 @@
+import * as React from 'react';
+
+import {
+    type AdaptiveVisitorClaims,
+    createExpressionEvaluationContext,
+} from '@/components/Adaptive';
+import type { Variables } from '@gitbook/api';
+import { ExpressionRuntime, formatExpressionResult } from '@gitbook/expr';
+
+/**
+ * Hook that returns a callback to evaluate an inline expression with visitor data
+ * and space/page variables as context.
+ */
+export function useEvaluateInlineExpression(args: {
+    visitorClaims: AdaptiveVisitorClaims | null;
+    variables: {
+        space?: Variables;
+        page?: Variables;
+    };
+}) {
+    const { visitorClaims, variables } = args;
+    const evaluateInlineExpression = React.useMemo(() => {
+        const runtime = new ExpressionRuntime();
+        const evaluationContext = createExpressionEvaluationContext({
+            visitorClaims,
+            variables,
+        });
+
+        return (expression: string) => {
+            try {
+                return formatExpressionResult(
+                    runtime.evaluate(expression, evaluationContext) ?? ''
+                );
+            } catch (err) {
+                console.error('Failed to evaluate expression:', expression, err);
+                return `{{${expression}}}`;
+            }
+        };
+    }, [variables, visitorClaims]);
+
+    return evaluateInlineExpression;
+}

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -143,11 +143,11 @@
 }
 
 .openapi-column-preview {
-    @apply flex flex-col flex-1;
+    @apply flex flex-col flex-1 xl:max-2xl:pt-20 lg:py-6 sticky max-h-[calc(100vh-var(--toc-top-offset))] top-(--toc-top-offset);
 }
 
 .openapi-column-preview-body {
-    @apply flex flex-col gap-4 sticky top-[calc(var(--toc-top-offset)+5rem)] print-mode:static;
+    @apply flex flex-col shrink overflow-hidden gap-4 print-mode:static;
 }
 
 .openapi-column-preview pre {
@@ -510,13 +510,21 @@
 .openapi-panel,
 .openapi-codesample,
 .openapi-response-examples {
-    @apply border rounded-md straight-corners:rounded-none circular-corners:rounded-xl bg-tint-subtle border-tint-subtle shadow-sm;
+    @apply border shrink min-h-40 overflow-hidden rounded-md straight-corners:rounded-none circular-corners:rounded-xl bg-tint-subtle border-tint-subtle shadow-sm;
+}
+
+.openapi-response-examples-panel {
+    @apply flex flex-col shrink overflow-hidden;
+}
+
+.openapi-codesample-panel {
+    @apply flex flex-col shrink overflow-hidden;
 }
 
 .openapi-panel pre,
 .openapi-codesample pre,
 .openapi-response-examples pre {
-    @apply bg-transparent border-none rounded-none shadow-none;
+    @apply bg-transparent border-none rounded-none shrink shadow-none;
 }
 
 .openapi-panel-heading {
@@ -579,7 +587,7 @@ body:has(.openapi-select-popover) {
 }
 
 .openapi-select > button {
-    @apply flex items-center font-normal cursor-pointer *:truncate gap-1.5 text-tint-strong max-w-32 rounded text-xs p-1.5 leading-none border border-tint-subtle bg-tint;
+    @apply flex items-center font-normal cursor-pointer *:truncate gap-1.5 text-tint-strong rounded text-xs p-1.5 leading-none border border-tint-subtle bg-tint;
     @apply hover:bg-tint-hover transition-all;
 }
 
@@ -613,7 +621,7 @@ body:has(.openapi-select-popover) {
 }
 
 .openapi-select-item {
-    @apply text-sm flex items-center cursor-pointer px-1.5 overflow-hidden py-1 *:truncate text-tint ring-0 border-none rounded !outline-none;
+    @apply text-sm flex items-center cursor-pointer px-1.5 overflow-hidden py-1 text-tint ring-0 border-none rounded !outline-none;
     @apply hover:bg-tint-hover hover:theme-gradient:bg-tint-12/1 hover:text-tint-strong contrast-more:hover:ring-1 contrast-more:hover:ring-inset contrast-more:hover:ring-current;
 }
 
@@ -638,6 +646,14 @@ body:has(.openapi-select-popover) {
 }
 
 /* Section Components */
+.openapi-section {
+    @apply flex flex-col overflow-hidden;
+}
+
+.openapi-section-body {
+    @apply flex flex-col shrink overflow-hidden;
+}
+
 .openapi-section-header {
     @apply flex flex-row items-center;
 }

packages/gitbook/src/components/DocumentView/Table/RecordCard.tsx

@@ -95,8 +95,12 @@ export async function RecordCard(
                     }}
                     sizes={[
                         {
+                            media: '(max-width: 640px)',
                             width: view.cardSize === 'medium' ? 245 : 376,
                         },
+                        {
+                            width: view.cardSize === 'medium' ? 490 : 752,
+                        },
                     ]}
                     resize={context.contentContext?.imageResizer}
                     className={tcls(

packages/gitbook/src/components/DocumentView/Table/utils.ts

@@ -71,16 +71,18 @@ function processCoverValue(value: DocumentTableImageRecord | string[] | null | u
         }
     }
 
+    const imageValue = value as DocumentTableImageRecord | null | undefined;
+
     // Check if it's the new schema with objectFit
-    if (value && typeof value === 'object' && 'ref' in value && 'objectFit' in value) {
+    if (imageValue && typeof imageValue === 'object' && 'ref' in imageValue) {
         return {
-            contentRef: value.ref,
-            objectFit: value.objectFit,
+            contentRef: imageValue.ref,
+            objectFit: imageValue.objectFit,
         };
     }
 
     // It's a direct ContentRef
-    return { contentRef: value as ContentRefFile | ContentRefURL };
+    return { contentRef: imageValue || null };
 }
 
 /**

packages/gitbook/src/components/Footer/FooterLinksGroup.tsx

@@ -36,13 +36,9 @@ async function FooterLink(props: { link: CustomizationContentLink; context: GitB
     const { link, context } = props;
     const resolved = await resolveContentRef(link.to, context);
 
-    if (!resolved) {
-        return null;
-    }
-
     return (
         <Link
-            href={resolved.href}
+            href={resolved?.href ?? '#'}
             className={tcls(
                 'font-normal',
                 'text-tint',

packages/gitbook/src/components/Header/CurrentContentIcon.tsx

@@ -42,11 +42,11 @@ export function CurrentContentIcon(
                       }
                     : {
                           light: {
-                              src: linker.toPathInSpace('~gitbook/icon?size=medium&theme=light'),
+                              src: linker.toPathInSpace('~gitbook/icon?size=large&theme=light'),
                               size: { width: 256, height: 256 },
                           },
                           dark: {
-                              src: linker.toPathInSpace('~gitbook/icon?size=medium&theme=dark'),
+                              src: linker.toPathInSpace('~gitbook/icon?size=large&theme=dark'),
                               size: { width: 256, height: 256 },
                           },
                       }

packages/gitbook/src/components/Header/Header.tsx

@@ -57,7 +57,7 @@ export function Header(props: {
                     'theme-bold:shadow-tint-12/2'
                 )}
             >
-                <div className="transition-all duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
+                <div className="transition-[padding] duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
                     <div
                         className={tcls(
                             'gap-4',
@@ -120,9 +120,25 @@ export function Header(props: {
                         >
                             <SearchContainer
                                 style={customization.styling.search}
-                                isMultiVariants={siteSpaces.length > 1}
+                                withVariants={withVariants === 'generic'}
+                                withSiteVariants={
+                                    sections?.list.some(
+                                        (s) =>
+                                            s.object === 'site-section' && s.siteSpaces.length > 1
+                                    ) ?? false
+                                }
+                                withSections={!!sections}
+                                section={
+                                    sections
+                                        ? // Client-encode to avoid a serialisation issue that was causing the language selector to disappear
+                                          encodeClientSiteSections(context, sections).current
+                                        : undefined
+                                }
                                 spaceTitle={siteSpace.title}
                                 siteSpaceId={siteSpace.id}
+                                siteSpaceIds={siteSpaces
+                                    .filter((s) => s.space.language === siteSpace.space.language)
+                                    .map((s) => s.id)}
                                 viewport={!withTopHeader ? 'mobile' : undefined}
                             />
                         </div>
@@ -163,42 +179,18 @@ export function Header(props: {
             </div>
 
             {sections ? (
-                <div className="transition-all duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
-                    <div
-                        className={tcls(
-                            'w-full',
-                            'overflow-x-auto',
-                            'no-scrollbar',
-                            '-mb-4 pb-4', // Positive padding / negative margin allows the navigation menu indicator to show in a scroll viewƒ
-                            !sections ? ['hidden', 'page-no-toc:flex'] : 'flex'
-                        )}
-                    >
-                        <div
-                            className={tcls(
-                                CONTAINER_STYLE,
-                                'grow',
-                                'flex',
-                                'items-end',
-                                'page-default-width:2xl:px-[calc((100%-1536px+4rem)/2)]'
-                            )}
-                        >
-                            {sections.list.some((s) => s.object === 'site-section-group') || // If there's even a single group, show the tabs
-                            sections.list.length > 1 ? ( // Otherwise, show the tabs if there's more than one section
-                                <SiteSectionTabs
-                                    sections={encodeClientSiteSections(context, sections)}
+                <div className="transition-[padding] duration-300 lg:chat-open:pr-80 xl:chat-open:pr-96">
+                    <SiteSectionTabs sections={encodeClientSiteSections(context, sections)}>
+                        {withVariants === 'translations' ? (
+                            <div className="before:contents[] flex self-start py-2 before:mr-4 before:border-tint before:border-l">
+                                <TranslationsDropdown
+                                    context={context}
+                                    siteSpace={siteSpace}
+                                    siteSpaces={siteSpaces}
                                 />
-                            ) : null}
-                            {withVariants === 'translations' ? (
-                                <div className="site-background before:contents[] -mr-4 sm:-mr-6 md:-mr-8 sticky inset-y-0 right-0 z-10 ml-6 flex h-full items-center py-2 pr-4 before:mr-4 before:h-full before:border-tint before:border-l sm:pr-6 md:pr-8">
-                                    <TranslationsDropdown
-                                        context={context}
-                                        siteSpace={siteSpace}
-                                        siteSpaces={siteSpaces}
-                                    />
-                                </div>
-                            ) : null}
-                        </div>
-                    </div>
+                            </div>
+                        ) : null}
+                    </SiteSectionTabs>
                 </div>
             ) : null}
         </header>

packages/gitbook/src/components/Header/HeaderLink.tsx

@@ -57,7 +57,7 @@ export async function HeaderLink(props: {
         );
     }
 
-    if (!target || !link.to) {
+    if (!link.to) {
         return null;
     }
 
@@ -68,7 +68,7 @@ export async function HeaderLink(props: {
             headerPreset={headerPreset}
             title={link.title}
             isDropdown={false}
-            href={target.href}
+            href={target?.href}
         />
     );
 }
@@ -78,7 +78,7 @@ export type HeaderLinkNavItemProps = {
     linkStyle: NonNullable<CustomizationHeaderItem['style']>;
     headerPreset: CustomizationHeaderPreset;
     title: string;
-    href: string;
+    href?: string;
     isDropdown: boolean;
 } & DropdownButtonProps<HTMLElement>;
 
@@ -165,7 +165,7 @@ function HeaderItemLink(props: Omit<HeaderLinkNavItemProps, 'linkStyle'>) {
     const { linkTarget, headerPreset, title, isDropdown, href, ...rest } = props;
     return (
         <Link
-            href={href}
+            href={href ?? '#'}
             className={getHeaderLinkClassName({ headerPreset })}
             insights={{
                 type: 'link_click',

packages/gitbook/src/components/Header/SpacesDropdown.tsx

@@ -76,7 +76,7 @@ export function TranslationsDropdown(props: {
             siteSpaces={siteSpaces}
             variant="blank"
             className={tcls(
-                '-mx-2 bg-transparent px-2 py-1 lg:max-w-64 max-md:[&_.button-content]:hidden',
+                '-mx-2 bg-transparent px-2 md:py-1 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)
                     : '',

packages/gitbook/src/components/Insights/InsightsProvider.tsx

@@ -119,14 +119,11 @@ export function InsightsProvider(props: InsightsProviderProps) {
             };
         }
 
-        if (allEvents.length > 0) {
-            if (enabled) {
-                sendEvents({
-                    eventUrl,
-                    events: allEvents,
-                });
-            } else {
-            }
+        if (allEvents.length > 0 && enabled) {
+            sendEvents({
+                eventUrl,
+                events: allEvents,
+            });
         }
     });
 
@@ -134,7 +131,7 @@ export function InsightsProvider(props: InsightsProviderProps) {
         flushEventsSync();
     }, 1500);
 
-    // Flush events once the visitor session is set
+    // Flush pending events once the visitor session has been fetched
     React.useEffect(() => {
         if (visitorSession) {
             flushEventsSync();

packages/gitbook/src/components/Insights/visitorId.tsx

@@ -12,6 +12,8 @@ const VISITORID_COOKIE = '__session';
 
 type SessionVisitorResponse = {
     deviceId: string;
+    userId?: undefined;
+    organizationId?: undefined;
 };
 
 type SessionUserResponse = SessionVisitorResponse & {
@@ -30,7 +32,7 @@ const visitorSessionStore = createStore<{
 }));
 
 /**
- * Fetch and provide the visitor session.
+ * Fetch, synchronize the visitor sesion with GitBook.
  */
 export function VisitorSessionProvider(
     props: React.PropsWithChildren<{
@@ -81,18 +83,16 @@ async function fetchSession({
         };
     }
 
-    const existingTrackingCookie = getSessionCookie();
+    const { existing, proposedId } = getSessionCookie();
 
-    if (existingTrackingCookie) {
+    if (existing) {
         // If the cookie already exists, we'll just use that. Avoids a server request.
-        return existingTrackingCookie;
+        return existing;
     }
-    // No tracking deviceId set, we'll need to consolidate with the server.
-    const proposed = generateRandomId();
 
     const url = new URL(appURL);
     url.pathname = '/__session/2/';
-    url.searchParams.set('proposed', proposed);
+    url.searchParams.set('proposed', proposedId);
 
     try {
         const resp = await fetch(url, {
@@ -107,21 +107,24 @@ async function fetchSession({
     } catch (error) {
         console.error('Failed to fetch visitor session ID', error);
         return {
-            deviceId: proposed,
+            deviceId: proposedId,
         };
     }
 }
 
-function getSessionCookie(): SessionResponse | null {
+function getSessionCookie(): { existing: SessionResponse | null; proposedId: string } {
+    const proposed = generateRandomId();
     const value = getBrowserCookie(VISITORID_COOKIE);
     if (!(value && typeof value === 'string')) {
-        return null;
+        return { existing: null, proposedId: proposed };
     }
 
     try {
         const parsed = JSON.parse(value) as SessionResponse;
-        return parsed;
+        return { existing: parsed, proposedId: proposed };
     } catch {
-        return { deviceId: value };
+        // Ignore legacy __session cookie format
+        // and we'll renew it with the server using the previous one as a proposed ID
+        return { existing: null, proposedId: proposed };
     }
 }

packages/gitbook/src/components/PageBody/PageBody.tsx

@@ -81,7 +81,10 @@ export function PageBody(props: {
                             blockStyle="page-api-block:ml-0"
                             context={{
                                 mode: 'default',
-                                contentContext: context,
+                                contentContext: {
+                                    ...context,
+                                    page,
+                                },
                                 withLinkPreviews,
                             }}
                         />

packages/gitbook/src/components/RootLayout/RootLayoutClientContexts.tsx

@@ -5,7 +5,7 @@ import type React from 'react';
 import { TranslateContext } from '@/intl/client';
 import type { TranslationLanguage } from '@/intl/translations';
 import { TooltipProvider } from '@radix-ui/react-tooltip';
-import { HashProvider } from '../hooks';
+import { NavigationStatusProvider } from '../hooks';
 import { LoadingStateProvider } from '../primitives/LoadingStateProvider';
 
 /**
@@ -20,9 +20,9 @@ export function RootLayoutClientContexts(props: {
     return (
         <TranslateContext.Provider value={language}>
             <TooltipProvider delayDuration={200}>
-                <HashProvider>
+                <NavigationStatusProvider>
                     <LoadingStateProvider>{children}</LoadingStateProvider>
-                </HashProvider>
+                </NavigationStatusProvider>
             </TooltipProvider>
         </TranslateContext.Provider>
     );

packages/gitbook/src/components/RootLayout/globals.css

@@ -217,6 +217,7 @@
         ::-webkit-scrollbar {
             background: transparent;
             max-width: 8px;
+            max-height: 6px;
         }
 
         ::-webkit-scrollbar-thumb {

packages/gitbook/src/components/Search/SearchContainer.tsx

@@ -1,6 +1,7 @@
 'use client';
 
-import { CustomizationSearchStyle } from '@gitbook/api';
+import { t, useLanguage } from '@/intl/client';
+import { CustomizationSearchStyle, type SiteSection } from '@gitbook/api';
 import { useRouter } from 'next/navigation';
 import React, { useRef } from 'react';
 import { useHotkeys } from 'react-hotkeys-hook';
@@ -16,11 +17,31 @@ import { SearchInput } from './SearchInput';
 import { SearchResults, type SearchResultsRef } from './SearchResults';
 import { SearchScopeToggle } from './SearchScopeToggle';
 import { useSearch } from './useSearch';
+import { useSearchResults } from './useSearchResults';
+import { useSearchResultsCursor } from './useSearchResultsCursor';
 
 interface SearchContainerProps {
+    /** The current site space id. */
     siteSpaceId: string;
+
+    /** The title of the current space. */
     spaceTitle: string;
-    isMultiVariants: boolean;
+
+    /** The ids of all spaces in the current section. */
+    siteSpaceIds: string[];
+
+    /** Whether there are sections on the site. */
+    withSections: boolean;
+
+    /** The current section, displayed in search scope toggle. */
+    section?: Pick<SiteSection, 'title' | 'icon'>;
+
+    /** Whether the current section has variants. */
+    withVariants: boolean;
+
+    /** Whether any section on the site has variants. */
+    withSiteVariants: boolean;
+
     style: CustomizationSearchStyle;
     className?: string;
     viewport?: 'desktop' | 'mobile';
@@ -30,7 +51,18 @@ interface SearchContainerProps {
  * Client component to render the search input and results.
  */
 export function SearchContainer(props: SearchContainerProps) {
-    const { siteSpaceId, spaceTitle, isMultiVariants, style, className, viewport } = props;
+    const {
+        siteSpaceId,
+        spaceTitle,
+        section,
+        withVariants,
+        withSiteVariants,
+        withSections,
+        style,
+        className,
+        viewport,
+        siteSpaceIds,
+    } = props;
 
     const { assistants } = useAI();
 
@@ -108,7 +140,7 @@ export function SearchContainer(props: SearchContainerProps) {
         }
         setSearchState((prev) => ({
             ask: withAI ? (prev?.ask ?? null) : null,
-            global: prev?.global ?? false,
+            scope: prev?.scope ?? 'default',
             query: prev?.query ?? (withSearchAI || !withAI ? prev?.ask : null) ?? '',
             open: true,
         }));
@@ -131,24 +163,11 @@ export function SearchContainer(props: SearchContainerProps) {
         };
     }, [onClose]);
 
-    const onKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
-        if (event.key === 'ArrowUp') {
-            event.preventDefault();
-            resultsRef.current?.moveUp();
-        } else if (event.key === 'ArrowDown') {
-            event.preventDefault();
-            resultsRef.current?.moveDown();
-        } else if (event.key === 'Enter') {
-            event.preventDefault();
-            resultsRef.current?.select();
-        }
-    };
-
     const onChange = (value: string) => {
         setSearchState((prev) => ({
             ask: withAI && !withSearchAI ? (prev?.ask ?? null) : null, // When typing, we reset ask to get back to normal search (unless non-search assistants are defined)
             query: value,
-            global: prev?.global ?? false,
+            scope: prev?.scope ?? 'default',
             open: true,
         }));
     };
@@ -157,10 +176,38 @@ export function SearchContainer(props: SearchContainerProps) {
     const normalizedQuery = state?.query?.trim() ?? '';
     const normalizedAsk = state?.ask?.trim() ?? '';
 
-    const showAsk = withSearchAI && normalizedAsk; // withSearchAI && normalizedAsk;
+    const showAsk = withSearchAI && normalizedAsk;
 
     const visible = viewport === 'desktop' ? !isMobile : viewport === 'mobile' ? isMobile : true;
 
+    const searchResultsId = `search-results-${React.useId()}`;
+    const { results, fetching } = useSearchResults({
+        disabled: !(state?.query || withAI),
+        query: normalizedQuery,
+        siteSpaceId,
+        siteSpaceIds,
+        scope: state?.scope ?? 'default',
+        withAI: withAI,
+    });
+    const searchValue = state?.query ?? (withSearchAI || !withAI ? state?.ask : null) ?? '';
+
+    const { cursor, moveBy: moveCursorBy } = useSearchResultsCursor({
+        query: normalizedQuery,
+        results,
+    });
+    const onKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+        if (event.key === 'ArrowUp') {
+            event.preventDefault();
+            moveCursorBy(-1);
+        } else if (event.key === 'ArrowDown') {
+            event.preventDefault();
+            moveCursorBy(1);
+        } else if (event.key === 'Enter') {
+            event.preventDefault();
+            resultsRef.current?.select();
+        }
+    };
+
     return (
         <SearchAskProvider value={searchAsk}>
             <Popover
@@ -168,15 +215,23 @@ export function SearchContainer(props: SearchContainerProps) {
                     // Only show content if there's a query or Ask is enabled
                     state?.query || withAI ? (
                         <React.Suspense fallback={null}>
-                            {isMultiVariants && !showAsk ? (
-                                <SearchScopeToggle spaceTitle={spaceTitle} />
+                            {(withVariants || withSections) && !showAsk ? (
+                                <SearchScopeToggle
+                                    section={section}
+                                    spaceTitle={spaceTitle}
+                                    withVariants={withVariants}
+                                    withSiteVariants={withSiteVariants}
+                                    withSections={withSections}
+                                />
                             ) : null}
                             {state !== null && !showAsk ? (
                                 <SearchResults
                                     ref={resultsRef}
                                     query={normalizedQuery}
-                                    global={state?.global ?? false}
-                                    siteSpaceId={siteSpaceId}
+                                    id={searchResultsId}
+                                    fetching={fetching}
+                                    results={results}
+                                    cursor={cursor}
                                 />
                             ) : null}
                             {showAsk ? <SearchAskAnswer query={normalizedAsk} /> : null}
@@ -184,22 +239,21 @@ export function SearchContainer(props: SearchContainerProps) {
                     ) : null
                 }
                 rootProps={{
-                    open: visible && (state?.open ?? false),
-                    onOpenChange: (open) => {
-                        open ? onOpen() : onClose();
-                    },
+                    open: Boolean(visible && (state?.open ?? false)),
                     modal: isMobile,
                 }}
                 contentProps={{
                     onOpenAutoFocus: (event) => event.preventDefault(),
                     align: 'start',
                     className:
-                        'bg-tint-base has-[.empty]:hidden gutter-stable scroll-py-2 w-128 p-2 pr-1 max-h-[min(32rem,var(--radix-popover-content-available-height))] max-w-[min(var(--radix-popover-content-available-width),32rem)]',
+                        '@container overflow-y-scroll bg-tint-base has-[.empty]:hidden scroll-py-2 w-128 p-2 max-h-[min(32rem,var(--radix-popover-content-available-height))] max-w-[min(var(--radix-popover-content-available-width),32rem)]',
                     onInteractOutside: (event) => {
                         // Don't close if clicking on the search input itself
                         if (searchInputRef.current?.contains(event.target as Node)) {
+                            event.preventDefault();
                             return;
                         }
+                        onClose();
                     },
                     sideOffset: 8,
                     collisionPadding: {
@@ -216,14 +270,23 @@ export function SearchContainer(props: SearchContainerProps) {
             >
                 <SearchInput
                     ref={searchInputRef}
-                    value={state?.query ?? (withSearchAI || !withAI ? state?.ask : null) ?? ''}
+                    value={searchValue}
                     onFocus={onOpen}
                     onChange={onChange}
                     onKeyDown={onKeyDown}
                     withAI={withSearchAI}
                     isOpen={state?.open ?? false}
                     className={className}
-                />
+                    aria-controls={searchResultsId}
+                    aria-activedescendant={
+                        cursor !== null ? `${searchResultsId}-${cursor}` : undefined
+                    }
+                >
+                    <LiveResultsAnnouncer
+                        count={results.length}
+                        showing={Boolean(searchValue) && !fetching}
+                    />
+                </SearchInput>
             </Popover>
             {assistants
                 .filter((assistant) => assistant.ui === true)
@@ -241,3 +304,21 @@ export function SearchContainer(props: SearchContainerProps) {
         </SearchAskProvider>
     );
 }
+
+/*
+ *  Screen reader announcement for search results.
+ *  Without it there is no feedback for screen reader users when a search returns no results.
+ */
+function LiveResultsAnnouncer(props: { count: number; showing: boolean }) {
+    const { count, showing } = props;
+    const language = useLanguage();
+    return (
+        <div className="sr-only" aria-live="assertive" role="alert" aria-relevant="all">
+            {showing
+                ? count > 0
+                    ? t(language, 'search_results_count', count)
+                    : t(language, 'search_no_results')
+                : ''}
+        </div>
+    );
+}

packages/gitbook/src/components/Search/SearchInput.tsx

@@ -16,6 +16,7 @@ interface SearchInputProps {
     withAI: boolean;
     isOpen: boolean;
     className?: string;
+    children?: React.ReactNode;
 }
 
 // Size classes for medium size button
@@ -26,7 +27,17 @@ const sizeClasses = ['text-sm', 'px-3.5', 'py-1.5', 'md:circular-corners:px-4'];
  */
 export const SearchInput = React.forwardRef<HTMLDivElement, SearchInputProps>(
     function SearchInput(props, ref) {
-        const { onChange, onKeyDown, onFocus, value, withAI, isOpen, className } = props;
+        const {
+            onChange,
+            onKeyDown,
+            onFocus,
+            value,
+            withAI,
+            isOpen,
+            className,
+            children,
+            ...rest
+        } = props;
         const inputRef = useRef<HTMLInputElement>(null);
 
         const language = useLanguage();
@@ -84,8 +95,9 @@ export const SearchInput = React.forwardRef<HTMLDivElement, SearchInputProps>(
                             className="size-4 shrink-0 animate-scale-in"
                         />
                     )}
-
+                    {children}
                     <input
+                        {...rest}
                         type="text"
                         onFocus={onFocus}
                         onKeyDown={onKeyDown}
@@ -100,6 +112,12 @@ export const SearchInput = React.forwardRef<HTMLDivElement, SearchInputProps>(
                             'peer z-10 min-w-0 grow bg-transparent py-0.5 text-tint-strong theme-bold:text-header-link outline-hidden transition-[width] duration-300 contain-paint placeholder:text-tint theme-bold:placeholder:text-current theme-bold:placeholder:opacity-7',
                             isOpen ? '' : 'max-md:opacity-0'
                         )}
+                        role="combobox"
+                        autoComplete="off"
+                        aria-autocomplete="list"
+                        aria-haspopup="listbox"
+                        aria-expanded={value && isOpen ? 'true' : 'false'}
+                        // Forward
                         ref={inputRef}
                     />
                     {!isOpen ? <Shortcut /> : null}

packages/gitbook/src/components/Search/SearchPageResultItem.tsx

@@ -14,7 +14,7 @@ export const SearchPageResultItem = React.forwardRef(function SearchPageResultIt
     },
     ref: React.Ref<HTMLAnchorElement>
 ) {
-    const { query, item, active } = props;
+    const { query, item, active, ...rest } = props;
     const language = useLanguage();
 
     const breadcrumbs =
@@ -41,6 +41,8 @@ export const SearchPageResultItem = React.forwardRef(function SearchPageResultIt
                     spaceId: item.spaceId,
                 },
             }}
+            aria-label={tString(language, 'search_page_result_title', item.title)}
+            {...rest}
         >
             {breadcrumbs.length > 0 ? (
                 <div

packages/gitbook/src/components/Search/SearchQuestionResultItem.tsx

@@ -14,7 +14,7 @@ export const SearchQuestionResultItem = React.forwardRef(function SearchQuestion
     },
     ref: React.Ref<HTMLAnchorElement>
 ) {
-    const { question, recommended = false, active, assistant } = props;
+    const { question, recommended = false, active, assistant, ...rest } = props;
     const language = useLanguage();
     const getLinkProp = useSearchLink();
 
@@ -38,6 +38,7 @@ export const SearchQuestionResultItem = React.forwardRef(function SearchQuestion
             active={active}
             leadingIcon={recommended ? 'search' : assistant.icon}
             className={recommended ? 'pr-1.5' : ''}
+            {...rest}
         >
             {recommended ? (
                 question

packages/gitbook/src/components/Search/SearchResultItem.tsx

@@ -51,6 +51,7 @@ export const SearchResultItem = React.forwardRef(function SearchResultItem(
                     : null,
                 className
             )}
+            role="option"
             {...rest}
         >
             <div className="size-4 shrink-0 text-tint-subtle">

packages/gitbook/src/components/Search/SearchResults.tsx

@@ -1,29 +1,19 @@
 'use client';
 
-import { readStreamableValue } from 'ai/rsc';
 import assertNever from 'assert-never';
 import React from 'react';
 
-import type { Assistant } from '@/components/AI';
+import { type Assistant, useAI } from '@/components/AI';
 import { t, useLanguage } from '@/intl/client';
 import { tcls } from '@/lib/tailwind';
-import { assert } from 'ts-essentials';
-import { useAI } from '../AI';
-import { useTrackEvent } from '../Insights';
+
 import { Loading } from '../primitives';
 import { SearchPageResultItem } from './SearchPageResultItem';
 import { SearchQuestionResultItem } from './SearchQuestionResultItem';
 import { SearchSectionResultItem } from './SearchSectionResultItem';
-import {
-    type OrderedComputedResult,
-    searchAllSiteContent,
-    searchSiteSpaceContent,
-    streamRecommendedQuestions,
-} from './server-actions';
+import type { OrderedComputedResult } from './server-actions';
 
 export interface SearchResultsRef {
-    moveUp(): void;
-    moveDown(): void;
     select(): void;
 }
 
@@ -32,14 +22,6 @@ type ResultType =
     | { type: 'question'; id: string; query: string; assistant: Assistant }
     | { type: 'recommended-question'; id: string; question: string };
 
-/**
- * We cache the recommended questions globally to avoid calling the API multiple times
- * when re-opening the search modal. The cache is per space, so that we can
- * have different recommended questions for different spaces of the same site.
- * It should not be used outside of an useEffect.
- */
-const cachedRecommendedQuestions: Map<string, ResultType[]> = new Map();
-
 /**
  * Fetch the results of the keyboard navigable elements to display for a query:
  *   - Recommended questions if no query is provided.
@@ -49,134 +31,20 @@ const cachedRecommendedQuestions: Map<string, ResultType[]> = new Map();
 export const SearchResults = React.forwardRef(function SearchResults(
     props: {
         children?: React.ReactNode;
+        id: string;
         query: string;
-        global: boolean;
-        siteSpaceId: string;
+        results: ResultType[];
+        fetching: boolean;
+        cursor: number | null;
     },
     ref: React.Ref<SearchResultsRef>
 ) {
-    const { children, query, global, siteSpaceId } = props;
+    const { children, id, query, results, fetching, cursor } = props;
 
     const language = useLanguage();
-    const trackEvent = useTrackEvent();
-    const [resultsState, setResultsState] = React.useState<{
-        results: ResultType[];
-        fetching: boolean;
-    }>({ results: [], fetching: true });
-    const [cursor, setCursor] = React.useState<number | null>(null);
+
     const refs = React.useRef<(null | HTMLAnchorElement)[]>([]);
 
-    const { assistants } = useAI();
-    const withAI = assistants.length > 0;
-
-    React.useEffect(() => {
-        if (!query) {
-            if (!withAI) {
-                setResultsState({ results: [], fetching: false });
-                return;
-            }
-
-            if (cachedRecommendedQuestions.has(siteSpaceId)) {
-                const results = cachedRecommendedQuestions.get(siteSpaceId);
-                assert(
-                    results,
-                    `Cached recommended questions should be set for site-space ${siteSpaceId}`
-                );
-                setResultsState({ results, fetching: false });
-                return;
-            }
-
-            setResultsState({ results: [], fetching: false });
-
-            let cancelled = false;
-
-            // We currently have a bug where the same question can be returned multiple times.
-            // This is a workaround to avoid that.
-            const questions = new Set<string>();
-            const recommendedQuestions: ResultType[] = [];
-
-            const timeout = setTimeout(async () => {
-                if (cancelled) {
-                    return;
-                }
-
-                const response = await streamRecommendedQuestions({ siteSpaceId });
-                for await (const entry of readStreamableValue(response.stream)) {
-                    if (!entry) {
-                        continue;
-                    }
-
-                    const { question } = entry;
-                    if (questions.has(question)) {
-                        continue;
-                    }
-
-                    questions.add(question);
-                    recommendedQuestions.push({
-                        type: 'recommended-question',
-                        id: question,
-                        question,
-                    });
-                    cachedRecommendedQuestions.set(siteSpaceId, recommendedQuestions);
-
-                    if (!cancelled) {
-                        setResultsState({ results: [...recommendedQuestions], fetching: false });
-                    }
-                }
-            }, 100);
-
-            return () => {
-                cancelled = true;
-                clearTimeout(timeout);
-            };
-        }
-        setResultsState((prev) => ({ results: prev.results, fetching: true }));
-        let cancelled = false;
-        const timeout = setTimeout(async () => {
-            const results = await (global
-                ? searchAllSiteContent(query)
-                : searchSiteSpaceContent(query));
-
-            if (cancelled) {
-                return;
-            }
-
-            if (!results) {
-                setResultsState({ results: [], fetching: false });
-                return;
-            }
-
-            setResultsState({ results, fetching: false });
-
-            trackEvent({
-                type: 'search_type_query',
-                query,
-            });
-        }, 350);
-
-        return () => {
-            cancelled = true;
-            clearTimeout(timeout);
-        };
-    }, [query, global, trackEvent, withAI, siteSpaceId]);
-
-    const results: ResultType[] = React.useMemo(() => {
-        if (!withAI) {
-            return resultsState.results;
-        }
-        return withAskTriggers(resultsState.results, query, assistants);
-    }, [resultsState.results, query, withAI]);
-
-    React.useEffect(() => {
-        if (!query) {
-            // Reset the cursor when there's no query
-            setCursor(null);
-        } else if (results.length > 0) {
-            // Auto-focus the first result
-            setCursor(0);
-        }
-    }, [results, query]);
-
     // Scroll to the active result.
     React.useEffect(() => {
         if (cursor === null || !refs.current[cursor]) {
@@ -189,19 +57,6 @@ export const SearchResults = React.forwardRef(function SearchResults(
         });
     }, [cursor]);
 
-    const moveBy = React.useCallback(
-        (delta: number) => {
-            setCursor((prev) => {
-                if (prev === null) {
-                    return 0;
-                }
-
-                return Math.max(Math.min(prev + delta, results.length - 1), 0);
-            });
-        },
-        [results]
-    );
-
     const select = React.useCallback(() => {
         if (cursor === null || !refs.current[cursor]) {
             return;
@@ -213,18 +68,14 @@ export const SearchResults = React.forwardRef(function SearchResults(
     React.useImperativeHandle(
         ref,
         () => ({
-            moveUp: () => {
-                moveBy(-1);
-            },
-            moveDown: () => {
-                moveBy(1);
-            },
             select,
         }),
-        [moveBy, select]
+        [select]
     );
 
-    if (resultsState.fetching) {
+    const { assistants } = useAI();
+
+    if (fetching) {
         return (
             <div className={tcls('flex', 'items-center', 'justify-center', 'py-8', 'h-full')}>
                 <Loading className={tcls('w-6', 'text-tint/6')} />
@@ -258,8 +109,19 @@ export const SearchResults = React.forwardRef(function SearchResults(
                 )
             ) : (
                 <>
-                    <div data-testid="search-results" className="flex flex-col gap-y-1">
+                    <div
+                        data-testid="search-results"
+                        className="flex flex-col gap-y-1"
+                        id={id}
+                        role="listbox"
+                        aria-live="polite"
+                    >
                         {results.map((item, index) => {
+                            const resultItemProps = {
+                                'aria-posinset': index + 1,
+                                'aria-setsize': results.length,
+                                id: `${id}-${index}`,
+                            };
                             switch (item.type) {
                                 case 'page': {
                                     return (
@@ -271,6 +133,7 @@ export const SearchResults = React.forwardRef(function SearchResults(
                                             query={query}
                                             item={item}
                                             active={index === cursor}
+                                            {...resultItemProps}
                                         />
                                     );
                                 }
@@ -284,6 +147,7 @@ export const SearchResults = React.forwardRef(function SearchResults(
                                             question={query}
                                             active={index === cursor}
                                             assistant={item.assistant}
+                                            {...resultItemProps}
                                         />
                                     );
                                 }
@@ -298,6 +162,7 @@ export const SearchResults = React.forwardRef(function SearchResults(
                                             active={index === cursor}
                                             assistant={assistants[0]!}
                                             recommended
+                                            {...resultItemProps}
                                         />
                                     );
                                 }
@@ -311,6 +176,7 @@ export const SearchResults = React.forwardRef(function SearchResults(
                                             query={query}
                                             item={item}
                                             active={index === cursor}
+                                            {...resultItemProps}
                                         />
                                     );
                                 }
@@ -325,28 +191,3 @@ export const SearchResults = React.forwardRef(function SearchResults(
         </div>
     );
 });
-
-/**
- * Add a "Ask <question>" item at the top of the results list.
- */
-function withAskTriggers(
-    results: ResultType[],
-    query: string,
-    assistants: Assistant[]
-): ResultType[] {
-    const without = results.filter((result) => result.type !== 'question');
-
-    if (query.length === 0) {
-        return without;
-    }
-
-    return [
-        ...assistants.map((assistant, index) => ({
-            type: 'question' as const,
-            id: `question-${index}`,
-            query,
-            assistant,
-        })),
-        ...(without ?? []),
-    ];
-}

packages/gitbook/src/components/Search/SearchScopeToggle.tsx

@@ -1,13 +1,22 @@
+'use client';
+
 import { tString, useLanguage } from '@/intl/client';
-import { Button } from '../primitives';
+import type { SiteSection } from '@gitbook/api';
+import { SegmentedControl, SegmentedControlItem } from '../primitives/SegmentedControl';
 import { useSearch } from './useSearch';
 
 /**
  * Toolbar to toggle between search modes (global or scoped to a space).
  * Only visible when the space is in a collection.
  */
-export function SearchScopeToggle(props: { spaceTitle: string }) {
-    const { spaceTitle } = props;
+export function SearchScopeToggle(props: {
+    spaceTitle: string;
+    section?: Pick<SiteSection, 'title' | 'icon'>;
+    withVariants: boolean;
+    withSiteVariants: boolean;
+    withSections: boolean;
+}) {
+    const { spaceTitle, section, withVariants, withSections, withSiteVariants } = props;
     const [state, setSearchState] = useSearch();
     const language = useLanguage();
 
@@ -16,37 +25,82 @@ export function SearchScopeToggle(props: { spaceTitle: string }) {
     }
 
     return (
-        <div
-            role="toolbar"
-            aria-orientation="horizontal"
-            className="mb-2 flex flex-row flex-wrap gap-1 circular-corners:rounded-3xl rounded-corners:rounded-lg bg-tint-subtle p-1"
-        >
-            <Button
-                variant="blank"
-                size="medium"
-                className="shrink grow justify-center whitespace-normal"
-                active={!state.global}
-                label={tString(language, 'search_scope_space', spaceTitle)}
-                onClick={() => {
-                    setSearchState({
-                        ...state,
-                        global: false,
-                    });
-                }}
-            />
-            <Button
-                variant="blank"
-                size="medium"
-                className="shrink grow justify-center whitespace-normal"
-                active={state.global}
-                label={tString(language, 'search_scope_all')}
-                onClick={() => {
-                    setSearchState({
-                        ...state,
-                        global: true,
-                    });
-                }}
-            />
-        </div>
+        <>
+            {withSections ? (
+                <SegmentedControl className="animate-scale-in">
+                    {/* `Default` scope = current section's current variant + best match in other sections */}
+                    <SegmentedControlItem
+                        active={
+                            withSiteVariants
+                                ? state.scope === 'default'
+                                : ['default', 'all'].includes(state.scope)
+                        }
+                        label={
+                            withSiteVariants
+                                ? tString(language, 'search_scope_default')
+                                : tString(language, 'search_scope_all')
+                        }
+                        className={withSiteVariants ? '@max-md:basis-full' : ''}
+                        icon={withSiteVariants ? 'bullseye-arrow' : 'infinity'}
+                        onClick={() => setSearchState({ ...state, scope: 'default' })}
+                    />
+
+                    {/* `Current` scope = current section's current variant (with further variant scope selection if necessary) */}
+                    <SegmentedControlItem
+                        active={state.scope === 'current' || state.scope === 'extended'}
+                        icon={section?.icon ?? 'crosshairs'}
+                        label={tString(language, 'search_scope_current', section?.title)}
+                        onClick={() => setSearchState({ ...state, scope: 'current' })}
+                    />
+
+                    {/* `All` scope = all content on the site. Only visible if site has variants, otherwise it's the same as default */}
+                    {withSiteVariants ? (
+                        <SegmentedControlItem
+                            active={state.scope === 'all'}
+                            label={tString(language, 'search_scope_all')}
+                            icon="infinity"
+                            onClick={() => setSearchState({ ...state, scope: 'all' })}
+                        />
+                    ) : null}
+                </SegmentedControl>
+            ) : null}
+            {withVariants &&
+            (!withSections || state.scope === 'current' || state.scope === 'extended') ? (
+                <SegmentedControl className="animate-scale-in">
+                    {/* `Current` scope = current section's current variant. `Default` on sites without sections. */}
+                    <SegmentedControlItem
+                        size={withSections ? 'small' : 'medium'}
+                        active={
+                            withSections
+                                ? state.scope === 'current'
+                                : ['default', 'current'].includes(state.scope)
+                        }
+                        className="py-1"
+                        label={tString(language, 'search_scope_current', spaceTitle)}
+                        onClick={() =>
+                            setSearchState({
+                                ...state,
+                                scope: withSections ? 'current' : 'default',
+                            })
+                        }
+                    />
+
+                    {/* `Extended` scope = all variants of the current section. `All` on sites without sections. */}
+                    <SegmentedControlItem
+                        size={withSections ? 'small' : 'medium'}
+                        active={
+                            withSections
+                                ? state.scope === 'extended'
+                                : ['extended', 'all'].includes(state.scope)
+                        }
+                        className="py-1"
+                        label={tString(language, 'search_scope_extended')}
+                        onClick={() =>
+                            setSearchState({ ...state, scope: withSections ? 'extended' : 'all' })
+                        }
+                    />
+                </SegmentedControl>
+            ) : null}
+        </>
     );
 }

packages/gitbook/src/components/Search/SearchSectionResultItem.tsx

@@ -13,7 +13,7 @@ export const SearchSectionResultItem = React.forwardRef(function SearchSectionRe
     },
     ref: React.Ref<HTMLAnchorElement>
 ) {
-    const { query, item, active } = props;
+    const { query, item, active, ...rest } = props;
     const language = useLanguage();
 
     return (
@@ -32,6 +32,18 @@ export const SearchSectionResultItem = React.forwardRef(function SearchSectionRe
                     spaceId: item.spaceId,
                 },
             }}
+            aria-label={
+                item.title
+                    ? tString(language, 'search_section_result_title', item.title)
+                    : item.body
+                      ? tString(
+                            language,
+                            'search_section_result_content',
+                            getAbbreviatedBody(item.body, query)
+                        )
+                      : tString(language, 'search_section_result_default')
+            }
+            {...rest}
         >
             <div className="grow border-tint-subtle border-l-2 pl-4">
                 {item.title ? (
@@ -51,7 +63,12 @@ function highlightQueryInBody(body: string, query: string) {
     // Ensure the query to be highlighted is visible in the body.
     return (
         <p className="wrap-anywhere relative line-clamp-3 text-sm">
-            <HighlightQuery query={query} text={idx < 20 ? body : `...${body.slice(idx - 10)}`} />
+            <HighlightQuery query={query} text={idx < 20 ? body : `…${body.slice(idx - 10)}`} />
         </p>
     );
 }
+
+function getAbbreviatedBody(body: string, query: string) {
+    const idx = body.toLocaleLowerCase().indexOf(query.toLocaleLowerCase());
+    return idx < 20 ? body.slice(0, 100) : `…${body.slice(idx - 10, idx + query.length + 30)}…`;
+}

packages/gitbook/src/components/Search/server-actions.tsx

@@ -14,6 +14,7 @@ import type {
     SearchSpaceResult,
     SiteSection,
     SiteSectionGroup,
+    SiteSpace,
     Space,
 } from '@gitbook/api';
 import { createStreamableValue } from 'ai/rsc';
@@ -81,18 +82,33 @@ export async function searchAllSiteContent(query: string): Promise<OrderedComput
 /**
  * Server action to search content in a space.
  */
-export async function searchSiteSpaceContent(query: string): Promise<OrderedComputedResult[]> {
+export async function searchCurrentSiteSpaceContent(
+    query: string,
+    siteSpaceId: string
+): Promise<OrderedComputedResult[]> {
     return traceErrorOnly('Search.searchSiteSpaceContent', async () => {
         const context = await getServerActionBaseContext();
-        const siteURLData = await getSiteURLDataFromMiddleware();
 
         return await searchSiteContent(context, {
             query,
-            // If we have a siteSectionId that means its a sections site use `current` mode
-            // which searches in the current space + all default spaces of sections
-            scope: siteURLData.siteSection
-                ? { mode: 'current', siteSpaceId: siteURLData.siteSpace }
-                : { mode: 'specific', siteSpaceIds: [siteURLData.siteSpace] },
+            scope: { mode: 'current', siteSpaceId },
+        });
+    });
+}
+
+/**
+ * Server action to search content in a specific space.
+ */
+export async function searchSpecificSiteSpaceContent(
+    query: string,
+    siteSpaceIds: string[]
+): Promise<OrderedComputedResult[]> {
+    return traceErrorOnly('Search.searchSiteSpaceContent', async () => {
+        const context = await getServerActionBaseContext();
+
+        return await searchSiteContent(context, {
+            query,
+            scope: { mode: 'specific', siteSpaceIds },
         });
     });
 }
@@ -281,6 +297,7 @@ async function searchSiteContent(
                         transformSitePageResult(context, {
                             pageItem,
                             spaceItem,
+                            siteSpace: found?.siteSpace,
                             space: found?.siteSpace.space,
                             spaceURL: found?.siteSpace.urls.published,
                             siteSection: siteSection ?? undefined,
@@ -369,12 +386,13 @@ async function transformSitePageResult(
         pageItem: SearchPageResult;
         spaceItem: SearchSpaceResult;
         space?: Space;
+        siteSpace?: SiteSpace;
         spaceURL?: string;
         siteSection?: SiteSection;
         siteSectionGroup?: SiteSectionGroup;
     }
 ): Promise<OrderedComputedResult[]> {
-    const { pageItem, spaceItem, space, spaceURL, siteSection, siteSectionGroup } = args;
+    const { pageItem, spaceItem, spaceURL, siteSection, siteSectionGroup, siteSpace } = args;
     const { linker } = context;
 
     const page: ComputedPageResult = {
@@ -395,9 +413,9 @@ async function transformSitePageResult(
                 icon: siteSection?.icon as IconName,
                 label: siteSection.title,
             },
-            (!siteSection || siteSection?.siteSpaces.length > 1) && space
+            (!siteSection || siteSection?.siteSpaces.length > 1) && siteSpace
                 ? {
-                      label: space?.title,
+                      label: siteSpace.title,
                   }
                 : undefined,
         ].filter((item) => item !== undefined),

packages/gitbook/src/components/Search/useSearch.tsx

@@ -1,14 +1,24 @@
 'use client';
 
-import { parseAsBoolean, parseAsString, useQueryStates } from 'nuqs';
+import { parseAsBoolean, parseAsString, parseAsStringLiteral, useQueryStates } from 'nuqs';
 import React from 'react';
 import type { LinkProps } from '../primitives';
 
+export type SearchScope =
+    /** Search all content on the site */
+    | 'all'
+    /** Search the current section's variant + matched/default variant for other sections */
+    | 'default'
+    /** Search all variants of the current section */
+    | 'extended'
+    /** Search only the current section's current variant */
+    | 'current';
+
 export interface SearchState {
     // URL-backed state
     query: string | null;
     ask: string | null;
-    global: boolean;
+    scope: SearchScope;
 
     // Local UI state
     open: boolean;
@@ -18,7 +28,8 @@ export interface SearchState {
 const keyMap = {
     q: parseAsString,
     ask: parseAsString,
-    global: parseAsBoolean,
+    scope: parseAsStringLiteral(['all', 'default', 'extended', 'current']).withDefault('default'),
+    global: parseAsBoolean, // Legacy support for global=true
 };
 
 export type UpdateSearchState = (
@@ -41,14 +52,21 @@ export function SearchContextProvider(props: React.PropsWithChildren): React.Rea
         history: 'replace',
     });
 
-    // Handle legacy ask=true format by converting it to the new format
     React.useEffect(() => {
+        // Handle legacy ask=true format by converting it to the new format
         if (rawState?.ask === 'true' && rawState?.q) {
             // Convert legacy format: q=query&ask=true -> ask=query&q=null
             setRawState({
                 q: null,
                 ask: rawState.q,
-                global: rawState.global,
+            });
+        }
+
+        // Handle legacy global=true
+        if (rawState?.global === true) {
+            setRawState({
+                scope: 'all',
+                global: null, // Remove the legacy parameter
             });
         }
     }, [rawState, setRawState]);
@@ -65,7 +83,7 @@ export function SearchContextProvider(props: React.PropsWithChildren): React.Rea
         return {
             query: rawState.q,
             ask: rawState.ask,
-            global: !!rawState.global,
+            scope: rawState.scope,
             open,
         };
     }, [rawState, open]);
@@ -85,14 +103,14 @@ export function SearchContextProvider(props: React.PropsWithChildren): React.Rea
 
             if (update === null) {
                 setIsOpen(false);
-                return setRawState({ q: null, ask: null, global: null });
+                return setRawState({ q: null, ask: null, scope: 'default' });
             }
 
             setIsOpen(update.open);
             return setRawState({
                 q: update.query,
                 ask: update.ask,
-                global: update.global ? true : null,
+                scope: update.scope,
             });
         },
         [setRawState]
@@ -126,7 +144,7 @@ export function useSearchLink(): (
             const searchParams = new URLSearchParams();
             params.query ? searchParams.set('q', params.query) : searchParams.delete('q');
             params.ask ? searchParams.set('ask', params.ask) : searchParams.delete('ask');
-            params.global ? searchParams.set('global', 'true') : searchParams.delete('global');
+            params.scope ? searchParams.set('scope', params.scope) : searchParams.delete('scope');
             return {
                 href: `?${searchParams.toString()}`,
                 prefetch: false,
@@ -137,7 +155,7 @@ export function useSearchLink(): (
                         ...prev,
                         query: params.query !== undefined ? params.query : null,
                         ask: params.ask !== undefined ? params.ask : null,
-                        global: params.global !== undefined ? params.global : false,
+                        scope: params.scope !== undefined ? params.scope : 'default',
                         open: params.open !== undefined ? params.open : false,
                     }));
                 },

packages/gitbook/src/components/Search/useSearchResults.ts

@@ -0,0 +1,194 @@
+import { readStreamableValue } from 'ai/rsc';
+import React from 'react';
+
+import { assert } from 'ts-essentials';
+
+import {
+    type OrderedComputedResult,
+    searchAllSiteContent,
+    searchCurrentSiteSpaceContent,
+    searchSpecificSiteSpaceContent,
+    streamRecommendedQuestions,
+} from './server-actions';
+
+import { type Assistant, useAI } from '@/components/AI';
+import { useTrackEvent } from '../Insights';
+import type { SearchScope } from './useSearch';
+
+export type ResultType =
+    | OrderedComputedResult
+    | { type: 'question'; id: string; query: string; assistant: Assistant }
+    | { type: 'recommended-question'; id: string; question: string };
+
+/**
+ * We cache the recommended questions globally to avoid calling the API multiple times
+ * when re-opening the search modal. The cache is per space, so that we can
+ * have different recommended questions for different spaces of the same site.
+ * It should not be used outside of an useEffect.
+ */
+const cachedRecommendedQuestions: Map<string, ResultType[]> = new Map();
+
+export function useSearchResults(props: {
+    disabled: boolean;
+    query: string;
+    siteSpaceId: string;
+    siteSpaceIds: string[];
+    scope: SearchScope;
+    withAI: boolean;
+}) {
+    const { disabled, query, siteSpaceId, siteSpaceIds, scope } = props;
+
+    const trackEvent = useTrackEvent();
+
+    const [resultsState, setResultsState] = React.useState<{
+        results: ResultType[];
+        fetching: boolean;
+    }>({ results: [], fetching: false });
+
+    const { assistants } = useAI();
+    const withAI = assistants.length > 0;
+
+    React.useEffect(() => {
+        if (disabled) {
+            return;
+        }
+        if (!query) {
+            if (!withAI) {
+                setResultsState({ results: [], fetching: false });
+                return;
+            }
+
+            if (cachedRecommendedQuestions.has(siteSpaceId)) {
+                const results = cachedRecommendedQuestions.get(siteSpaceId);
+                assert(
+                    results,
+                    `Cached recommended questions should be set for site-space ${siteSpaceId}`
+                );
+                setResultsState({ results, fetching: false });
+                return;
+            }
+
+            setResultsState({ results: [], fetching: false });
+
+            let cancelled = false;
+
+            // We currently have a bug where the same question can be returned multiple times.
+            // This is a workaround to avoid that.
+            const questions = new Set<string>();
+            const recommendedQuestions: ResultType[] = [];
+
+            const timeout = setTimeout(async () => {
+                if (cancelled) {
+                    return;
+                }
+
+                const response = await streamRecommendedQuestions({ siteSpaceId });
+                for await (const entry of readStreamableValue(response.stream)) {
+                    if (!entry) {
+                        continue;
+                    }
+
+                    const { question } = entry;
+                    if (questions.has(question)) {
+                        continue;
+                    }
+
+                    questions.add(question);
+                    recommendedQuestions.push({
+                        type: 'recommended-question',
+                        id: question,
+                        question,
+                    });
+                    cachedRecommendedQuestions.set(siteSpaceId, recommendedQuestions);
+
+                    if (!cancelled) {
+                        setResultsState({ results: [...recommendedQuestions], fetching: false });
+                    }
+                }
+            }, 100);
+
+            return () => {
+                cancelled = true;
+                clearTimeout(timeout);
+            };
+        }
+        setResultsState((prev) => ({ results: prev.results, fetching: true }));
+        let cancelled = false;
+        const timeout = setTimeout(async () => {
+            const results = await (() => {
+                if (scope === 'all') {
+                    // Search all content on the site
+                    return searchAllSiteContent(query);
+                }
+                if (scope === 'default') {
+                    // Search the current section's variant + matched/default variant for other sections
+                    return searchCurrentSiteSpaceContent(query, siteSpaceId);
+                }
+                if (scope === 'extended') {
+                    // Search all variants of the current section
+                    return searchSpecificSiteSpaceContent(query, siteSpaceIds);
+                }
+                if (scope === 'current') {
+                    // Search only the current section's current variant
+                    return searchSpecificSiteSpaceContent(query, [siteSpaceId]);
+                }
+                throw new Error(`Unhandled search scope: ${scope}`);
+            })();
+
+            if (cancelled) {
+                return;
+            }
+
+            if (!results) {
+                setResultsState({ results: [], fetching: false });
+                return;
+            }
+
+            setResultsState({ results, fetching: false });
+
+            trackEvent({
+                type: 'search_type_query',
+                query,
+            });
+        }, 350);
+
+        return () => {
+            cancelled = true;
+            clearTimeout(timeout);
+        };
+    }, [query, scope, trackEvent, withAI, siteSpaceId, siteSpaceIds, disabled]);
+
+    const aiEnrichedResults: ResultType[] = React.useMemo(() => {
+        if (!withAI) {
+            return resultsState.results;
+        }
+        return withAskTriggers(resultsState.results, query, assistants);
+    }, [resultsState.results, query, withAI]);
+
+    return { ...resultsState, results: aiEnrichedResults };
+}
+
+/**
+ * Add a "Ask <question>" item at the top of the results list.
+ */
+function withAskTriggers(
+    results: ResultType[],
+    query: string,
+    assistants: Assistant[]
+): ResultType[] {
+    const without = results.filter((result) => result.type !== 'question');
+
+    if (query.length === 0) {
+        return without;
+    }
+
+    return [
+        ...assistants.map((assistant, index) => ({
+            type: 'question' as const,
+            id: `question-${index}`,
+            query,
+            assistant,
+        })),
+        ...(without ?? []),
+    ];
+}

packages/gitbook/src/components/Search/useSearchResultsCursor.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+import type { ResultType } from './useSearchResults';
+
+export function useSearchResultsCursor(props: { query: string; results: ResultType[] }) {
+    const [cursor, setCursor] = React.useState<number | null>(null);
+    const { query, results } = props;
+
+    React.useEffect(() => {
+        if (!query) {
+            // Reset the cursor when there's no query
+            setCursor(null);
+        }
+    }, [query]);
+
+    React.useEffect(() => {
+        if (results.length > 0) {
+            // Auto-focus the first result
+            setCursor(0);
+        }
+    }, [results]);
+
+    const moveBy = React.useCallback(
+        (delta: number) => {
+            setCursor((prev) => {
+                if (prev === null) {
+                    return 0;
+                }
+                return Math.max(Math.min(prev + delta, results.length - 1), 0);
+            });
+        },
+        [results]
+    );
+
+    return {
+        cursor,
+        setCursor,
+        moveBy,
+    };
+}

packages/gitbook/src/components/SiteLayout/SiteLayout.tsx

@@ -108,6 +108,8 @@ export async function generateSiteLayoutMetadata(context: GitBookSiteContext): P
     const customIcon = 'icon' in customization.favicon ? customization.favicon.icon : null;
 
     const faviconSize = 48;
+    const appIconSize = 180;
+
     const icons = await Promise.all(
         [
             {
@@ -140,12 +142,44 @@ export async function generateSiteLayoutMetadata(context: GitBookSiteContext): P
         }))
     );
 
+    const appIcons = await Promise.all(
+        [
+            {
+                url: customIcon?.light
+                    ? getResizedImageURL(imageResizer, customIcon.light, {
+                          width: appIconSize,
+                          height: appIconSize,
+                      })
+                    : linker.toAbsoluteURL(
+                          linker.toPathInSpace('~gitbook/icon?size=medium&theme=light&border=false')
+                      ),
+                type: 'image/png',
+                media: '(prefers-color-scheme: light)',
+            },
+            {
+                url: customIcon?.dark
+                    ? getResizedImageURL(imageResizer, customIcon.dark, {
+                          width: appIconSize,
+                          height: appIconSize,
+                      })
+                    : linker.toAbsoluteURL(
+                          linker.toPathInSpace('~gitbook/icon?size=medium&theme=dark&border=false')
+                      ),
+                type: 'image/png',
+                media: '(prefers-color-scheme: dark)',
+            },
+        ].map(async (icon) => ({
+            ...icon,
+            url: await icon.url,
+        }))
+    );
+
     return {
         title: site.title,
         generator: `GitBook (${buildVersion()})`,
         icons: {
             icon: icons,
-            apple: icons,
+            apple: appIcons,
         },
         appleWebApp: {
             capable: true,

packages/gitbook/src/components/SiteSections/SiteSectionList.tsx

@@ -5,10 +5,10 @@ import { motion } from 'framer-motion';
 import React from 'react';
 
 import { type ClassValue, tcls } from '@/lib/tailwind';
-
-import { TOCScrollContainer, useScrollToActiveTOCItem } from '../TableOfContents/TOCScroller';
-import { useIsMounted, useToggleAnimation } from '../hooks';
+import { findSectionInGroup } from '@/lib/utils';
+import { useToggleAnimation } from '../hooks';
 import { Link } from '../primitives';
+import { ScrollContainer } from '../primitives/ScrollContainer';
 import { SectionIcon } from './SectionIcon';
 import type {
     ClientSiteSection,
@@ -16,7 +16,7 @@ import type {
     ClientSiteSections,
 } from './encodeClientSiteSections';
 
-const MAX_ITEMS = 5; // If there are more sections than this, they'll be shown below the fold in a scrollview.
+const MAX_ITEMS = 6; // If there are more sections than this, they'll be shown below the fold in a scrollview.
 
 /**
  * A list of items representing site sections for multi-section sites
@@ -36,30 +36,34 @@ export function SiteSectionList(props: { sections: ClientSiteSections; className
                     className
                 )}
             >
-                <TOCScrollContainer
+                <ScrollContainer
+                    orientation="vertical"
                     style={{ maxHeight: `${MAX_ITEMS * 3 + 2}rem` }}
-                    className="overflow-y-auto px-2 pb-4"
+                    className="pb-4"
+                    activeId={currentSection.id}
                 >
-                    {sectionsAndGroups.map((item) => {
-                        if (item.object === 'site-section-group') {
+                    <div className="flex w-full flex-col px-2">
+                        {sectionsAndGroups.map((item) => {
+                            if (item.object === 'site-section-group') {
+                                return (
+                                    <SiteSectionGroupItem
+                                        key={item.id}
+                                        group={item}
+                                        currentSection={currentSection}
+                                    />
+                                );
+                            }
+
                             return (
-                                <SiteSectionGroupItem
+                                <SiteSectionListItem
+                                    section={item}
+                                    isActive={item.id === currentSection.id}
                                     key={item.id}
-                                    group={item}
-                                    currentSection={currentSection}
                                 />
                             );
-                        }
-
-                        return (
-                            <SiteSectionListItem
-                                section={item}
-                                isActive={item.id === currentSection.id}
-                                key={item.id}
-                            />
-                        );
-                    })}
-                </TOCScrollContainer>
+                        })}
+                    </div>
+                </ScrollContainer>
             </nav>
         )
     );
@@ -69,20 +73,15 @@ export function SiteSectionListItem(props: {
     section: ClientSiteSection;
     isActive: boolean;
     className?: string;
+    style?: React.CSSProperties;
 }) {
-    const { section, isActive, className, ...otherProps } = props;
-
-    const isMounted = useIsMounted();
-    React.useEffect(() => {}, [isMounted]); // This updates the useScrollToActiveTOCItem hook once we're mounted, so we can actually scroll to the this item
-
-    const anchorRef = React.createRef<HTMLAnchorElement>();
-    useScrollToActiveTOCItem({ anchorRef, isActive });
+    const { section, isActive, className, style, ...otherProps } = props;
 
     return (
         <Link
-            ref={anchorRef}
             href={section.url}
             aria-current={isActive && 'page'}
+            id={section.id}
             className={tcls(
                 'group/section-link',
                 'flex',
@@ -104,6 +103,7 @@ export function SiteSectionListItem(props: {
                     : null,
                 className
             )}
+            style={style}
             {...otherProps}
         >
             <div
@@ -130,11 +130,12 @@ export function SiteSectionListItem(props: {
 export function SiteSectionGroupItem(props: {
     group: ClientSiteSectionGroup;
     currentSection: ClientSiteSection;
+    level?: number;
 }) {
-    const { group, currentSection } = props;
+    const { group, currentSection, level = 0 } = props;
 
-    const hasDescendants = group.sections.length > 0;
-    const isActiveGroup = group.sections.some((section) => section.id === currentSection.id);
+    const hasDescendants = group.children.length > 0;
+    const isActiveGroup = Boolean(findSectionInGroup(group, currentSection.id));
     const shouldOpen = hasDescendants && isActiveGroup;
     const [isOpen, setIsOpen] = React.useState(shouldOpen);
 
@@ -164,7 +165,7 @@ export function SiteSectionGroupItem(props: {
                     className={tcls(
                         'flex size-8 shrink-0 items-center justify-center rounded-md straight-corners:rounded-none bg-tint-subtle text-lg text-tint leading-none shadow-tint shadow-xs ring-1 ring-tint-subtle transition-transform group-hover/section-link:scale-110 group-hover/section-link:ring-tint-hover group-active/section-link:scale-90 group-active/section-link:shadow-none contrast-more:text-tint-strong dark:shadow-none',
                         isActiveGroup
-                            ? 'bg-primary tint:bg-primary-solid text-primary tint:text-contrast-primary-solid shadow-md shadow-primary ring-primary group-hover/section-link:ring-primary-hover, contrast-more:text-primary-strong contrast-more:ring-2 contrast-more:ring-primary'
+                            ? 'bg-primary text-primary shadow-md shadow-primary ring-primary group-hover/section-link:ring-primary-hover, contrast-more:text-primary-strong contrast-more:ring-2 contrast-more:ring-primary'
                             : null
                     )}
                 >
@@ -219,14 +220,26 @@ export function SiteSectionGroupItem(props: {
             </button>
             {hasDescendants ? (
                 <Descendants isVisible={isOpen}>
-                    {group.sections.map((section) => (
-                        <SiteSectionListItem
-                            section={section}
-                            isActive={section.id === currentSection.id}
-                            key={section.id}
-                            className="pl-5"
-                        />
-                    ))}
+                    {group.children.map((child) => {
+                        if (child.object === 'site-section') {
+                            return (
+                                <SiteSectionListItem
+                                    section={child}
+                                    isActive={child.id === currentSection.id}
+                                    key={child.id}
+                                />
+                            );
+                        }
+
+                        return (
+                            <SiteSectionGroupItem
+                                group={child}
+                                currentSection={currentSection}
+                                key={child.id}
+                                level={level + 1}
+                            />
+                        );
+                    })}
                 </Descendants>
             ) : null}
         </>
@@ -242,7 +255,7 @@ function Descendants(props: {
     return (
         <motion.div
             ref={scope}
-            className={isVisible ? undefined : '[&_ul>li]:opacity-1'}
+            className={isVisible ? 'pl-3' : 'pl-3 [&_ul>li]:opacity-1'}
             initial={isVisible ? show : hide}
         >
             {children}

packages/gitbook/src/components/SiteSections/SiteSectionTabs.tsx

@@ -1,113 +1,128 @@
 'use client';
 
-import { Icon, type IconName } from '@gitbook/icons';
+import type { IconName } from '@gitbook/icons';
 import * as NavigationMenu from '@radix-ui/react-navigation-menu';
 import React from 'react';
 
-import { Link } from '@/components/primitives';
+import { Button, DropdownChevron, Link } from '@/components/primitives';
 import { tcls } from '@/lib/tailwind';
+import { findSectionInGroup } from '@/lib/utils';
+import { useIsMobile } from '../hooks/useIsMobile';
+import { CONTAINER_STYLE } from '../layout';
+import { ScrollContainer } from '../primitives/ScrollContainer';
 import { SectionIcon } from './SectionIcon';
-import type { ClientSiteSection, ClientSiteSections } from './encodeClientSiteSections';
+import type {
+    ClientSiteSection,
+    ClientSiteSectionGroup,
+    ClientSiteSections,
+} from './encodeClientSiteSections';
 
-const VIEWPORT_ITEM_WIDTH = 240; /* width of the tile (w-60) */
-const MIN_ITEMS_FOR_COLS = 4; /* number of items to switch to 2 columns */
+const SCREEN_OFFSET = 16; // 1rem
+const MAX_ITEMS_PER_COLUMN = 5; // number of items per column
 /**
  * A set of navigational links representing site sections for multi-section sites
  */
-export function SiteSectionTabs(props: { sections: ClientSiteSections }) {
+export function SiteSectionTabs(props: {
+    sections: ClientSiteSections;
+    className?: string;
+    children?: React.ReactNode;
+}) {
     const {
-        sections: { list: sectionsAndGroups, current: currentSection },
+        sections: { list: structure, current: currentSection },
+        className,
+        children,
     } = props;
-    const [value, setValue] = React.useState<string | null>();
+
+    const currentTriggerRef = React.useRef<HTMLButtonElement | null>(null);
     const [offset, setOffset] = React.useState<number | null>(null);
-    const menuContainerRef = React.useRef<HTMLDivElement>(null);
+    const [value, setValue] = React.useState<string | undefined>();
 
-    const onNodeUpdate = (trigger: HTMLButtonElement | null, itemValue: string, size = 0) => {
-        const padding = 16;
-        const margin = -12; // Offsetting the menu container's negative margin
-        const windowWidth = document.documentElement.clientWidth;
-        const windowBuffer = 16; // constrain to within the window with some buffer on the left and right we don't want the menu to enter
-        const viewportWidth =
-            size < MIN_ITEMS_FOR_COLS
-                ? VIEWPORT_ITEM_WIDTH + padding
-                : VIEWPORT_ITEM_WIDTH * 2 + padding;
-        const minOffset = 0 - (menuContainerRef.current?.offsetLeft ?? 0) + margin;
-        const maxOffset = minOffset + windowWidth - viewportWidth;
+    const isMobile = useIsMobile(768);
 
-        if (windowWidth < 768) {
-            // if the screen is small don't offset the menu
-            setOffset(minOffset + windowBuffer);
-        } else if (trigger && value === itemValue) {
-            const position = minOffset + trigger?.getBoundingClientRect().left;
-            setOffset(
-                Math.min(maxOffset - windowBuffer, Math.max(minOffset + windowBuffer, position))
-            );
-        } else if (!value) {
-            setOffset(null);
+    React.useEffect(() => {
+        const trigger = currentTriggerRef.current;
+        if (!value || !trigger) {
+            return;
         }
-    };
 
-    return sectionsAndGroups.length > 0 ? (
+        const triggerWidth = trigger.getBoundingClientRect().width;
+        const triggerLeft = trigger.getBoundingClientRect().left;
+        setOffset(triggerLeft + triggerWidth / 2);
+    }, [value]);
+
+    return structure.length > 0 ? (
         <NavigationMenu.Root
-            aria-label="Sections"
-            id="sections"
+            className={tcls(
+                CONTAINER_STYLE,
+                'relative z-10 flex w-full flex-nowrap items-end',
+                'page-default-width:2xl:px-[calc((100%-1536px+4rem)/2)]',
+                className
+            )}
+            value={value}
             onValueChange={setValue}
-            className="z-10 flex w-full flex-nowrap items-center"
+            skipDelayDuration={500}
         >
-            <div
-                ref={menuContainerRef}
-                className="-mx-3"
-                // className="-mb-4 pb-4" /* Positive padding / negative margin allows the navigation menu indicator to show in a scroll view */
+            <ScrollContainer
+                orientation="horizontal"
+                className={tcls(
+                    'grow',
+                    'md:-ml-8 -ml-4 sm:-ml-6',
+                    !children ? 'md:-mr-8 -mr-4 sm:-mr-6' : ''
+                )}
+                activeId={currentSection.id}
             >
-                <NavigationMenu.List className="center m-0 flex list-none gap-2 bg-transparent">
-                    {sectionsAndGroups.map((sectionOrGroup) => {
-                        const { id, title, icon } = sectionOrGroup;
-                        const isGroup = sectionOrGroup.object === 'site-section-group';
+                <NavigationMenu.List
+                    className={tcls(
+                        '-mx-3 flex grow gap-2 bg-transparent',
+                        'pl-4 sm:pl-6 md:pl-8',
+                        !children ? 'pr-4 sm:pr-6 md:pr-8' : ''
+                    )}
+                    aria-label="Sections"
+                    id="sections"
+                >
+                    {structure.map((structureItem) => {
+                        const { id, title, icon } = structureItem;
+                        const isGroup = structureItem.object === 'site-section-group';
                         const isActiveGroup =
                             isGroup &&
-                            Boolean(
-                                sectionOrGroup.sections.find((s) => s.id === currentSection.id)
-                            );
+                            Boolean(findSectionInGroup(structureItem, currentSection.id));
                         const isActive = isActiveGroup || id === currentSection.id;
                         return (
-                            <NavigationMenu.Item key={id} value={id}>
-                                {isGroup ? (
-                                    sectionOrGroup.sections.length > 0 ? (
-                                        <>
-                                            <NavigationMenu.Trigger
-                                                ref={(node) =>
-                                                    onNodeUpdate(
-                                                        node,
-                                                        id,
-                                                        sectionOrGroup.sections.length
-                                                    )
+                            <NavigationMenu.Item key={id} value={id} id={id}>
+                                {isGroup && structureItem.children.length > 0 ? (
+                                    <>
+                                        <NavigationMenu.Trigger
+                                            asChild
+                                            ref={value === id ? currentTriggerRef : undefined}
+                                            onClick={(e) => {
+                                                // Prevent clicking the trigger from closing when the viewport is open
+                                                if (value === id) {
+                                                    e.preventDefault();
+                                                    e.stopPropagation();
                                                 }
-                                                asChild
-                                                onClick={(e) => {
-                                                    if (value) {
-                                                        e.preventDefault();
-                                                        e.stopPropagation();
-                                                    }
-                                                }}
-                                            >
-                                                <SectionGroupTab
-                                                    isActive={isActive}
-                                                    title={title}
-                                                    icon={icon as IconName}
-                                                />
-                                            </NavigationMenu.Trigger>
-                                            <NavigationMenu.Content className="absolute top-0 left-0 z-20 w-full motion-safe:data-[motion=from-end]:animate-enter-from-right motion-safe:data-[motion=from-start]:animate-enter-from-left motion-safe:data-[motion=to-end]:animate-exit-to-right motion-safe:data-[motion=to-start]:animate-exit-to-left md:w-max">
-                                                <SectionGroupTileList
-                                                    sections={sectionOrGroup.sections}
-                                                    currentSection={currentSection}
-                                                />
-                                            </NavigationMenu.Content>
-                                        </>
-                                    ) : null
+                                            }}
+                                        >
+                                            <SectionTab
+                                                isActive={isActive}
+                                                title={title}
+                                                icon={icon as IconName}
+                                            />
+                                        </NavigationMenu.Trigger>
+                                        <NavigationMenu.Content>
+                                            <SectionGroupTileList
+                                                items={structureItem.children}
+                                                currentSection={currentSection}
+                                            />
+                                        </NavigationMenu.Content>
+                                    </>
                                 ) : (
                                     <NavigationMenu.Link asChild>
                                         <SectionTab
-                                            url={sectionOrGroup.url}
+                                            url={
+                                                structureItem.object === 'site-section'
+                                                    ? structureItem.url
+                                                    : undefined
+                                            }
                                             isActive={isActive}
                                             title={title}
                                             icon={icon ? (icon as IconName) : undefined}
@@ -117,26 +132,30 @@ export function SiteSectionTabs(props: { sections: ClientSiteSections }) {
                             </NavigationMenu.Item>
                         );
                     })}
-                    <NavigationMenu.Indicator
-                        className="fixed top-full z-50 flex h-3 items-end justify-center duration-150 motion-safe:transition-[width,transform] motion-safe:data-[state=hidden]:animate-fade-out motion-safe:data-[state=visible]:animate-fade-in"
-                        aria-hidden
-                    >
-                        <div className="relative top-1/2 size-3 rotate-45 rounded-tl-sm border-tint-subtle border-t border-l bg-tint-base" />
-                    </NavigationMenu.Indicator>
                 </NavigationMenu.List>
-            </div>
+            </ScrollContainer>
+
+            {children}
+
             <div
-                className="absolute top-full flex transition-transform duration-200 ease-in-out"
+                className="fixed top-full left-0 z-20 flex w-full"
                 style={{
-                    display: offset === null ? 'none' : undefined,
-                    transform: offset ? `translateX(${offset}px) translateZ(0)` : 'translateZ(0)', // TranslateZ is needed to force a stacking context, fixing a rendering bug on Safari
+                    padding: `0 ${SCREEN_OFFSET}px 0 ${SCREEN_OFFSET}px`,
                 }}
             >
                 <NavigationMenu.Viewport
-                    className="relative mt-3 h-(--radix-navigation-menu-viewport-height) w-[calc(100vw-2rem)] origin-[top_center] overflow-hidden rounded-lg straight-corners:rounded-xs bg-tint-base depth-flat:shadow-none shadow-lg shadow-tint-10/6 ring-1 ring-tint-subtle duration-250 data-[state=closed]:duration-150 motion-safe:transition-[width,height,transform] motion-safe:data-[state=closed]:animate-scale-out motion-safe:data-[state=open]:animate-scale-in md:mx-0 md:w-(--radix-navigation-menu-viewport-width) dark:shadow-tint-1/6"
+                    className={tcls(
+                        'relative origin-top overflow-auto circular-corners:rounded-3xl rounded-corners:rounded-xl border border-tint bg-tint-base shadow-lg transition-transform duration-250 ease-in-out',
+                        '-mt-0.5 w-full md:w-max',
+                        'max-h-[calc(100vh-8rem)] data-[state=closed]:animate-scale-out data-[state=open]:animate-scale-in',
+                        "[&:not([style*='--radix-navigation-menu-viewport-width'])]:hidden" // The viewport width is only calculated once it's triggered, and can take a while. We hide the viewport until it's ready.
+                    )}
                     style={{
                         translate:
-                            undefined /* don't move this to a Tailwind class as Radix renders viewport incorrectly for a few frames */,
+                            !isMobile && offset
+                                ? `clamp(0px, calc(${offset}px - ${SCREEN_OFFSET}px - 50%), calc(100vw - var(--radix-navigation-menu-viewport-width, 0px) - ${SCREEN_OFFSET * 3}px)) 0 0`
+                                : '0 0 0', // TranslateZ is needed to force a stacking context, fixing a rendering bug on Safari
+                        display: offset === null ? 'none' : undefined,
                     }}
                 />
             </div>
@@ -145,131 +164,172 @@ export function SiteSectionTabs(props: { sections: ClientSiteSections }) {
 }
 
 /**
- * A tab representing a section
+ * A tab representing a section or section group
  */
 const SectionTab = React.forwardRef(function SectionTab(
-    props: { isActive: boolean; title: string; icon?: IconName; url: string },
+    props: { isActive: boolean; title: string; icon?: IconName; url?: string },
     ref: React.Ref<HTMLAnchorElement>
 ) {
     const { isActive, title, icon, url, ...rest } = props;
+    const isGroup = url === undefined;
     return (
-        <Link
+        <Button
             ref={ref}
+            size="medium"
+            variant="blank"
             {...rest}
+            icon={icon ? <SectionIcon isActive={isActive} icon={icon} /> : null}
+            label={title}
+            trailing={isGroup ? <DropdownChevron /> : null}
+            active={isActive}
             className={tcls(
-                'group relative my-2 flex select-none items-center justify-between circular-corners:rounded-full rounded-corners:rounded-xs px-3 py-1',
+                'group/dropdown relative my-2 overflow-visible px-3 py-1',
                 isActive
-                    ? 'text-primary-subtle'
-                    : 'text-tint hover:bg-tint-hover hover:text-tint-strong'
+                    ? 'after:contents-[] after:-bottom-2 bg-transparent text-primary-subtle after:absolute after:inset-x-3 after:h-0.5 after:bg-primary-9'
+                    : ''
             )}
             href={url}
-        >
-            <span className="flex w-full items-center gap-2 truncate">
-                {icon ? <SectionIcon isActive={isActive} icon={icon} /> : null}
-                {title}
-            </span>
-            {isActive ? <ActiveTabIndicator /> : null}
-        </Link>
+        />
     );
 });
 
-/**
- * A tab representing a section group
- */
-const SectionGroupTab = React.forwardRef(function SectionGroupTab(
-    props: { isActive: boolean; title: string; icon?: IconName },
-    ref: React.Ref<HTMLButtonElement>
-) {
-    const { isActive, title, icon, ...rest } = props;
-    return (
-        <button
-            ref={ref}
-            {...rest}
-            className={tcls(
-                'group relative my-2 flex select-none items-center justify-between circular-corners:rounded-full rounded-sm straight-corners:rounded-none px-3 py-1 transition-colors hover:cursor-default',
-                isActive
-                    ? 'text-primary-subtle'
-                    : 'text-tint hover:bg-tint-hover hover:text-tint-strong'
-            )}
-        >
-            <span className="flex w-full items-center gap-2 truncate">
-                {icon ? <SectionIcon isActive={isActive} icon={icon as IconName} /> : null}
-                {title}
-            </span>
-            {isActive ? <ActiveTabIndicator /> : null}
-            <Icon
-                aria-hidden
-                icon="chevron-down"
-                className="ms-1 size-3 shrink-0 opacity-6 transition-all group-data-[state=open]:rotate-180"
-            />
-        </button>
-    );
-});
-
-/**
- * Horizontal line indicating the active tab
- */
-function ActiveTabIndicator() {
-    return (
-        <span className="-bottom-2 absolute inset-x-3 h-0.5 bg-primary-9 contrast-more:bg-primary-11" />
-    );
-}
-
 /**
  * A list of section tiles grouped in the dropdown for a section group
  */
 function SectionGroupTileList(props: {
-    sections: ClientSiteSection[];
+    items: (ClientSiteSection | ClientSiteSectionGroup)[];
     currentSection: ClientSiteSection;
 }) {
-    const { sections, currentSection } = props;
+    const { items, currentSection } = props;
+
+    // Separate non-grouped sections from grouped sections
+    const sections = items.filter((item) => item.object === 'site-section');
+    const groups = items.filter((item) => item.object === 'site-section-group');
+
+    const hasSections = sections.length > 0;
+    const hasGroups = groups.length > 0;
+
     return (
-        <ul
-            className={tcls(
-                'grid w-full gap-1 p-2 sm:grid-cols-1 md:w-max',
-                sections.length < MIN_ITEMS_FOR_COLS ? 'md:grid-cols-1' : 'md:grid-cols-2'
+        <div className="flex flex-col md:flex-row">
+            {/* Non-grouped sections */}
+            {hasSections && (
+                <ul
+                    className={tcls(
+                        'flex grid-flow-row flex-col gap-x-2 gap-y-1 p-2 md:grid',
+                        hasGroups ? 'bg-tint-base' : ''
+                    )}
+                    style={{
+                        gridTemplateColumns: `repeat(${Math.ceil(sections.length / MAX_ITEMS_PER_COLUMN)}, minmax(0, 1fr))`,
+                    }}
+                >
+                    {sections.map((section) => (
+                        <SectionGroupTile
+                            key={section.id}
+                            child={section}
+                            currentSection={currentSection}
+                        />
+                    ))}
+                </ul>
             )}
-        >
-            {sections.map((section) => (
-                <SectionGroupTile
-                    key={section.id}
-                    section={section}
-                    isActive={section.id === currentSection.id}
-                />
-            ))}
-        </ul>
+
+            {/* Grouped sections */}
+            {hasGroups && (
+                <ul
+                    className={tcls(
+                        'flex grid-flow-col flex-col items-start gap-x-2 gap-y-4 p-2 md:grid md:gap-y-1',
+                        hasSections
+                            ? 'border-tint-subtle bg-tint-subtle max-md:border-t md:border-l'
+                            : ''
+                    )}
+                >
+                    {groups.map((group) => (
+                        <SectionGroupTile
+                            key={group.id}
+                            child={group}
+                            currentSection={currentSection}
+                        />
+                    ))}
+                </ul>
+            )}
+        </div>
     );
 }
 
 /**
  * A section tile shown in the dropdown for a section group
  */
-function SectionGroupTile(props: { section: ClientSiteSection; isActive: boolean }) {
-    const { section, isActive } = props;
-    const { url, icon, title } = section;
+function SectionGroupTile(props: {
+    child: ClientSiteSection | ClientSiteSectionGroup;
+    currentSection: ClientSiteSection;
+}) {
+    const { child, currentSection } = props;
+
+    if (child.object === 'site-section') {
+        const { url, icon, title, description } = child;
+        const isActive = child.id === currentSection.id;
+        return (
+            <li className="group/section-tile flex w-full shrink grow md:w-68">
+                <Link
+                    href={url}
+                    className={tcls(
+                        'grow circular-corners:rounded-2xl rounded-corners:rounded-lg px-3 py-2 transition-colors',
+                        isActive
+                            ? 'bg-primary-active text-primary-strong'
+                            : 'text-tint-strong hover:bg-tint-hover'
+                    )}
+                >
+                    <div className="mb-auto flex grow items-center gap-2">
+                        {icon && (
+                            <div
+                                className={tcls(
+                                    '-ml-1 self-start circular-corners:rounded-2xl rounded-corners:rounded-lg p-2 transition-colors',
+                                    isActive
+                                        ? 'bg-primary-base text-primary-subtle'
+                                        : 'bg-tint text-tint-strong group-hover/section-tile:bg-tint-base'
+                                )}
+                            >
+                                <SectionIcon isActive={isActive} icon={icon as IconName} />
+                            </div>
+                        )}
+                        <div className="flex flex-col gap-1">
+                            {title}
+                            {description && (
+                                <p className={isActive ? 'text-primary' : 'text-tint'}>
+                                    {description}
+                                </p>
+                            )}
+                        </div>
+                    </div>
+                </Link>
+            </li>
+        );
+    }
+
+    // Handle nested section group
+    const { title, icon, children } = child;
+
     return (
-        <li className="flex w-full md:w-60">
-            <Link
-                href={url}
-                className={tcls(
-                    'flex w-full select-none flex-col gap-1 rounded-sm straight-corners:rounded-none px-3 py-2 transition-colors hover:bg-tint-hover',
-                    isActive ? 'text-primary' : 'text-tint-strong'
+        <li className="flex w-full shrink grow flex-col gap-1">
+            <div className="mt-3 mb-2 flex gap-2.5 px-3 font-semibold text-tint-subtle text-xs uppercase tracking-wider">
+                {icon && (
+                    <SectionIcon className="mt-0.5" isActive={false} icon={icon as IconName} />
                 )}
+                {title}
+            </div>
+            <ul
+                className="flex grid-flow-row flex-col gap-x-2 gap-y-1 md:grid"
+                style={{
+                    gridTemplateColumns: `repeat(${Math.ceil(children.length / MAX_ITEMS_PER_COLUMN)}, minmax(0, 1fr))`,
+                }}
             >
-                <div className="flex w-full gap-2">
-                    {icon ? (
-                        <SectionIcon
-                            className="mt-[3px]"
-                            isActive={false}
-                            icon={icon as IconName}
-                        />
-                    ) : null}
-                    {title}
-                </div>
-                {section.description ? (
-                    <p className="text-tint-subtle">{section.description}</p>
-                ) : null}
-            </Link>
+                {children.map((nestedChild) => (
+                    <SectionGroupTile
+                        key={nestedChild.id}
+                        child={nestedChild}
+                        currentSection={currentSection}
+                    />
+                ))}
+            </ul>
         </li>
     );
 }

packages/gitbook/src/components/SiteSections/encodeClientSiteSections.ts

@@ -16,7 +16,7 @@ export type ClientSiteSection = Pick<
 };
 
 export type ClientSiteSectionGroup = Pick<SiteSectionGroup, 'id' | 'title' | 'icon' | 'object'> & {
-    sections: ClientSiteSection[];
+    children: (ClientSiteSection | ClientSiteSectionGroup)[];
 };
 
 /**
@@ -30,10 +30,10 @@ export function encodeClientSiteSections(context: GitBookSiteContext, sections:
     for (const item of list) {
         switch (item.object) {
             case 'site-section-group': {
-                const sections = item.sections.map((section) => encodeSection(context, section));
+                const children = encodeChildren(context, item.children);
 
                 // Skip empty groups
-                if (sections.length === 0) {
+                if (children.length === 0) {
                     continue;
                 }
 
@@ -42,7 +42,7 @@ export function encodeClientSiteSections(context: GitBookSiteContext, sections:
                     title: item.title,
                     icon: item.icon,
                     object: item.object,
-                    sections,
+                    children,
                 });
                 continue;
             }
@@ -61,6 +61,43 @@ export function encodeClientSiteSections(context: GitBookSiteContext, sections:
     };
 }
 
+function encodeChildren(
+    context: GitBookSiteContext,
+    children: (SiteSection | SiteSectionGroup)[]
+): (ClientSiteSection | ClientSiteSectionGroup)[] {
+    const clientChildren: (ClientSiteSection | ClientSiteSectionGroup)[] = [];
+
+    for (const child of children) {
+        switch (child.object) {
+            case 'site-section': {
+                clientChildren.push(encodeSection(context, child));
+                break;
+            }
+            case 'site-section-group': {
+                const nestedChildren = encodeChildren(context, child.children);
+
+                // Skip empty groups
+                if (nestedChildren.length === 0) {
+                    continue;
+                }
+
+                clientChildren.push({
+                    id: child.id,
+                    title: child.title,
+                    icon: child.icon,
+                    object: child.object,
+                    children: nestedChildren,
+                });
+                break;
+            }
+            default:
+                assertNever(child, 'Unknown site section object type');
+        }
+    }
+
+    return clientChildren;
+}
+
 function encodeSection(context: GitBookSiteContext, section: SiteSection) {
     return {
         id: section.id,

packages/gitbook/src/components/SpaceLayout/SpaceLayout.tsx

@@ -25,6 +25,7 @@ import { InsightsProvider, VisitorSessionProvider } from '../Insights';
 import { SearchContainer } from '../Search';
 import { SiteSectionList, encodeClientSiteSections } from '../SiteSections';
 import { CurrentContentProvider } from '../hooks';
+import { NavigationLoader } from '../primitives/NavigationLoader';
 import { SpaceLayoutContextProvider } from './SpaceLayoutContext';
 
 type SpaceLayoutProps = {
@@ -125,6 +126,7 @@ export function SpaceLayout(props: SpaceLayoutProps) {
         <SpaceLayoutServerContext {...props}>
             <Announcement context={context} />
             <Header withTopHeader={withTopHeader} withVariants={withVariants} context={context} />
+            <NavigationLoader />
             {customization.ai?.mode === CustomizationAIMode.Assistant ? (
                 <AIChat trademark={customization.trademark.enabled} />
             ) : null}
@@ -180,9 +182,25 @@ export function SpaceLayout(props: SpaceLayoutProps) {
                                     <div className="flex gap-2">
                                         <SearchContainer
                                             style={CustomizationSearchStyle.Subtle}
-                                            isMultiVariants={siteSpaces.length > 1}
+                                            withVariants={withVariants === 'generic'}
+                                            withSiteVariants={
+                                                sections?.list.some(
+                                                    (s) =>
+                                                        s.object === 'site-section' &&
+                                                        s.siteSpaces.length > 1
+                                                ) ?? false
+                                            }
+                                            withSections={withSections}
+                                            section={sections?.current}
                                             spaceTitle={siteSpace.title}
                                             siteSpaceId={siteSpace.id}
+                                            siteSpaceIds={siteSpaces
+                                                .filter(
+                                                    (s) =>
+                                                        s.space.language ===
+                                                        siteSpace.space.language
+                                                )
+                                                .map((s) => s.id)}
                                             className="max-lg:hidden"
                                             viewport="desktop"
                                         />

packages/gitbook/src/components/hooks/useHash.tsx

@@ -1,17 +1,26 @@
 'use client';
+
+import { usePathname } from 'next/navigation';
 import React from 'react';
 
-export const HashContext = React.createContext<{
+export const NavigationStatusContext = React.createContext<{
     hash: string | null;
     /**
-     * Updates the hash value from the URL provided here.
-     * It will then be used by the `useHash` hook.
+     * Updates the navigation state from the URL provided here.
      * URL can be relative or absolute.
      */
-    updateHashFromUrl: (href: string) => void;
+    onNavigationClick: (href: string) => void;
+    /**
+     * Indicates if a link has been clicked recently.
+     * Becomes true after a click and resets to false when pathname changes.
+     * It is debounced to avoid flickering on fast navigations.
+     * Debounce time is 400ms (= doherty threshold for responsiveness).
+     */
+    isNavigating: boolean;
 }>({
     hash: null,
-    updateHashFromUrl: () => {},
+    onNavigationClick: () => {},
+    isNavigating: false,
 });
 
 function getHash(): string | null {
@@ -21,20 +30,62 @@ function getHash(): string | null {
     return window.location.hash.slice(1);
 }
 
-export const HashProvider: React.FC<React.PropsWithChildren<{}>> = ({ children }) => {
+export const NavigationStatusProvider: React.FC<React.PropsWithChildren> = ({ children }) => {
     const [hash, setHash] = React.useState<string | null>(getHash);
-    const updateHashFromUrl = React.useCallback((href: string) => {
+    const [isNavigating, setIsNavigating] = React.useState(false);
+    const timeoutRef = React.useRef<number | null>(null);
+    const pathname = usePathname();
+    const pathnameRef = React.useRef(pathname);
+
+    // Reset isNavigating when pathname changes
+    React.useEffect(() => {
+        if (pathnameRef.current !== pathname) {
+            setIsNavigating(false);
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+                timeoutRef.current = null;
+            }
+            pathnameRef.current = pathname;
+        }
+    }, [pathname]);
+
+    // Cleanup timeout on unmount
+    React.useEffect(() => {
+        return () => {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, []);
+
+    const onNavigationClick = React.useCallback((href: string) => {
         const url = new URL(
             href,
             typeof window !== 'undefined' ? window.location.origin : 'http://localhost'
         );
         setHash(url.hash.slice(1));
+
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+        }
+        if (pathnameRef.current !== url.pathname) {
+            timeoutRef.current = window.setTimeout(() => {
+                setIsNavigating(true);
+                timeoutRef.current = null;
+                return;
+            }, 400); // 400ms timeout - doherty threshold for responsiveness
+        }
     }, []);
+
     const memoizedValue = React.useMemo(
-        () => ({ hash, updateHashFromUrl }),
-        [hash, updateHashFromUrl]
+        () => ({ hash, onNavigationClick, isNavigating }),
+        [hash, onNavigationClick, isNavigating]
+    );
+    return (
+        <NavigationStatusContext.Provider value={memoizedValue}>
+            {children}
+        </NavigationStatusContext.Provider>
     );
-    return <HashContext.Provider value={memoizedValue}>{children}</HashContext.Provider>;
 };
 
 /**
@@ -45,8 +96,16 @@ export const HashProvider: React.FC<React.PropsWithChildren<{}>> = ({ children }
  * Since we have a single Link component that handles all links, we can use a context to share the hash.
  */
 export function useHash() {
-    // const params = useParams();
-    const { hash } = React.useContext(HashContext);
+    const { hash } = React.useContext(NavigationStatusContext);
 
     return hash;
 }
+
+/**
+ * Hook to get the current navigation state.
+ * @returns True if a navigation has been triggered recently. False otherwise, it also resets to false when the navigation is complete.
+ */
+export function useIsNavigating() {
+    const { isNavigating: hasBeenClicked } = React.useContext(NavigationStatusContext);
+    return hasBeenClicked;
+}

packages/gitbook/src/components/primitives/Button.tsx

@@ -40,11 +40,16 @@ export const variantClasses = {
         'bg-transparent',
         'text-tint',
         'border-0',
+        'contrast-more:border',
         'shadow-none!',
+        'translate-y-0!',
         'hover:bg-tint-hover',
         'hover:text-tint-strong',
+        'focus-visible:bg-tint-hover',
+        'focus-visible:text-tint-strong',
+        'data-[state=open]:bg-tint-hover',
+        'data-[state=open]:text-tint-strong',
         'contrast-more:bg-tint-subtle',
-        'hover:depth-subtle:translate-y-0',
         'disabled:text-tint/8',
         'disabled:bg-transparent',
     ],
@@ -80,9 +85,9 @@ export const variantClasses = {
     ],
 };
 
-const activeClasses = {
+export const activeClasses = {
     primary: 'bg-primary-solid-hover',
-    blank: 'bg-primary-active disabled:bg-primary-active text-primary-strong font-medium hover:text-primary-strong disabled:text-primary-strong hover:bg-primary-active',
+    blank: 'bg-primary-active contrast-more:bg-primary-12 contrast-more:text-contrast-primary-12 disabled:bg-primary-active text-primary-strong font-medium hover:text-primary-strong disabled:text-primary-strong hover:bg-primary-active focus-visible:bg-primary-active focus-visible:text-primary-strong data-[state=open]:bg-primary-active data-[state=open]:text-primary-strong',
     secondary: 'bg-tint-active disabled:bg-tint-active',
     header: 'bg-header-link/3',
 };
@@ -134,7 +139,7 @@ export const Button = React.forwardRef<
                     typeof icon === 'string' ? (
                         <Icon
                             icon={icon as IconName}
-                            className={tcls('button-leading-icon size-[1em]')}
+                            className={tcls('button-leading-icon size-[1em] shrink-0')}
                         />
                     ) : (
                         icon
@@ -154,6 +159,7 @@ export const Button = React.forwardRef<
                 aria-label={label?.toString()}
                 aria-pressed={active}
                 target={target}
+                data-active={active}
                 {...rest}
             >
                 {content}
@@ -166,6 +172,7 @@ export const Button = React.forwardRef<
                 aria-label={label?.toString()}
                 aria-pressed={active}
                 disabled={disabled}
+                data-active={active}
                 {...rest}
             >
                 {content}

packages/gitbook/src/components/primitives/DateRelative.tsx

@@ -3,6 +3,7 @@
 import React from 'react';
 
 import { useLanguage } from '@/intl/client';
+import { Tooltip } from './Tooltip';
 
 /**
  * Display a date as a relative time.
@@ -28,14 +29,11 @@ export function DateRelative(props: { value: string }) {
     const date = new Date(value);
     const diff = now - date.getTime();
     return (
-        <time
-            data-visual-test="transparent"
-            suppressHydrationWarning={true}
-            dateTime={value}
-            title={date.toLocaleString()}
-        >
-            {formatDiff(language.locale, diff)}
-        </time>
+        <Tooltip label={date.toLocaleString()}>
+            <time data-visual-test="transparent" suppressHydrationWarning={true} dateTime={value}>
+                {formatDiff(language.locale, diff)}
+            </time>
+        </Tooltip>
     );
 }
 

packages/gitbook/src/components/primitives/DropdownMenu.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { Icon } from '@gitbook/icons';
+import { Icon, type IconName } from '@gitbook/icons';
 import type { DetailedHTMLProps, HTMLAttributes } from 'react';
 import { createContext, useCallback, useContext, useState } from 'react';
 
@@ -146,10 +146,20 @@ export function DropdownMenuItem(
         active?: boolean;
         className?: ClassValue;
         children: React.ReactNode;
+        leadingIcon?: IconName | React.ReactNode;
     } & LinkInsightsProps &
         RadixDropdownMenu.DropdownMenuItemProps
 ) {
-    const { children, active = false, href, className, insights, target, ...rest } = props;
+    const {
+        children,
+        active = false,
+        href,
+        className,
+        insights,
+        target,
+        leadingIcon,
+        ...rest
+    } = props;
 
     const itemClassName = tcls(
         'rounded-xs straight-corners:rounded-xs circular-corners:rounded-lg px-3 py-1 text-sm flex gap-2 items-center',
@@ -161,10 +171,22 @@ export function DropdownMenuItem(
         className
     );
 
+    const icon = leadingIcon ? (
+        typeof leadingIcon === 'string' ? (
+            <Icon
+                icon={leadingIcon as IconName}
+                className={tcls('size-4 shrink-0', active ? 'text-primary' : 'text-tint-subtle')}
+            />
+        ) : (
+            leadingIcon
+        )
+    ) : null;
+
     if (href) {
         return (
             <RadixDropdownMenu.Item {...rest} asChild>
                 <Link href={href} insights={insights} className={itemClassName} target={target}>
+                    {icon}
                     {children}
                 </Link>
             </RadixDropdownMenu.Item>
@@ -173,6 +195,7 @@ export function DropdownMenuItem(
 
     return (
         <RadixDropdownMenu.Item {...rest} className={tcls('px-3 py-1', itemClassName, className)}>
+            {icon}
             {children}
         </RadixDropdownMenu.Item>
     );

packages/gitbook/src/components/primitives/Link.tsx

@@ -6,7 +6,7 @@ import React from 'react';
 import { tcls } from '@/lib/tailwind';
 import { SiteExternalLinksTarget } from '@gitbook/api';
 import { type TrackEventInput, useTrackEvent } from '../Insights';
-import { HashContext } from '../hooks';
+import { NavigationStatusContext } from '../hooks';
 import { isExternalLink } from '../utils/link';
 import { type DesignTokenName, useClassnames } from './StyleProvider';
 
@@ -72,7 +72,7 @@ export const Link = React.forwardRef(function Link(
 ) {
     const { href, prefetch, children, insights, classNames, className, ...domProps } = props;
     const { externalLinksTarget } = React.useContext(LinkSettingsContext);
-    const { updateHashFromUrl } = React.useContext(HashContext);
+    const { onNavigationClick } = React.useContext(NavigationStatusContext);
     const trackEvent = useTrackEvent();
     const forwardedClassNames = useClassnames(classNames || []);
     const isExternal = isExternalLink(href);
@@ -81,7 +81,7 @@ export const Link = React.forwardRef(function Link(
     const onClick = (event: React.MouseEvent<HTMLAnchorElement>) => {
         const isExternalWithOrigin = isExternalLink(href, window.location.origin);
         if (!isExternal) {
-            updateHashFromUrl(href);
+            onNavigationClick(href);
         }
 
         if (insights) {

packages/gitbook/src/components/primitives/NavigationLoader.tsx

@@ -0,0 +1,22 @@
+'use client';
+import { tcls } from '@/lib/tailwind';
+import { useIsNavigating } from '../hooks';
+
+export const NavigationLoader = () => {
+    const isNavigating = useIsNavigating();
+
+    return (
+        <div
+            className={tcls(
+                'pointer-events-none fixed inset-x-0 top-0 z-50 h-0.5 overflow-hidden',
+                isNavigating ? 'block' : 'hidden animate-fade-out-slow'
+            )}
+        >
+            <div
+                className={tcls(
+                    'h-full w-full origin-left animate-crawl bg-primary-solid theme-bold:bg-header-link'
+                )}
+            />
+        </div>
+    );
+};

packages/gitbook/src/components/primitives/ScrollContainer.tsx

@@ -0,0 +1,177 @@
+'use client';
+
+import { tString, useLanguage } from '@/intl/client';
+import { tcls } from '@/lib/tailwind';
+import * as React from 'react';
+import { Button } from './Button';
+
+/**
+ * A container that encapsulates a scrollable area with usability features.
+ * - Faded edges when there is more content than the container can display.
+ * - Buttons to advance the scroll position.
+ * - Auto-scroll to the active item when it's initially active.
+ */
+export type ScrollContainerProps = {
+    children: React.ReactNode;
+    className?: string;
+
+    /** The direction of the scroll container. */
+    orientation: 'horizontal' | 'vertical';
+
+    /** The ID of the active item to scroll to. */
+    activeId?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+export function ScrollContainer(props: ScrollContainerProps) {
+    const { children, className, orientation, activeId, ...rest } = props;
+
+    const containerRef = React.useRef<HTMLDivElement>(null);
+
+    const [scrollPosition, setScrollPosition] = React.useState(0);
+    const [scrollSize, setScrollSize] = React.useState(0);
+
+    const language = useLanguage();
+
+    React.useEffect(() => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+
+        // Update scroll position on scroll using requestAnimationFrame
+        const scrollListener: EventListener = () => {
+            requestAnimationFrame(() => {
+                setScrollPosition(
+                    orientation === 'horizontal' ? container.scrollLeft : container.scrollTop
+                );
+            });
+        };
+        container.addEventListener('scroll', scrollListener);
+
+        // Update max scroll position using resize observer
+        const resizeObserver = new ResizeObserver((entries) => {
+            const containerEntry = entries.find((i) => i.target === containerRef.current);
+            if (containerEntry) {
+                setScrollSize(
+                    orientation === 'horizontal'
+                        ? containerEntry.target.scrollWidth - containerEntry.target.clientWidth - 1
+                        : containerEntry.target.scrollHeight -
+                              containerEntry.target.clientHeight -
+                              1
+                );
+            }
+        });
+        resizeObserver.observe(container);
+
+        return () => {
+            container.removeEventListener('scroll', scrollListener);
+            resizeObserver.disconnect();
+        };
+    }, [orientation]);
+
+    // Scroll to the active item
+    React.useEffect(() => {
+        const container = containerRef.current;
+        if (!container || !activeId) {
+            return;
+        }
+        const activeItem = container.querySelector(`#${CSS.escape(activeId)}`);
+        if (activeItem) {
+            activeItem.scrollIntoView({
+                inline: 'center',
+                block: 'center',
+            });
+        }
+    }, [activeId]);
+
+    const scrollFurther = () => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+        container.scrollTo({
+            top: orientation === 'vertical' ? scrollPosition + container.clientHeight : undefined,
+            left: orientation === 'horizontal' ? scrollPosition + container.clientWidth : undefined,
+            behavior: 'smooth',
+        });
+    };
+
+    const scrollBack = () => {
+        const container = containerRef.current;
+        if (!container) {
+            return;
+        }
+        container.scrollTo({
+            top: orientation === 'vertical' ? scrollPosition - container.clientHeight : undefined,
+            left: orientation === 'horizontal' ? scrollPosition - container.clientWidth : undefined,
+            behavior: 'smooth',
+        });
+    };
+
+    return (
+        <div
+            className={tcls('group/scroll-container relative flex overflow-hidden', className)}
+            {...rest}
+        >
+            {/* Scrollable content */}
+            <div
+                className={tcls(
+                    'flex shrink grow',
+                    orientation === 'horizontal' ? 'no-scrollbar' : 'hide-scrollbar',
+                    orientation === 'horizontal' ? 'overflow-x-scroll' : 'overflow-y-auto',
+                    scrollPosition > 0
+                        ? orientation === 'horizontal'
+                            ? 'mask-l-from-[calc(100%-2rem)]'
+                            : 'mask-t-from-[calc(100%-2rem)]'
+                        : '',
+                    scrollPosition < scrollSize
+                        ? orientation === 'horizontal'
+                            ? 'mask-r-from-[calc(100%-2rem)]'
+                            : 'mask-b-from-[calc(100%-2rem)]'
+                        : ''
+                )}
+                ref={containerRef}
+            >
+                {children}
+            </div>
+
+            {/* Scroll buttons back & forward */}
+            <Button
+                icon={orientation === 'horizontal' ? 'chevron-left' : 'chevron-up'}
+                iconOnly
+                size="xsmall"
+                variant="secondary"
+                tabIndex={-1}
+                className={tcls(
+                    orientation === 'horizontal'
+                        ? '-translate-y-1/2! top-1/2 left-0 ml-2'
+                        : '-translate-x-1/2! top-0 left-1/2 mt-2',
+                    'absolute not-pointer-none:block hidden scale-0 opacity-0 transition-[scale,opacity]',
+                    scrollPosition > 0
+                        ? 'not-pointer-none:group-hover/scroll-container:scale-100 not-pointer-none:group-hover/scroll-container:opacity-11'
+                        : 'pointer-events-none'
+                )}
+                onClick={scrollBack}
+                label={tString(language, 'scroll_back')}
+            />
+            <Button
+                icon={orientation === 'horizontal' ? 'chevron-right' : 'chevron-down'}
+                iconOnly
+                size="xsmall"
+                variant="secondary"
+                tabIndex={-1}
+                className={tcls(
+                    orientation === 'horizontal'
+                        ? '-translate-y-1/2! top-1/2 right-0 mr-2'
+                        : '-translate-x-1/2! bottom-0 left-1/2 mb-2',
+                    'absolute not-pointer-none:block hidden scale-0 transition-[scale,opacity]',
+                    scrollPosition < scrollSize
+                        ? 'not-pointer-none:group-hover/scroll-container:scale-100 not-pointer-none:group-hover/scroll-container:opacity-11'
+                        : 'pointer-events-none'
+                )}
+                onClick={scrollFurther}
+                label={tString(language, 'scroll_further')}
+            />
+        </div>
+    );
+}