Version Packages (#3720)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

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

.github/workflows/publish.yaml

@@ -37,6 +37,7 @@ jobs:
                   # https://github.com/orgs/community/discussions/26875#discussioncomment-3253761
                   GITHUB_TOKEN: ${{ secrets.GH_PERSONAL_TOKEN }}
                   NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+                  NPM_CONFIG_TOKEN: ${{ secrets.NPM_TOKEN }}
                   CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
                   CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 

package.json

@@ -3,9 +3,9 @@
     "version": "0.1.0",
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
-        "@changesets/cli": "^2.27.12",
-        "turbo": "^2.5.0",
-        "vercel": "^39.3.0"
+        "@changesets/cli": "^2.29.7",
+        "turbo": "^2.5.8",
+        "vercel": "^39.4.2"
     },
     "packageManager": "bun@1.2.15",
     "overrides": {
@@ -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",
@@ -26,16 +26,18 @@
         "e2e": "turbo run e2e",
         "e2e-customers": "turbo run e2e-customers",
         "changeset": "changeset",
-        "changeset-version": "changeset version && bun run format",
-        "release": "turbo run release && changeset publish",
+        "changeset-version": "changeset version && bun run format && bun update",
+        "release": "turbo run release && bun run publish-all-packages",
+        "publish-all-packages": "for dir in packages/*; do (cd \"$dir\" && bun publish || true); done && changeset tag",
         "download:env": "op read op://gitbook-x-dev/gitbook-open/.env.local >> .env.local",
         "clean": "turbo run clean"
     },
     "workspaces": {
         "packages": ["packages/*"],
         "catalog": {
-            "@gitbook/api": "^0.140.0",
-            "bidc": "^0.0.2"
+            "@gitbook/api": "0.143.2",
+            "bidc": "^0.0.2",
+            "tsdown": "^0.15.6"
         }
     },
     "patchedDependencies": {

packages/browser-types/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @gitbook/browser-types
 
+## 0.1.1
+
+### Patch Changes
+
+- 295f03d: Republish packages
+- Updated dependencies [295f03d]
+  - @gitbook/icons@0.3.2
+
 ## 0.1.0
 
 ### Minor Changes

packages/browser-types/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.1.0",
+    "version": "0.1.1",
     "dependencies": {
         "@gitbook/api": "catalog:",
         "@gitbook/icons": "workspace:"
@@ -20,5 +20,9 @@
         "build": "tsc",
         "typecheck": "tsc --noEmit"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md"]
+    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    }
 }

packages/cache-tags/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @gitbook/cache-tags
 
+## 0.3.2
+
+### Patch Changes
+
+- 295f03d: Republish packages
+
 ## 0.3.1
 
 ### Patch Changes

packages/cache-tags/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.3.1",
+    "version": "0.3.2",
     "dependencies": {
         "@gitbook/api": "catalog:",
         "assert-never": "^1.2.1"
@@ -21,5 +21,9 @@
         "typecheck": "tsc --noEmit",
         "dev": "tsc -w"
     },
-    "files": ["dist", "src", "README.md", "CHANGELOG.md"]
+    "files": ["dist", "src", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    }
 }

packages/colors/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @gitbook/colors
 
+## 0.4.1
+
+### Patch Changes
+
+- 295f03d: Republish packages
+
 ## 0.4.0
 
 ### Minor Changes

packages/colors/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.4.0",
+    "version": "0.4.1",
     "devDependencies": {
         "typescript": "^5.5.3"
     },
@@ -17,5 +17,9 @@
         "typecheck": "tsc --noEmit",
         "dev": "tsc -w"
     },
-    "files": ["dist", "src", "README.md", "CHANGELOG.md"]
+    "files": ["dist", "src", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    }
 }

packages/embed/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @gitbook/embed
 
+## 0.1.3
+
+### Patch Changes
+
+- 295f03d: Republish packages
+- Updated dependencies [295f03d]
+  - @gitbook/icons@0.3.2
+
+## 0.1.2
+
+### Patch Changes
+
+- 7508674: Fix bundling of packages
+
 ## 0.1.1
 
 ### Patch Changes

packages/embed/package.json

@@ -5,12 +5,14 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "default": "./dist/index.js",
-            "standalone": "./dist/standalone/index.js",
-            "react": "./dist/react/index.js"
+            "default": "./dist/index.js"
+        },
+        "./react": {
+            "types": "./dist/react/index.d.ts",
+            "default": "./dist/react/index.js"
         }
     },
-    "version": "0.1.1",
+    "version": "0.1.3",
     "dependencies": {
         "@gitbook/api": "catalog:",
         "@gitbook/icons": "workspace:",
@@ -20,12 +22,21 @@
         "react": "^18.0.0"
     },
     "devDependencies": {
+        "tsdown": "catalog:",
         "typescript": "^5.5.3",
         "react": "^19.0.0"
     },
     "scripts": {
-        "build": "tsc && bun build src/standalone/index.ts --bundle --minify --outdir=standalone",
-        "typecheck": "tsc --noEmit"
+        "build": "bun run build-lib && bun run build-standalone",
+        "build-lib": "tsdown",
+        "build-standalone": "bun build src/standalone/index.ts --bundle --minify --outdir=standalone",
+        "clean": "rm -rf ./dist",
+        "typecheck": "tsc --noEmit",
+        "dev": "bun run build -- --watch ./src"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md", "standalone"]
+    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    }
 }

packages/embed/tsdown.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig([
+    {
+        entry: ['src/index.ts', 'src/react/index.ts'],
+        dts: true,
+        format: ['esm'],
+    },
+]);

packages/emoji-codepoints/CHANGELOG.md

@@ -1,13 +1,19 @@
 # @gitbook/emoji-codepoints
 
+## 0.2.1
+
+### Patch Changes
+
+- 295f03d: Republish packages
+
 ## 0.2.0
 
 ### Minor Changes
 
--   57adb3e: Second release to fix publishing with changeset
+- 57adb3e: Second release to fix publishing with changeset
 
 ## 0.1.0
 
 ### Minor Changes
 
--   5f8a8fe: Initial release
+- 5f8a8fe: Initial release

packages/emoji-codepoints/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@gitbook/emoji-codepoints",
     "description": "Optimized mapping of codepoints to the fully qualified emoji codepoints",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "private": true,
     "exports": "./dist/index.ts",
     "dependencies": {},
@@ -11,5 +11,9 @@
     "scripts": {
         "generate": "bun ./build.ts",
         "clean": "rm -rf ./dist"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
     }
 }

packages/expr/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @gitbook/expr
 
+## 1.2.2
+
+### Patch Changes
+
+- 295f03d: Republish packages
+
+## 1.2.1
+
+### Patch Changes
+
+- a629900: Add dev script for @gitbook/expr
+
+## 1.2.0
+
+### Minor Changes
+
+- 6da3655: Fix exports in gitbook/expr package.json
+
 ## 1.1.1
 
 ### Patch Changes

packages/expr/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@gitbook/expr",
     "description": "Safely evaluate & parse user-defined GitBook expressions.",
-    "version": "1.1.1",
+    "version": "1.2.2",
     "type": "module",
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "development": "./src/index.ts",
+            "import": "./dist/index.js",
             "default": "./dist/index.js"
         }
     },
@@ -21,17 +21,22 @@
     },
     "devDependencies": {
         "bun-types": "^1.1.20",
-        "tsdown": "^0.15.0",
+        "tsdown": "catalog:",
         "@types/estree": "^1.0.6",
         "@babel/types": "^7.26.0",
         "@types/json-schema": "^7.0.15",
         "@types/escodegen": "^0.0.10"
     },
     "scripts": {
-        "build": "tsdown --project tsconfig.build.json",
+        "build": "tsdown",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
-        "clean": "rm -rf ./dist"
+        "clean": "rm -rf ./dist",
+        "dev": "bun run build -- --watch ./src"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md"]
+    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    }
 }

packages/expr/tsconfig.build.json

@@ -1,10 +0,0 @@
-{
-    "$schema": "https://json.schemastore.org/tsconfig",
-    "extends": ["./tsconfig.json"],
-    "exclude": ["**/*.test.ts"],
-    "compilerOptions": {
-        "declaration": true,
-        "noEmit": false,
-        "outDir": "dist"
-    }
-}

packages/fonts/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @gitbook/fonts
 
+## 0.1.1
+
+### Patch Changes
+
+- 295f03d: Republish packages
+
 ## 0.1.0
 
 ### Minor Changes

packages/fonts/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.1.0",
+    "version": "0.1.1",
     "dependencies": {
         "@gitbook/api": "catalog:"
     },
@@ -27,5 +27,9 @@
     "files": ["dist", "src", "bin", "README.md", "CHANGELOG.md"],
     "engines": {
         "node": ">=20.0.0"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
     }
 }

packages/gitbook/CHANGELOG.md

@@ -1,5 +1,87 @@
 # gitbook
 
+## 0.19.1
+
+### Patch Changes
+
+- 295f03d: Republish packages
+- Updated dependencies [bdde392]
+- Updated dependencies [295f03d]
+  - @gitbook/react-contentkit@0.7.6
+  - @gitbook/browser-types@0.1.1
+  - @gitbook/cache-tags@0.3.2
+  - @gitbook/colors@0.4.1
+  - @gitbook/emoji-codepoints@0.2.1
+  - @gitbook/expr@1.2.2
+  - @gitbook/fonts@0.1.1
+  - @gitbook/icons@0.3.2
+  - @gitbook/openapi-parser@3.0.3
+  - @gitbook/react-math@0.6.2
+  - @gitbook/react-openapi@1.5.1
+
+## 0.19.0
+
+### Minor Changes
+
+- ed7d47d: Show a toolbar for authenticated users with access to the current site.
+- 50c1be3: Move inline expression evaluation from API to GBO
+- 56e46ce: Add Italian translation
+- b932e4e: Scope search across sections and variants
+
+### Patch Changes
+
+- 162cfe4: Hide sections if only one is present
+- 1456251: Unify section display condition
+- 9344431: Fix missing geo data in site insights because of incorrect proxying of events.
+- eea8f1e: Enhance OpenAPI security scopes handling
+- 2b8a2d2: Add stable scroll gutter to search container
+- b498521: Fix robots.txt preventing favicon from being indexed.
+- ceb32b1: Redo search scope UI
+- 8e99871: Highlight discriminator properties in oneOf, allOf, anyOf objects
+- 2fc2127: Make search accessible
+- f3e4041: Adapt OpenAPI code samples to prefill API key using visitor data
+- 6815dd1: Fix markdownPageURL for PageActions
+- c06b3dd: Improve default site icon
+- cba583a: Use sitespace title instead of space title in search
+- e434442: Support nested site section groups
+- 469b332: Add support for inline expressions rendering with visitor data on GBO side
+- 0ef5dc8: Update to column width sizing
+- 1e4e54e: Fix rounded outline items
+- 379d486: Expose "Best match" when site has translations
+- c21693f: Improve screen reader accessibility for hints
+- badf3a9: Add alt text to inline image
+- c23d4ef: Fix crash for card cover defined without objectFit
+- d74f8a7: Improve wide page width layout
+- b8388e5: Add scrollcontainer component
+- b85eccd: Refactor section tabs
+- 1e53f46: Fix button content truncate
+- 7a504b7: Fix OpenAPI response dropdown & vertical overflow
+- a4c3399: Fix OpenAPI alternatives not showing
+- Updated dependencies [a629900]
+- Updated dependencies [eea8f1e]
+- Updated dependencies [8e99871]
+- Updated dependencies [f3e4041]
+- Updated dependencies [319a1e5]
+- Updated dependencies [529f940]
+- Updated dependencies [754cc11]
+- Updated dependencies [d7948e3]
+- Updated dependencies [a4c3399]
+  - @gitbook/expr@1.2.1
+  - @gitbook/react-openapi@1.5.0
+
+## 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

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/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,6 +1,6 @@
 {
     "name": "gitbook",
-    "version": "0.17.2",
+    "version": "0.19.1",
     "private": true,
     "dependencies": {
         "@gitbook/api": "catalog:",
@@ -8,13 +8,15 @@
         "@gitbook/cache-tags": "workspace:*",
         "@gitbook/colors": "workspace:*",
         "@gitbook/emoji-codepoints": "workspace:*",
+        "@gitbook/expr": "workspace:*",
         "@gitbook/fonts": "workspace:*",
         "@gitbook/icons": "workspace:*",
         "@gitbook/openapi-parser": "workspace:*",
         "@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.9.2",
         "@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,8 +49,9 @@
         "memoizee": "^0.4.17",
         "micromark-extension-frontmatter": "^2.0.0",
         "micromark-extension-gfm": "^3.0.0",
+        "motion": "^12.23.12",
         "next": "15.4.0",
-        "next-themes": "^0.2.1",
+        "next-themes": "^0.4.6",
         "nuqs": "^2.2.3",
         "object-hash": "^3.0.0",
         "object-identity": "^0.1.2",
@@ -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,9 +116,14 @@
         "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": [
         ">0.3%, chrome >= 64, edge >= 79, firefox >= 67, opera >= 51, safari >= 12 and not dead"
-    ]
+    ],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    }
 }

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,391 @@
+'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 { HideToolbarButton } from './HideToolbarButton';
+import { IframeWrapper } from './IframeWrapper';
+import { RefreshContentButton } from './RefreshContentButton';
+import {
+    Toolbar,
+    ToolbarBody,
+    ToolbarButton,
+    ToolbarButtonGroup,
+    type ToolbarButtonProps,
+    ToolbarSeparator,
+    ToolbarSubtitle,
+    ToolbarTitle,
+} from './Toolbar';
+import {
+    type ToolbarControlsContextValue,
+    ToolbarControlsProvider,
+} from './ToolbarControlsContext';
+import type { AdminToolbarClientProps, AdminToolbarContext } from './types';
+import { useToolbarVisibility } from './utils';
+
+export function AdminToolbarClient(props: AdminToolbarClientProps) {
+    const { context, onPersistentClose, onSessionClose, onToggleMinify } = props;
+    const {
+        minified,
+        setMinified,
+        shouldAutoExpand,
+        hidden,
+        minimize,
+        closeSession,
+        closePersistent,
+    } = useToolbarVisibility({
+        onPersistentClose,
+        onSessionClose,
+        onToggleMinify,
+    });
+
+    const visitorSession = useVisitorSession();
+
+    const toolbarControls: ToolbarControlsContextValue = {
+        minimize,
+        closeSession,
+        closePersistent,
+        shouldAutoExpand,
+    };
+
+    if (hidden) {
+        return null;
+    }
+
+    // If there is a change request, show the change request toolbar
+    if (context.changeRequest) {
+        return (
+            <ToolbarControlsWrapper value={toolbarControls}>
+                <ChangeRequestToolbar
+                    context={context}
+                    minified={minified}
+                    onMinifiedChange={setMinified}
+                />
+            </ToolbarControlsWrapper>
+        );
+    }
+
+    // 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 (
+            <ToolbarControlsWrapper value={toolbarControls}>
+                <RevisionToolbar
+                    context={context}
+                    minified={minified}
+                    onMinifiedChange={setMinified}
+                />
+            </ToolbarControlsWrapper>
+        );
+    }
+
+    // If the user is authenticated and part of the organization owning this site, show the authenticated user toolbar
+    if (visitorSession?.organizationId === context.organizationId) {
+        return (
+            <ToolbarControlsWrapper value={toolbarControls}>
+                <AuthenticatedUserToolbar
+                    context={context}
+                    minified={minified}
+                    onMinifiedChange={setMinified}
+                />
+            </ToolbarControlsWrapper>
+        );
+    }
+
+    return null;
+}
+
+/**
+ * Reusable wrapper that provides tooling and containers that are used by all types of toolbar views.
+ */
+export function ToolbarControlsWrapper(
+    props: React.PropsWithChildren<{ value: ToolbarControlsContextValue | null }>
+) {
+    const { children, value } = props;
+    return (
+        <ToolbarControlsProvider value={value}>
+            <IframeWrapper>
+                <MotionConfig reducedMotion="user">{children}</MotionConfig>
+            </IframeWrapper>
+        </ToolbarControlsProvider>
+    );
+}
+
+interface ToolbarViewProps {
+    context: AdminToolbarContext;
+    minified: boolean;
+    onMinifiedChange: (value: boolean) => void;
+}
+
+function ChangeRequestToolbar(props: ToolbarViewProps) {
+    const { context, minified, onMinifiedChange } = props;
+    const { changeRequest, site } = context;
+    if (!changeRequest) {
+        throw new Error('Change request is not set');
+    }
+
+    const author = changeRequest.createdBy.displayName;
+
+    const { refreshForUpdates, updated } = useCheckForContentUpdate({
+        revisionId: changeRequest.revision,
+    });
+
+    return (
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange} label="Site preview">
+            <ToolbarBody>
+                <ToolbarTitle
+                    prefix={`Change #${changeRequest.number}:`}
+                    suffix={`${changeRequest.subject || 'Untitled'}`}
+                />
+                <ToolbarSubtitle
+                    subtitle={
+                        <>
+                            <DateRelative value={changeRequest.updatedAt} /> by {author}
+                        </>
+                    }
+                />
+            </ToolbarBody>
+
+            <ToolbarSeparator />
+
+            <ToolbarActions>
+                {/* Refresh to retrieve latest changes */}
+                {updated ? <RefreshContentButton refreshForUpdates={refreshForUpdates} /> : null}
+
+                {/* Edit in GitBook */}
+                <EditPageButton href={changeRequest.urls.app} siteId={site.id} />
+
+                {/* Comment in app */}
+                <ToolbarButton
+                    title="Comment in a GitBook"
+                    href={getToolbarHref({
+                        href: `${changeRequest.urls.app}~/comments`,
+                        siteId: site.id,
+                        buttonId: 'comment',
+                    })}
+                    icon="comment"
+                />
+
+                {/* Open production site */}
+                {site.urls.published ? (
+                    <ToolbarButton
+                        title="Open production site"
+                        href={getToolbarHref({
+                            href: site.urls.published,
+                            siteId: site.id,
+                            buttonId: 'production-site',
+                        })}
+                        icon="globe"
+                    />
+                ) : null}
+
+                {/* Open CR in GitBook */}
+                <ToolbarButton
+                    title="View change request in GitBook"
+                    href={getToolbarHref({
+                        href: changeRequest.urls.app,
+                        siteId: site.id,
+                        buttonId: 'change-request',
+                    })}
+                    icon="code-pull-request"
+                />
+            </ToolbarActions>
+        </Toolbar>
+    );
+}
+
+function RevisionToolbar(props: ToolbarViewProps) {
+    const { context, minified, onMinifiedChange } = props;
+    const { revision, site } = context;
+    if (!revision) {
+        throw new Error('Revision is not set');
+    }
+
+    const gitURL = revision.git?.url;
+    const isGitHub = gitURL?.includes('github.com');
+    const gitProvider = isGitHub ? 'GitHub' : 'GitLab';
+
+    return (
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange} label="Site preview">
+            <ToolbarBody>
+                <ToolbarTitle prefix="Site version" suffix={context.site.title} />
+                <ToolbarSubtitle
+                    subtitle={
+                        <>
+                            Created <DateRelative value={revision.createdAt} />
+                        </>
+                    }
+                />
+            </ToolbarBody>
+            <ToolbarSeparator />
+            <ToolbarActions>
+                {/* Open commit in Git client */}
+                <ToolbarButton
+                    title={
+                        gitURL ? (
+                            `Open commit in ${gitProvider}`
+                        ) : (
+                            <div className="flex items-center gap-2">
+                                Setup GitSync to edit using Git{' '}
+                                <div className="flex items-center gap-1 text-neutral-8 text-xs hover:text-neutral-6 hover:underline dark:text-neutral-3">
+                                    <a
+                                        href="https://gitbook.com/docs/getting-started/git-sync"
+                                        target="_blank"
+                                        rel="noopener noreferrer"
+                                        className=""
+                                        onClick={(e) => e.stopPropagation()}
+                                    >
+                                        Learn more
+                                    </a>
+                                    <Icon icon="arrow-up-right" className="size-3" />
+                                </div>
+                            </div>
+                        )
+                    }
+                    href={gitURL}
+                    disabled={!gitURL}
+                    icon={gitURL ? (isGitHub ? 'github' : 'gitlab') : 'github'}
+                />
+                {site.urls.published ? (
+                    <ToolbarButton
+                        title="Open production site"
+                        href={getToolbarHref({
+                            href: site.urls.published,
+                            siteId: site.id,
+                            buttonId: 'production-site',
+                        })}
+                        icon="globe"
+                    />
+                ) : null}
+                <ToolbarButton
+                    title="View this revision in GitBook"
+                    href={getToolbarHref({
+                        href: revision.urls.app,
+                        siteId: site.id,
+                        buttonId: 'revision',
+                    })}
+                    icon="code-commit"
+                />
+            </ToolbarActions>
+        </Toolbar>
+    );
+}
+
+function AuthenticatedUserToolbar(props: ToolbarViewProps) {
+    const { context, minified, onMinifiedChange } = props;
+    const { revision, space, site } = context;
+    const { refreshForUpdates, updated } = useCheckForContentUpdate({
+        revisionId: space.revision,
+    });
+
+    return (
+        <Toolbar
+            minified={minified}
+            onMinifiedChange={onMinifiedChange}
+            label="Only visible to your GitBook organization"
+        >
+            <ToolbarBody>
+                <ToolbarTitle suffix={context.site.title} />
+                <ToolbarSubtitle
+                    subtitle={
+                        <>
+                            Updated <DateRelative value={revision.createdAt} />
+                        </>
+                    }
+                />
+            </ToolbarBody>
+            <ToolbarSeparator />
+            <ToolbarActions>
+                {/* Refresh to retrieve latest changes */}
+                {updated ? <RefreshContentButton refreshForUpdates={refreshForUpdates} /> : null}
+
+                {/* Edit in GitBook */}
+                <EditPageButton href={space.urls.app} siteId={site.id} />
+
+                {/* Open site in GitBook */}
+                <ToolbarButton
+                    title="Open site in GitBook"
+                    href={getToolbarHref({
+                        href: site.urls.app,
+                        siteId: site.id,
+                        buttonId: 'site',
+                    })}
+                    icon="gears"
+                />
+
+                {/* Customize in GitBook */}
+                <ToolbarButton
+                    title="Customize in GitBook"
+                    href={getToolbarHref({
+                        href: `${site.urls.app}/customization/general`,
+                        siteId: site.id,
+                        buttonId: 'customize',
+                    })}
+                    icon="palette"
+                />
+
+                {/* Open insights in GitBook */}
+                <ToolbarButton
+                    title="Open insights in GitBook"
+                    href={getToolbarHref({
+                        href: `${site.urls.app}/insights`,
+                        siteId: site.id,
+                        buttonId: 'insights',
+                    })}
+                    icon="chart-simple"
+                />
+            </ToolbarActions>
+        </Toolbar>
+    );
+}
+
+function ToolbarActions(props: { children: React.ReactNode }) {
+    const { children } = props;
+
+    return (
+        <ToolbarButtonGroup>
+            {children}
+            <HideToolbarButton />
+        </ToolbarButtonGroup>
+    );
+}
+
+function EditPageButton(props: {
+    href: string;
+    siteId: string;
+    motionValues?: ToolbarButtonProps['motionValues'];
+}) {
+    const { href, motionValues, siteId } = props;
+    const pagePath = useCurrentPagePath();
+
+    return (
+        <ToolbarButton
+            title="Edit in GitBook"
+            href={getToolbarHref({
+                href: `${href}${pagePath.startsWith('/') ? pagePath.slice(1) : pagePath}`,
+                siteId,
+                buttonId: 'edit',
+            })}
+            icon="pencil"
+            motionValues={motionValues}
+        />
+    );
+}
+
+/**
+ * Append utm parameters to a URL to track usage of the toolbar.
+ */
+function getToolbarHref({
+    href,
+    siteId,
+    buttonId,
+}: { href: string; siteId: string; buttonId: string }) {
+    const url = new URL(href);
+    url.searchParams.set('utm_source', 'content');
+    url.searchParams.set('utm_medium', 'toolbar');
+    url.searchParams.set('utm_campaign', siteId);
+    url.searchParams.set('utm_content', buttonId);
+
+    return url.toString();
+}

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

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

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

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

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

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

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

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

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

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

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

@@ -1,65 +1,343 @@
 'use client';
-
-import type * as React from 'react';
+import {
+    AnimatePresence,
+    type MotionValue,
+    motion,
+    useReducedMotion,
+    useSpring,
+} from 'motion/react';
+import React from 'react';
+import { AnimatedLogo } from './AnimatedLogo';
+import { useToolbarControls } from './ToolbarControlsContext';
 
 import { tcls } from '@/lib/tailwind';
+import { Icon, type IconName, IconStyle } from '@gitbook/icons';
+import { Tooltip } from '../primitives';
+import { getCopyVariants, toolbarEasings } from './transitions';
+import { useMagnificationEffect } from './useMagnificationEffect';
 
-export function Toolbar(props: { children: React.ReactNode }) {
-    const { children } = props;
+const DURATION_LOGO_APPEARANCE = 2000;
+const DELAY_BETWEEN_LOGO_AND_CONTENT = 100;
+
+interface ToolbarProps {
+    label: React.ReactNode;
+    children: React.ReactNode;
+    minified: boolean;
+    onMinifiedChange: (value: boolean) => void;
+}
+
+export function Toolbar(props: ToolbarProps) {
+    const { children, label, minified, onMinifiedChange } = props;
+    const controls = useToolbarControls();
+    const [isReady, setIsReady] = React.useState(false);
+    const autoExpandTriggeredRef = React.useRef(false);
+
+    const shouldAutoExpand = Boolean(controls?.shouldAutoExpand);
+    const [shouldAnimateLogo, setShouldAnimateLogo] = React.useState(shouldAutoExpand);
+
+    // 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 || autoExpandTriggeredRef.current) {
+            return;
+        }
+
+        if (!shouldAutoExpand) {
+            // When we already know the toolbar should stay expanded (e.g. the user previously
+            // opened it this session) we short-circuit the auto-expand animation and immediately
+            // render the expanded state without replaying the logo animation.
+            autoExpandTriggeredRef.current = true;
+            setShouldAnimateLogo(false);
+            return;
+        }
+
+        autoExpandTriggeredRef.current = true;
+
+        // On a fresh session we let the toolbar appear in its compact form, play the logo
+        // animation, and only then expand the toolbar. The timeout mirrors the duration of the
+        // logo animation so both transitions feel connected.
+        const expandAfterTimeout = setTimeout(() => {
+            setShouldAnimateLogo(false);
+            onMinifiedChange(false);
+        }, DURATION_LOGO_APPEARANCE + DELAY_BETWEEN_LOGO_AND_CONTENT);
+
+        return () => clearTimeout(expandAfterTimeout);
+    }, [isReady, onMinifiedChange, shouldAutoExpand]);
+
+    React.useEffect(() => {
+        if (!minified) {
+            // Any manual expansion should stop the logo animation so the icon stays in its
+            // “settled” state once the toolbar is open.
+            setShouldAnimateLogo(false);
+        }
+    }, [minified]);
+
+    // 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 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) {
+                                setShouldAnimateLogo(false);
+                                onMinifiedChange(false);
+                            }
+                        }}
+                        layout
+                        transition={toolbarEasings.spring}
+                        className={tcls(
+                            minified ? 'cursor-pointer px-2' : 'pr-2 pl-3.5',
+                            'flex',
+                            'items-center',
+                            'justify-center',
+                            'min-h-11',
+                            'min-w-12',
+                            'h-12',
+                            'py-2',
+                            'backdrop-blur-sm',
+                            'origin-center',
+                            'border-[0.5px] border-neutral-5 border-solid dark:border-neutral-8',
+                            'bg-[linear-gradient(45deg,rgba(39,39,39,0.8)_100%,rgba(39,39,39,0.4)_80%)]',
+                            'dark:bg-[linear-gradient(45deg,rgba(39,39,39,0.5)_100%,rgba(39,39,39,0.3)_80%)]'
+                        )}
+                        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 shouldAnimate={shouldAnimateLogo} />
+                        </motion.div>
+
+                        {!minified ? children : null}
+                    </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 childEl = child as React.ReactElement;
+                const childKey = childEl.key ?? `toolbar-button-${index}`;
+                return (
+                    <ToolbarButtonWrapper
+                        key={childKey}
+                        child={childEl}
+                        rawMotionValues={buttonMotionValues[index]}
+                    />
+                );
+            })}
+        </motion.div>
+    );
+}
+
+export interface ToolbarButtonProps extends Omit<React.HTMLProps<HTMLAnchorElement>, 'title'> {
+    motionValues?: {
+        scale: MotionValue<number>;
+        x: MotionValue<number>;
+    };
+    icon: IconName;
+    iconClassName?: string;
+    title?: React.ReactNode;
+    children?: React.ReactNode;
+}
+
+export const ToolbarButton = React.forwardRef<HTMLDivElement, ToolbarButtonProps>((props, ref) => {
+    const {
+        title,
+        disabled,
+        motionValues,
+        className,
+        style,
+        href,
+        onClick,
+        icon,
+        iconClassName,
+        children,
+    } = props;
+    const reduceMotion = useReducedMotion();
+
+    return (
+        <motion.div variants={toolbarEasings.staggeringChild} className="relative" ref={ref}>
+            {children ? children : null}
+            <Tooltip label={title}>
+                <motion.a
+                    href={href}
+                    onClick={onClick}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    style={
+                        reduceMotion
+                            ? undefined
+                            : {
+                                  scale: motionValues?.scale,
+                                  x: motionValues?.x,
+                                  transformOrigin: 'bottom center',
+                                  zIndex: motionValues?.scale ? 10 : 'auto',
+                                  ...style,
+                              }
+                    }
+                    transition={{
+                        type: 'spring',
+                        stiffness: 400,
+                        damping: 30,
+                    }}
+                    className={tcls(
+                        'toolbar-button',
+                        className,
+                        'flex',
+                        'relative',
+                        'items-center',
+                        'justify-center',
+                        'gap-1',
+                        'text-sm',
+                        'rounded-full',
+                        'truncate',
+                        'text-tint-1',
+                        'dark:text-tint-12',
+                        'cursor-pointer',
+                        'transition-colors',
+                        'size-8',
+                        disabled ? 'cursor-not-allowed opacity-50' : '',
+                        'border border-[rgba(256,_256,_256,_0.06)] border-solid',
+                        'bg-[linear-gradient(45deg,rgba(51,53,57,1)_0%,rgba(50,52,56,1)_100%)]'
+                    )}
+                >
+                    <Icon
+                        icon={icon}
+                        iconStyle={IconStyle.Solid}
+                        className={tcls(
+                            'size-4 shrink-0 group-hover:scale-110 group-hover:text-tint-3',
+                            iconClassName
+                        )}
+                    />
+                </motion.a>
+            </Tooltip>
+        </motion.div>
+    );
+});
+
+ToolbarButton.displayName = 'ToolbarButton';
+
+function ToolbarButtonWrapper(props: {
+    child: React.ReactElement;
+    rawMotionValues?: { scale: MotionValue<number>; x: MotionValue<number> };
+}) {
+    const { child, rawMotionValues } = props;
+
+    // Convert the raw motion values to smooth spring easings
+    const springScale = useSpring(rawMotionValues?.scale.get() ?? 1, {
+        stiffness: 400,
+        damping: 30,
+    });
+    const springX = useSpring(rawMotionValues?.x.get() ?? 0, { stiffness: 400, damping: 30 });
+
+    // Sync springs with raw motion values
+    React.useEffect(() => {
+        if (!rawMotionValues) return;
+
+        const unsubScale = rawMotionValues.scale.on('change', (v) => springScale.set(v));
+        const unsubX = rawMotionValues.x.on('change', (v) => springX.set(v));
+
+        return () => {
+            unsubScale();
+            unsubX();
+        };
+    }, [rawMotionValues, springScale, springX]);
+
+    const motionValues = {
+        scale: springScale,
+        x: springX,
+    };
+
+    return React.cloneElement(child, {
+        motionValues,
+    });
+}
+
+export function ToolbarSeparator() {
+    return <div className="h-5 w-px bg-tint-1/3" />;
+}
+
+export function ToolbarTitle(props: { prefix?: string; suffix: string }) {
+    return (
+        <div className="flex items-center gap-1 text-xs ">
+            {props.prefix ? <ToolbarTitlePrefix title={props.prefix} /> : null}
+            <ToolbarTitleSuffix title={props.suffix} />
+        </div>
+    );
+}
+
+function ToolbarTitlePrefix(props: { title: string }) {
+    return (
+        <motion.span
+            {...getCopyVariants(0)}
+            className="truncate font-medium text-neutral-1 dark:text-neutral-12"
+        >
+            {props.title}
+        </motion.span>
+    );
+}
+
+function ToolbarTitleSuffix(props: { title: string }) {
+    return (
+        <motion.span
+            {...getCopyVariants(1)}
+            className="max-w-[20ch] truncate text-neutral-1 dark:text-neutral-12"
+        >
+            {props.title}
+        </motion.span>
+    );
+}
+
+export function ToolbarSubtitle(props: { subtitle: React.ReactNode }) {
+    return (
+        <motion.span
+            {...getCopyVariants(1)}
+            className="text-neutral-1/80 text-xxs dark:text-neutral-12/80"
+        >
+            {props.subtitle}
+        </motion.span>
     );
 }

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

@@ -0,0 +1,27 @@
+'use client';
+import React from 'react';
+
+export interface ToolbarControlsContextValue {
+    minimize: () => void;
+    closeSession?: () => void;
+    closePersistent?: () => void;
+    shouldAutoExpand?: boolean;
+}
+
+const ToolbarControlsContext = React.createContext<ToolbarControlsContextValue | null>(null);
+
+/*
+ * Provides reusable state setters (mainly for hiding/showing the toolbar) for the toolbar controls propagated through to the children
+ */
+export function ToolbarControlsProvider(
+    props: React.PropsWithChildren<{ value: ToolbarControlsContextValue | null }>
+) {
+    const { children, value } = props;
+    return (
+        <ToolbarControlsContext.Provider value={value}>{children}</ToolbarControlsContext.Provider>
+    );
+}
+
+export function useToolbarControls() {
+    return React.useContext(ToolbarControlsContext);
+}

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

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

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

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

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

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

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

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

@@ -0,0 +1,154 @@
+import React from 'react';
+
+import {
+    getLocalStorageItem,
+    getSessionStorageItem,
+    removeSessionStorageItem,
+    setLocalStorageItem,
+    setSessionStorageItem,
+} from '@/lib/browser/local-storage';
+
+const STORAGE_KEY = 'gitbook_toolbar_closed';
+const SESSION_STORAGE_KEY = 'gitbook_toolbar_session_closed';
+const SESSION_MINIFIED_KEY = 'gitbook_toolbar_minified';
+
+type SessionHideReason = 'session' | 'persistent';
+
+/**
+ * Read the current session hide state. We store whether the toolbar was hidden “for session” or
+ * “persistently” so we can distinguish between a temporary dismissal and a user preference.
+ */
+export const getSessionHideState = (): { hidden: boolean; reason?: SessionHideReason } => {
+    const value = getSessionStorageItem<SessionHideReason | null>(SESSION_STORAGE_KEY, null);
+    if (value === 'session' || value === 'persistent') {
+        return { hidden: true, reason: value };
+    }
+    return { hidden: false, reason: undefined };
+};
+
+/**
+ * Persist the session hide state. Passing `false` clears the stored preference entirely.
+ */
+export const setSessionHidden = (value: boolean, reason?: SessionHideReason) => {
+    if (value && reason) {
+        setSessionStorageItem(SESSION_STORAGE_KEY, reason);
+    } else {
+        removeSessionStorageItem(SESSION_STORAGE_KEY);
+    }
+};
+
+/**
+ * Retrieve the last minified state from session storage. If no value was ever stored we return
+ * `undefined`, which signals that the toolbar should auto-expand once the logo animation finishes.
+ */
+export const getStoredMinified = (): boolean | undefined => {
+    const stored = getSessionStorageItem<boolean | null>(SESSION_MINIFIED_KEY, null);
+    if (stored === null || stored === undefined) {
+        removeSessionStorageItem(SESSION_MINIFIED_KEY);
+        return undefined;
+    }
+    return stored;
+};
+
+/**
+ * Persist the current minified state for the ongoing session.
+ */
+export const setStoredMinified = (value: boolean) => {
+    setSessionStorageItem(SESSION_MINIFIED_KEY, value);
+};
+
+interface UseToolbarVisibilityOptions {
+    onPersistentClose?: () => void;
+    onSessionClose?: () => void;
+    onToggleMinify?: () => void;
+}
+
+export function useToolbarVisibility(options: UseToolbarVisibilityOptions = {}) {
+    const { onPersistentClose, onSessionClose, onToggleMinify } = options;
+
+    const [initialStoredMinified] = React.useState<boolean | undefined>(() =>
+        typeof window !== 'undefined' ? getStoredMinified() : undefined
+    );
+    const shouldAutoExpand = initialStoredMinified === undefined;
+
+    const [minified, setMinifiedState] = React.useState<boolean>(() =>
+        initialStoredMinified !== undefined ? initialStoredMinified : true
+    );
+
+    const [persistentHidden, setPersistentHidden] = React.useState(() =>
+        getLocalStorageItem(STORAGE_KEY, false)
+    );
+
+    const [sessionReason, setSessionReason] = React.useState<SessionHideReason | undefined>(() => {
+        const state = getSessionHideState();
+        return state.hidden ? state.reason : undefined;
+    });
+
+    React.useEffect(() => {
+        if (typeof window === 'undefined') {
+            return;
+        }
+
+        const handleStorage = () => {
+            setPersistentHidden(getLocalStorageItem(STORAGE_KEY, false));
+            const state = getSessionHideState();
+            setSessionReason(state.hidden ? state.reason : undefined);
+        };
+
+        window.addEventListener('storage', handleStorage);
+        return () => window.removeEventListener('storage', handleStorage);
+    }, []);
+
+    React.useEffect(() => {
+        if (persistentHidden) {
+            if (sessionReason !== 'persistent') {
+                // Sync the session flag so we honour the persistent preference and avoid flashes when
+                // opening new tabs in the same browsing session.
+                setSessionHidden(true, 'persistent');
+                setSessionReason('persistent');
+            }
+            return;
+        }
+
+        if (sessionReason === 'persistent') {
+            // If the persistent preference was cleared we also clear the session flag so the toolbar
+            // can reappear immediately without requiring a full reload.
+            setSessionHidden(false);
+            setSessionReason(undefined);
+        }
+    }, [persistentHidden, sessionReason]);
+
+    const setMinified = (value: boolean) => {
+        setMinifiedState(value);
+        setStoredMinified(value);
+        onToggleMinify?.();
+    };
+
+    const minimize = () => setMinified(true);
+
+    const closeSession = () => {
+        setSessionHidden(true, 'session');
+        setSessionReason('session');
+        onSessionClose?.();
+    };
+
+    const closePersistent = () => {
+        setLocalStorageItem(STORAGE_KEY, true);
+        setPersistentHidden(true);
+        setSessionHidden(true, 'persistent');
+        setSessionReason('persistent');
+        onPersistentClose?.();
+    };
+
+    const hidden = persistentHidden || sessionReason === 'session';
+
+    return {
+        minified,
+        setMinified,
+        shouldAutoExpand,
+        hidden,
+        minimize,
+        closeSession,
+        closePersistent,
+    };
+}

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

@@ -1,10 +1,23 @@
-import type { DocumentInlineIcon } from '@gitbook/api';
+import type { DocumentInlineIcon, DocumentMarkColor } from '@gitbook/api';
 
+import { tcls } from '@/lib/tailwind';
 import { Icon, type IconName } from '@gitbook/icons';
 import type { InlineProps } from './Inline';
+import { textColorToStyle } from './utils/colors';
 
 export async function InlineIcon(props: InlineProps<DocumentInlineIcon>) {
     const { inline } = props;
+    const icon = inline.data.icon as IconName;
+    // @ts-expect-error remove this comment once API is updated
+    const color = inline.data.color
+        ? // @ts-expect-error remove "as DocumentMarkColor['data']['text']" once API is updated
+          (inline.data.color as DocumentMarkColor['data']['text'])
+        : undefined;
 
-    return <Icon icon={inline.data.icon as IconName} className="inline size-[1em]" />;
+    return (
+        <Icon
+            icon={icon}
+            className={tcls('inline size-[1em]', color ? textColorToStyle[color] : null)}
+        />
+    );
 }

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;
 }
@@ -313,10 +317,11 @@
 }
 
 .openapi-securities-oauth-flows {
-    @apply flex flex-col gap-2 divide-y divide-tint-subtle;
+    @apply flex flex-col gap-3;
 }
 
-.openapi-securities-oauth-content {
+.openapi-securities-oauth-content,
+.openapi-securities-scopes {
     @apply prose *:!prose-sm *:text-tint;
 }
 
@@ -324,7 +329,7 @@
     @apply text-xs;
 }
 
-.openapi-securities-oauth-content ul {
+.openapi-securities-scopes ul {
     @apply !my-0;
 }
 
@@ -510,13 +515,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 +592,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 +626,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 +651,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 +841,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/DocumentView/Text.tsx

@@ -12,7 +12,8 @@ import type {
 } from '@gitbook/api';
 import React from 'react';
 
-import { type ClassValue, tcls } from '@/lib/tailwind';
+import { tcls } from '@/lib/tailwind';
+import { backgroundColorToStyle, textColorToStyle } from './utils/colors';
 
 export function Text(props: { text: DocumentText }) {
     const { text } = props;
@@ -121,51 +122,3 @@ function Color(props: MarkedLeafProps<DocumentMarkColor>) {
         </span>
     );
 }
-
-/**
- * @TODO replace by DocumentMarkColor['data']['text'] and DocumentMarkColor['data']['background']
- * once the API is updated.
- */
-type DocumentMarkColorValue =
-    | 'default'
-    | 'green'
-    | 'blue'
-    | 'red'
-    | 'orange'
-    | 'yellow'
-    | 'purple'
-    | '$primary'
-    | '$info'
-    | '$success'
-    | '$warning'
-    | '$danger';
-
-const textColorToStyle: { [color in DocumentMarkColorValue]: ClassValue } = {
-    default: [],
-    blue: ['text-blue-500'],
-    red: ['text-red-500'],
-    green: ['text-green-500'],
-    yellow: ['text-yellow-600'],
-    purple: ['text-purple-500'],
-    orange: ['text-orange-500'],
-    $primary: ['text-primary'],
-    $info: ['text-info'],
-    $success: ['text-success'],
-    $warning: ['text-warning'],
-    $danger: ['text-danger'],
-};
-
-const backgroundColorToStyle: { [color in DocumentMarkColorValue]: ClassValue } = {
-    default: [],
-    blue: ['bg-mark-blue'],
-    red: ['bg-mark-red'],
-    green: ['bg-mark-green'],
-    yellow: ['bg-mark-yellow'],
-    purple: ['bg-mark-purple'],
-    orange: ['bg-mark-orange'],
-    $primary: ['bg-primary'],
-    $info: ['bg-info'],
-    $success: ['bg-success'],
-    $warning: ['bg-warning'],
-    $danger: ['bg-danger'],
-};

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

@@ -0,0 +1,34 @@
+import type { ClassValue } from '@/lib/tailwind';
+import type { DocumentMarkColor } from '@gitbook/api';
+
+export const textColorToStyle: { [color in DocumentMarkColor['data']['text']]: ClassValue } = {
+    default: [],
+    blue: ['text-blue-500'],
+    red: ['text-red-500'],
+    green: ['text-green-500'],
+    yellow: ['text-yellow-600'],
+    purple: ['text-purple-500'],
+    orange: ['text-orange-500'],
+    $primary: ['text-primary'],
+    $info: ['text-info'],
+    $success: ['text-success'],
+    $warning: ['text-warning'],
+    $danger: ['text-danger'],
+};
+
+export const backgroundColorToStyle: {
+    [color in DocumentMarkColor['data']['background']]: ClassValue;
+} = {
+    default: [],
+    blue: ['bg-mark-blue'],
+    red: ['bg-mark-red'],
+    green: ['bg-mark-green'],
+    yellow: ['bg-mark-yellow'],
+    purple: ['bg-mark-purple'],
+    orange: ['bg-mark-orange'],
+    $primary: ['bg-primary'],
+    $info: ['bg-info'],
+    $success: ['bg-success'],
+    $warning: ['bg-warning'],
+    $danger: ['bg-danger'],
+};

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

@@ -23,6 +23,12 @@ export function Header(props: {
     const { context, withTopHeader, withVariants } = props;
     const { siteSpace, siteSpaces, sections, customization } = context;
 
+    const withSections = Boolean(
+        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'))
+    );
+
     return (
         <header
             id="site-header"
@@ -57,7 +63,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,15 +126,31 @@ 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>
 
                         {customization.header.links.length > 0 ||
-                        (!sections && withVariants === 'translations') ? (
+                        (!withSections && withVariants === 'translations') ? (
                             <HeaderLinks>
                                 {customization.header.links.length > 0 ? (
                                     <>
@@ -148,7 +170,7 @@ export function Header(props: {
                                         />
                                     </>
                                 ) : null}
-                                {!sections && withVariants === 'translations' ? (
+                                {!withSections && withVariants === 'translations' ? (
                                     <TranslationsDropdown
                                         context={context}
                                         siteSpace={siteSpace}
@@ -162,43 +184,19 @@ 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 && withSections ? (
+                <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 };
+    }
+}

packages/gitbook/src/components/PageActions/PageActions.tsx

@@ -2,9 +2,6 @@
 
 import { useAIChatState } from '@/components/AI';
 import type { Assistant } from '@/components/AI';
-import { ChatGPTIcon } from '@/components/PageActions/assets/ChatGPTIcon';
-import { ClaudeIcon } from '@/components/PageActions/assets/ClaudeIcon';
-import { MarkdownIcon } from '@/components/PageActions/assets/MarkdownIcon';
 import { Button } from '@/components/primitives/Button';
 import { DropdownMenuItem, useDropdownMenuClose } from '@/components/primitives/DropdownMenu';
 import { tString, useLanguage } from '@/intl/client';
@@ -13,15 +10,15 @@ import type { GitSyncState } from '@gitbook/api';
 import { Icon, type IconName, IconStyle } from '@gitbook/icons';
 import assertNever from 'assert-never';
 import QuickLRU from 'quick-lru';
-import type React from 'react';
+import React from 'react';
 import { create } from 'zustand';
 
 type PageActionType = 'button' | 'dropdown-menu-item';
 
 /**
- * Opens our AI Docs Assistant.
+ * Action to open the GitBook Assistant.
  */
-export function OpenAIAssistant(props: { assistant: Assistant; type: PageActionType }) {
+export function ActionOpenAssistant(props: { assistant: Assistant; type: PageActionType }) {
     const { assistant, type } = props;
     const chat = useAIChatState();
     const language = useLanguage();
@@ -87,14 +84,14 @@ const useCopiedStore = create<
 const markdownCache = new QuickLRU<string, string>({ maxSize: 10 });
 
 /**
- * Copies the markdown version of the page to the clipboard.
+ * Action to copy the markdown version of the page to the clipboard.
  */
-export function CopyMarkdown(props: {
-    markdownPageUrl: string;
+export function ActionCopyMarkdown(props: {
+    markdownPageURL: string;
     type: PageActionType;
     isDefaultAction?: boolean;
 }) {
-    const { markdownPageUrl, type, isDefaultAction } = props;
+    const { markdownPageURL, type, isDefaultAction } = props;
     const language = useLanguage();
 
     const closeDropdown = useDropdownMenuClose();
@@ -105,8 +102,8 @@ export function CopyMarkdown(props: {
     const fetchMarkdown = async () => {
         setLoading(true);
 
-        const result = await fetch(markdownPageUrl).then((res) => res.text());
-        markdownCache.set(markdownPageUrl, result);
+        const result = await fetch(markdownPageURL).then((res) => res.text());
+        markdownCache.set(markdownPageURL, result);
 
         setLoading(false);
 
@@ -120,7 +117,7 @@ export function CopyMarkdown(props: {
             e.preventDefault();
         }
 
-        copy(markdownCache.get(markdownPageUrl) || (await fetchMarkdown()), {
+        copy(markdownCache.get(markdownPageURL) || (await fetchMarkdown()), {
             onSuccess: () => {
                 // We close the dropdown menu if the action is a dropdown menu item and not the default action.
                 if (type === 'dropdown-menu-item' && !isDefaultAction) {
@@ -146,17 +143,17 @@ export function CopyMarkdown(props: {
 /**
  * Redirects to the markdown version of the page.
  */
-export function ViewAsMarkdown(props: { markdownPageUrl: string; type: PageActionType }) {
-    const { markdownPageUrl, type } = props;
+export function ActionViewAsMarkdown(props: { markdownPageURL: string; type: PageActionType }) {
+    const { markdownPageURL, type } = props;
     const language = useLanguage();
 
     return (
         <PageActionWrapper
             type={type}
-            icon={<MarkdownIcon className="size-4 fill-current" />}
+            icon="markdown"
             label={tString(language, 'view_page_markdown')}
             description={tString(language, 'view_page_plaintext')}
-            href={markdownPageUrl}
+            href={markdownPageURL}
         />
     );
 }
@@ -164,7 +161,7 @@ export function ViewAsMarkdown(props: { markdownPageUrl: string; type: PageActio
 /**
  * Open the page in a LLM with a pre-filled prompt. Either ChatGPT or Claude.
  */
-export function OpenInLLM(props: {
+export function ActionOpenInLLM(props: {
     provider: 'chatgpt' | 'claude';
     url: string;
     type: PageActionType;
@@ -177,13 +174,7 @@ export function OpenInLLM(props: {
     return (
         <PageActionWrapper
             type={type}
-            icon={
-                provider === 'chatgpt' ? (
-                    <ChatGPTIcon className="size-3.5 fill-current" />
-                ) : (
-                    <ClaudeIcon className="size-3.5 fill-current" />
-                )
-            }
+            icon={provider}
             label={tString(language, 'open_in', providerLabel)}
             shortLabel={providerLabel}
             description={tString(language, 'ai_chat_ask_about_page', providerLabel)}
@@ -192,7 +183,10 @@ export function OpenInLLM(props: {
     );
 }
 
-export function GitEditLink(props: {
+/**
+ * Action to open the page in the associated Git repository.
+ */
+export function ActionOpenEditOnGit(props: {
     type: PageActionType;
     provider: GitSyncState['installationProvider'];
     url: string;
@@ -214,7 +208,66 @@ export function GitEditLink(props: {
     );
 }
 
-export function ViewAsPDF(props: { url: string; type: PageActionType }) {
+/**
+ * Action to copy the MCP URL to the clipboard.
+ */
+export function ActionCopyMCPURL(props: { mcpURL: string; type: PageActionType }) {
+    const { mcpURL, type } = props;
+    const language = useLanguage();
+
+    return (
+        <CopyToClipboard
+            type={type}
+            data={mcpURL}
+            label={tString(language, 'connect_with_mcp')}
+            description={tString(language, 'copy_mcp_url')}
+            icon="mcp"
+        />
+    );
+}
+
+/**
+ * Action to open the MCP server in a specific editor.
+ */
+export function ActionOpenMCP(props: {
+    siteTitle: string;
+    mcpURL: string;
+    provider: 'vscode';
+    type: PageActionType;
+}) {
+    const { siteTitle, provider, mcpURL, type } = props;
+    const language = useLanguage();
+
+    const providerInfo = React.useMemo<{ label: string; icon: IconName; url: string }>(() => {
+        switch (provider) {
+            case 'vscode': {
+                const vscodeConfig = { name: siteTitle, url: mcpURL };
+                return {
+                    label: 'VSCode',
+                    icon: 'vscode',
+                    url: `vscode:mcp/install?${encodeURIComponent(JSON.stringify(vscodeConfig))}`,
+                };
+            }
+            default:
+                assertNever(provider);
+        }
+    }, [provider, mcpURL, siteTitle]);
+
+    return (
+        <PageActionWrapper
+            type={type}
+            href={providerInfo.url}
+            label={tString(language, 'connect_mcp_to', providerInfo.label)}
+            description={tString(language, 'install_mcp_on', providerInfo.label)}
+            icon={providerInfo.icon}
+        />
+    );
+}
+
+/**
+ * Action to view the page as a PDF.
+ */
+export function ActionViewAsPDF(props: { url: string; type: PageActionType }) {
     const { url, type } = props;
     const language = useLanguage();
 
@@ -229,6 +282,30 @@ export function ViewAsPDF(props: { url: string; type: PageActionType }) {
     );
 }
 
+/**
+ * Action to copy a string to the clipboard.
+ */
+export function CopyToClipboard(props: {
+    type: PageActionType;
+    data: string;
+    label: string;
+    description: string;
+    icon: IconName;
+}) {
+    const { type, data, label, description, icon } = props;
+    return (
+        <PageActionWrapper
+            type={type}
+            icon={icon}
+            label={label}
+            description={description}
+            onClick={() => {
+                navigator.clipboard.writeText(data);
+            }}
+        />
+    );
+}
+
 /**
  * Wraps an action in a button (for the default action) or dropdown menu item.
  */

packages/gitbook/src/components/PageActions/PageActionsDropdown.tsx

@@ -1,30 +1,39 @@
 'use client';
 
-import {
-    CopyMarkdown,
-    GitEditLink,
-    OpenAIAssistant,
-    OpenInLLM,
-    ViewAsMarkdown,
-    ViewAsPDF,
-} from '@/components/PageActions/PageActions';
 import { Button, ButtonGroup } from '@/components/primitives/Button';
 import { DropdownMenu, DropdownMenuSeparator } from '@/components/primitives/DropdownMenu';
 import { tString, useLanguage } from '@/intl/client';
 import type { GitSyncState, SiteCustomizationSettings } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
-import { useRef } from 'react';
+import React, { useRef } from 'react';
 import { useAI } from '../AI';
+import {
+    ActionCopyMCPURL,
+    ActionCopyMarkdown,
+    ActionOpenAssistant,
+    ActionOpenEditOnGit,
+    ActionOpenInLLM,
+    ActionOpenMCP,
+    ActionViewAsMarkdown,
+    ActionViewAsPDF,
+} from './PageActions';
 
-interface PageActionsDropdownProps {
-    markdownPageUrl: string;
-    className?: string;
-    actions: SiteCustomizationSettings['pageActions'];
+export type PageActionsDropdownURLs = {
+    html: string;
+    markdown: string;
+    mcp?: string;
+    pdf?: string;
     editOnGit?: {
         provider: GitSyncState['installationProvider'];
         url: string;
     };
-    pdfUrl?: string;
+};
+
+interface PageActionsDropdownProps {
+    siteTitle: string;
+    urls: PageActionsDropdownURLs;
+    className?: string;
+    actions: SiteCustomizationSettings['pageActions'];
 }
 
 /**
@@ -32,19 +41,14 @@ interface PageActionsDropdownProps {
  */
 export function PageActionsDropdown(props: PageActionsDropdownProps) {
     const ref = useRef<HTMLDivElement>(null);
-    const assistants = useAI().assistants.filter(
-        (assistant) => assistant.ui === true && assistant.pageAction
-    );
     const language = useLanguage();
 
-    const defaultActions = [assistants.length > 0, props.actions.markdown, props.editOnGit].filter(
-        Boolean
-    );
-    const dropdownActions = [props.actions.externalAI, props.pdfUrl].filter(Boolean);
+    const defaultAction = getPageDefaultAction(props);
+    const dropdownActions = getPageDropdownActions(props);
 
-    return [...defaultActions, ...dropdownActions].length > 0 ? (
+    return defaultAction || dropdownActions.length > 0 ? (
         <ButtonGroup ref={ref} className={props.className}>
-            {defaultActions.length > 0 ? <DefaultAction {...props} /> : null}
+            {defaultAction}
             {dropdownActions.length > 0 ? (
                 <DropdownMenu
                     align="end"
@@ -57,18 +61,15 @@ export function PageActionsDropdown(props: PageActionsDropdownProps) {
                                     className="size-3 transition-transform group-data-[state=open]/button:rotate-180"
                                 />
                             }
-                            label={tString(
-                                language,
-                                defaultActions.some(Boolean) ? 'more' : 'actions'
-                            )}
-                            iconOnly={defaultActions.some(Boolean)}
+                            label={tString(language, defaultAction ? 'more' : 'actions')}
+                            iconOnly={!!defaultAction}
                             size="xsmall"
                             variant="secondary"
                             className="bg-tint-base text-sm"
                         />
                     }
                 >
-                    <PageActionsDropdownMenuContent {...props} />
+                    {dropdownActions}
                 </DropdownMenu>
             ) : null}
         </ButtonGroup>
@@ -76,94 +77,105 @@ export function PageActionsDropdown(props: PageActionsDropdownProps) {
 }
 
 /**
- * The content of the dropdown menu.
+ * Return the list of actions to show in the dropdown menu.
  */
-function PageActionsDropdownMenuContent(props: PageActionsDropdownProps) {
-    const { markdownPageUrl, actions } = props;
+function getPageDropdownActions(props: PageActionsDropdownProps): React.ReactNode[] {
+    const { siteTitle, urls, actions } = props;
     const assistants = useAI().assistants.filter(
         (assistant) => assistant.ui === true && assistant.pageAction
     );
 
-    return (
-        <>
-            {assistants.map((assistant) => (
-                <OpenAIAssistant
-                    key={assistant.label}
-                    assistant={assistant}
+    return [
+        ...assistants.map((assistant) => (
+            <ActionOpenAssistant
+                key={assistant.label}
+                assistant={assistant}
+                type="dropdown-menu-item"
+            />
+        )),
+
+        actions.markdown ? (
+            <React.Fragment key="markdown">
+                <DropdownMenuSeparator className="first:hidden" />
+                <ActionCopyMarkdown
+                    isDefaultAction={!assistants.length}
+                    markdownPageURL={urls.markdown}
                     type="dropdown-menu-item"
                 />
-            ))}
+                <ActionViewAsMarkdown markdownPageURL={urls.markdown} type="dropdown-menu-item" />
+            </React.Fragment>
+        ) : null,
 
-            {actions.markdown ? (
-                <>
-                    <DropdownMenuSeparator className="first:hidden" />
-                    <CopyMarkdown
-                        isDefaultAction={!assistants.length}
-                        markdownPageUrl={markdownPageUrl}
+        actions.externalAI ? (
+            <React.Fragment key="externalAI">
+                <DropdownMenuSeparator className="first:hidden" />
+                <ActionOpenInLLM provider="chatgpt" url={urls.html} type="dropdown-menu-item" />
+                <ActionOpenInLLM provider="claude" url={urls.html} type="dropdown-menu-item" />
+            </React.Fragment>
+        ) : null,
+
+        actions.mcp && urls.mcp ? (
+            <React.Fragment key="mcp">
+                <DropdownMenuSeparator className="first:hidden" />
+                <ActionCopyMCPURL mcpURL={urls.mcp} type="dropdown-menu-item" />
+                <ActionOpenMCP
+                    provider="vscode"
+                    mcpURL={urls.mcp}
+                    siteTitle={siteTitle}
+                    type="dropdown-menu-item"
+                />
+            </React.Fragment>
+        ) : null,
+
+        urls.editOnGit || urls.pdf ? (
+            <React.Fragment key="editOnGit">
+                <DropdownMenuSeparator className="first:hidden" />
+                {urls.editOnGit ? (
+                    <ActionOpenEditOnGit
                         type="dropdown-menu-item"
+                        provider={urls.editOnGit.provider}
+                        url={urls.editOnGit.url}
                     />
-                    <ViewAsMarkdown markdownPageUrl={markdownPageUrl} type="dropdown-menu-item" />
-                </>
-            ) : null}
-
-            {actions.externalAI ? (
-                <>
-                    <DropdownMenuSeparator className="first:hidden" />
-                    <OpenInLLM provider="chatgpt" url={markdownPageUrl} type="dropdown-menu-item" />
-                    <OpenInLLM provider="claude" url={markdownPageUrl} type="dropdown-menu-item" />
-                </>
-            ) : null}
-
-            {props.editOnGit || props.pdfUrl ? (
-                <>
-                    <DropdownMenuSeparator className="first:hidden" />
-                    {props.editOnGit ? (
-                        <GitEditLink
-                            type="dropdown-menu-item"
-                            provider={props.editOnGit.provider}
-                            url={props.editOnGit.url}
-                        />
-                    ) : null}
-                    {props.pdfUrl ? (
-                        <ViewAsPDF url={props.pdfUrl} type="dropdown-menu-item" />
-                    ) : null}
-                </>
-            ) : null}
-        </>
-    );
+                ) : null}
+                {urls.pdf ? <ActionViewAsPDF url={urls.pdf} type="dropdown-menu-item" /> : null}
+            </React.Fragment>
+        ) : null,
+    ].filter(Boolean);
 }
 
 /**
  * A default action shown as a quick-access button beside the dropdown menu
  */
-function DefaultAction(props: PageActionsDropdownProps) {
-    const { markdownPageUrl, actions } = props;
+function getPageDefaultAction(props: PageActionsDropdownProps) {
+    const { urls, actions } = props;
     const assistants = useAI().assistants.filter(
         (assistant) => assistant.ui === true && assistant.pageAction
     );
 
     const assistant = assistants[0];
     if (assistant) {
-        return <OpenAIAssistant assistant={assistant} type="button" />;
+        return <ActionOpenAssistant assistant={assistant} type="button" />;
     }
 
-    if (props.editOnGit) {
+    if (urls.editOnGit) {
         return (
-            <GitEditLink
+            <ActionOpenEditOnGit
                 type="button"
-                provider={props.editOnGit.provider}
-                url={props.editOnGit.url}
+                provider={urls.editOnGit.provider}
+                url={urls.editOnGit.url}
             />
         );
     }
 
     if (actions.markdown) {
         return (
-            <CopyMarkdown
+            <ActionCopyMarkdown
                 isDefaultAction={!assistant}
-                markdownPageUrl={markdownPageUrl}
+                markdownPageURL={urls.markdown}
                 type="button"
             />
         );
     }
+
+    return null;
 }

packages/gitbook/src/components/PageActions/assets/ChatGPTIcon.tsx

@@ -1,8 +0,0 @@
-export function ChatGPTIcon(props: React.SVGProps<SVGSVGElement>) {
-    return (
-        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 320" {...props}>
-            <title>ChatGPT</title>
-            <path d="m297.06 130.97c7.26-21.79 4.76-45.66-6.85-65.48-17.46-30.4-52.56-46.04-86.84-38.68-15.25-17.18-37.16-26.95-60.13-26.81-35.04-.08-66.13 22.48-76.91 55.82-22.51 4.61-41.94 18.7-53.31 38.67-17.59 30.32-13.58 68.54 9.92 94.54-7.26 21.79-4.76 45.66 6.85 65.48 17.46 30.4 52.56 46.04 86.84 38.68 15.24 17.18 37.16 26.95 60.13 26.8 35.06.09 66.16-22.49 76.94-55.86 22.51-4.61 41.94-18.7 53.31-38.67 17.57-30.32 13.55-68.51-9.94-94.51zm-120.28 168.11c-14.03.02-27.62-4.89-38.39-13.88.49-.26 1.34-.73 1.89-1.07l63.72-36.8c3.26-1.85 5.26-5.32 5.24-9.07v-89.83l26.93 15.55c.29.14.48.42.52.74v74.39c-.04 33.08-26.83 59.9-59.91 59.97zm-128.84-55.03c-7.03-12.14-9.56-26.37-7.15-40.18.47.28 1.3.79 1.89 1.13l63.72 36.8c3.23 1.89 7.23 1.89 10.47 0l77.79-44.92v31.1c.02.32-.13.63-.38.83l-64.41 37.19c-28.69 16.52-65.33 6.7-81.92-21.95zm-16.77-139.09c7-12.16 18.05-21.46 31.21-26.29 0 .55-.03 1.52-.03 2.2v73.61c-.02 3.74 1.98 7.21 5.23 9.06l77.79 44.91-26.93 15.55c-.27.18-.61.21-.91.08l-64.42-37.22c-28.63-16.58-38.45-53.21-21.95-81.89zm221.26 51.49-77.79-44.92 26.93-15.54c.27-.18.61-.21.91-.08l64.42 37.19c28.68 16.57 38.51 53.26 21.94 81.94-7.01 12.14-18.05 21.44-31.2 26.28v-75.81c.03-3.74-1.96-7.2-5.2-9.06zm26.8-40.34c-.47-.29-1.3-.79-1.89-1.13l-63.72-36.8c-3.23-1.89-7.23-1.89-10.47 0l-77.79 44.92v-31.1c-.02-.32.13-.63.38-.83l64.41-37.16c28.69-16.55 65.37-6.7 81.91 22 6.99 12.12 9.52 26.31 7.15 40.1zm-168.51 55.43-26.94-15.55c-.29-.14-.48-.42-.52-.74v-74.39c.02-33.12 26.89-59.96 60.01-59.94 14.01 0 27.57 4.92 38.34 13.88-.49.26-1.33.73-1.89 1.07l-63.72 36.8c-3.26 1.85-5.26 5.31-5.24 9.06l-.04 89.79zm14.63-31.54 34.65-20.01 34.65 20v40.01l-34.65 20-34.65-20z" />
-        </svg>
-    );
-}

packages/gitbook/src/components/PageActions/assets/ClaudeIcon.tsx

@@ -1,19 +0,0 @@
-export function ClaudeIcon(props: React.SVGProps<SVGSVGElement>) {
-    return (
-        <svg
-            viewBox="0 0 256 257"
-            version="1.1"
-            xmlns="http://www.w3.org/2000/svg"
-            preserveAspectRatio="xMidYMid"
-            {...props}
-        >
-            <title>Claude</title>
-            <g>
-                <path
-                    d="M50.2278481,170.321013 L100.585316,142.063797 L101.427848,139.601013 L100.585316,138.24 L98.1225316,138.24 L89.6972152,137.721519 L60.921519,136.943797 L35.9696203,135.906835 L11.795443,134.610633 L5.70329114,133.31443 L0,125.796456 L0.583291139,122.037468 L5.70329114,118.602532 L13.0268354,119.250633 L29.2293671,120.352405 L53.5331646,122.037468 L71.161519,123.07443 L97.28,125.796456 L101.427848,125.796456 L102.011139,124.111392 L100.585316,123.07443 L99.4835443,122.037468 L74.3372152,104.992405 L47.116962,86.9751899 L32.8587342,76.6055696 L25.1463291,71.3559494 L21.2577215,66.4303797 L19.5726582,55.6718987 L26.5721519,47.9594937 L35.9696203,48.6075949 L38.3675949,49.2556962 L47.8946835,56.5792405 L68.2450633,72.3281013 L94.8172152,91.9007595 L98.7058228,95.1412658 L100.261266,94.0394937 L100.455696,93.2617722 L98.7058228,90.3453165 L84.2531646,64.2268354 L68.8283544,37.6546835 L61.958481,26.636962 L60.1437975,20.0263291 C59.4956962,17.3043038 59.0420253,15.0359494 59.0420253,12.2491139 L67.0136709,1.42582278 L71.4207595,-1.42108547e-14 L82.0496203,1.42582278 L86.521519,5.31443038 L93.1321519,20.4151899 L103.825823,44.2005063 L120.417215,76.5407595 L125.277975,86.1326582 L127.87038,95.0116456 L128.842532,97.7336709 L130.527595,97.7336709 L130.527595,96.1782278 L131.888608,77.9665823 L134.416203,55.6070886 L136.878987,26.8313924 L137.721519,18.7301266 L141.739747,9.00860759 L149.711392,3.75898734 L155.933165,6.74025316 L161.053165,14.0637975 L160.340253,18.7949367 L157.294177,38.5620253 L151.331646,69.5412658 L147.443038,90.2805063 L149.711392,90.2805063 L152.303797,87.6881013 L162.803038,73.7539241 L180.431392,51.718481 L188.208608,42.9691139 L197.282025,33.3124051 L203.114937,28.7108861 L214.132658,28.7108861 L222.233924,40.7655696 L218.604557,53.2091139 L207.262785,67.596962 L197.865316,79.7812658 L184.38481,97.9281013 L175.959494,112.44557 L176.737215,113.612152 L178.746329,113.417722 L209.207089,106.936709 L225.668861,103.955443 L245.306329,100.585316 L254.185316,104.733165 L255.157468,108.945823 L251.657722,117.56557 L230.659241,122.75038 L206.031392,127.675949 L169.348861,136.360506 L168.89519,136.684557 L169.413671,137.332658 L185.940253,138.888101 L193.004557,139.276962 L210.308861,139.276962 L242.519494,141.674937 L250.94481,147.248608 L256,154.053671 L255.157468,159.238481 L242.195443,165.849114 L224.696709,161.701266 L183.866329,151.979747 L169.867342,148.48 L167.923038,148.48 L167.923038,149.646582 L179.588861,161.053165 L200.976203,180.366582 L227.742785,205.253671 L229.103797,211.410633 L225.668861,216.271392 L222.039494,215.752911 L198.513418,198.059747 L189.44,190.088101 L168.89519,172.783797 L167.534177,172.783797 L167.534177,174.598481 L172.265316,181.533165 L197.282025,219.123038 L198.578228,230.659241 L196.763544,234.418228 L190.282532,236.686582 L183.153418,235.39038 L168.506329,214.84557 L153.40557,191.708354 L141.221266,170.969114 L139.730633,171.811646 L132.536709,249.259747 L129.166582,253.213165 L121.389367,256.19443 L114.908354,251.268861 L111.473418,243.297215 L114.908354,227.548354 L119.056203,207.003544 L122.426329,190.671392 L125.472405,170.385823 L127.287089,163.64557 L127.157468,163.191899 L125.666835,163.386329 L110.371646,184.38481 L87.1048101,215.817722 L68.6987342,235.52 L64.2916456,237.269873 L56.6440506,233.316456 L57.356962,226.252152 L61.6344304,219.96557 L87.1048101,187.560506 L102.46481,167.469367 L112.380759,155.868354 L112.315949,154.183291 L111.732658,154.183291 L44.0708861,198.124557 L32.0162025,199.68 L26.8313924,194.819241 L27.4794937,186.847595 L29.9422785,184.25519 L50.2926582,170.256203 L50.2278481,170.321013 Z"
-                    fill="currentColor"
-                />
-            </g>
-        </svg>
-    );
-}

packages/gitbook/src/components/PageActions/assets/MarkdownIcon.tsx

@@ -1,9 +0,0 @@
-export function MarkdownIcon(props: React.SVGProps<SVGSVGElement>) {
-    return (
-        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 471 289.85" {...props}>
-            <title>Markdown</title>
-            <path d="M437,289.85H34a34,34,0,0,1-34-34V34A34,34,0,0,1,34,0H437a34,34,0,0,1,34,34V255.88A34,34,0,0,1,437,289.85ZM34,22.64A11.34,11.34,0,0,0,22.64,34V255.88A11.34,11.34,0,0,0,34,267.2H437a11.34,11.34,0,0,0,11.33-11.32V34A11.34,11.34,0,0,0,437,22.64Z" />
-            <path d="M67.93,221.91v-154h45.29l45.29,56.61L203.8,67.93h45.29v154H203.8V133.6l-45.29,56.61L113.22,133.6v88.31Zm283.06,0-67.94-74.72h45.29V67.93h45.29v79.26h45.29Z" />
-        </svg>
-    );
-}

packages/gitbook/src/components/PageAside/PageAside.tsx

@@ -35,6 +35,7 @@ export function PageAside(props: {
         <aside
             className={tcls(
                 'group/aside',
+                'order-last',
                 'hidden',
                 'pt-8',
                 'pb-4',

packages/gitbook/src/components/PageAside/ScrollSectionsList.tsx

@@ -110,7 +110,7 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
                                 'opacity-8',
                                 'contrast-more:opacity-11',
 
-                                'sidebar-list-default:rounded-l-none',
+                                'sidebar-list-default:rounded-l-none!',
                                 'sidebar-list-default:border-l',
                                 'sidebar-list-default:border-tint',
                             ],

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

@@ -51,10 +51,10 @@ export function PageBody(props: {
             <main
                 className={tcls(
                     'relative min-w-0 flex-1',
-                    'mx-auto max-w-screen-2xl py-8',
+                    'max-w-screen-2xl py-8',
                     // Allow words to break if they are too long.
                     'break-anywhere',
-                    pageWidthWide ? 'page-width-wide 2xl:px-8' : 'page-width-default',
+                    pageWidthWide ? 'page-width-wide 3xl:px-8' : 'page-width-default',
                     siteWidthWide ? 'site-width-wide' : 'site-width-default',
                     page.layout.tableOfContents ? 'page-has-toc' : 'page-no-toc'
                 )}
@@ -81,7 +81,10 @@ export function PageBody(props: {
                             blockStyle="page-api-block:ml-0"
                             context={{
                                 mode: 'default',
-                                contentContext: context,
+                                contentContext: {
+                                    ...context,
+                                    page,
+                                },
                                 withLinkPreviews,
                             }}
                         />

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

@@ -1,11 +1,14 @@
 import type { GitBookSiteContext } from '@/lib/context';
 import type { AncestorRevisionPage } from '@/lib/pages';
 import { tcls } from '@/lib/tailwind';
-import type { RevisionPageDocument } from '@gitbook/api';
+import { type RevisionPageDocument, SiteVisibility } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
 import urlJoin from 'url-join';
 import { getPDFURLSearchParams } from '../PDF';
-import { PageActionsDropdown } from '../PageActions/PageActionsDropdown';
+import {
+    PageActionsDropdown,
+    type PageActionsDropdownURLs,
+} from '../PageActions/PageActionsDropdown';
 import { PageIcon } from '../PageIcon';
 import { StyledLink } from '../primitives';
 
@@ -39,28 +42,8 @@ export async function PageHeader(props: {
             {page.layout.tableOfContents ? (
                 // Show page actions if *any* of the actions are enabled
                 <PageActionsDropdown
-                    markdownPageUrl={`${context.linker.toAbsoluteURL(context.linker.toPathInSpace(page.path))}.md`}
-                    editOnGit={
-                        context.customization.git.showEditLink &&
-                        context.space.gitSync?.url &&
-                        page.git
-                            ? {
-                                  provider: context.space?.gitSync?.installationProvider,
-                                  url: urlJoin(context.space.gitSync.url, page.git.path),
-                              }
-                            : undefined
-                    }
-                    pdfUrl={
-                        context.customization.pdf.enabled
-                            ? context.linker.toPathInSpace(
-                                  `~gitbook/pdf?${getPDFURLSearchParams({
-                                      page: page.id,
-                                      only: true,
-                                      limit: 100,
-                                  }).toString()}`
-                              )
-                            : undefined
-                    }
+                    siteTitle={context.site.title}
+                    urls={getPageActionsURLs(context, page)}
                     actions={context.customization.pageActions}
                     className={tcls(
                         'float-right ml-4 xl:max-2xl:page-api-block:mr-62',
@@ -138,3 +121,38 @@ export async function PageHeader(props: {
         </header>
     );
 }
+
+/**
+ * Return the URLs for the page actions.
+ */
+function getPageActionsURLs(
+    context: GitBookSiteContext,
+    page: RevisionPageDocument
+): PageActionsDropdownURLs {
+    return {
+        html: context.linker.toAbsoluteURL(
+            context.linker.toPathForPage({ pages: context.revision.pages, page })
+        ),
+        markdown: `${context.linker.toAbsoluteURL(context.linker.toPathInSpace(page.path))}.md`,
+        editOnGit:
+            context.customization.git.showEditLink && context.space.gitSync?.url && page.git
+                ? {
+                      provider: context.space?.gitSync?.installationProvider,
+                      url: urlJoin(context.space.gitSync.url, page.git.path),
+                  }
+                : undefined,
+        pdf: context.customization.pdf.enabled
+            ? context.linker.toPathInSpace(
+                  `~gitbook/pdf?${getPDFURLSearchParams({
+                      page: page.id,
+                      only: true,
+                      limit: 100,
+                  }).toString()}`
+              )
+            : undefined,
+        mcp:
+            context.site.visibility !== SiteVisibility.VisitorAuth
+                ? context.linker.toAbsoluteURL(context.linker.toPathInSpace('~gitbook/mcp'))
+                : undefined,
+    };
+}

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

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

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

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

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

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

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

@@ -16,6 +16,7 @@ interface SearchInputProps {
     withAI: boolean;
     isOpen: boolean;
     className?: string;
+    children?: React.ReactNode;
 }
 
 // Size classes for medium size button
@@ -26,7 +27,17 @@ const sizeClasses = ['text-sm', 'px-3.5', 'py-1.5', 'md:circular-corners:px-4'];
  */
 export const SearchInput = React.forwardRef<HTMLDivElement, SearchInputProps>(
     function SearchInput(props, ref) {
-        const { onChange, onKeyDown, onFocus, value, withAI, isOpen, className } = props;
+        const {
+            onChange,
+            onKeyDown,
+            onFocus,
+            value,
+            withAI,
+            isOpen,
+            className,
+            children,
+            ...rest
+        } = props;
         const inputRef = useRef<HTMLInputElement>(null);
 
         const language = useLanguage();
@@ -61,7 +72,7 @@ export const SearchInput = React.forwardRef<HTMLDivElement, SearchInputProps>(
                         'has-[input:focus]:-translate-y-px h-9 grow cursor-pointer px-2.5 has-[input:focus]:bg-tint-base has-[input:focus]:depth-subtle:shadow-lg has-[input:focus]:depth-subtle:shadow-primary-subtle has-[input:focus-visible]:ring-2 has-[input:focus-visible]:ring-primary-hover md:cursor-text',
                         'theme-bold:border-header-link/3 has-[input:focus-visible]:theme-bold:border-header-link/5 has-[input:focus-visible]:theme-bold:bg-header-link/3 has-[input:focus-visible]:theme-bold:ring-header-link/5',
                         'theme-bold:before:absolute theme-bold:before:inset-0 theme-bold:before:bg-header-background/7 theme-bold:before:backdrop-blur-xl ', // Special overlay to make the transparent colors of theme-bold visible.
-                        'relative z-30 shrink grow justify-start max-md:absolute max-md:right-0',
+                        'relative z-30 max-w-none shrink grow justify-start max-md:absolute max-md:right-0',
                         isOpen ? 'max-md:w-56' : 'max-md:w-[38px]'
                     )}
                 >
@@ -84,8 +95,9 @@ export const SearchInput = React.forwardRef<HTMLDivElement, SearchInputProps>(
                             className="size-4 shrink-0 animate-scale-in"
                         />
                     )}
-
+                    {children}
                     <input
+                        {...rest}
                         type="text"
                         onFocus={onFocus}
                         onKeyDown={onKeyDown}
@@ -100,6 +112,12 @@ export const SearchInput = React.forwardRef<HTMLDivElement, SearchInputProps>(
                             'peer z-10 min-w-0 grow bg-transparent py-0.5 text-tint-strong theme-bold:text-header-link outline-hidden transition-[width] duration-300 contain-paint placeholder:text-tint theme-bold:placeholder:text-current theme-bold:placeholder:opacity-7',
                             isOpen ? '' : 'max-md:opacity-0'
                         )}
+                        role="combobox"
+                        autoComplete="off"
+                        aria-autocomplete="list"
+                        aria-haspopup="listbox"
+                        aria-expanded={value && isOpen ? 'true' : 'false'}
+                        // Forward
                         ref={inputRef}
                     />
                     {!isOpen ? <Shortcut /> : null}