Fix merge logic for allOf alternatives (#3515)

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

.changeset/afraid-cougars-happen.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Hide sections if only one is present

.changeset/blue-countries-beg.md

@@ -0,0 +1,5 @@
+---
+"@gitbook/expr": patch
+---
+
+Add dev script for @gitbook/expr

.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/curly-fishes-accept.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Redo search scope UI

.changeset/dirty-mice-sleep.md

@@ -0,0 +1,6 @@
+---
+"@gitbook/react-openapi": patch
+"gitbook": patch
+---
+
+Highlight discriminator properties in oneOf, allOf, anyOf objects

.changeset/dry-melons-joke.md

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

.changeset/dry-pens-behave.md

@@ -0,0 +1,6 @@
+---
+"@gitbook/react-openapi": patch
+"gitbook": patch
+---
+
+Adapt OpenAPI code samples to prefill API key using visitor data

.changeset/eight-eels-sort.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix markdownPageURL for PageActions

.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/mean-starfishes-promise.md

@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Move inline expression evaluation from API to GBO

.changeset/mighty-bears-type.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix rounded outline items

.changeset/quick-donuts-double.md

@@ -0,0 +1,5 @@
+---
+"@gitbook/react-openapi": patch
+---
+
+Ensure operation security requirements inherits from spec-level when not defined

.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/shaggy-shoes-eat.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add alt text to inline image

.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/silly-ducks-kiss.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Improve wide page width layout

.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/spicy-trainers-dance.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix button content truncate

.changeset/tame-months-knock.md

@@ -0,0 +1,5 @@
+---
+'@gitbook/react-openapi': patch
+---
+
+Fix merge logic for allOf alternatives

.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/unlucky-pumpkins-yawn.md

@@ -0,0 +1,6 @@
+---
+"@gitbook/react-openapi": patch
+"gitbook": patch
+---
+
+Fix OpenAPI alternatives not showing

.changeset/wicked-hornets-crash.md

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

.github/workflows/deploy-preview.yaml

@@ -182,9 +182,9 @@ jobs:
                   SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
                   ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
                   ARGOS_BUILD_NAME: 'customers-v2'
-    pagespeed-testing-v2:
+    browserless-testing-v2-vercel:
         runs-on: ubuntu-latest
-        name: PageSpeed Testing v1
+        name: Browserless Testing v2 (Vercel)
         needs: deploy-v2-vercel
         steps:
             - name: Checkout
@@ -195,8 +195,26 @@ jobs:
               run: bun install --frozen-lockfile
               env:
                   PUPPETEER_SKIP_DOWNLOAD: 1
-            - name: Run pagespeed tests
-              run: bun ./packages/gitbook/tests/pagespeed-testing.ts
+            - name: Run tests
+              run: cd ./packages/gitbook && bun e2e-browserless
               env:
                   BASE_URL: ${{needs.deploy-v2-vercel.outputs.deployment-url}}
-                  PAGESPEED_API_KEY: ${{ secrets.PAGESPEED_API_KEY }}
+                  SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
+    # browserless-testing-v2-cloudflare:
+    #     runs-on: ubuntu-latest
+    #     name: Browserless Testing v2 (Cloudflare)
+    #     needs: deploy-v2-cloudflare
+    #     steps:
+    #         - name: Checkout
+    #           uses: actions/checkout@v4
+    #         - name: Setup Bun
+    #           uses: ./.github/composite/setup-bun
+    #         - name: Install dependencies
+    #           run: bun install --frozen-lockfile
+    #           env:
+    #               PUPPETEER_SKIP_DOWNLOAD: 1
+    #         - name: Run tests
+    #           run: cd ./packages/gitbook && bun e2e-browserless
+    #           env:
+    #               BASE_URL: ${{needs.deploy-v2-cloudflare.outputs.deployment-url}}
+    #               SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/

package.json

@@ -16,7 +16,7 @@
     },
     "private": true,
     "scripts": {
-        "dev": "turbo run dev",
+        "dev": "turbo run dev --concurrency 20",
         "build": "turbo run build",
         "clean-deps": "rm -rf node_modules && rm -rf packages/*/node_modules",
         "typecheck": "turbo run typecheck",
@@ -34,7 +34,7 @@
     "workspaces": {
         "packages": ["packages/*"],
         "catalog": {
-            "@gitbook/api": "^0.140.0",
+            "@gitbook/api": "0.143.2",
             "bidc": "^0.0.2"
         }
     },

packages/expr/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @gitbook/expr
 
+## 1.2.0
+
+### Minor Changes
+
+- 6da3655: Fix exports in gitbook/expr package.json
+
+## 1.1.1
+
+### Patch Changes
+
+- 3548fa6: Fix eval-estree-expr named import
+
 ## 1.1.0
 
 ### Minor Changes

packages/expr/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@gitbook/expr",
     "description": "Safely evaluate & parse user-defined GitBook expressions.",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "type": "module",
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "development": "./src/index.ts",
+            "import": "./dist/index.js",
             "default": "./dist/index.js"
         }
     },
@@ -31,7 +31,8 @@
         "build": "tsdown --project tsconfig.build.json",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
-        "clean": "rm -rf ./dist"
+        "clean": "rm -rf ./dist",
+        "dev": "bun run build -- --watch"
     },
     "files": ["dist", "README.md", "CHANGELOG.md"]
 }

packages/expr/src/runtime.ts

@@ -10,7 +10,8 @@ import {
 } from 'acorn';
 import { parse as parseLoose } from 'acorn-loose';
 import escodegen from 'escodegen';
-import { evaluate } from 'eval-estree-expression';
+import evalESTreeExpr from 'eval-estree-expression';
+const { evaluate } = evalESTreeExpr;
 
 import { AutoComplete } from './autocomplete';
 import { ExpressionError } from './errors';

packages/gitbook/CHANGELOG.md

@@ -1,5 +1,24 @@
 # gitbook
 
+## 0.18.0
+
+### Minor Changes
+
+- 262afa3: Expose a MCP server for the docs site under /~gitbook/mcp
+
+### Patch Changes
+
+- Updated dependencies [262afa3]
+  - @gitbook/icons@0.3.1
+  - @gitbook/react-openapi@1.4.3
+  - @gitbook/react-contentkit@0.7.5
+
+## 0.17.2
+
+### Patch Changes
+
+- @gitbook/react-openapi@1.4.2
+
 ## 0.17.1
 
 ### Patch Changes

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/e2e/util.ts

@@ -336,6 +336,7 @@ export function getCustomizationURL(partial: DeepPartial<SiteCustomizationSettin
         pageActions: {
             externalAI: true,
             markdown: true,
+            mcp: true,
         },
         trademark: {
             enabled: true,

packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc

@@ -17,7 +17,8 @@
         "dev": {
             "vars": {
                 "STAGE": "dev",
-                "OPEN_NEXT_REQUEST_ID_HEADER": "true"
+                "OPEN_NEXT_REQUEST_ID_HEADER": "true",
+                "GITBOOK_URL": "http://localhost:8771"
             },
             "r2_buckets": [
                 {

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

@@ -1,9 +1,10 @@
 {
     "name": "gitbook",
-    "version": "0.17.1",
+    "version": "0.18.0",
     "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,7 +49,8 @@
         "memoizee": "^0.4.17",
         "micromark-extension-frontmatter": "^2.0.0",
         "micromark-extension-gfm": "^3.0.0",
-        "next": "15.3.5",
+        "motion": "^12.23.12",
+        "next": "15.4.0",
         "next-themes": "^0.2.1",
         "nuqs": "^2.2.3",
         "object-hash": "^3.0.0",
@@ -71,6 +75,7 @@
         "url-join": "^5.0.0",
         "usehooks-ts": "^3.1.0",
         "warn-once": "^0.1.1",
+        "zod": "^3",
         "zustand": "^5.0.3"
     },
     "devDependencies": {
@@ -84,7 +89,6 @@
         "@types/node": "^20",
         "@types/object-hash": "^3.0.6",
         "@types/parse-cache-control": "^1.0.4",
-        "@types/psi": "^4.1.6",
         "@types/react": "18.3.13",
         "@types/react-dom": "18.3.1",
         "@types/rison": "^0.0.9",
@@ -92,7 +96,6 @@
         "env-cmd": "^10.1.0",
         "jsonwebtoken": "^9.0.2",
         "postcss": "^8",
-        "psi": "^4.1.0",
         "stylelint": "^16.16.0",
         "tailwindcss": "^4.1.11",
         "ts-essentials": "^10.0.1",
@@ -113,6 +116,7 @@
         "e2e": "playwright test e2e/internal.spec.ts e2e/pdf.spec.ts --project=chromium",
         "e2e-customers": "playwright test e2e/customers.spec.ts --project=chromium",
         "unit": "bun test {src,packages} --preload ./tests/preload-bun.ts",
+        "e2e-browserless": "bun test ./tests/",
         "typecheck": "tsc --noEmit"
     },
     "browserslist": [

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/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/mcp/route.ts

@@ -0,0 +1,92 @@
+import { type RouteLayoutParams, getStaticSiteContext } from '@/app/utils';
+import { throwIfDataError } from '@/lib/data';
+import { joinPathWithBaseURL } from '@/lib/paths';
+import { findSiteSpaceBy } from '@/lib/sites';
+import { createMcpHandler } from 'mcp-handler';
+import type { NextRequest } from 'next/server';
+import { z } from 'zod';
+
+async function handler(
+    nextRequest: NextRequest,
+    { params }: { params: Promise<RouteLayoutParams> }
+) {
+    const { context } = await getStaticSiteContext(await params);
+    const { dataFetcher, linker, site } = context;
+
+    const mcpHandler = createMcpHandler(
+        (server) => {
+            server.tool(
+                'searchDocumentation',
+                `Search across the documentation to find relevant information, code examples, API references, and guides. Use this tool when you need to answer questions about ${site.title}, find specific documentation, understand how features work, or locate implementation details. The search returns contextual content with titles and direct links to the documentation pages.`,
+                {
+                    query: z.string(),
+                },
+                async ({ query }) => {
+                    const results = await throwIfDataError(
+                        dataFetcher.searchSiteContent({
+                            organizationId: context.organizationId,
+                            siteId: site.id,
+                            query,
+                            scope: { mode: 'all' },
+                        })
+                    );
+
+                    return {
+                        content: results.flatMap((spaceResult) => {
+                            const found = findSiteSpaceBy(
+                                context.structure,
+                                (siteSpace) => siteSpace.space.id === spaceResult.id
+                            );
+                            const spaceURL = found?.siteSpace.urls.published;
+                            if (!spaceURL) {
+                                return [];
+                            }
+
+                            return spaceResult.pages.map((pageResult) => {
+                                const pageURL = linker.toAbsoluteURL(
+                                    linker.toLinkForContent(
+                                        joinPathWithBaseURL(spaceURL, pageResult.path)
+                                    )
+                                );
+
+                                const body = pageResult.sections
+                                    ?.map((section) => section.body)
+                                    .join('\n');
+
+                                return {
+                                    type: 'text',
+                                    text: [
+                                        `Title: ${pageResult.title}`,
+                                        `Link: ${pageURL}`,
+                                        body ? `Content: ${body}` : '',
+                                    ]
+                                        .filter(Boolean)
+                                        .join('\n'),
+                                };
+                            });
+                        }),
+                    };
+                }
+            );
+        },
+        {},
+        {
+            basePath: context.linker.toPathInSite('~gitbook/'),
+            streamableHttpEndpoint: '/mcp',
+            maxDuration: 60,
+            verboseLogs: true,
+            disableSse: true,
+        }
+    );
+
+    // Next.js request.url is the original URL and not the rewritten one from the middleware
+    const requestURL = new URL(
+        context.linker.toAbsoluteURL(context.linker.toPathInSite('~gitbook/mcp'))
+    );
+    requestURL.search = nextRequest.nextUrl.search;
+
+    const request = new Request(requestURL, nextRequest);
+    return mcpHandler(request);
+}
+
+export { handler as GET, handler as POST };

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/AIChatButton.tsx

@@ -1,7 +1,6 @@
 'use client';
 import { useLanguage } from '@/intl/client';
 import { t } from '@/intl/translate';
-import { tcls } from '@/lib/tailwind';
 import type { Assistant } from '../AI';
 import { Button } from '../primitives';
 import { KeyboardShortcut } from '../primitives/KeyboardShortcut';
@@ -24,7 +23,7 @@ export function AIChatButton(props: {
             iconOnly={!showLabel}
             size="medium"
             variant="header"
-            className={tcls('h-9 px-2.5')}
+            className="h-9 px-2.5 max-md:[&_.button-content]:hidden"
             label={
                 <div className="flex items-center gap-2">
                     {t(language, 'ai_chat_ask', assistant.label)}
@@ -38,7 +37,7 @@ export function AIChatButton(props: {
             }
             onClick={() => assistant.open()}
         >
-            {showLabel ? <span className="max-md:hidden">{t(language, 'ask')}</span> : null}
+            {showLabel ? t(language, 'ask') : null}
         </Button>
     );
 }

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,306 @@
+'use client';
+import { Icon } from '@gitbook/icons';
+import { MotionConfig } from 'motion/react';
+import { useCheckForContentUpdate } from '../AutoRefreshContent';
+import { useVisitorSession } from '../Insights';
+import { useCurrentPagePath } from '../hooks';
+import { DateRelative } from '../primitives';
+import { IframeWrapper } from './IframeWrapper';
+import { RefreshContentButton } from './RefreshContentButton';
+import {
+    Toolbar,
+    ToolbarBody,
+    ToolbarButton,
+    ToolbarButtonGroup,
+    type ToolbarButtonProps,
+    ToolbarSeparator,
+    ToolbarSubtitle,
+    ToolbarTitle,
+} from './Toolbar';
+import type { AdminToolbarClientProps } from './types';
+
+export function AdminToolbarClient(props: AdminToolbarClientProps) {
+    const { context } = props;
+    const visitorSession = useVisitorSession();
+
+    // If there is a change request, show the change request toolbar
+    if (context.changeRequest) {
+        return (
+            <IframeWrapper>
+                <MotionConfig reducedMotion="user">
+                    <ChangeRequestToolbar context={context} />
+                </MotionConfig>
+            </IframeWrapper>
+        );
+    }
+
+    // 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 (
+            <IframeWrapper>
+                <MotionConfig reducedMotion="user">
+                    <RevisionToolbar context={context} />
+                </MotionConfig>
+            </IframeWrapper>
+        );
+    }
+
+    // If the user is authenticated and part of the organization owning this site, show the authenticated user toolbar
+    if (visitorSession?.organizationId === context.organizationId) {
+        return (
+            <IframeWrapper>
+                <MotionConfig reducedMotion="user">
+                    <AuthenticatedUserToolbar context={context} />
+                </MotionConfig>
+            </IframeWrapper>
+        );
+    }
+}
+
+function ChangeRequestToolbar(props: AdminToolbarClientProps) {
+    const { context } = 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 label="Site preview">
+            <ToolbarBody>
+                <ToolbarTitle
+                    prefix="Change request"
+                    suffix={`#${changeRequest.number} ${changeRequest.subject || 'Untitled'}`}
+                />
+                <ToolbarSubtitle
+                    subtitle={
+                        <>
+                            <DateRelative value={changeRequest.updatedAt} /> by {author}
+                        </>
+                    }
+                />
+            </ToolbarBody>
+
+            <ToolbarSeparator />
+
+            <ToolbarButtonGroup>
+                {/* Refresh to retrieve latest changes */}
+                {updated ? <RefreshContentButton refreshForUpdates={refreshForUpdates} /> : null}
+                {/* 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"
+                />
+
+                {/* Edit in GitBook */}
+                <EditPageButton href={changeRequest.urls.app} siteId={site.id} />
+            </ToolbarButtonGroup>
+        </Toolbar>
+    );
+}
+
+function RevisionToolbar(props: AdminToolbarClientProps) {
+    const { context } = 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 label="Site preview">
+            <ToolbarBody>
+                <ToolbarTitle prefix="Site version" suffix={context.site.title} />
+                <ToolbarSubtitle
+                    subtitle={
+                        <>
+                            Created <DateRelative value={revision.createdAt} />
+                        </>
+                    }
+                />
+            </ToolbarBody>
+            <ToolbarSeparator />
+            <ToolbarButtonGroup>
+                {/* 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"
+                />
+            </ToolbarButtonGroup>
+        </Toolbar>
+    );
+}
+
+function AuthenticatedUserToolbar(props: AdminToolbarClientProps) {
+    const { context } = props;
+    const { revision, space, site } = context;
+    const { refreshForUpdates, updated } = useCheckForContentUpdate({
+        revisionId: space.revision,
+    });
+
+    return (
+        <Toolbar label="Only visible to your GitBook organization">
+            <ToolbarBody>
+                <ToolbarTitle prefix="Site" suffix={context.site.title} />
+                <ToolbarSubtitle
+                    subtitle={
+                        <>
+                            Updated <DateRelative value={revision.createdAt} />
+                        </>
+                    }
+                />
+            </ToolbarBody>
+            <ToolbarSeparator />
+            <ToolbarButtonGroup>
+                {/* Refresh to retrieve latest changes */}
+                {updated ? <RefreshContentButton refreshForUpdates={refreshForUpdates} /> : null}
+                <ToolbarButton
+                    title="Open site in GitBook"
+                    href={getToolbarHref({
+                        href: site.urls.app,
+                        siteId: site.id,
+                        buttonId: 'site',
+                    })}
+                    icon="gear"
+                />
+                <ToolbarButton
+                    title="Customize in GitBook"
+                    href={getToolbarHref({
+                        href: `${site.urls.app}/customization/general`,
+                        siteId: site.id,
+                        buttonId: 'customize',
+                    })}
+                    icon="palette"
+                />
+                <ToolbarButton
+                    title="Open insights in GitBook"
+                    href={getToolbarHref({
+                        href: `${site.urls.app}/insights`,
+                        siteId: site.id,
+                        buttonId: 'insights',
+                    })}
+                    icon="chart-simple"
+                />
+                <EditPageButton href={space.urls.app} siteId={site.id} />
+            </ToolbarButtonGroup>
+        </Toolbar>
+    );
+}
+
+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-100);
+  --seg-A-color: #2782c4;
+  --seg-B-color: #43b7f2;
+  --seg-C-color: #8be2ff;
+  --trace-color: #46474c;
+
+
+  --T: 2s;
+  shape-rendering: geometricPrecision;
+  vector-effect: non-scaling-stroke;
+}
+
+:global(html.dark) .svgLogo {
+  --logo-fill: var(--color-neutral-800);
+  --trace-color: #dedfe3;
+}
+
+/* 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/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.tsx

@@ -1,65 +1,298 @@
 'use client';
-
-import type * as React from 'react';
+import { AnimatePresence, type MotionValue, motion, useReducedMotion } from 'motion/react';
+import React from 'react';
+import { AnimatedLogo } from './AnimatedLogo';
 
 import { tcls } from '@/lib/tailwind';
+import { Icon, type IconName } from '@gitbook/icons';
+import { Tooltip } from '../primitives';
+import { getCopyVariants, minifyButtonAnimation, 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;
+    label: React.ReactNode;
+}
+
+export function Toolbar(props: ToolbarProps) {
+    const { children, label } = props;
+    const [minified, setMinified] = React.useState(true);
+    const [showToolbarControls, setShowToolbarControls] = React.useState(false);
+    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) {
+            const expandAfterTimeout = setTimeout(() => {
+                setMinified(false);
+            }, DURATION_LOGO_APPEARANCE + DELAY_BETWEEN_LOGO_AND_CONTENT);
+
+            return () => clearTimeout(expandAfterTimeout);
+        }
+    }, [isReady]);
+
+    // 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>
+        <Tooltip label={label}>
+            <motion.div
+                onMouseEnter={() => setShowToolbarControls(true)}
+                onMouseLeave={() => setShowToolbarControls(false)}
+                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) {
+                                setMinified((prev) => !prev);
+                            }
+                        }}
+                        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',
+                            'border-tint-1/3',
+                            'backdrop-blur-sm',
+                            'origin-center',
+                            'bg-[linear-gradient(110deg,rgba(20,23,28,0.90)_0%,rgba(20,23,28,0.80)_100%)]',
+                            'dark:bg-[linear-gradient(110deg,rgba(256,256,256,0.90)_0%,rgba(256,256,256,0.80)_100%)]'
+                        )}
+                        initial={{
+                            scale: 1,
+                            opacity: 1,
+                        }}
+                        animate={{
+                            scale: 1,
+                            opacity: 1,
+                            boxShadow: minified
+                                ? '0 4px 40px 8px rgba(0, 0, 0, .2), 0 0 0 .5px rgba(0, 0, 0, .4), inset 0 .5px 0 0 hsla(0, 0%, 100%, .15)'
+                                : '0 4px 40px 8px rgba(0, 0, 0, .4), 0 0 0 .5px rgba(0, 0, 0, .8), inset 0 .5px 0 0 hsla(0, 0%, 100%, .3)',
+                        }}
+                        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}
+
+                        {!minified && showToolbarControls && (
+                            <MinifyButton setMinified={setMinified} />
+                        )}
+                    </motion.div>
+                </AnimatePresence>
+            </motion.div>
+        </Tooltip>
     );
 }
 
 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 motionValues = buttonMotionValues[index];
+                const childEl = child as React.ReactElement;
+                return React.cloneElement(childEl, {
+                    key: index,
+                    motionValues,
+                });
+            })}
+        </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;
+}
+
+export function ToolbarButton(props: ToolbarButtonProps) {
+    const { title, disabled, motionValues, className, style, href, onClick, icon, iconClassName } =
+        props;
+    const reduceMotion = useReducedMotion();
+
+    return (
+        <motion.div variants={toolbarEasings.staggeringChild}>
+            <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,
+                              }
+                    }
+                    transition={{
+                        type: 'spring',
+                        stiffness: 400,
+                        damping: 30,
+                    }}
+                    className={tcls(
+                        'toolbar-button',
+                        className,
+                        'flex',
+                        'relative',
+                        'items-center',
+                        'justify-center',
+                        'gap-1',
+                        'text-sm',
+                        'rounded-full',
+                        'border-neutral-500',
+                        'outline-neutral-800',
+                        'outline-1',
+                        'border',
+                        'truncate',
+                        'text-tint-1',
+                        'dark:text-tint-12',
+                        'cursor-pointer',
+                        'transition-colors',
+                        'size-8',
+                        'bg-tint-1/3',
+                        'hover:bg-tint-1/4',
+                        'dark:bg-tint-3',
+                        'dark:hover:bg-tint-1',
+                        disabled ? 'cursor-not-allowed opacity-50' : '',
+                        'shadow-1xs'
+                    )}
+                >
+                    <Icon icon={icon} className={tcls('size-4', iconClassName)} />
+                </motion.a>
+            </Tooltip>
+        </motion.div>
+    );
+}
+
+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 ">
+            <ToolbarTitlePrefix title={props.prefix} />
+            <ToolbarTitleSuffix title={props.suffix} />
+        </div>
+    );
+}
+
+function ToolbarTitlePrefix(props: { title: string }) {
+    return (
+        <motion.span
+            {...getCopyVariants(0)}
+            className="font-light text-neutral-7 dark:text-neutral-3"
+        >
+            {props.title}
+        </motion.span>
+    );
+}
+
+function ToolbarTitleSuffix(props: { title: string }) {
+    return (
+        <motion.span
+            {...getCopyVariants(1)}
+            className="max-w-[24ch] truncate font-semibold text-neutral-3 dark:text-neutral-2"
+        >
+            {props.title}
+        </motion.span>
+    );
+}
+
+export function ToolbarSubtitle(props: { subtitle: React.ReactNode }) {
+    return (
+        <motion.span
+            {...getCopyVariants(1)}
+            className="text-neutral-7 text-xxs dark:text-neutral-2"
+        >
+            {props.subtitle}
+        </motion.span>
+    );
+}
+
+function MinifyButton(props: { setMinified: (minified: boolean) => void }) {
+    return (
+        <Tooltip label="Minify">
+            <motion.div
+                {...minifyButtonAnimation}
+                transition={{
+                    duration: 0.2,
+                }}
+                whileHover={{
+                    scale: 1.05,
+                }}
+                onClick={(e) => {
+                    e.stopPropagation();
+                    props.setMinified(true);
+                }}
+                className={tcls(
+                    '-top-2 -right-4 absolute flex size-4 cursor-pointer items-center justify-center rounded-full border',
+                    'border-neutral-500 bg-neutral-700 hover:border-neutral-400 hover:bg-neutral-600',
+                    'dark:border-neutral-400 dark:bg-neutral-200 dark:hover:border-neutral-200 dark:hover:bg-neutral-100'
+                )}
+            >
+                <Icon icon="minus" className="size-2 text-neutral-1 dark:text-neutral-9" />
+            </motion.div>
+        </Tooltip>
     );
 }

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,57 @@
+/*
+ * 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;
+}

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

@@ -0,0 +1,258 @@
+import { type MotionValue, motionValue } from 'framer-motion';
+import React from 'react';
+
+interface ButtonMotionValues {
+    scale: MotionValue<number>;
+    x: MotionValue<number>;
+}
+
+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
+};
+
+// Helper functions for cleaner code
+const createMotionValues = (count: number): ButtonMotionValues[] =>
+    Array.from({ length: count }, () => ({
+        scale: motionValue(1),
+        x: motionValue(0),
+    }));
+
+const resetMotionValues = (motionValues: ButtonMotionValues[]) => {
+    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,
+    mouseY: number,
+    buttonCenterX: number,
+    buttonCenterY: number,
+    containerRect: DOMRect,
+    config: Required<MagnificationConfig>
+) => {
+    // Calculate 2D distance from mouse to button center
+    const deltaX = mouseX - buttonCenterX;
+    const deltaY = mouseY - buttonCenterY;
+    const distance = Math.sqrt(deltaX * deltaX + deltaY * deltaY);
+
+    if (distance > config.influenceRadius) return 1;
+
+    // Calculate distance from container edge
+    const distanceFromEdgeX = Math.min(mouseX - containerRect.left, containerRect.right - mouseX);
+    const distanceFromEdgeY = Math.min(mouseY - containerRect.top, containerRect.bottom - mouseY);
+    const distanceFromEdge = Math.min(distanceFromEdgeX, distanceFromEdgeY);
+
+    // 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 [buttonMotionValues, setButtonMotionValues] = React.useState<ButtonMotionValues[]>([]);
+    const originalPositionsRef = React.useRef<
+        Array<{ left: number; width: number; top: number; height: number }>
+    >([]);
+
+    const finalConfig = React.useMemo(() => ({ ...defaultConfig, ...config }), [config]);
+
+    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;
+        }
+
+        // Initialize motion values if button count changed
+        if (buttonMotionValues.length !== buttons.length) {
+            setButtonMotionValues(createMotionValues(buttons.length));
+        }
+
+        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 buttonCenterY = pos.top + pos.height / 2;
+                const scale = calculateScale(
+                    mouseX,
+                    mouseY,
+                    buttonCenterX,
+                    buttonCenterY,
+                    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
+            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/Blocks.tsx

@@ -89,7 +89,7 @@ export function UnwrappedBlocks<TBlock extends DocumentBlock>(props: UnwrappedBl
                     node.data && 'fullWidth' in node.data && node.data.fullWidth
                         ? 'max-w-screen-xl'
                         : 'max-w-3xl',
-                    FULL_WIDTH_BLOCKS.includes(node.type) && 'page-width-wide:max-w-screen-2xl',
+                    FULL_WIDTH_BLOCKS.includes(node.type) && 'page-width-wide:max-w-full',
                     blockStyle,
                 ]}
                 isEstimatedOffscreen={isOffscreen}

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

@@ -24,6 +24,7 @@ export function Caption(
         wrapperStyle?: ClassValue;
         block: DocumentBlockImage | DocumentBlockDrawing | DocumentBlockEmbed | DocumentBlockFile;
         withBorder?: boolean;
+        withFrame?: boolean;
     } & DocumentContextProps
 ) {
     const {
@@ -33,6 +34,7 @@ export function Caption(
         context,
         fit = false,
         withBorder = false,
+        withFrame = false,
         wrapperStyle = [
             'relative',
             'overflow-hidden',
@@ -44,6 +46,7 @@ export function Caption(
             withBorder
                 ? 'rounded-corners:rounded-sm circular-corners:rounded-2xl after:border-tint-subtle after:border after:rounded circular-corners:after:rounded-2xl rounded-corners:after:rounded-sm dark:after:mix-blend-plus-lighter after:pointer-events-none'
                 : null,
+            withFrame && 'p-2',
         ],
         style,
     } = props;
@@ -62,7 +65,14 @@ export function Caption(
     return (
         <picture className={tcls('relative', style)}>
             <div className={tcls(wrapperStyle, 'mx-auto')}>{children}</div>
-            <figcaption className={tcls('text-sm', 'text-center', 'mt-2', 'text-tint')}>
+            <figcaption
+                className={tcls(
+                    'text-xs',
+                    'text-center',
+                    'text-tint',
+                    withFrame ? 'mt-0.5 mb-2.5' : 'mt-2'
+                )}
+            >
                 <Inlines
                     nodes={captionParagraph.nodes}
                     document={document}

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/PlainCodeBlock.tsx

@@ -1,7 +1,8 @@
-import type { DocumentBlockCode, JSONDocument } from '@gitbook/api';
+import type { JSONDocument } from '@gitbook/api';
 import { useId } from 'react';
 
 import { CodeBlock } from './CodeBlock';
+import { convertCodeStringToBlock } from './utils';
 
 /**
  * Plain code block with syntax highlighting.
@@ -11,31 +12,7 @@ export function PlainCodeBlock(props: { code: string; syntax: string }) {
     const { code, syntax } = props;
     const id = useId();
 
-    const block: DocumentBlockCode = {
-        key: id,
-        object: 'block',
-        type: 'code',
-        data: {
-            syntax,
-        },
-        nodes: code.split('\n').map((line) => ({
-            object: 'block',
-            type: 'code-line',
-            data: {},
-            nodes: [
-                {
-                    object: 'text',
-                    leaves: [
-                        {
-                            object: 'leaf',
-                            text: line,
-                            marks: [],
-                        },
-                    ],
-                },
-            ],
-        })),
-    };
+    const block = convertCodeStringToBlock({ key: id, code, syntax });
 
     const document: JSONDocument = {
         object: 'document',

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/CodeBlock/utils.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, it } from 'bun:test';
+import { convertCodeStringToBlock } from './utils';
+
+describe('convertCodeStringToBlock', () => {
+    it('converts plain code string without placeholders', () => {
+        const result = convertCodeStringToBlock({
+            key: 'test1',
+            code: 'console.log("hello");',
+            syntax: 'javascript',
+        });
+
+        expect(result).toEqual({
+            key: 'test1',
+            object: 'block',
+            type: 'code',
+            data: { syntax: 'javascript' },
+            nodes: [
+                {
+                    object: 'block',
+                    type: 'code-line',
+                    data: {},
+                    nodes: [
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: 'console.log("hello");', marks: [] }],
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+
+    it('converts a single placeholder into an expression node', () => {
+        const result = convertCodeStringToBlock({
+            key: 'test2',
+            code: 'const config = { API_KEY: "$$__X-GITBOOK-PREFILL[visitor.claims.apiKey ?? "YOUR_API_KEY"]__$$" }',
+            syntax: 'javascript',
+        });
+
+        expect(result).toEqual({
+            key: 'test2',
+            object: 'block',
+            type: 'code',
+            data: { syntax: 'javascript' },
+            nodes: [
+                {
+                    object: 'block',
+                    type: 'code-line',
+                    data: {},
+                    nodes: [
+                        {
+                            object: 'text',
+                            leaves: [
+                                { object: 'leaf', text: 'const config = { API_KEY: "', marks: [] },
+                            ],
+                        },
+                        {
+                            object: 'inline',
+                            type: 'expression',
+                            data: { expression: 'visitor.claims.apiKey ?? "YOUR_API_KEY"' },
+                            isVoid: true,
+                        },
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: '" }', marks: [] }],
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+
+    it('handles multiple placeholders in one line', () => {
+        const result = convertCodeStringToBlock({
+            key: 'test3',
+            code: 'let a = $$__X-GITBOOK-PREFILL[valA]__$$, b = $$__X-GITBOOK-PREFILL[valB]__$$;',
+            syntax: 'javascript',
+        });
+
+        expect(result).toEqual({
+            key: 'test3',
+            object: 'block',
+            type: 'code',
+            data: { syntax: 'javascript' },
+            nodes: [
+                {
+                    object: 'block',
+                    type: 'code-line',
+                    data: {},
+                    nodes: [
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: 'let a = ', marks: [] }],
+                        },
+                        {
+                            object: 'inline',
+                            type: 'expression',
+                            data: { expression: 'valA' },
+                            isVoid: true,
+                        },
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: ', b = ', marks: [] }],
+                        },
+                        {
+                            object: 'inline',
+                            type: 'expression',
+                            data: { expression: 'valB' },
+                            isVoid: true,
+                        },
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: ';', marks: [] }],
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+
+    it('handles multiple placeholders across different lines', () => {
+        const result = convertCodeStringToBlock({
+            key: 'test4',
+            code: [
+                'const name = "$$__X-GITBOOK-PREFILL[visitor.claims.userName]__$$";',
+                'const age = $$__X-GITBOOK-PREFILL[visitor.claims.userAge]__$$;',
+                'console.log(name, age);',
+            ].join('\n'),
+            syntax: 'javascript',
+        });
+
+        expect(result).toEqual({
+            key: 'test4',
+            object: 'block',
+            type: 'code',
+            data: { syntax: 'javascript' },
+            nodes: [
+                {
+                    object: 'block',
+                    type: 'code-line',
+                    data: {},
+                    nodes: [
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: 'const name = "', marks: [] }],
+                        },
+                        {
+                            object: 'inline',
+                            type: 'expression',
+                            data: { expression: 'visitor.claims.userName' },
+                            isVoid: true,
+                        },
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: '";', marks: [] }],
+                        },
+                    ],
+                },
+                {
+                    object: 'block',
+                    type: 'code-line',
+                    data: {},
+                    nodes: [
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: 'const age = ', marks: [] }],
+                        },
+                        {
+                            object: 'inline',
+                            type: 'expression',
+                            data: { expression: 'visitor.claims.userAge' },
+                            isVoid: true,
+                        },
+                        {
+                            object: 'text',
+                            leaves: [{ object: 'leaf', text: ';', marks: [] }],
+                        },
+                    ],
+                },
+                {
+                    object: 'block',
+                    type: 'code-line',
+                    data: {},
+                    nodes: [
+                        {
+                            object: 'text',
+                            leaves: [
+                                { object: 'leaf', text: 'console.log(name, age);', marks: [] },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        });
+    });
+
+    it('returns an empty code block for empty string', () => {
+        const result = convertCodeStringToBlock({
+            key: 'test5',
+            code: '',
+            syntax: 'javascript',
+        });
+
+        expect(result).toEqual({
+            key: 'test5',
+            object: 'block',
+            type: 'code',
+            data: { syntax: 'javascript' },
+            nodes: [
+                {
+                    object: 'block',
+                    type: 'code-line',
+                    data: {},
+                    nodes: [],
+                },
+            ],
+        });
+    });
+});

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

@@ -0,0 +1,67 @@
+import type { DocumentBlockCode, DocumentBlockCodeLine } from '@gitbook/api';
+
+const PREFILL_WITH_EXPR_REGEX = /\$\$__X-GITBOOK-PREFILL\[(.+?)\]__\$\$/g;
+
+/**
+ * Convert a raw code string into a `DocumentBlockCode` object representation.
+ *
+ * Any placeholder of the form `$$__X-GITBOOK-PREFILL[<expression>]__$$` inside the code
+ * string is transformed into a DocumentInlineExpression node with its `data.expression` set to the
+ * extracted `<expression>`.
+ */
+export function convertCodeStringToBlock(args: {
+    key: string;
+    code: string;
+    syntax: string;
+}): DocumentBlockCode {
+    const { key, code, syntax } = args;
+    const lines = code.split('\n').map<DocumentBlockCodeLine>((line) => {
+        const nodes: DocumentBlockCodeLine['nodes'] = [];
+        let lastIndex = 0;
+
+        for (const match of line.matchAll(PREFILL_WITH_EXPR_REGEX)) {
+            const [placeholder, expression] = match;
+            const start = match.index ?? 0;
+
+            if (start > lastIndex) {
+                nodes.push({
+                    object: 'text',
+                    leaves: [{ object: 'leaf', text: line.slice(lastIndex, start), marks: [] }],
+                });
+            }
+
+            if (expression) {
+                nodes.push({
+                    object: 'inline',
+                    type: 'expression',
+                    data: { expression },
+                    isVoid: true,
+                });
+            }
+
+            lastIndex = start + placeholder.length;
+        }
+
+        if (lastIndex < line.length) {
+            nodes.push({
+                object: 'text',
+                leaves: [{ object: 'leaf', text: line.slice(lastIndex), marks: [] }],
+            });
+        }
+
+        return {
+            object: 'block',
+            type: 'code-line',
+            data: {},
+            nodes,
+        };
+    });
+
+    return {
+        key,
+        object: 'block',
+        type: 'code',
+        data: { syntax },
+        nodes: lines,
+    };
+}

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/Images.tsx

@@ -11,8 +11,8 @@ import type { DocumentContext } from './DocumentView';
 export function Images(props: BlockProps<DocumentBlockImages>) {
     const { document, block, style, context, isEstimatedOffscreen } = props;
 
-    const isMultipleImages = block.nodes.length > 1;
-    const { align = 'center' } = block.data;
+    const hasMultipleImages = block.nodes.length > 1;
+    const { align = 'center', withFrame } = block.data;
 
     return (
         <div
@@ -24,7 +24,15 @@ export function Images(props: BlockProps<DocumentBlockImages>) {
                 align === 'center' && 'justify-center',
                 align === 'right' && 'justify-end',
                 align === 'left' && 'justify-start',
-                isMultipleImages && ['grid', 'grid-flow-col']
+                hasMultipleImages && ['grid', 'grid-flow-col'],
+                withFrame && [
+                    'rounded-2xl',
+                    'border',
+                    'border-[rgb(234,235,238)]',
+                    'dark:border-[rgb(45,50,58)]',
+                    'relative',
+                    'overflow-hidden',
+                ]
             )}
         >
             {block.nodes.map((node: any, _i: number) => (
@@ -36,6 +44,7 @@ export function Images(props: BlockProps<DocumentBlockImages>) {
                     siblings={block.nodes.length}
                     context={context}
                     isEstimatedOffscreen={isEstimatedOffscreen}
+                    withFrame={withFrame}
                 />
             ))}
         </div>
@@ -62,8 +71,9 @@ async function ImageBlock(props: {
     context: DocumentContext;
     siblings: number;
     isEstimatedOffscreen: boolean;
+    withFrame?: boolean;
 }) {
-    const { block, context, isEstimatedOffscreen } = props;
+    const { block, context, isEstimatedOffscreen, withFrame } = props;
 
     const [src, darkSrc] = await Promise.all([
         context.contentContext ? resolveContentRef(block.data.ref, context.contentContext) : null,
@@ -77,33 +87,66 @@ async function ImageBlock(props: {
     }
 
     return (
-        <Caption {...props} fit>
-            <Image
-                alt={block.data.alt ?? ''}
-                sizes={imageBlockSizes}
-                resize={context.contentContext?.imageResizer}
-                sources={{
-                    light: {
-                        src: src.href,
-                        size: src.file?.dimensions,
-                    },
-                    dark: darkSrc
-                        ? {
-                              src: darkSrc.href,
-                              size: darkSrc.file?.dimensions,
-                          }
-                        : null,
-                }}
-                priority={isEstimatedOffscreen ? 'lazy' : 'high'}
-                preload
-                zoom
-                inlineStyle={{
-                    maxWidth: '100%',
-                    width: getImageDimension(block.data.width, undefined),
-                    height: getImageDimension(block.data.height, 'auto'),
-                }}
-            />
-        </Caption>
+        <div className={tcls('relative', 'overflow-hidden')}>
+            {/* Frame grid */}
+            {withFrame && (
+                <div
+                    className={tcls(
+                        'absolute',
+                        '-top-0.5',
+                        '-left-0.5',
+                        'right-px',
+                        'bottom-px',
+                        'opacity-40',
+                        'dark:opacity-[0.1]',
+                        'bg-[length:24px_24px,24px_24px]',
+                        'bg-[linear-gradient(to_right,_rgb(234,235,238)_1px,_transparent_1px),linear-gradient(to_bottom,_rgb(234,235,238)_1px,_transparent_1px)]',
+                        'dark:bg-[linear-gradient(to_right,_rgb(122,128,139)_1px,_transparent_1px),linear-gradient(to_bottom,_rgb(122,128,139)_1px,_transparent_1px)]',
+                        'bg-repeat'
+                    )}
+                />
+            )}
+
+            {/* Shadow overlay */}
+            {withFrame && (
+                <div
+                    className={tcls(
+                        'pointer-events-none absolute inset-0 rounded-2xl',
+                        'shadow-[inset_0_0_10px_10px_rgba(255,255,255,0.9)]',
+                        'dark:shadow-[inset_0_0_10px_10px_rgb(29,29,29)]'
+                    )}
+                />
+            )}
+
+            <Caption {...props} fit>
+                <Image
+                    alt={block.data.alt ?? ''}
+                    sizes={imageBlockSizes}
+                    resize={context.contentContext?.imageResizer}
+                    sources={{
+                        light: {
+                            src: src.href,
+                            size: src.file?.dimensions,
+                        },
+                        dark: darkSrc
+                            ? {
+                                  src: darkSrc.href,
+                                  size: darkSrc.file?.dimensions,
+                              }
+                            : null,
+                    }}
+                    priority={isEstimatedOffscreen ? 'lazy' : 'high'}
+                    preload
+                    zoom
+                    inlineStyle={{
+                        maxWidth: '100%',
+                        width: getImageDimension(block.data.width, undefined),
+                        height: getImageDimension(block.data.height, 'auto'),
+                    }}
+                    style={withFrame ? 'rounded-xl' : undefined}
+                />
+            </Caption>
+        </div>
     );
 }
 

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/InlineImage.tsx

@@ -34,7 +34,7 @@ export async function InlineImage(props: InlineProps<DocumentInlineImage>) {
             )}
         >
             <Image
-                alt={inline.data.caption ?? ''}
+                alt={inline.data.alt ?? inline.data.caption ?? ''}
                 sizes={sizes}
                 resize={context.contentContext?.imageResizer}
                 sources={{

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 {
@@ -192,7 +192,7 @@
 .openapi-schema-name {
     /* To make double click on the property name select only the name,
     we disable selection on the parent and re-enable it on the children. */
-    @apply select-none text-sm text-balance *:whitespace-nowrap flex flex-wrap gap-y-1.5 gap-x-2.5;
+    @apply select-none text-sm text-balance *:whitespace-nowrap flex flex-wrap gap-y-1.5 gap-x-2.5 items-center;
 }
 
 .openapi-schema-name .openapi-deprecated {
@@ -207,6 +207,10 @@
     @apply line-through opacity-9;
 }
 
+.openapi-schema-discriminator {
+    @apply text-primary-subtle/9 text-[0.813rem] lowercase;
+}
+
 .openapi-schema-required {
     @apply text-warning-subtle text-[0.813rem] lowercase;
 }
@@ -510,13 +514,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 +591,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 +625,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 +650,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;
 }
@@ -820,7 +840,7 @@ body:has(.openapi-select-popover) {
 }
 
 .openapi-disclosure-trigger-label {
-    @apply absolute right-3 px-2 h-5 justify-end shrink-0 ring-tint-subtle truncate text-tint duration-300 transition-all rounded straight-corners:rounded-none circular-corners:rounded-xl flex flex-row gap-1 items-center text-xs;
+    @apply absolute right-3 mr-px px-2 h-5 justify-end shrink-0 ring-tint-subtle truncate text-tint duration-300 transition-all rounded straight-corners:rounded-none circular-corners:rounded-xl flex flex-row gap-1 items-center text-xs;
 }
 
 .openapi-disclosure-trigger-label span {

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>
@@ -162,43 +178,21 @@ export function Header(props: {
                 </div>
             </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)}
+            {sections &&
+            (sections.list.length > 1 || // Show section tabs if there are at least 2 sections or at least 1 section group
+                sections.list.some((s) => s.object === 'site-section-group')) ? (
+                <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

@@ -8,7 +8,7 @@ import { useDebounceCallback, useEventCallback } from 'usehooks-ts';
 import { getAllBrowserCookiesMap } from '@/lib/browser';
 import { type CurrentContentContext, useCurrentContent } from '../hooks';
 import { getSession } from './sessions';
-import { getVisitorId } from './visitorId';
+import { type SessionResponse, useVisitorSession } from './visitorId';
 
 export type InsightsEventName = api.SiteInsightsEvent['type'];
 
@@ -55,12 +55,6 @@ interface InsightsProviderProps {
     /** If true, the events will be sent to the server. */
     enabled: boolean;
 
-    /** If true, the visitor cookie tracking will be used */
-    visitorCookieTrackingEnabled: boolean;
-
-    /** The application URL. */
-    appURL: string;
-
     /** The url of the endpoint to send events to */
     eventUrl: string;
 
@@ -72,10 +66,10 @@ interface InsightsProviderProps {
  * Wrap the content of the app with the InsightsProvider to track events.
  */
 export function InsightsProvider(props: InsightsProviderProps) {
-    const { enabled, children, visitorCookieTrackingEnabled, eventUrl, appURL } = props;
+    const { enabled, children, eventUrl } = props;
 
+    const visitorSession = useVisitorSession();
     const currentContent = useCurrentContent();
-    const visitorIdRef = React.useRef<string | null>(null);
     const eventsRef = React.useRef<{
         [pathname: string]:
             | {
@@ -92,9 +86,8 @@ export function InsightsProvider(props: InsightsProviderProps) {
      */
     const flushEventsSync = useEventCallback(() => {
         const session = getSession();
-        const visitorId = visitorIdRef.current;
-        if (!visitorId) {
-            throw new Error('Visitor ID should be set before flushing events');
+        if (!visitorSession) {
+            return;
         }
 
         const allEvents: api.SiteInsightsEvent[] = [];
@@ -114,7 +107,7 @@ export function InsightsProvider(props: InsightsProviderProps) {
                     events: eventsForPathname.events,
                     context: currentContent,
                     pageContext: eventsForPathname.pageContext,
-                    visitorId,
+                    visitorSession,
                     sessionId: session.id,
                 })
             );
@@ -126,25 +119,25 @@ 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,
+            });
         }
     });
 
-    const flushBatchedEvents = useDebounceCallback(async () => {
-        const visitorId =
-            visitorIdRef.current ?? (await getVisitorId(appURL, visitorCookieTrackingEnabled));
-        visitorIdRef.current = visitorId;
-
+    const flushBatchedEvents = useDebounceCallback(() => {
         flushEventsSync();
     }, 1500);
 
+    // Flush pending events once the visitor session has been fetched
+    React.useEffect(() => {
+        if (visitorSession) {
+            flushEventsSync();
+        }
+    }, [visitorSession, flushEventsSync]);
+
     const trackEvent: TrackEventCallback = useEventCallback(
         (
             event: TrackEventInput<InsightsEventName>,
@@ -169,7 +162,7 @@ export function InsightsProvider(props: InsightsProviderProps) {
             if (eventsRef.current[pathname].pageContext !== undefined) {
                 // If the pageId is set, we know that the page_view event has been tracked
                 // and we can flush the events
-                if (options?.immediate && visitorIdRef.current) {
+                if (options?.immediate) {
                     flushBatchedEvents.cancel();
                     flushEventsSync();
                 } else {
@@ -180,18 +173,14 @@ export function InsightsProvider(props: InsightsProviderProps) {
     );
 
     /**
-     * Get the visitor ID and store it in a ref.
+     * When the page is unloaded, flush all events.
      */
     React.useEffect(() => {
-        getVisitorId(appURL, visitorCookieTrackingEnabled).then((visitorId) => {
-            visitorIdRef.current = visitorId;
-            // When the page is unloaded, flush all events, but only if the visitor ID is set
-            window.addEventListener('beforeunload', flushEventsSync);
-        });
+        window.addEventListener('beforeunload', flushEventsSync);
         return () => {
             window.removeEventListener('beforeunload', flushEventsSync);
         };
-    }, [flushEventsSync, visitorCookieTrackingEnabled, appURL]);
+    }, [flushEventsSync]);
 
     return (
         <InsightsContext.Provider value={trackEvent}>
@@ -245,12 +234,12 @@ function transformEvents(input: {
     events: TrackEventInput<InsightsEventName>[];
     context: CurrentContentContext;
     pageContext: InsightsEventPageContext;
-    visitorId: string;
+    visitorSession: SessionResponse;
     sessionId: string;
 }): api.SiteInsightsEvent[] {
     const session: api.SiteInsightsEventSession = {
         sessionId: input.sessionId,
-        visitorId: input.visitorId,
+        visitorId: input.visitorSession.deviceId,
         userAgent: window.navigator.userAgent,
         language: window.navigator.language,
         cookies: getAllBrowserCookiesMap(),

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

@@ -1,73 +0,0 @@
-'use client';
-
-import { getBrowserCookie } from '@/lib/browser';
-
-import { isCookiesTrackingDisabled } from './cookies';
-import { generateRandomId } from './utils';
-
-const VISITORID_COOKIE = '__session';
-
-let visitorId: string | null = null;
-let pendingVisitorId: Promise<string> | null = null;
-
-/**
- * Return the current visitor identifier.
- */
-export async function getVisitorId(
-    appURL: string,
-    visitorCookieTrackingEnabled: boolean
-): Promise<string> {
-    if (!visitorId) {
-        if (!pendingVisitorId) {
-            pendingVisitorId = fetchVisitorID(appURL, visitorCookieTrackingEnabled).finally(() => {
-                pendingVisitorId = null;
-            });
-        }
-
-        visitorId = await pendingVisitorId;
-    }
-
-    return visitorId;
-}
-
-/**
- * Propose a visitor identifier to the GitBook.com server and get the devideId back.
- */
-async function fetchVisitorID(
-    appURL: string,
-    visitorCookieTrackingEnabled: boolean
-): Promise<string> {
-    const withoutCookies = isCookiesTrackingDisabled();
-
-    if (withoutCookies || !visitorCookieTrackingEnabled) {
-        return generateRandomId();
-    }
-
-    const existingTrackingCookie = getBrowserCookie(VISITORID_COOKIE);
-
-    if (existingTrackingCookie) {
-        // If the cookie already exists, we'll just use that. Avoids a server request.
-        return existingTrackingCookie;
-    }
-    // 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);
-
-    try {
-        const resp = await fetch(url, {
-            method: 'GET', // Use GET to play nicely with SameSite cookies.
-            credentials: 'include', // Make sure to send/receive cookies.
-            cache: 'no-cache',
-            mode: 'cors', // Need to use cors as we are on a different domain.
-        });
-
-        const { deviceId } = (await resp.json()) as { deviceId: string };
-        return deviceId;
-    } catch (error) {
-        console.error('Failed to fetch visitor session ID', error);
-        return proposed;
-    }
-}

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

@@ -0,0 +1,130 @@
+'use client';
+
+import { createStore, useStore } from 'zustand';
+
+import { getBrowserCookie } from '@/lib/browser';
+
+import React from 'react';
+import { isCookiesTrackingDisabled } from './cookies';
+import { generateRandomId } from './utils';
+
+const VISITORID_COOKIE = '__session';
+
+type SessionVisitorResponse = {
+    deviceId: string;
+    userId?: undefined;
+    organizationId?: undefined;
+};
+
+type SessionUserResponse = SessionVisitorResponse & {
+    userId: string;
+    organizationId: string;
+};
+
+export type SessionResponse = SessionVisitorResponse | SessionUserResponse;
+
+const visitorSessionStore = createStore<{
+    session: SessionResponse | null;
+    pendingSession: Promise<SessionResponse> | null;
+}>(() => ({
+    session: null,
+    pendingSession: null,
+}));
+
+/**
+ * Fetch, synchronize the visitor sesion with GitBook.
+ */
+export function VisitorSessionProvider(
+    props: React.PropsWithChildren<{
+        appURL: string;
+        visitorCookieTrackingEnabled: boolean;
+    }>
+) {
+    const { appURL, visitorCookieTrackingEnabled, children } = props;
+
+    React.useEffect(() => {
+        const state = visitorSessionStore.getState();
+        if (state.pendingSession || state.session) {
+            return;
+        }
+
+        const pendingSession = fetchSession({ appURL, visitorCookieTrackingEnabled });
+        visitorSessionStore.setState({ pendingSession, session: null });
+        pendingSession.then((session) => {
+            visitorSessionStore.setState({ pendingSession: null, session });
+        });
+    }, [appURL, visitorCookieTrackingEnabled]);
+
+    return <>{children}</>;
+}
+
+/**
+ * Hook to get the current visitor session.
+ */
+export function useVisitorSession() {
+    return useStore(visitorSessionStore, (state) => state.session);
+}
+
+/**
+ * Propose a visitor identifier to the GitBook.com server and get the devideId back.
+ */
+async function fetchSession({
+    appURL,
+    visitorCookieTrackingEnabled,
+}: {
+    appURL: string;
+    visitorCookieTrackingEnabled: boolean;
+}): Promise<SessionResponse> {
+    const withoutCookies = isCookiesTrackingDisabled();
+
+    if (withoutCookies || !visitorCookieTrackingEnabled) {
+        return {
+            deviceId: generateRandomId(),
+        };
+    }
+
+    const { existing, proposedId } = getSessionCookie();
+
+    if (existing) {
+        // If the cookie already exists, we'll just use that. Avoids a server request.
+        return existing;
+    }
+
+    const url = new URL(appURL);
+    url.pathname = '/__session/2/';
+    url.searchParams.set('proposed', proposedId);
+
+    try {
+        const resp = await fetch(url, {
+            method: 'GET', // Use GET to play nicely with SameSite cookies.
+            credentials: 'include', // Make sure to send/receive cookies.
+            cache: 'no-cache',
+            mode: 'cors', // Need to use cors as we are on a different domain.
+        });
+
+        const session = (await resp.json()) as SessionResponse;
+        return session;
+    } catch (error) {
+        console.error('Failed to fetch visitor session ID', error);
+        return {
+            deviceId: proposedId,
+        };
+    }
+}
+
+function getSessionCookie(): { existing: SessionResponse | null; proposedId: string } {
+    const proposed = generateRandomId();
+    const value = getBrowserCookie(VISITORID_COOKIE);
+    if (!(value && typeof value === 'string')) {
+        return { existing: null, proposedId: proposed };
+    }
+
+    try {
+        const parsed = JSON.parse(value) as SessionResponse;
+        return { existing: parsed, proposedId: proposed };
+    } catch {
+        // 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 };
+    }
+}