linting

Co-authored-by: Samy Pessé <samypesse@gmail.com>

.changeset/bright-ladybugs-march.md

@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Simplify AI Chat

.changeset/cuddly-eels-live.md

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

.changeset/five-worlds-kneel.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/openapi-parser': patch
+'@gitbook/react-openapi': patch
+---
+
+Add x-gitbook-prefix and x-gitbook-token-placeholder for OpenAPI security scheme

.changeset/late-mangos-draw.md

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

.changeset/ready-ducks-burn.md

@@ -0,0 +1,5 @@
+---
+'@gitbook/react-openapi': patch
+---
+
+Fix OpenAPI basic auth placeholder

.changeset/social-berries-visit.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix links to other spaces and root page in embeddable view.

.changeset/tender-windows-double.md

@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Add a RSS feed to all pages with update blocks.

.changeset/three-melons-enjoy.md

@@ -0,0 +1,5 @@
+---
+'gitbook': patch
+---
+
+Remove hidden site spaces from navigation

.changeset/tiny-carrots-rush.md

@@ -0,0 +1,5 @@
+---
+'gitbook': patch
+---
+
+Fix hidden section not found

.changeset/wicked-hornets-crash.md

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

.changeset/yellow-jobs-nail.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/react-openapi': patch
+'gitbook': patch
+---
+
+Improve OpenAPI circular references

.github/CONTRIBUTING.md

@@ -54,10 +54,9 @@ After forking this repository, you'll want to [create a branch](https://docs.git
 #### 3. Install dependencies and run the project locally
 
 ##### Prerequisites:
-- Node.js (Version: >=20.6)
-  - Use `nvm` for easy Node management
-- [Bun](https://bun.sh/) (Version: >=1.2.15)
-  - We use a text-based lockfile which isn't supported below 1.2.15
+
+- [Node.js](https://nodejs.org/en) (see "engines" in `package.json`)
+- [Bun](https://bun.sh/) (see "packageManager" in `package.json`)
 
 ##### Setup steps:
 

.github/actions/gradual-deploy-cloudflare/action.yaml

@@ -30,7 +30,7 @@ runs:
             apiToken: ${{ inputs.apiToken }}
             accountId: ${{ inputs.accountId }}
             workingDirectory: ./
-            wranglerVersion: '4.10.0'
+            wranglerVersion: '4.43.0'
             environment: ${{ inputs.environment }}
             command: deployments status --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
 
@@ -49,7 +49,7 @@ runs:
             apiToken: ${{ inputs.apiToken }}
             accountId: ${{ inputs.accountId }}
             workingDirectory: ./
-            wranglerVersion: '4.10.0'
+            wranglerVersion: '4.43.0'
             environment: ${{ inputs.environment }}
             command: versions deploy ${{ steps.extract_current_version.outputs.version_id }}@100% ${{ inputs.serverVersionId }}@0% -y --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
 
@@ -61,7 +61,7 @@ runs:
             apiToken: ${{ inputs.apiToken }}
             accountId: ${{ inputs.accountId }}
             workingDirectory: ./
-            wranglerVersion: '4.10.0'
+            wranglerVersion: '4.43.0'
             environment: ${{ inputs.environment }}
             command: versions deploy ${{ inputs.middlewareVersionId }}@100% -y --config ./packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc
 
@@ -71,7 +71,7 @@ runs:
             apiToken: ${{ inputs.apiToken }}
             accountId: ${{ inputs.accountId }}
             workingDirectory: ./
-            wranglerVersion: '4.10.0'
+            wranglerVersion: '4.43.0'
             environment: ${{ inputs.environment }}
             command: versions deploy ${{ inputs.serverVersionId }}@100% -y --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
 

.github/composite/deploy-cloudflare/action.yaml

@@ -70,7 +70,7 @@ runs:
               apiToken: ${{ inputs.apiToken }}
               accountId: ${{ inputs.accountId }}
               workingDirectory: ./
-              wranglerVersion: '4.10.0'
+              wranglerVersion: '4.43.0'
               environment: ${{ inputs.environment }}
               command: deploy --config ./packages/gitbook/openNext/customWorkers/doWrangler.jsonc
 
@@ -81,7 +81,7 @@ runs:
               apiToken: ${{ inputs.apiToken }}
               accountId: ${{ inputs.accountId }}
               workingDirectory: ./
-              wranglerVersion: '4.10.0'
+              wranglerVersion: '4.43.0'
               environment: ${{ inputs.environment }}
               command: ${{ format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
 
@@ -104,7 +104,7 @@ runs:
               apiToken: ${{ inputs.apiToken }}
               accountId: ${{ inputs.accountId }}
               workingDirectory: ./
-              wranglerVersion: '4.10.0'
+              wranglerVersion: '4.43.0'
               environment: ${{ inputs.environment }}
               command: ${{ format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc
         

.github/workflows/ci.yaml

@@ -4,8 +4,9 @@ on:
     push:
         branches:
             - main
+            - changeset-release/main
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     format:
         runs-on: ubuntu-latest
@@ -41,7 +42,7 @@ jobs:
         name: Build (Open Source)
         timeout-minutes: 6
         env:
-            NPM_TOKEN_READONLY: ''
+            BUN_NPM_TOKEN: ''
         steps:
             - name: Checkout
               uses: actions/checkout@v4

.github/workflows/deploy-preview.yaml

@@ -5,7 +5,7 @@ on:
       branches:
         - main
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (preview)

.github/workflows/deploy-production.yaml

@@ -4,7 +4,7 @@ on:
         branches:
             - main
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (production)

.github/workflows/deploy-staging.yaml

@@ -4,7 +4,7 @@ on:
         branches:
             - main
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (staging)

.github/workflows/publish.yaml

@@ -6,7 +6,7 @@ on:
             - main
 
 env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
     
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
@@ -14,29 +14,38 @@ jobs:
     publish:
         name: Publish
         runs-on: ubuntu-latest
+        permissions:
+            id-token: write
+            pull-requests: write
+            contents: write
         steps:
             - name: Checkout Repo
               uses: actions/checkout@v3
               with:
                   # This makes Actions fetch all Git history so that Changesets can generate changelogs with the correct commits
                   fetch-depth: 0
+            - name: Setup Node
+              uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+                  registry-url: 'https://registry.npmjs.org'
+            # Ensure npm 11.5.1 or later is installed
+            - name: Update npm
+              run: npm install -g npm@latest
             - name: Setup Bun
               uses: ./.github/composite/setup-bun
             - name: Install dependencies
               run: bun install --frozen-lockfile
               env:
                   PUPPETEER_SKIP_DOWNLOAD: 1
-            - name: Create Release Pull Request or Publish to npm
+            - name: Create Release Pull Request
               id: changesets
               uses: changesets/action@v1
               with:
-                  publish: npm run release
-                  version: npm run changeset-version
+                  publish: bun run publish-all-packages
+                  version: bun run changeset-version
               env:
                   # Using a PAT instead of GITHUB_TOKEN because we need to run workflows when releases are created
                   # https://github.com/orgs/community/discussions/26875#discussioncomment-3253761
                   GITHUB_TOKEN: ${{ secrets.GH_PERSONAL_TOKEN }}
-                  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-                  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-                  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
 

.gitignore

@@ -25,3 +25,7 @@ yarn-error.log*
 
 # TypeScript
 *.tsbuildinfo
+.npmrc
+
+# Bun pack artifacts
+packages/*/*.tgz

.nvmrc

@@ -1 +1 @@
-v20.6
+v22.3

README.md

@@ -35,7 +35,7 @@ To run a local version of this project, please follow these simple steps.
 
 ### Prerequisites
 
-- Node.js (Version: >=20.6)
+- Node.js (Version: >= 22.3)
     - Use nvm for easy Node management
 - [Bun](https://bun.sh/) (Version: >=1.2.15)
   - We use a text-based lockfile which isn't supported below 1.2.15
@@ -90,7 +90,7 @@ If you are GitBook staff, you'll need our NPM token in your local environment.
 ```
 .env.local
 
-NPM_TOKEN_READONLY=xxx
+BUN_NPM_TOKEN=xxx
 ```
 
 and then reinstall dependencies.

bunfig.toml

@@ -1,2 +1,2 @@
 [install.scopes]
-"gitbook" = { token = "$NPM_TOKEN_READONLY", url = "https://registry.npmjs.org" }
+"gitbook" = { token = "$BUN_NPM_TOKEN", url = "https://registry.npmjs.org" }

package.json

@@ -1,22 +1,27 @@
 {
     "name": "gitbook",
     "version": "0.1.0",
+    "engines": {
+        "node": "^22.3.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.6.1",
+        "vercel": "^39.4.2"
     },
-    "packageManager": "bun@1.2.15",
+    "packageManager": "bun@1.3.2",
     "overrides": {
         "@codemirror/state": "6.4.1",
-        "react": "^19.0.0",
-        "react-dom": "^19.0.0",
+        "@types/react": "catalog:",
+        "@types/react-dom": "catalog:",
+        "react": "catalog:",
+        "react-dom": "catalog:",
         "esbuild": "0.24.2"
     },
     "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 +31,29 @@
         "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",
+        "publish-all-packages": "turbo run publish-to-npm --continue=dependencies-successful",
         "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.141.0",
-            "bidc": "^0.0.2"
+            "@tsconfig/strictest": "^2.0.6",
+            "@tsconfig/node20": "^20.1.6",
+            "@gitbook/api": "0.151.0",
+            "@scalar/api-client-react": "^1.3.46",
+            "@types/react": "^19.0.0",
+            "@types/react-dom": "^19.0.0",
+            "assert-never": "^1.4.0",
+            "bidc": "^0.0.2",
+            "bun-types": "^1.1.20",
+            "classnames": "^2.5.1",
+            "react": "^19.0.0",
+            "react-dom": "^19.0.0",
+            "tsdown": "^0.15.6",
+            "typescript": "^5.5.3",
+            "usehooks-ts": "^3.1.1"
         }
     },
     "patchedDependencies": {

packages/browser-types/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @gitbook/browser-types
 
+## 0.1.3
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+- Updated dependencies [10995e0]
+  - @gitbook/icons@0.3.4
+
+## 0.1.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+- Updated dependencies [6142d6b]
+  - @gitbook/icons@0.3.3
+
+## 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,17 +8,29 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.1.0",
+    "sideEffects": false,
+    "version": "0.1.3",
     "dependencies": {
         "@gitbook/api": "catalog:",
         "@gitbook/icons": "workspace:"
     },
     "devDependencies": {
-        "typescript": "^5.5.3"
+        "bun-types": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
-        "build": "tsc",
-        "typecheck": "tsc --noEmit"
+        "build": "tsdown",
+        "typecheck": "tsc --noEmit",
+        "dev": "bun run build -- --watch ./src",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md"]
+    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
+    }
 }

packages/cache-tags/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @gitbook/cache-tags
 
+## 0.3.4
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+
+## 0.3.3
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
+## 0.3.2
+
+### Patch Changes
+
+- 295f03d: Republish packages
+
 ## 0.3.1
 
 ### Patch Changes

packages/cache-tags/package.json

@@ -4,22 +4,32 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "development": "./src/index.ts",
             "default": "./dist/index.js"
         }
     },
-    "version": "0.3.1",
+    "sideEffects": false,
+    "version": "0.3.4",
     "dependencies": {
         "@gitbook/api": "catalog:",
-        "assert-never": "^1.2.1"
+        "assert-never": "catalog:"
     },
     "devDependencies": {
-        "typescript": "^5.5.3"
+        "bun-types": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
-        "build": "tsc",
+        "build": "tsdown",
         "typecheck": "tsc --noEmit",
-        "dev": "tsc -w"
+        "dev": "bun run build -- --watch ./src",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "src", "README.md", "CHANGELOG.md"]
+    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
+    }
 }

packages/colors/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @gitbook/colors
 
+## 0.4.3
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+
+## 0.4.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
+## 0.4.1
+
+### Patch Changes
+
+- 295f03d: Republish packages
+
 ## 0.4.0
 
 ### Minor Changes

packages/colors/package.json

@@ -4,18 +4,28 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "development": "./src/index.ts",
             "default": "./dist/index.js"
         }
     },
-    "version": "0.4.0",
+    "sideEffects": false,
+    "version": "0.4.3",
     "devDependencies": {
-        "typescript": "^5.5.3"
+        "bun-types": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
-        "build": "tsc",
+        "build": "tsdown",
         "typecheck": "tsc --noEmit",
-        "dev": "tsc -w"
+        "dev": "bun run build -- --watch ./src",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "src", "README.md", "CHANGELOG.md"]
+    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
+    }
 }

packages/embed/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @gitbook/embed
 
+## 0.1.5
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+- Updated dependencies [10995e0]
+  - @gitbook/icons@0.3.4
+
+## 0.1.4
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+- Updated dependencies [6142d6b]
+  - @gitbook/icons@0.3.3
+
+## 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,27 +5,44 @@
     "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",
+    "sideEffects": false,
+    "version": "0.1.5",
     "dependencies": {
         "@gitbook/api": "catalog:",
         "@gitbook/icons": "workspace:",
         "bidc": "catalog:"
     },
     "peerDependencies": {
-        "react": "^18.0.0"
+        "react": "*"
     },
     "devDependencies": {
-        "typescript": "^5.5.3",
-        "react": "^19.0.0"
+        "@types/react": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:",
+        "react": "catalog:"
     },
     "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",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md", "standalone"]
+    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
+    }
 }

packages/embed/src/react/GitBookFrame.tsx

@@ -1,4 +1,6 @@
-import React from 'react';
+'use client';
+
+import { useEffect, useMemo, useRef, useState } from 'react';
 import type {
     GetFrameURLOptions,
     GitBookEmbeddableConfiguration,
@@ -17,19 +19,19 @@ export type GitBookFrameProps = {
 export function GitBookFrame(props: GitBookFrameProps) {
     const { className, visitor, buttons, welcomeMessage, suggestions, tools } = props;
 
-    const frameRef = React.useRef<HTMLIFrameElement>(null);
+    const frameRef = useRef<HTMLIFrameElement>(null);
     const gitbook = useGitBook();
-    const [gitbookFrame, setGitbookFrame] = React.useState<GitBookFrameClient | null>(null);
+    const [gitbookFrame, setGitbookFrame] = useState<GitBookFrameClient | null>(null);
 
-    const frameURL = React.useMemo(() => gitbook.getFrameURL({ visitor }), [gitbook, visitor]);
+    const frameURL = useMemo(() => gitbook.getFrameURL({ visitor }), [gitbook, visitor]);
 
-    React.useEffect(() => {
+    useEffect(() => {
         if (frameRef.current) {
             setGitbookFrame(gitbook.createFrame(frameRef.current));
         }
     }, [gitbook]);
 
-    React.useEffect(() => {
+    useEffect(() => {
         gitbookFrame?.configure({
             buttons,
             welcomeMessage,

packages/embed/src/standalone/style.css

@@ -29,6 +29,16 @@
     --gitbook-widget-easing-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
 }
 
+@media (prefers-color-scheme: dark) {
+    :root {
+        --gitbook-widget-text-color: #FFFFFF;
+        --gitbook-widget-border-color: #202020;
+        --gitbook-widget-background-translucent: rgba(15, 15, 15, 0.9);
+        --gitbook-widget-background-translucent-hover: rgba(20, 20, 20, 0.9);
+        --gitbook-widget-background-solid: #f0f0f0;
+    }
+}
+
 * {
     box-sizing: border-box;
 }
@@ -120,7 +130,8 @@
     z-index: 9998;
     width: calc(min(var(--gitbook-widget-window-width), calc(100vw - var(--gitbook-widget-right) - var(--gitbook-widget-left))));
     height: calc(min(var(--gitbook-widget-window-height), calc(100vh - var(--gitbook-widget-window-bottom) - var(--gitbook-widget-top))));
-    background-color: var(--gitbook-widget-background-solid);
+    background-color: var(--gitbook-widget-background-translucent);
+    backdrop-filter: blur(48px);
     border: 1px solid var(--gitbook-widget-border-color);
     border-radius: var(--gitbook-widget-radius);
     box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);

packages/embed/tsdown.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig([
+    {
+        entry: 'src/index.ts',
+        outDir: 'dist',
+    },
+    {
+        entry: 'src/react/index.ts',
+        outDir: 'dist/react',
+        unbundle: true,
+    },
+]);

packages/emoji-codepoints/CHANGELOG.md

@@ -1,13 +1,25 @@
 # @gitbook/emoji-codepoints
 
+## 0.2.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
+## 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,12 +1,12 @@
 {
     "name": "@gitbook/emoji-codepoints",
     "description": "Optimized mapping of codepoints to the fully qualified emoji codepoints",
-    "version": "0.2.0",
+    "version": "0.2.2",
     "private": true,
     "exports": "./dist/index.ts",
-    "dependencies": {},
+    "sideEffects": false,
     "devDependencies": {
-        "emoji-assets": "^8.0.0"
+        "emoji-assets": "^9.0.0"
     },
     "scripts": {
         "generate": "bun ./build.ts",

packages/expr/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @gitbook/expr
 
+## 1.2.4
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+- 10995e0: Use NPM dependency for eval-estree-expression
+
+## 1.2.3
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
+## 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

packages/expr/package.json

@@ -1,37 +1,47 @@
 {
     "name": "@gitbook/expr",
     "description": "Safely evaluate & parse user-defined GitBook expressions.",
-    "version": "1.2.0",
+    "version": "1.2.4",
     "type": "module",
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "import": "./dist/index.js",
             "default": "./dist/index.js"
         }
     },
     "sideEffects": false,
     "dependencies": {
-        "eval-estree-expression": "github:jonschlinkert/eval-estree-expression#9cf28d2",
         "acorn": "^8.14.0",
         "acorn-loose": "8.4.0",
         "acorn-walk": "^8.3.4",
+        "assert-never": "catalog:",
         "escodegen": "^2.1.0",
-        "assert-never": "^1.2.1"
+        "eval-estree-expression": "github:jonschlinkert/eval-estree-expression#fb0246a"
     },
     "devDependencies": {
-        "bun-types": "^1.1.20",
-        "tsdown": "^0.15.0",
+        "@tsconfig/strictest": "catalog:",
+        "@tsconfig/node20": "catalog:",
+        "@types/escodegen": "^0.0.10",
         "@types/estree": "^1.0.6",
-        "@babel/types": "^7.26.0",
         "@types/json-schema": "^7.0.15",
-        "@types/escodegen": "^0.0.10"
+        "bun-types": "catalog:",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "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",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md"]
+    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
+    }
 }

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,23 @@
 # @gitbook/fonts
 
+## 0.1.3
+
+### Patch Changes
+
+- 10995e0: Use NPM Trusted publishing for publishing the package.
+
+## 0.1.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+
+## 0.1.1
+
+### Patch Changes
+
+- 295f03d: Republish packages
+
 ## 0.1.0
 
 ### Minor Changes

packages/fonts/package.json

@@ -4,28 +4,38 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
-            "development": "./src/index.ts",
             "default": "./dist/index.js"
         }
     },
-    "version": "0.1.0",
+    "sideEffects": false,
+    "version": "0.1.3",
     "dependencies": {
         "@gitbook/api": "catalog:"
     },
     "devDependencies": {
-        "google-font-metadata": "^6.0.3",
-        "typescript": "^5.5.3"
+        "bun-types": "catalog:",
+        "google-font-metadata": "^6.0.7",
+        "tsdown": "catalog:",
+        "typescript": "catalog:"
     },
     "scripts": {
         "generate": "bun ./bin/generate.js",
-        "build": "tsc --project tsconfig.build.json",
+        "build": "tsdown",
         "typecheck": "tsc --noEmit",
-        "dev": "tsc -w",
+        "dev": "bun run build -- --watch ./src",
         "clean": "rm -rf ./dist && rm -rf ./src/data",
-        "unit": "bun test"
+        "unit": "bun test",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "src", "bin", "README.md", "CHANGELOG.md"],
+    "files": ["dist", "bin", "README.md", "CHANGELOG.md"],
     "engines": {
         "node": ">=20.0.0"
+    },
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
     }
 }

packages/fonts/src/__snapshots__/getDefaultFont.test.ts.snap

@@ -1,57 +1,57 @@
-// Bun Snapshot v1, https://goo.gl/fbAQLP
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
 
 exports[`getDefaultFont should return correct object for Latin text 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
 }
 `;
 
 exports[`getDefaultFont should return correct object for Cyrillic text 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZthjp-Ek-_0ewmM.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZthjp-Ek-_0ewmM.woff",
 }
 `;
 
 exports[`getDefaultFont should return correct object for Greek text 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZxhjp-Ek-_0ewmM.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZxhjp-Ek-_0ewmM.woff",
 }
 `;
 
 exports[`getDefaultFont should handle mixed script text 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZthjp-Ek-_0ewmM.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZthjp-Ek-_0ewmM.woff",
 }
 `;
 
 exports[`getDefaultFont should handle different font weights: regular 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
 }
 `;
 
 exports[`getDefaultFont should handle different font weights: bold 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuFuYAZ9hjp-Ek-_0ew.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuFuYAZ9hjp-Ek-_0ew.woff",
 }
 `;
 
 exports[`getDefaultFont should handle different fonts: inter 1`] = `
 {
   "font": "Inter",
-  "url": "https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
+  "url": "https://fonts.gstatic.com/s/inter/v20/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hjp-Ek-_0ew.woff",
 }
 `;
 
 exports[`getDefaultFont should handle different fonts: roboto 1`] = `
 {
   "font": "Roboto",
-  "url": "https://fonts.gstatic.com/s/roboto/v32/KFOmCnqEu92Fr1Mu4mxMKTU1Kg.woff",
+  "url": "https://fonts.gstatic.com/s/roboto/v49/KFOMCnqEu92Fr1ME7kSn66aGLdTylUAMQXC89YmC2DPNWubEbVmUiAz0klQm_20.woff",
 }
 `;

packages/fonts/tsconfig.build.json

@@ -1,4 +0,0 @@
-{
-    "extends": "./tsconfig.json",
-    "exclude": ["node_modules", "src/**/*.test.ts"]
-}

packages/gitbook/CHANGELOG.md

@@ -1,5 +1,149 @@
 # gitbook
 
+## 0.20.0
+
+### Minor Changes
+
+- 1d92dc1: Update site layout and blocks with container queries and better transitions
+
+### Patch Changes
+
+- 8fdc5c8: Fix webframe height issue
+- 9022d87: Add breadcrumbs to search results
+- 0c01832: SearchInput fixes — Translate Clear button, Bold theme color, "Esc" keyboard shortcut
+- 1d1f0a7: Fix search container shadow
+- 2aa4f2e: Update dropdown menu styling
+- a49781e: Printable collapsed code block
+- 7d6a316: Revert contentref anchor title
+- e27986b: Reword "Everywhere" search scope to "All docs"
+- 758b34d: Move the "Ask <query>" to the bottom of search results if query is not a question
+- 0ae7cfd: Improve AI Search branding
+- f9f8011: Add alt text support to card covers
+- ebbb476: Improve ancestor label in references
+- 1b0613e: Tweak language dropdown styling
+- 3355960: Fix ToggeableLinkItem display
+- c31e564: Fix icon resolution for page group
+- 55c0b03: Support translations and generic variants together
+- 3876f70: Edgeless Assistant window on `depth: flat` sites
+- 683bb8f: Add confirmation to "Copy MCP URL" page action
+- 4534ea8: Implement unique title tags for sections & variants
+- 6d56df7: Treat pages without visible TOC items as `no-toc`
+- 8606f22: Add padding to TOC page group items
+- 3676d64: Update search scope UI
+- c32d449: Fix OpenAPI path display
+- 8ce7322: Add OpenAPI servers selection
+- 2c3066e: Improve OAuth2 scopes handling in OpenAPI
+- 6b1c9fe: Fix opacity of ScrollContainer buttons on bold themes
+- Updated dependencies [b4a021a]
+- Updated dependencies [a512c90]
+- Updated dependencies [df1966d]
+- Updated dependencies [b45feaf]
+- Updated dependencies [10995e0]
+- Updated dependencies [f9f8011]
+- Updated dependencies [10995e0]
+- Updated dependencies [8ce7322]
+- Updated dependencies [2c3066e]
+  - @gitbook/react-openapi@1.5.3
+  - @gitbook/openapi-parser@3.0.5
+  - @gitbook/react-contentkit@0.7.8
+  - @gitbook/browser-types@0.1.3
+  - @gitbook/cache-tags@0.3.4
+  - @gitbook/react-math@0.6.4
+  - @gitbook/colors@0.4.3
+  - @gitbook/embed@0.1.5
+  - @gitbook/fonts@0.1.3
+  - @gitbook/icons@0.3.4
+  - @gitbook/expr@1.2.4
+
+## 0.19.2
+
+### Patch Changes
+
+- 6142d6b: Mark as sideEffects, fix all package bundles
+- 75543b1: Update minimum Node version in .npmrc
+- 511f1cf: Add scroll margin to Expandable
+- Updated dependencies [6142d6b]
+  - @gitbook/emoji-codepoints@0.2.2
+  - @gitbook/react-contentkit@0.7.7
+  - @gitbook/openapi-parser@3.0.4
+  - @gitbook/browser-types@0.1.2
+  - @gitbook/react-openapi@1.5.2
+  - @gitbook/cache-tags@0.3.3
+  - @gitbook/react-math@0.6.3
+  - @gitbook/colors@0.4.2
+  - @gitbook/fonts@0.1.2
+  - @gitbook/icons@0.3.3
+  - @gitbook/expr@1.2.3
+
+## 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

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',
@@ -112,11 +112,11 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://adiblar.gitbook.io',
         tests: [{ name: 'Home', url: '/' }],
     },
-    {
-        name: 'docs.gradient.network',
-        contentBaseURL: 'https://docs.gradient.network',
-        tests: [{ name: 'Home', url: '/' }],
-    },
+    // {
+    //     name: 'docs.gradient.network',
+    //     contentBaseURL: 'https://docs.gradient.network',
+    //     tests: [{ name: 'Home', url: '/' }],
+    // },
     // {
     //     name: 'mygate-network.gitbook.io',
     //     contentBaseURL: 'https://mygate-network.gitbook.io',
@@ -172,11 +172,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://docs.realapp.link',
         tests: [{ name: 'Home', url: '/' }],
     },
-    {
-        name: 'docs.plaza.finance',
-        contentBaseURL: 'https://docs.plaza.finance',
-        tests: [{ name: 'Home', url: '/' }],
-    },
     {
         name: 'docs.publicai.io',
         contentBaseURL: 'https://docs.publicai.io',

packages/gitbook/e2e/internal.spec.ts

@@ -33,9 +33,35 @@ import {
     headerLinks,
     runTestCases,
     waitForCookiesDialog,
+    waitForCoverImages,
     waitForNotFound,
 } from './util';
 
+const AI_PROMPT = `You're being invoked by the GitBook CI/CD pipeline. To make screenshot testing of the GitBook Assistant visually consistent, look up the title of the first page you find and respond with only EXACTLY its title. To find the page title, invoke the search tool with the query "GitBook". Before invoking the search tool, respond with the exact text: "I'm going to look up 'GitBook' and then respond with only the page title.". Do not execute any other tools or output any other text.`;
+
+const overrideAIInitialState = () => {
+    const greeting = document.querySelector('[data-testid="ai-chat-time-greeting"]');
+    if (greeting) {
+        greeting.textContent = 'Good morning';
+    }
+};
+const overrideAIResponse = () => {
+    const userMessage = document.querySelector('[data-testid="ai-chat-message-user"]');
+    if (userMessage) {
+        userMessage.textContent = '[Replaced message] Chat message sent by the user';
+    }
+    const assistantMessage = document.querySelectorAll(
+        '[data-testid="ai-chat-message-assistant"] .ai-response-document'
+    );
+    assistantMessage.forEach((message) => {
+        message.innerHTML = '[Replaced message] AI chat response';
+    });
+    const suggestions = document.querySelectorAll('[data-testid="ai-chat-followup-suggestion"]');
+    suggestions.forEach((suggestion) => {
+        suggestion.textContent = 'Follow-up suggestion';
+    });
+};
+
 const searchTestCases: Test[] = [
     {
         name: 'Search - AI Mode: None - Complete flow',
@@ -52,7 +78,9 @@ const searchTestCases: Test[] = [
 
             // Fill search input, expecting search results
             await searchInput.fill('gitbook');
-            await expect(page.getByTestId('search-results')).toBeVisible();
+            await expect(page.getByTestId('search-results')).toBeVisible({
+                timeout: 10_000,
+            });
             const pageResults = await page.getByTestId('search-page-result').all();
             await expect(pageResults.length).toBeGreaterThanOrEqual(1);
             const pageSectionResults = await page.getByTestId('search-page-section-result').all();
@@ -97,9 +125,6 @@ const searchTestCases: Test[] = [
             await expect(page.getByTestId('search-results')).toBeVisible();
         },
     },
-    // TODO: Re-enable the following tests when we have fixed the AI Search timing out:
-    // - Search - AI Mode: Search - Complete flow
-    // - Search - AI Mode: Search - URL query (Initial)
     {
         name: 'Search - AI Mode: Search - URL query (Results)',
         url: `${getCustomizationURL({
@@ -107,16 +132,12 @@ const searchTestCases: Test[] = [
                 mode: CustomizationAIMode.Search,
             },
         })}&q=gitbook`,
-        screenshot: false,
         run: async (page) => {
             await expect(page.getByTestId('search-input')).toBeFocused();
             await expect(page.getByTestId('search-input')).toHaveValue('gitbook');
             await expect(page.getByTestId('search-results')).toBeVisible();
         },
     },
-    // TODO: Re-enable the following tests when we have fixed the AI Search timing out:
-    // - Ask - AI Mode: Search - URL query (Ask initial)
-    // - Ask - AI Mode: Search - URL query (Ask results)
     {
         name: 'Ask - AI Mode: Assistant - Complete flow',
         url: getCustomizationURL({
@@ -124,25 +145,32 @@ const searchTestCases: Test[] = [
                 mode: CustomizationAIMode.Assistant,
             },
         }),
-        screenshot: false,
         run: async (page) => {
             const searchInput = page.locator('css=[data-testid="search-input"]');
 
             // Focus search input, expecting recommended questions
             await searchInput.focus();
-            // TODO: Re-enable this part of the test when we have fixed the AI Search timing out
-            // await expect(page.getByTestId('search-results')).toBeVisible();
-            // const recommendedQuestions = await page
-            //     .getByTestId('search-recommended-question')
-            //     .all();
-            // await expect(recommendedQuestions.length).toBeGreaterThan(2); // Expect at least 3 questions
+            await expect(page.getByTestId('search-results')).toBeVisible({
+                timeout: 30_000,
+            });
+            const recommendedQuestions = await page
+                .getByTestId('search-recommended-question')
+                .all();
+            await expect(recommendedQuestions.length).toBeGreaterThan(2); // Expect at least 3 questions
 
             // Fill search input, expecting AI search option
-            await searchInput.fill('What is gitbook?');
+            await searchInput.fill(AI_PROMPT);
             const aiSearchResult = page.getByTestId('search-ask-question');
             await expect(aiSearchResult).toBeVisible();
             await aiSearchResult.click();
             await expect(page.getByTestId('ai-chat')).toBeVisible();
+            await expect(page.getByTestId('ai-chat-message-user').first()).toHaveText(AI_PROMPT);
+            await expect(page.getByTestId('ai-chat-message-assistant').first()).toBeVisible();
+            await expect(page.getByTestId('ai-chat-followup-suggestion')).toHaveCount(3, {
+                timeout: 60_000,
+            });
+            // Override text content for visual consistency in screenshots
+            await page.evaluate(overrideAIResponse);
         },
     },
     {
@@ -152,11 +180,12 @@ const searchTestCases: Test[] = [
                 mode: CustomizationAIMode.Assistant,
             },
         }),
-        screenshot: false,
         run: async (page) => {
             await page.keyboard.press('ControlOrMeta+I');
             await expect(page.getByTestId('ai-chat')).toBeVisible();
             await expect(page.getByTestId('ai-chat-input')).toBeFocused();
+            // Override text content for visual consistency in screenshots
+            await page.evaluate(overrideAIInitialState);
         },
     },
     {
@@ -171,6 +200,8 @@ const searchTestCases: Test[] = [
             await page.getByTestId('ai-chat-button').click();
             await expect(page.getByTestId('ai-chat')).toBeVisible();
             await expect(page.getByTestId('ai-chat-input')).toBeFocused();
+            // Override text content for visual consistency in screenshots
+            await page.evaluate(overrideAIInitialState);
         },
     },
     {
@@ -180,12 +211,13 @@ const searchTestCases: Test[] = [
                 mode: CustomizationAIMode.Assistant,
             },
         })}&ask=`,
-        screenshot: false,
         run: async (page) => {
             await expect(page.getByTestId('search-input')).not.toBeFocused();
-            await expect(page.getByTestId('search-input')).not.toHaveValue('What is GitBook?');
+            await expect(page.getByTestId('search-input')).toBeEmpty();
             await expect(page.getByTestId('ai-chat')).toBeVisible();
             await expect(page.getByTestId('ai-chat-input')).toBeFocused();
+            // Override text content for visual consistency in screenshots
+            await page.evaluate(overrideAIInitialState);
         },
     },
     {
@@ -194,17 +226,18 @@ const searchTestCases: Test[] = [
             ai: {
                 mode: CustomizationAIMode.Assistant,
             },
-        })}&ask=What+is+GitBook%3F`,
-        screenshot: false,
+        })}&ask=${encodeURIComponent(AI_PROMPT)}`,
         run: async (page) => {
             await expect(page.getByTestId('search-input')).not.toBeFocused();
             await expect(page.getByTestId('search-input')).not.toHaveValue('What is GitBook?');
-            await expect(page.getByTestId('ai-chat')).toBeVisible({
-                timeout: 15_000,
+            await expect(page.getByTestId('ai-chat')).toBeVisible();
+            await expect(page.getByTestId('ai-chat-message-user').first()).toHaveText(AI_PROMPT);
+            await expect(page.getByTestId('ai-chat-message-assistant').first()).toBeVisible();
+            await expect(page.getByTestId('ai-chat-followup-suggestion')).toHaveCount(3, {
+                timeout: 60_000,
             });
-            await expect(page.getByTestId('ai-chat-message').first()).toHaveText(
-                'What is GitBook?'
-            );
+            // Override text content for visual consistency in screenshots
+            await page.evaluate(overrideAIResponse);
         },
     },
 ];
@@ -228,6 +261,58 @@ const testCases: TestsCase[] = [
                     );
                 },
             },
+            {
+                name: 'Expandable TOC navigation',
+                url: '',
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+
+                    // Verify "Navigation" link is not visible initially
+                    const navigationLink = page.getByRole('link', { name: 'Navigation' });
+                    await expect(navigationLink).not.toBeVisible();
+
+                    // Find and click the chevron element that is next to "Editor" in the TOC
+                    // It is a span inside the link
+                    const editorChevron = page
+                        .getByRole('link', { name: 'Editor' })
+                        .locator('span');
+                    await editorChevron.click();
+
+                    // Verify "Navigation" link becomes visible after expansion
+                    await expect(navigationLink).toBeVisible();
+                },
+            },
+            {
+                name: 'Expandable nested TOC navigation',
+                url: '',
+                screenshot: false,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+
+                    // Verify "Spaces" link is not visible initially
+                    const navigationLink = page.getByRole('link', { name: 'Spaces' });
+                    await expect(navigationLink).not.toBeVisible();
+
+                    // Find and click the chevron element that is next to "Editor" in the TOC
+                    // It is a span inside the link
+                    const editorChevron = page
+                        .getByRole('link', { name: 'Editor' })
+                        .locator('span');
+                    await editorChevron.click();
+
+                    // At this stage the link should still not be visible
+                    await expect(navigationLink).not.toBeVisible();
+
+                    // Then we click 'Content Structure' chevron to expand further
+                    const contentStructureChevron = page
+                        .getByRole('link', { name: 'Content Structure' })
+                        .locator('span');
+                    await contentStructureChevron.click();
+
+                    // Verify "Spaces" link becomes visible after expansion
+                    await expect(navigationLink).toBeVisible();
+                },
+            },
             ...searchTestCases,
             {
                 name: 'Not found',
@@ -285,6 +370,37 @@ const testCases: TestsCase[] = [
                     ).toBeVisible();
                 },
             },
+            {
+                name: 'Switch variant with alternate link in metadata',
+                url: 'rfcs',
+                run: async (page) => {
+                    const spaceDropdown = page
+                        .locator('[data-testid="space-dropdown-button"]')
+                        .locator('visible=true');
+                    await spaceDropdown.click();
+
+                    const variantSelectionDropdown = page.locator(
+                        'css=[data-testid="dropdown-menu"]'
+                    );
+
+                    // Click the variant space called 'Multi-Variants' for which
+                    // there is an alternate link in the current (RFC variant) page metadata
+                    await variantSelectionDropdown
+                        .getByRole('menuitem', {
+                            name: 'Multi-Variants',
+                        })
+                        .click();
+
+                    // It should navigate to the alternate link defined in the metadata (a completely different page)
+                    await page.waitForURL((url) =>
+                        url.pathname.includes('multi-variants/reference/api-reference/pets')
+                    );
+                    // Verify we are on the correct page by checking the h1
+                    await expect(
+                        page.getByRole('heading', { level: 1, name: 'Pets' })
+                    ).toBeVisible();
+                },
+            },
         ],
     },
     {
@@ -727,7 +843,10 @@ const testCases: TestsCase[] = [
                 url: 'blocks/integrations',
                 run: async (page) => {
                     await waitForCookiesDialog(page);
-                    const mermaidIframe = page.locator('iframe[title*="mermaid"]').contentFrame();
+                    const mermaidIframe = page
+                        .locator('iframe[title*="mermaid"]')
+                        .first()
+                        .contentFrame();
                     await expect(mermaidIframe.getByText('Mermaid', { exact: true })).toBeVisible();
                     await expect(mermaidIframe.getByText('Diagram', { exact: true })).toBeVisible();
                 },
@@ -793,6 +912,11 @@ const testCases: TestsCase[] = [
                 url: 'blocks/cards',
                 fullPage: true,
             },
+            {
+                name: 'Updates',
+                url: 'blocks/updates',
+                fullPage: true,
+            },
             {
                 name: 'Math',
                 url: 'blocks/math',
@@ -851,7 +975,10 @@ const testCases: TestsCase[] = [
             {
                 name: 'With cover',
                 url: 'page-options/page-with-cover',
-                run: waitForCookiesDialog,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+                    await waitForCoverImages(page);
+                },
             },
             {
                 name: 'With cover for dark mode',
@@ -866,12 +993,18 @@ const testCases: TestsCase[] = [
             {
                 name: 'With hero cover',
                 url: 'page-options/page-with-hero-cover',
-                run: waitForCookiesDialog,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+                    await waitForCoverImages(page);
+                },
             },
             {
                 name: 'With cover and no TOC',
                 url: 'page-options/page-with-cover-and-no-toc',
-                run: waitForCookiesDialog,
+                run: async (page) => {
+                    await waitForCookiesDialog(page);
+                    await waitForCoverImages(page);
+                },
                 screenshot: {
                     waitForTOCScrolling: false,
                 },
@@ -1454,10 +1587,7 @@ const testCases: TestsCase[] = [
                     locale,
                 },
             }),
-            run: async (page) => {
-                const dialog = page.getByTestId('cookies-dialog');
-                await expect(dialog).toBeVisible();
-            },
+            run: waitForCookiesDialog,
         })),
     },
     {

packages/gitbook/e2e/util.ts

@@ -143,7 +143,10 @@ export const headerLinks: CustomizationHeaderItem[] = [
 
 export async function waitForCookiesDialog(page: Page) {
     const dialog = page.getByTestId('cookies-dialog');
-    await expect(dialog).toBeVisible();
+    await expect(dialog).toBeVisible({
+        // Cookies dialog may take some times to appear
+        timeout: 10_000,
+    });
 }
 
 export async function waitForNotFound(_page: Page, response: Response | null) {
@@ -151,6 +154,13 @@ export async function waitForNotFound(_page: Page, response: Response | null) {
     expect(response?.status()).toBe(404);
 }
 
+export async function waitForCoverImages(page: Page) {
+    // Wait for cover images to exist (not the shimmer placeholder)
+    await expect(page.locator('img[alt="Page cover"]').first()).toBeVisible({
+        timeout: 10_000,
+    });
+}
+
 /**
  * Transform test cases into Playwright tests and run it.
  */

packages/gitbook/open-next.config.ts

@@ -7,7 +7,8 @@ export default {
             converter: 'edge',
             proxyExternalRequest: 'fetch',
             queue: () => import('./openNext/queue/middleware').then((m) => m.default),
-            incrementalCache: () => import('./openNext/incrementalCache').then((m) => m.default),
+            incrementalCache: () =>
+                import('./openNext/incrementalCache/server').then((m) => m.default),
             tagCache: () => import('./openNext/tagCache/middleware').then((m) => m.default),
         },
     },
@@ -18,7 +19,8 @@ export default {
             converter: 'edge',
             proxyExternalRequest: 'fetch',
             queue: () => import('./openNext/queue/middleware').then((m) => m.default),
-            incrementalCache: () => import('./openNext/incrementalCache').then((m) => m.default),
+            incrementalCache: () =>
+                import('./openNext/incrementalCache/middleware').then((m) => m.default),
             tagCache: () => import('./openNext/tagCache/middleware').then((m) => m.default),
         },
     },

packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc

@@ -1,15 +1,13 @@
 {
     "main": "default.js",
     "name": "gitbook-open-v2-server",
+    "keep_names": false,
     "compatibility_date": "2025-04-14",
     "compatibility_flags": [
         "nodejs_compat",
         "allow_importable_env",
         "global_fetch_strictly_public"
     ],
-    "observability": {
-        "enabled": true
-    },
     "vars": {
         "NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE": "true"
     },

packages/gitbook/openNext/customWorkers/doWrangler.jsonc

@@ -2,14 +2,12 @@
     "main": "do.js",
     "name": "gitbook-open-v2-do",
     "compatibility_date": "2025-04-14",
+    "keep_names": false,
     "compatibility_flags": [
         "nodejs_compat",
         "allow_importable_env",
         "global_fetch_strictly_public"
     ],
-    "observability": {
-        "enabled": true
-    },
     "env": {
         "preview": {
             "vars": {

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/customWorkers/middlewareWrangler.jsonc

@@ -2,6 +2,7 @@
     "main": "middleware.js",
     "name": "gitbook-open-v2",
     "compatibility_date": "2025-04-14",
+    "keep_names": false,
     "compatibility_flags": [
         "nodejs_compat",
         "allow_importable_env",
@@ -11,9 +12,6 @@
         "directory": "../../.open-next/assets",
         "binding": "ASSETS"
     },
-    "observability": {
-        "enabled": true
-    },
     "vars": {
         "NEXT_CACHE_DO_QUEUE_DISABLE_SQLITE": "true"
     },

packages/gitbook/openNext/incrementalCache/incrementalCache.ts

@@ -18,15 +18,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 {
+export class GitbookIncrementalCache implements IncrementalCache {
     name = 'GitbookIncrementalCache';
 
-    protected localCache: Cache | undefined;
-
     async get<CacheType extends CacheEntryType = 'cache'>(
         key: string,
         cacheType?: CacheType
@@ -34,7 +31,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 +38,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 +75,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 +86,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 +119,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 +134,4 @@ 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();

packages/gitbook/openNext/incrementalCache/middleware.ts

@@ -0,0 +1,11 @@
+import { withRegionalCache } from '@opennextjs/cloudflare/overrides/incremental-cache/regional-cache';
+import { GitbookIncrementalCache } from './incrementalCache';
+
+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/openNext/incrementalCache/server.ts

@@ -0,0 +1,12 @@
+import { withRegionalCache } from '@opennextjs/cloudflare/overrides/incremental-cache/regional-cache';
+import { GitbookIncrementalCache } from './incrementalCache';
+
+export default withRegionalCache(new GitbookIncrementalCache(), {
+    mode: 'long-lived',
+    // Because of a race condition, the middleware may have populated the cache entry before `cache.match` had time to run on the server.
+    // TODO: We should bypass the incremental cache entirely when the interceptor has caught the request. Should be done in OpenNext.
+    bypassTagCacheOnCacheHit: false,
+    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,20 +1,25 @@
 {
     "name": "gitbook",
-    "version": "0.18.0",
+    "version": "0.20.0",
     "private": true,
     "dependencies": {
+        "@cloudflare/workers-types": "^4.20251011.0",
         "@gitbook/api": "catalog:",
         "@gitbook/browser-types": "workspace:*",
         "@gitbook/cache-tags": "workspace:*",
         "@gitbook/colors": "workspace:*",
+        "@gitbook/embed": "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/aws": "^3.8.5",
+        "@opennextjs/cloudflare": "^1.11.0",
         "@radix-ui/react-checkbox": "^1.0.4",
         "@radix-ui/react-dropdown-menu": "^2.1.12",
         "@radix-ui/react-hover-card": "^1.1.15",
@@ -26,19 +31,17 @@
         "@tailwindcss/typography": "^0.5.16",
         "@tusbar/cache-control": "^1.0.2",
         "ai": "^4.2.2",
-        "assert-never": "^1.2.1",
+        "assert-never": "catalog:",
         "bidc": "catalog:",
-        "bun-types": "^1.1.20",
-        "classnames": "^2.5.1",
+        "classnames": "catalog:",
         "direction": "^2.0.1",
         "event-iterator": "^2.0.0",
-        "framer-motion": "^10.16.14",
+        "feed": "^5.1.0",
         "image-size": "^2.0.2",
         "js-cookie": "^3.0.5",
         "jsontoxml": "^1.0.1",
         "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,15 +49,17 @@
         "memoizee": "^0.4.17",
         "micromark-extension-frontmatter": "^2.0.0",
         "micromark-extension-gfm": "^3.0.0",
-        "motion": "^12.23.12",
+        "motion": "^12.23.24",
         "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",
         "openapi-types": "^12.1.3",
         "p-map": "^7.0.3",
         "quick-lru": "^7.0.1",
+        "react": "catalog:",
+        "react-dom": "catalog:",
         "react-hotkeys-hook": "^4.4.1",
         "rehype-sanitize": "^6.0.0",
         "rehype-stringify": "^10.0.1",
@@ -70,16 +75,15 @@
         "unist-util-remove": "^4.0.0",
         "unist-util-visit": "^5.0.0",
         "url-join": "^5.0.0",
-        "usehooks-ts": "^3.1.0",
+        "usehooks-ts": "catalog:",
         "warn-once": "^0.1.1",
-        "zustand": "^5.0.3",
-        "mcp-handler": "^1.0.2",
-        "@modelcontextprotocol/sdk": "^1.17.5",
-        "zod": "^3"
+        "zod": "^3",
+        "zustand": "^5.0.3"
     },
     "devDependencies": {
         "@argos-ci/playwright": "^5.0.9",
         "@playwright/test": "^1.54.2",
+        "@scalar/api-client-react": "catalog:",
         "@tailwindcss/postcss": "^4.1.11",
         "@types/js-cookie": "^3.0.6",
         "@types/jsontoxml": "^1.0.5",
@@ -88,9 +92,10 @@
         "@types/node": "^20",
         "@types/object-hash": "^3.0.6",
         "@types/parse-cache-control": "^1.0.4",
-        "@types/react": "18.3.13",
-        "@types/react-dom": "18.3.1",
+        "@types/react": "catalog:",
+        "@types/react-dom": "catalog:",
         "@types/rison": "^0.0.9",
+        "bun-types": "catalog:",
         "deepmerge": "^4.3.1",
         "env-cmd": "^10.1.0",
         "jsonwebtoken": "^9.0.2",
@@ -98,8 +103,10 @@
         "stylelint": "^16.16.0",
         "tailwindcss": "^4.1.11",
         "ts-essentials": "^10.0.1",
-        "typescript": "^5.5.3",
-        "vercel": "^39.3.0"
+        "typescript": "catalog:",
+        "vercel": "^39.3.0",
+        "wrangler": "^4.43.0",
+        "rss-parser": "^3.13.0"
     },
     "scripts": {
         "generate": "./scripts/generate.sh",
@@ -120,5 +127,9 @@
     },
     "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/dynamic/[mode]/[siteURL]/[siteData]/(content)/layout.tsx

@@ -22,7 +22,11 @@ export default async function SiteDynamicLayout({
     const withTracking = shouldTrackEvents(await headers());
 
     return (
-        <CustomizationRootLayout forcedTheme={forcedTheme} context={context}>
+        <CustomizationRootLayout
+            className="site-background"
+            forcedTheme={forcedTheme}
+            context={context}
+        >
             <SiteLayout
                 context={context}
                 forcedTheme={forcedTheme}

packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx

@@ -1,16 +1,7 @@
-import type { RouteLayoutParams } from '@/app/utils';
 import { EmbeddableAssistantPage } from '@/components/Embeddable';
-import { getEmbeddableDynamicContext } from '@/lib/embeddable';
 
 export const dynamic = 'force-static';
 
-type PageProps = {
-    params: Promise<RouteLayoutParams>;
-};
-
-export default async function Page(props: PageProps) {
-    const params = await props.params;
-    const { context } = await getEmbeddableDynamicContext(params);
-
-    return <EmbeddableAssistantPage context={context} />;
+export default async function Page() {
+    return <EmbeddableAssistantPage />;
 }

packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/(content)/layout.tsx

@@ -19,7 +19,7 @@ export default async function SiteStaticLayout({
     const withTracking = shouldTrackEvents();
 
     return (
-        <CustomizationRootLayout context={context}>
+        <CustomizationRootLayout className="site-background" context={context}>
             <SiteLayout
                 context={context}
                 withTracking={withTracking}

packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/~gitbook/embed/assistant/page.tsx

@@ -1,16 +1,7 @@
-import type { RouteLayoutParams } from '@/app/utils';
 import { EmbeddableAssistantPage } from '@/components/Embeddable';
-import { getEmbeddableStaticContext } from '@/lib/embeddable';
 
 export const dynamic = 'force-static';
 
-type PageProps = {
-    params: Promise<RouteLayoutParams>;
-};
-
-export default async function Page(props: PageProps) {
-    const params = await props.params;
-    const { context } = await getEmbeddableStaticContext(params);
-
-    return <EmbeddableAssistantPage context={context} />;
+export default async function Page() {
+    return <EmbeddableAssistantPage />;
 }

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/rss/[pagePath]/route.ts

@@ -0,0 +1,12 @@
+import { type RouteParams, getPagePathFromParams, getStaticSiteContext } from '@/app/utils';
+import { servePageRSS } from '@/routes/rss';
+import type { NextRequest } from 'next/server';
+
+export const dynamic = 'force-static';
+
+export async function GET(_request: NextRequest, { params }: { params: Promise<RouteParams> }) {
+    const { context } = await getStaticSiteContext(await params);
+    const pathname = getPagePathFromParams(await params);
+
+    return servePageRSS(context, pathname);
+}

packages/gitbook/src/components/AI/server-actions/AIMessageView.tsx

@@ -16,14 +16,14 @@ export function AIMessageView(
 ) {
     const { message, context, withToolCalls = true, withLinkPreviews = true } = props;
 
-    return (
+    return message.steps.length > 0 ? (
         <div className="flex flex-col gap-2">
             {message.steps.map((step, index) => {
                 return (
                     <div
                         key={index}
                         className={tcls(
-                            'flex animate-fade-in-slow flex-col gap-2',
+                            'flex flex-col gap-2',
                             step.content.nodes.length > 0 ? 'has-content' : ''
                         )}
                     >
@@ -35,7 +35,7 @@ export function AIMessageView(
                                 wrapBlocksInSuspense: false,
                                 withLinkPreviews,
                             }}
-                            style="mt-2 space-y-4 empty:hidden"
+                            style="ai-response-document mt-2 space-y-4 *:origin-top-left *:animate-blur-in-slow"
                         />
 
                         {withToolCalls && step.toolCalls && step.toolCalls.length > 0 ? (
@@ -45,5 +45,5 @@ export function AIMessageView(
                 );
             })}
         </div>
-    );
+    ) : null;
 }

packages/gitbook/src/components/AI/server-actions/AIToolCallsSummary.tsx

@@ -39,7 +39,7 @@ function ToolCallSummary(props: { toolCall: AIToolCall; context: GitBookSiteCont
     const { toolCall, context } = props;
 
     return (
-        <div className="flex origin-left animate-scale-in-slow items-start gap-2 text-sm text-tint-subtle">
+        <div className="mt-2 flex origin-top-left animate-blur-in-slow items-start gap-2 text-sm text-tint-subtle">
             <Icon
                 icon={getIconForToolCall(toolCall)}
                 className="mt-1 size-3 shrink-0 text-tint-subtle/8"
@@ -160,7 +160,7 @@ async function DescriptionForSearchToolCall(props: {
     const hasResults = toolCall.results.length > 0;
 
     return (
-        <details className={tcls('-ml-5 group flex w-full flex-col', hasResults ? 'gap-2' : '')}>
+        <details className="-ml-5 group flex w-full flex-col">
             <summary
                 className={tcls(
                     '-mx-2 flex list-none items-center gap-2 circular-corners:rounded-2xl rounded-corners:rounded-md pr-4 pl-7 transition-colors marker:hidden',
@@ -187,7 +187,7 @@ async function DescriptionForSearchToolCall(props: {
                 ) : null}
             </summary>
             {hasResults ? (
-                <div className="hide-scrollbar mt-1 max-h-0 overflow-y-auto circular-corners:rounded-2xl rounded-corners:rounded-lg border border-tint-subtle p-2 opacity-0 transition-all transition-discrete duration-500 group-open:max-h-96 group-open:opacity-11">
+                <div className="hide-scrollbar mt-4 max-h-0 overflow-y-auto circular-corners:rounded-2xl rounded-corners:rounded-lg border border-tint-subtle p-2 opacity-0 transition-all transition-discrete duration-500 group-open:max-h-96 group-open:opacity-11">
                     <ol className="space-y-1">
                         {searchResultsWithHrefs.map((result, index) => (
                             <li

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

@@ -1,14 +1,14 @@
 'use client';
 
 import { CustomizationAIMode } from '@gitbook/api';
-import { Icon, type IconName, IconStyle } from '@gitbook/icons';
+import { Icon, type IconName } from '@gitbook/icons';
 import * as React from 'react';
 import type { ReactNode } from 'react';
 
 import { tString, useLanguage } from '@/intl/client';
 import type { GitBookAssistant } from '@gitbook/browser-types';
 import { useAIChatController, useAIChatState } from '.';
-import { AIChatIcon, getAIChatName } from '../AIChat';
+import { AIChatIcon, AISearchIcon, getAIChatName } from '../AIChat';
 import { useIntegrationAssistants } from '../Integrations';
 import { useSearch } from '../Search/useSearch';
 
@@ -104,16 +104,7 @@ export function useAI(): AIContext {
         assistants.push({
             id: 'gitbook-ai-search',
             label: tString(language, 'ai_chat_context_badge'),
-            icon: (
-                <div className="relative">
-                    <Icon icon="search" className="size-4" />
-                    <Icon
-                        icon="sparkle"
-                        iconStyle={IconStyle.Solid}
-                        className="absolute top-[2.5px] left-[2.6px] size-2"
-                    />
-                </div>
-            ),
+            icon: <AISearchIcon />,
             open: (query?: string) => {
                 if (query) {
                     setSearchState((prev) =>

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

@@ -21,7 +21,6 @@ export type AIChatMessage = {
     role: AIMessageRole;
     content: React.ReactNode;
     query?: string;
-    note?: string;
 };
 
 export type AIChatPendingTool = {
@@ -392,11 +391,11 @@ export function AIChatProvider(props: {
                 return {
                     ...state,
                     messages: [
+                        ...state.messages,
                         {
                             role: AIMessageRole.User,
                             content: input.message,
                             query: input.message,
-                            note: state.messages.length > 0 ? 'Starting a new chat' : undefined,
                         },
                     ],
                     query: input.message,

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

@@ -2,12 +2,14 @@
 
 import { t, tString, useLanguage } from '@/intl/client';
 import type { TranslationLanguage } from '@/intl/translations';
+import { tcls } from '@/lib/tailwind';
 import { Icon } from '@gitbook/icons';
 import React from 'react';
 import { useHotkeys } from 'react-hotkeys-hook';
 import {
     type AIChatController,
     type AIChatState,
+    useAI,
     useAIChatController,
     useAIChatState,
 } from '../AI';
@@ -23,15 +25,15 @@ import {
 import { useTrackEvent } from '../Insights';
 import { useNow } from '../hooks';
 import { Button } from '../primitives';
+import { ScrollContainer } from '../primitives/ScrollContainer';
 import { AIChatControlButton } from './AIChatControlButton';
 import { AIChatIcon } from './AIChatIcon';
 import { AIChatInput } from './AIChatInput';
 import { AIChatMessages } from './AIChatMessages';
 import AIChatSuggestedQuestions from './AIChatSuggestedQuestions';
 
-export function AIChat(props: { trademark: boolean }) {
-    const { trademark } = props;
-
+export function AIChat() {
+    const { config } = useAI();
     const language = useLanguage();
     const chat = useAIChatState();
     const chatController = useAIChatController();
@@ -65,21 +67,22 @@ export function AIChat(props: { trademark: boolean }) {
         }
     }, [chat.opened, trackEvent]);
 
-    if (!chat.opened) {
-        return null;
-    }
-
     return (
         <div
             data-testid="ai-chat"
-            className="ai-chat inset-y-0 right-0 z-40 mx-auto flex max-w-3xl animate-present scroll-mt-36 px-4 py-4 transition-all duration-300 sm:px-6 lg:fixed lg:w-80 lg:animate-enter-from-right lg:pr-4 lg:pl-0 xl:w-96"
+            className={tcls(
+                'ai-chat inset-y-0 right-0 z-40 mx-auto flex max-w-3xl scroll-mt-36 px-4 py-4 transition-[width,opacity,margin,display] transition-discrete duration-300 sm:px-6 lg:fixed lg:w-80 lg:p-0 xl:w-96',
+                chat.opened
+                    ? 'lg:starting:ml-0 lg:starting:w-0 lg:starting:opacity-0'
+                    : 'hidden lg:ml-0 lg:w-0! lg:opacity-0'
+            )}
         >
-            <EmbeddableFrame className="relative circular-corners:rounded-3xl rounded-corners:rounded-md depth-subtle:shadow-lg shadow-tint ring-1 ring-tint-subtle">
+            <EmbeddableFrame className="relative shrink-0 border-tint-subtle border-l to-tint-base transition-all duration-300 max-lg:circular-corners:rounded-3xl max-lg:rounded-corners:rounded-md max-lg:border lg:w-80 xl:w-96">
                 <EmbeddableFrameHeader>
-                    <AIChatDynamicIcon trademark={trademark} />
+                    <AIChatDynamicIcon trademark={config.trademark} />
                     <EmbeddableFrameHeaderMain>
                         <EmbeddableFrameTitle>
-                            {getAIChatName(language, trademark)}
+                            {getAIChatName(language, config.trademark)}
                         </EmbeddableFrameTitle>
                         <AIChatSubtitle chat={chat} />
                     </EmbeddableFrameHeaderMain>
@@ -96,7 +99,7 @@ export function AIChat(props: { trademark: boolean }) {
                     </EmbeddableFrameButtons>
                 </EmbeddableFrameHeader>
                 <EmbeddableFrameBody>
-                    <AIChatBody chatController={chatController} chat={chat} trademark={trademark} />
+                    <AIChatBody chatController={chatController} chat={chat} />
                 </EmbeddableFrameBody>
             </EmbeddableFrame>
         </div>
@@ -143,10 +146,33 @@ export function AIChatSubtitle(props: {
     const language = useLanguage();
 
     return (
-        <EmbeddableFrameSubtitle className={chat.loading ? 'h-3 opacity-11' : 'h-0 opacity-0'}>
-            {chat.messages[chat.messages.length - 1]?.content
-                ? tString(language, 'ai_chat_working')
-                : tString(language, 'ai_chat_thinking')}
+        <EmbeddableFrameSubtitle
+            className={tcls('relative', chat.loading ? 'h-3 opacity-11' : 'h-0 opacity-0')}
+        >
+            <span
+                className={tcls(
+                    'absolute left-0',
+                    chat.loading
+                        ? chat.messages[chat.messages.length - 1]?.content
+                            ? 'animate-blur-in-slow'
+                            : 'hidden'
+                        : 'animate-blur-out-slow'
+                )}
+            >
+                {t(language, 'ai_chat_working')}
+            </span>
+            <span
+                className={tcls(
+                    'absolute left-0',
+                    chat.loading
+                        ? chat.messages[chat.messages.length - 1]?.content
+                            ? 'animate-blur-out-slow'
+                            : 'animate-blur-in-slow'
+                        : 'hidden'
+                )}
+            >
+                {t(language, 'ai_chat_thinking')}
+            </span>
         </EmbeddableFrameSubtitle>
     );
 }
@@ -157,20 +183,13 @@ export function AIChatSubtitle(props: {
 export function AIChatBody(props: {
     chatController: AIChatController;
     chat: AIChatState;
-    trademark: boolean;
     welcomeMessage?: string;
     suggestions?: string[];
 }) {
-    const { chatController, chat, trademark, suggestions } = props;
+    const { chatController, chat, suggestions } = props;
+    const { trademark } = useAI().config;
 
     const [input, setInput] = React.useState('');
-
-    const scrollContainerRef = React.useRef<HTMLDivElement>(null);
-    // Ref for the last user message element
-    const lastUserMessageRef = React.useRef<HTMLDivElement>(null);
-    const inputRef = React.useRef<HTMLDivElement>(null);
-
-    const [inputHeight, setInputHeight] = React.useState(0);
     const language = useLanguage();
     const now = useNow(60 * 60 * 1000); // Refresh every hour for greeting
 
@@ -184,67 +203,43 @@ export function AIChatBody(props: {
         return tString(language, 'ai_chat_assistant_greeting_evening');
     }, [now, language]);
 
-    // Auto-scroll to the latest user message when messages change
-    React.useEffect(() => {
-        if (chat.messages.length > 0 && lastUserMessageRef.current) {
-            lastUserMessageRef.current.scrollIntoView({
-                behavior: 'smooth',
-                block: 'start',
-            });
-        }
-    }, [chat.messages.length]);
-
-    React.useEffect(() => {
-        const timeout = setTimeout(() => {
-            if (lastUserMessageRef.current) {
-                lastUserMessageRef.current.scrollIntoView({
-                    behavior: 'smooth',
-                    block: 'start',
-                });
-            }
-        }, 100);
-
-        // We want the chat messages to scroll underneath the input, but they should scroll past the input when scrolling all the way down.
-        // The best way to do this is to observe the input height and adjust the padding bottom of the scroll container accordingly.
-        const observer = new ResizeObserver((entries) => {
-            entries.forEach((entry) => {
-                setInputHeight(entry.contentRect.height + 32);
-            });
-        });
-        if (inputRef.current) {
-            observer.observe(inputRef.current);
-        }
-        return () => {
-            observer.disconnect();
-            clearTimeout(timeout);
-        };
-    }, []);
-
     return (
         <>
-            <div
-                ref={scrollContainerRef}
-                className="gutter-stable flex grow scroll-pt-4 flex-col gap-4 overflow-y-auto p-4"
-                style={{
-                    paddingBottom: `${inputHeight}px`,
-                }}
+            <ScrollContainer
+                className="shrink grow basis-80 animate-fade-in-slow [container-type:size]"
+                contentClassName="p-4 gutter-stable flex flex-col gap-4"
+                orientation="vertical"
+                fadeEdges={['leading']}
+                active={`message-group-${chat.messages.filter((message) => message.role === 'user').length - 1}`}
             >
                 {isEmpty ? (
-                    <div className="flex min-h-full w-full shrink-0 flex-col items-center justify-center gap-6 py-4">
-                        <div className="flex size-32 animate-fade-in-slow items-center justify-center rounded-full bg-tint-subtle">
-                            <AIChatIcon
-                                state="intro"
-                                trademark={trademark}
-                                className="size-16 animate-[present_500ms_200ms_both]"
-                            />
-                        </div>
-                        <div className="animate-[fadeIn_500ms_400ms_both]">
-                            <h5 className=" text-center font-bold text-lg text-tint-strong">
-                                {timeGreeting}
-                            </h5>
-                            <p className="text-center text-tint">
-                                {t(language, 'ai_chat_assistant_description')}
-                            </p>
+                    <div className="flex grow flex-col">
+                        <div className="my-auto flex flex-row items-center gap-4 pb-6 [@container(min-height:400px)]:flex-col">
+                            <div
+                                className="flex size-16 shrink-0 animate-scale-in items-center justify-center rounded-full bg-primary-solid/1 [@container(min-height:400px)]:size-32"
+                                style={{ animationDelay: '.3s' }}
+                            >
+                                <AIChatIcon
+                                    state="intro"
+                                    trademark={trademark}
+                                    className="size-8 text-primary [@container(min-height:400px)]:size-16"
+                                />
+                            </div>
+                            <div className="flex flex-col items-start [@container(min-height:400px)]:items-center">
+                                <h5
+                                    className="animate-blur-in-slow font-bold text-lg text-tint-strong [@container(min-height:400px)]:text-center"
+                                    style={{ animationDelay: '.5s' }}
+                                    data-testid="ai-chat-time-greeting"
+                                >
+                                    {timeGreeting}
+                                </h5>
+                                <p
+                                    className="animate-blur-in-slow text-tint [@container(min-height:400px)]:text-center"
+                                    style={{ animationDelay: '.6s' }}
+                                >
+                                    {t(language, 'ai_chat_assistant_description')}
+                                </p>
+                            </div>
                         </div>
                         {!chat.error ? (
                             <AIChatSuggestedQuestions
@@ -254,17 +249,11 @@ export function AIChatBody(props: {
                         ) : null}
                     </div>
                 ) : (
-                    <AIChatMessages
-                        chat={chat}
-                        chatController={chatController}
-                        lastUserMessageRef={lastUserMessageRef}
-                    />
+                    <AIChatMessages chat={chat} chatController={chatController} />
                 )}
-            </div>
-            <div
-                ref={inputRef}
-                className="absolute inset-x-0 bottom-0 mr-2 flex select-none flex-col gap-4 bg-linear-to-b from-transparent to-50% to-tint-base/9 p-4 pr-2"
-            >
+            </ScrollContainer>
+
+            <div className="flex flex-col gap-2 px-4 pb-4">
                 {/* Display an error banner when something went wrong. */}
                 {chat.error ? <AIChatError chatController={chatController} /> : null}
 

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-2xl:[&_.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/AIChatIcon.tsx

@@ -1,5 +1,5 @@
 import { tcls } from '@/lib/tailwind';
-import { Icon } from '@gitbook/icons';
+import { Icon, IconStyle } from '@gitbook/icons';
 import type React from 'react';
 
 interface AIChatIconProps extends React.SVGProps<SVGSVGElement> {
@@ -9,17 +9,18 @@ interface AIChatIconProps extends React.SVGProps<SVGSVGElement> {
     trademark?: boolean;
 }
 
-export const AIChatIcon = ({
+export function AIChatIcon({
     className = 'size-4',
     size,
     trademark = true,
     state = 'default',
     ...props
-}: AIChatIconProps) => {
+}: AIChatIconProps) {
     if (!trademark) {
         return (
             <Icon
                 icon="sparkle"
+                {...props}
                 className={tcls(
                     className,
                     (state === 'thinking' || state === 'working') &&
@@ -163,4 +164,36 @@ export const AIChatIcon = ({
             </g>
         </svg>
     );
-};
+}
+
+export function AISearchIcon({
+    className = 'size-4',
+    state = 'default',
+}: Pick<AIChatIconProps, 'className' | 'state'>) {
+    return (
+        <div
+            className={tcls(
+                'relative',
+                state === 'intro' && 'animate-[fadeIn_1s_both,orbit_1s_cubic-bezier(0.16,1,0.3,1)]',
+                state === 'thinking' || state === 'working'
+                    ? 'animate-[fadeIn_1s_both,orbit_1s_ease-out,orbit_2s_1s_infinite_forwards_linear]'
+                    : ''
+            )}
+        >
+            <Icon icon="search" className={className} />
+            <Icon
+                icon="sparkle"
+                iconStyle={IconStyle.Solid}
+                className={tcls(
+                    'absolute top-[15.7%] left-[15.6%] size-[50%]',
+                    state === 'thinking' || state === 'working'
+                        ? 'animate-[spin_2s_infinite_forwards_cubic-bezier(0.16,1,0.3,1)]'
+                        : '',
+                    state === 'intro'
+                        ? 'animate-[spin_2s_.5s_forwards_cubic-bezier(0.16,1,0.3,1)]'
+                        : ''
+                )}
+            />
+        </div>
+    );
+}

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

@@ -3,6 +3,7 @@ import { tcls } from '@/lib/tailwind';
 import { Icon } from '@gitbook/icons';
 import { useEffect, useRef } from 'react';
 import { useHotkeys } from 'react-hotkeys-hook';
+import { useAIChatState } from '../AI/useAIChat';
 import { Button, HoverCard, HoverCardRoot, HoverCardTrigger } from '../primitives';
 import { KeyboardShortcut } from '../primitives/KeyboardShortcut';
 
@@ -19,6 +20,7 @@ export function AIChatInput(props: {
     const { value, onChange, onSubmit, disabled, loading } = props;
 
     const language = useLanguage();
+    const chat = useAIChatState();
 
     const inputRef = useRef<HTMLTextAreaElement>(null);
 
@@ -32,7 +34,7 @@ export function AIChatInput(props: {
     };
 
     useEffect(() => {
-        if (!disabled && !loading) {
+        if (chat.opened && !disabled && !loading) {
             // Add a small delay to ensure the input is rendered before focusing
             // This fixes inconsistent focus behaviour across browsers
             const timeout = setTimeout(() => {
@@ -41,7 +43,7 @@ export function AIChatInput(props: {
 
             return () => clearTimeout(timeout);
         }
-    }, [disabled, loading]);
+    }, [disabled, loading, chat.opened]);
 
     useHotkeys(
         'mod+i',
@@ -55,7 +57,7 @@ export function AIChatInput(props: {
     );
 
     return (
-        <div className="depth-subtle:has-[textarea:focus]:-translate-y-px relative flex flex-col overflow-hidden circular-corners:rounded-2xl rounded-corners:rounded-md bg-tint-base/9 depth-subtle:shadow-sm shadow-tint/6 ring-1 ring-tint-subtle backdrop-blur-lg transition-all depth-subtle:has-[textarea:focus]:shadow-lg has-[textarea:focus]:shadow-primary-subtle has-[textarea:focus]:ring-2 has-[textarea:focus]:ring-primary-hover contrast-more:bg-tint-base dark:shadow-tint-1">
+        <div className="depth-subtle:has-[textarea:focus]:-translate-y-px relative flex animate-blur-in-slow flex-col overflow-hidden circular-corners:rounded-3xl rounded-corners:rounded-xl bg-tint-base/9 depth-subtle:shadow-sm shadow-tint/6 ring-1 ring-tint-subtle backdrop-blur-lg transition-all depth-subtle:has-[textarea:focus]:shadow-lg has-[textarea:focus]:shadow-primary-subtle has-[textarea:focus]:ring-2 has-[textarea:focus]:ring-primary-hover contrast-more:bg-tint-base dark:shadow-tint-1">
             <textarea
                 ref={inputRef}
                 disabled={disabled || loading}
@@ -106,7 +108,7 @@ export function AIChatInput(props: {
                 </div>
             ) : null}
             <div className="absolute inset-x-0 bottom-0 flex items-center gap-2 px-2 py-2">
-                <HoverCardRoot>
+                <HoverCardRoot openDelay={500}>
                     <HoverCard
                         className="max-w-xs bg-tint p-2 text-sm text-tint"
                         arrow={{ className: 'fill-tint-3' }}
@@ -140,7 +142,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/AIChat/AIChatMessages.tsx

@@ -2,62 +2,90 @@ import { useLanguage } from '@/intl/client';
 import { tString } from '@/intl/translate';
 import { tcls } from '@/lib/tailwind';
 import { AIMessageRole } from '@gitbook/api';
-import type React from 'react';
 import type { AIChatController, AIChatState } from '../AI';
 import { AIChatToolConfirmations } from './AIChatToolConfirmations';
 import { AIResponseFeedback } from './AIResponseFeedback';
+import { AIChatFollowupSuggestions } from './AiChatFollowupSuggestions';
 
 export function AIChatMessages(props: {
     chat: AIChatState;
     chatController: AIChatController;
-    lastUserMessageRef?: React.RefObject<HTMLDivElement>;
 }) {
-    const { chat, lastUserMessageRef } = props;
+    const { chat, chatController } = props;
 
-    return (
-        <>
-            {chat.messages.map((message, index) => {
-                const isLastMessage = index === chat.messages.length - 1;
-                const isLastUserMessage =
-                    message.role === AIMessageRole.User &&
-                    index === chat.messages.map((m) => m.role).lastIndexOf(AIMessageRole.User);
+    // Group messages: user messages start a new group, all following messages until next user message belong to that group
+    type Message = (typeof chat.messages)[0];
+    type MessageGroup = { message: Message; originalIndex: number };
+    const messageGroups: Array<Array<MessageGroup>> = [];
+    let currentGroup: Array<MessageGroup> = [];
 
-                return (
-                    <>
-                        {message.note ? (
-                            <div
-                                key={`${index}-note`}
-                                className="self-center text-tint-subtle text-xs"
-                            >
-                                {message.note}
-                            </div>
-                        ) : null}
+    chat.messages.forEach((message, index) => {
+        if (message.role === AIMessageRole.User) {
+            // Start a new group
+            if (currentGroup.length > 0) {
+                messageGroups.push(currentGroup);
+            }
+            currentGroup = [{ message, originalIndex: index }];
+        } else {
+            // Add to current group
+            currentGroup.push({ message, originalIndex: index });
+        }
+    });
+
+    // Add the last group if it exists
+    if (currentGroup.length > 0) {
+        messageGroups.push(currentGroup);
+    }
+
+    return messageGroups.map((group, groupIndex) => {
+        const isLastGroup = group === messageGroups[messageGroups.length - 1];
+        return (
+            <div
+                key={groupIndex}
+                id={`message-group-${groupIndex}`}
+                className={tcls(
+                    'flex flex-col gap-2 pt-2',
+                    isLastGroup ? 'shrink-0 basis-full' : '',
+
+                    'transition-discrete'
+                )}
+                style={{ animationDelay: '.2s' }}
+            >
+                {group.map(({ message, originalIndex }) => {
+                    const isLastMessage = originalIndex === chat.messages.length - 1;
+                    return (
                         <div
-                            ref={isLastUserMessage ? lastUserMessageRef : undefined}
-                            data-testid="ai-chat-message"
+                            key={originalIndex}
+                            data-testid={
+                                message.role === AIMessageRole.User
+                                    ? 'ai-chat-message-user'
+                                    : 'ai-chat-message-assistant'
+                            }
+                            id={`message-${originalIndex}`}
                             className={tcls(
-                                message.content ? 'animate-fade-in-slow' : '',
-                                'shrink-0',
-                                'last:min-h-[calc(100%-5rem)]',
-                                'scroll-mt-36',
-                                'lg:scroll-mt-0',
                                 'flex flex-col gap-6',
                                 'break-words',
                                 'group/message',
+                                'animate-blur-in-slow',
+                                isLastMessage ? 'basis-full' : '',
                                 message.role === AIMessageRole.User
-                                    ? 'max-w-[80%] self-end circular-corners:rounded-2xl rounded-corners:rounded-md bg-tint px-4 py-2'
-                                    : 'text-tint-strong'
+                                    ? 'max-w-[80%] origin-top-right self-end circular-corners:rounded-2xl rounded-corners:rounded-md bg-tint px-4 py-2'
+                                    : 'origin-top-left text-tint-strong'
                             )}
                             style={{
-                                animationDelay: `${Math.min(index * 0.05, 0.5)}s`,
+                                animationDelay: `${Math.min(originalIndex * 0.1, 0.6)}s`,
                             }}
-                            key={index}
                         >
-                            {message.content ? message.content : null}
+                            {message.content}
 
-                            {isLastMessage && chat.loading ? (
-                                <div className="flex w-full animate-fade-in-slow flex-col gap-2">
-                                    {!message.content ? <HoldMessage /> : null}
+                            {isLastMessage && message.role === AIMessageRole.Assistant ? (
+                                <div
+                                    className={tcls(
+                                        'flex w-full shrink-0 flex-col gap-2 starting:opacity-0 transition-all transition-discrete duration-500',
+                                        chat.loading ? '' : 'hidden opacity-0'
+                                    )}
+                                >
+                                    <HoldMessage className={message.content ? 'hidden' : ''} />
                                     <LoadingSkeleton />
                                 </div>
                             ) : null}
@@ -76,27 +104,39 @@ export function AIChatMessages(props: {
                                         />
                                     ) : null}
                                     <AIChatToolConfirmations chat={chat} />
+                                    <AIChatFollowupSuggestions
+                                        chat={chat}
+                                        chatController={chatController}
+                                    />
                                 </>
                             ) : null}
                         </div>
-                    </>
-                );
-            })}
-        </>
-    );
+                    );
+                })}
+            </div>
+        );
+    });
 }
 
-function HoldMessage() {
+export function HoldMessage({
+    breakLines = false,
+    className,
+}: { breakLines?: boolean; className?: string }) {
     const language = useLanguage();
 
     return (
-        <div className="animate-[heightIn_500ms_4500ms_ease_both] py-2 text-tint-subtle">
+        <div
+            className={tcls(
+                'animate-[heightIn_.5s_5s_ease_both] overflow-hidden py-2 text-tint-subtle [&.hidden]:animate-[heightOut_1s_ease-in_both]',
+                className
+            )}
+        >
             {tString(language, 'ai_chat_hold_message_1')
                 .split(' ')
                 .map((word, index) => (
                     <span
                         key={index}
-                        className="animate-fade-in-slow"
+                        className="animate-blur-in-slow"
                         style={{
                             animationDelay: `${5000 + index * 200}ms`,
                         }}
@@ -104,12 +144,13 @@ function HoldMessage() {
                         {word}{' '}
                     </span>
                 ))}
+            {breakLines ? <br /> : null}
             {tString(language, 'ai_chat_hold_message_2')
                 .split(' ')
                 .map((word, index) => (
                     <span
                         key={index}
-                        className="animate-fade-in-slow"
+                        className="animate-blur-in-slow"
                         style={{
                             animationDelay: `${10000 + index * 200}ms`,
                         }}
@@ -127,9 +168,9 @@ function LoadingSkeleton() {
             {Array.from({ length: 7 }).map((_, index) => (
                 <div
                     key={index}
-                    className="h-4 animate-[fadeIn_500ms_ease_both,pulse_1.5s_infinite] circular-corners:rounded-2xl rounded-corners:rounded-md bg-tint-4"
+                    className="h-4 animate-[blurIn_500ms_ease-out_both,pulse_1.5s_infinite] circular-corners:rounded-2xl rounded-corners:rounded-md bg-tint-solid/2"
                     style={{
-                        width: `calc(${(index % 4) * 20 + 10}% - 4px)`,
+                        width: `calc(${(4 - (index % 4)) * 8 + 14}% - 4px)`,
                         animationDelay: `${index * 0.1}s`,
                     }}
                 />

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

@@ -17,15 +17,15 @@ export default function AIChatSuggestedQuestions(props: {
     } = props;
 
     return (
-        <div className="flex flex-col items-center gap-2">
+        <div className="flex flex-col items-start gap-2 self-start">
             {suggestions.map((question, index) => (
                 <Button
                     key={question}
-                    variant="secondary"
+                    variant="blank"
                     size="medium"
-                    className="max-w-full animate-[present_500ms_both] whitespace-normal"
+                    className="max-w-full animate-blur-in-slow border-none bg-primary-solid/1 px-3 py-1.5 hover:bg-primary-hover"
                     style={{
-                        animationDelay: `${800 + index * 100}ms`,
+                        animationDelay: `${1000 + index * 100}ms`,
                     }}
                     onClick={() => chatController.postMessage({ message: question })}
                 >

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

@@ -29,7 +29,7 @@ export function AIChatToolConfirmations(props: {
     );
 
     return (
-        <div className="flex w-full flex-wrap justify-end gap-2">
+        <div className="flex w-full flex-wrap justify-end gap-2 empty:hidden">
             {chat.pendingTools.map((tool, index) => (
                 <div
                     className="flex w-full animate-present-slow flex-col gap-1"

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

@@ -24,7 +24,9 @@ export function AIResponseFeedback(props: {
     };
 
     return (
-        <div className={tcls('flex h-fit items-center', className)}>
+        <div
+            className={tcls('flex h-fit animate-[heightIn_.5s_ease_both] items-center', className)}
+        >
             <Button
                 icon="thumbs-up"
                 iconOnly
@@ -35,7 +37,7 @@ export function AIResponseFeedback(props: {
                     rating !== null && rating !== 1 && 'px-0 text-[0rem] opacity-0'
                 )}
                 size="medium"
-                style={{ animationDuration: '.5s' }}
+                style={{ animationDelay: '.5s', animationDuration: '.5s' }}
                 onClick={() => handleRating(1)}
                 disabled={rating !== null}
                 active={rating === 1}
@@ -51,7 +53,7 @@ export function AIResponseFeedback(props: {
                     rating !== null && rating !== -1 && 'px-0 text-[0rem] opacity-0'
                 )}
                 size="medium"
-                style={{ animationDelay: '.2s', animationDuration: '.5s' }}
+                style={{ animationDelay: '.7s', animationDuration: '.5s' }}
                 onClick={() => handleRating(-1)}
                 disabled={rating !== null}
                 active={rating === -1}
@@ -59,8 +61,8 @@ export function AIResponseFeedback(props: {
             />
             {rating !== null ? (
                 <span
-                    className="ml-2 animate-fade-in-slow text-tint-subtle"
-                    style={{ animationDelay: '.3s' }}
+                    className="ml-2 animate-blur-in-slow text-tint-subtle"
+                    style={{ animationDelay: '.5s' }}
                 >
                     {t(language, 'was_this_helpful_thank_you')}
                 </span>

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

@@ -15,22 +15,28 @@ export function AIChatFollowupSuggestions(props: {
     }
 
     return (
-        <div className="mt-auto flex w-full flex-wrap justify-end gap-2">
-            {chat.followUpSuggestions.map((suggestion, index) => (
-                <Button
-                    key={index}
-                    onClick={() => {
-                        chatController.postMessage({ message: suggestion });
-                    }}
-                    label={suggestion}
-                    className="whitespace-normal! max-w-full animate-[present_500ms_both] text-left ring-1 ring-tint-subtle"
-                    size="medium"
-                    variant="blank"
-                    style={{
-                        animationDelay: `${250 + Math.min(index * 50, 150)}ms`,
-                    }}
-                />
-            ))}
+        <div className="flex grow flex-col">
+            <div
+                className="sticky bottom-0 mt-auto flex flex-col items-start gap-2"
+                data-testid="ai-chat-followup-suggestions"
+            >
+                {chat.followUpSuggestions.map((suggestion, index) => (
+                    <Button
+                        data-testid="ai-chat-followup-suggestion"
+                        key={index}
+                        onClick={() => {
+                            chatController.postMessage({ message: suggestion });
+                        }}
+                        label={suggestion}
+                        className="starting:h-0 max-w-full origin-left animate-blur-in-slow whitespace-normal border-none bg-primary-11/1 px-3 py-1.5 starting:py-0 text-left transition-all transition-discrete duration-500 *:whitespace-normal hover:bg-primary-hover"
+                        size="medium"
+                        variant="blank"
+                        style={{
+                            animationDelay: `${250 + Math.min(index * 50, 150)}ms`,
+                        }}
+                    />
+                ))}
+            </div>
         </div>
     );
 }

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

@@ -5,6 +5,7 @@ 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 {
@@ -17,48 +18,108 @@ import {
     ToolbarSubtitle,
     ToolbarTitle,
 } from './Toolbar';
-import type { AdminToolbarClientProps } from './types';
+import {
+    type ToolbarControlsContextValue,
+    ToolbarControlsProvider,
+} from './ToolbarControlsContext';
+import type { AdminToolbarClientProps, AdminToolbarContext } from './types';
+import { useToolbarVisibility } from './utils';
 
 export function AdminToolbarClient(props: AdminToolbarClientProps) {
-    const { context } = props;
+    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 (
-            <IframeWrapper>
-                <MotionConfig reducedMotion="user">
-                    <ChangeRequestToolbar context={context} />
-                </MotionConfig>
-            </IframeWrapper>
+            <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 (
-            <IframeWrapper>
-                <MotionConfig reducedMotion="user">
-                    <RevisionToolbar context={context} />
-                </MotionConfig>
-            </IframeWrapper>
+            <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 (
-            <IframeWrapper>
-                <MotionConfig reducedMotion="user">
-                    <AuthenticatedUserToolbar context={context} />
-                </MotionConfig>
-            </IframeWrapper>
+            <ToolbarControlsWrapper value={toolbarControls}>
+                <AuthenticatedUserToolbar
+                    context={context}
+                    minified={minified}
+                    onMinifiedChange={setMinified}
+                />
+            </ToolbarControlsWrapper>
         );
     }
+
+    return null;
 }
 
-function ChangeRequestToolbar(props: AdminToolbarClientProps) {
-    const { context } = props;
+/**
+ * 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');
@@ -71,11 +132,11 @@ function ChangeRequestToolbar(props: AdminToolbarClientProps) {
     });
 
     return (
-        <Toolbar>
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange} label="Site preview">
             <ToolbarBody>
                 <ToolbarTitle
-                    prefix="Change request"
-                    suffix={`#${changeRequest.number} ${changeRequest.subject || 'Untitled'}`}
+                    prefix={`Change #${changeRequest.number}:`}
+                    suffix={`${changeRequest.subject || 'Untitled'}`}
                 />
                 <ToolbarSubtitle
                     subtitle={
@@ -88,9 +149,13 @@ function ChangeRequestToolbar(props: AdminToolbarClientProps) {
 
             <ToolbarSeparator />
 
-            <ToolbarButtonGroup>
+            <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"
@@ -102,10 +167,10 @@ function ChangeRequestToolbar(props: AdminToolbarClientProps) {
                     icon="comment"
                 />
 
-                {/* Open production site */}
+                {/* Open published/live site */}
                 {site.urls.published ? (
                     <ToolbarButton
-                        title="Open production site"
+                        title="Open live site"
                         href={getToolbarHref({
                             href: site.urls.published,
                             siteId: site.id,
@@ -125,16 +190,13 @@ function ChangeRequestToolbar(props: AdminToolbarClientProps) {
                     })}
                     icon="code-pull-request"
                 />
-
-                {/* Edit in GitBook */}
-                <EditPageButton href={changeRequest.urls.app} siteId={site.id} />
-            </ToolbarButtonGroup>
+            </ToolbarActions>
         </Toolbar>
     );
 }
 
-function RevisionToolbar(props: AdminToolbarClientProps) {
-    const { context } = props;
+function RevisionToolbar(props: ToolbarViewProps) {
+    const { context, minified, onMinifiedChange } = props;
     const { revision, site } = context;
     if (!revision) {
         throw new Error('Revision is not set');
@@ -145,7 +207,7 @@ function RevisionToolbar(props: AdminToolbarClientProps) {
     const gitProvider = isGitHub ? 'GitHub' : 'GitLab';
 
     return (
-        <Toolbar>
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange} label="Site preview">
             <ToolbarBody>
                 <ToolbarTitle prefix="Site version" suffix={context.site.title} />
                 <ToolbarSubtitle
@@ -157,7 +219,7 @@ function RevisionToolbar(props: AdminToolbarClientProps) {
                 />
             </ToolbarBody>
             <ToolbarSeparator />
-            <ToolbarButtonGroup>
+            <ToolbarActions>
                 {/* Open commit in Git client */}
                 <ToolbarButton
                     title={
@@ -187,7 +249,7 @@ function RevisionToolbar(props: AdminToolbarClientProps) {
                 />
                 {site.urls.published ? (
                     <ToolbarButton
-                        title="Open production site"
+                        title="Open live site"
                         href={getToolbarHref({
                             href: site.urls.published,
                             siteId: site.id,
@@ -205,22 +267,26 @@ function RevisionToolbar(props: AdminToolbarClientProps) {
                     })}
                     icon="code-commit"
                 />
-            </ToolbarButtonGroup>
+            </ToolbarActions>
         </Toolbar>
     );
 }
 
-function AuthenticatedUserToolbar(props: AdminToolbarClientProps) {
-    const { context } = props;
+function AuthenticatedUserToolbar(props: ToolbarViewProps) {
+    const { context, minified, onMinifiedChange } = props;
     const { revision, space, site } = context;
     const { refreshForUpdates, updated } = useCheckForContentUpdate({
         revisionId: space.revision,
     });
 
     return (
-        <Toolbar>
+        <Toolbar
+            minified={minified}
+            onMinifiedChange={onMinifiedChange}
+            label="Only visible to your GitBook organization"
+        >
             <ToolbarBody>
-                <ToolbarTitle prefix="Site" suffix={context.site.title} />
+                <ToolbarTitle suffix={context.site.title} />
                 <ToolbarSubtitle
                     subtitle={
                         <>
@@ -230,9 +296,14 @@ function AuthenticatedUserToolbar(props: AdminToolbarClientProps) {
                 />
             </ToolbarBody>
             <ToolbarSeparator />
-            <ToolbarButtonGroup>
+            <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({
@@ -240,8 +311,10 @@ function AuthenticatedUserToolbar(props: AdminToolbarClientProps) {
                         siteId: site.id,
                         buttonId: 'site',
                     })}
-                    icon="gear"
+                    icon="gears"
                 />
+
+                {/* Customize in GitBook */}
                 <ToolbarButton
                     title="Customize in GitBook"
                     href={getToolbarHref({
@@ -251,6 +324,8 @@ function AuthenticatedUserToolbar(props: AdminToolbarClientProps) {
                     })}
                     icon="palette"
                 />
+
+                {/* Open insights in GitBook */}
                 <ToolbarButton
                     title="Open insights in GitBook"
                     href={getToolbarHref({
@@ -260,12 +335,22 @@ function AuthenticatedUserToolbar(props: AdminToolbarClientProps) {
                     })}
                     icon="chart-simple"
                 />
-                <EditPageButton href={space.urls.app} siteId={site.id} />
-            </ToolbarButtonGroup>
+            </ToolbarActions>
         </Toolbar>
     );
 }
 
+function ToolbarActions(props: { children: React.ReactNode }) {
+    const { children } = props;
+
+    return (
+        <ToolbarButtonGroup>
+            {children}
+            <HideToolbarButton />
+        </ToolbarButtonGroup>
+    );
+}
+
 function EditPageButton(props: {
     href: string;
     siteId: string;

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

@@ -3,18 +3,23 @@
   --seg-A-color: #2782c4;
   --seg-B-color: #43b7f2;
   --seg-C-color: #8be2ff;
+  --trace-color: #46474c;
+
 
   --T: 2s;
   shape-rendering: geometricPrecision;
   vector-effect: non-scaling-stroke;
 }
 
-:global(html.dark) .svgLogo {
-  --logo-fill: var(--color-neutral-800);
-  --seg-A-color: #19537d;
-  --seg-B-color: #2782c4;
-  --seg-C-color: #43b7f2;
-  --trace-color: #46474c;
+.static .trace {
+  animation: none;
+  fill: var(--logo-fill);
+  stroke: none;
+}
+
+.static .seg {
+  animation: none;
+  opacity: 0;
 }
 
 /* Base segment animation */
@@ -177,4 +182,4 @@
     fill: var(--logo-fill);
     stroke:none;
   }
-}
+}

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

@@ -2,10 +2,16 @@ import { tcls } from '@/lib/tailwind';
 import type React from 'react';
 import styles from './AnimatedLogo.module.css';
 
-export const AnimatedLogo: React.FC = () => {
+interface AnimatedLogoProps {
+    shouldAnimate?: boolean;
+}
+
+export const AnimatedLogo: React.FC<AnimatedLogoProps> = (props) => {
+    const { shouldAnimate = true } = props;
+
     return (
         <svg
-            className={styles.svgLogo}
+            className={tcls(styles.svgLogo, shouldAnimate ? undefined : styles.static)}
             width="28"
             height="28"
             viewBox="0 0 28 28"

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

@@ -0,0 +1,233 @@
+'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);
+    };
+    // @ts-expect-error wrong type for ref
+    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/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,21 +1,39 @@
 'use client';
-import { AnimatePresence, type MotionValue, motion, useReducedMotion } from 'motion/react';
-import React from 'react';
+import {
+    AnimatePresence,
+    type MotionValue,
+    motion,
+    useReducedMotion,
+    useSpring,
+} from 'motion/react';
+import React, { isValidElement } from 'react';
 import { AnimatedLogo } from './AnimatedLogo';
+import { useToolbarControls } from './ToolbarControlsContext';
 
 import { tcls } from '@/lib/tailwind';
-import { Icon, type IconName } from '@gitbook/icons';
+import { Icon, type IconName, IconStyle } from '@gitbook/icons';
 import { Tooltip } from '../primitives';
-import { getCopyVariants, minifyButtonAnimation, toolbarEasings } from './transitions';
+import { getCopyVariants, toolbarEasings } from './transitions';
 import { useMagnificationEffect } from './useMagnificationEffect';
 
 const DURATION_LOGO_APPEARANCE = 2000;
 const DELAY_BETWEEN_LOGO_AND_CONTENT = 100;
 
-export function Toolbar(props: { children: React.ReactNode }) {
-    const [minified, setMinified] = React.useState(true);
-    const [showToolbarControls, setShowToolbarControls] = React.useState(false);
+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(() => {
@@ -31,16 +49,41 @@ export function Toolbar(props: { children: React.ReactNode }) {
         }
     }, []);
 
-    // After toolbar appears, wait then show the full content
+    // After toolbar appears, wait, then show the full content
     React.useEffect(() => {
-        if (isReady) {
-            const expandAfterTimeout = setTimeout(() => {
-                setMinified(false);
-            }, DURATION_LOGO_APPEARANCE + DELAY_BETWEEN_LOGO_AND_CONTENT);
-
-            return () => clearTimeout(expandAfterTimeout);
+        if (!isReady || autoExpandTriggeredRef.current) {
+            return;
         }
-    }, [isReady]);
+
+        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) {
@@ -48,61 +91,47 @@ export function Toolbar(props: { children: React.ReactNode }) {
     }
 
     return (
-        <motion.div
-            onMouseEnter={() => setShowToolbarControls(true)}
-            onMouseLeave={() => setShowToolbarControls(false)}
-            className="-translate-x-1/2 fixed bottom-5 left-1/2 z-40 w-auto max-w-xl transform px-4"
-        >
-            <AnimatePresence mode="wait">
-                <motion.div
-                    onClick={() => {
-                        if (minified) {
-                            setMinified((prev) => !prev);
-                        }
-                    }}
-                    layout
-                    transition={toolbarEasings.spring}
-                    className={tcls(
-                        minified ? 'cursor-pointer px-2' : 'pr-2 pl-3.5',
-                        'flex',
-                        'items-center',
-                        'justify-center',
-                        'min-h-11',
-                        'min-w-12',
-                        'h-12',
-                        'py-2',
-                        'border-tint-1/3',
-                        'backdrop-blur-sm',
-                        'origin-center',
-                        'bg-[linear-gradient(110deg,rgba(20,23,28,0.90)_0%,rgba(20,23,28,0.80)_100%)]',
-                        'dark:bg-[linear-gradient(110deg,rgba(256,256,256,0.90)_0%,rgba(256,256,256,0.80)_100%)]'
-                    )}
-                    initial={{
-                        scale: 1,
-                        opacity: 1,
-                    }}
-                    animate={{
-                        scale: 1,
-                        opacity: 1,
-                        boxShadow: minified
-                            ? '0 4px 40px 8px rgba(0, 0, 0, .2), 0 0 0 .5px rgba(0, 0, 0, .4), inset 0 .5px 0 0 hsla(0, 0%, 100%, .15)'
-                            : '0 4px 40px 8px rgba(0, 0, 0, .4), 0 0 0 .5px rgba(0, 0, 0, .8), inset 0 .5px 0 0 hsla(0, 0%, 100%, .3)',
-                    }}
-                    style={{
-                        borderRadius: '100px', // This is set on `style` so Framer Motion can correct for distortions
-                    }}
-                >
-                    {/* Logo with stroke segments animation in blue-tints */}
-                    <motion.div layout>
-                        <AnimatedLogo />
+        <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>
-
-                    {!minified ? props.children : null}
-
-                    {!minified && showToolbarControls && <MinifyButton setMinified={setMinified} />}
-                </motion.div>
-            </AnimatePresence>
-        </motion.div>
+                </AnimatePresence>
+            </motion.div>
+        </Tooltip>
     );
 }
 
@@ -129,12 +158,15 @@ export function ToolbarButtonGroup(props: { children: React.ReactNode }) {
             className="flex items-center gap-1 overflow-visible pr-2 pl-4"
         >
             {buttonChildren.map((child, index) => {
-                const motionValues = buttonMotionValues[index];
                 const childEl = child as React.ReactElement;
-                return React.cloneElement(childEl, {
-                    key: index,
-                    motionValues,
-                });
+                const childKey = childEl.key ?? `toolbar-button-${index}`;
+                return (
+                    <ToolbarButtonWrapper
+                        key={childKey}
+                        child={childEl}
+                        rawMotionValues={buttonMotionValues[index]}
+                    />
+                );
             })}
         </motion.div>
     );
@@ -148,15 +180,27 @@ export interface ToolbarButtonProps extends Omit<React.HTMLProps<HTMLAnchorEleme
     icon: IconName;
     iconClassName?: string;
     title?: React.ReactNode;
+    children?: React.ReactNode;
 }
 
-export function ToolbarButton(props: ToolbarButtonProps) {
-    const { title, disabled, motionValues, className, style, href, onClick, icon, iconClassName } =
-        props;
+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}>
+        <motion.div variants={toolbarEasings.staggeringChild} className="relative" ref={ref}>
+            {children ? children : null}
             <Tooltip label={title}>
                 <motion.a
                     href={href}
@@ -189,39 +233,81 @@ export function ToolbarButton(props: ToolbarButtonProps) {
                         'gap-1',
                         'text-sm',
                         'rounded-full',
-                        'border-neutral-500',
-                        'outline-neutral-800',
-                        'outline-1',
-                        'border',
                         'truncate',
                         'text-tint-1',
                         'dark:text-tint-12',
                         'cursor-pointer',
                         'transition-colors',
                         'size-8',
-                        'bg-tint-1/3',
-                        'hover:bg-tint-1/4',
-                        'dark:bg-tint-3',
-                        'dark:hover:bg-tint-1',
                         disabled ? 'cursor-not-allowed opacity-50' : '',
-                        'shadow-1xs'
+                        '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} className={tcls('size-4', iconClassName)} />
+                    <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,
+    };
+
+    if (!isValidElement<{ motionValues: typeof motionValues }>(child)) {
+        return null;
+    }
+
+    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 }) {
+export function ToolbarTitle(props: { prefix?: string; suffix: string }) {
     return (
         <div className="flex items-center gap-1 text-xs ">
-            <ToolbarTitlePrefix title={props.prefix} />
+            {props.prefix ? <ToolbarTitlePrefix title={props.prefix} /> : null}
             <ToolbarTitleSuffix title={props.suffix} />
         </div>
     );
@@ -231,7 +317,7 @@ function ToolbarTitlePrefix(props: { title: string }) {
     return (
         <motion.span
             {...getCopyVariants(0)}
-            className="font-light text-neutral-7 dark:text-neutral-3"
+            className="truncate font-medium text-neutral-1 dark:text-neutral-12"
         >
             {props.title}
         </motion.span>
@@ -242,7 +328,7 @@ function ToolbarTitleSuffix(props: { title: string }) {
     return (
         <motion.span
             {...getCopyVariants(1)}
-            className="max-w-[24ch] truncate font-semibold text-neutral-3 dark:text-neutral-2"
+            className="max-w-[20ch] truncate text-neutral-1 dark:text-neutral-12"
         >
             {props.title}
         </motion.span>
@@ -253,36 +339,9 @@ export function ToolbarSubtitle(props: { subtitle: React.ReactNode }) {
     return (
         <motion.span
             {...getCopyVariants(1)}
-            className="text-neutral-7 text-xxs dark:text-neutral-2"
+            className="text-neutral-1/80 text-xxs dark:text-neutral-12/80"
         >
             {props.subtitle}
         </motion.span>
     );
 }
-
-function MinifyButton(props: { setMinified: (minified: boolean) => void }) {
-    return (
-        <Tooltip label="Minify">
-            <motion.div
-                {...minifyButtonAnimation}
-                transition={{
-                    duration: 0.2,
-                }}
-                whileHover={{
-                    scale: 1.05,
-                }}
-                onClick={(e) => {
-                    e.stopPropagation();
-                    props.setMinified(true);
-                }}
-                className={tcls(
-                    '-top-2 -right-4 absolute flex size-4 cursor-pointer items-center justify-center rounded-full border',
-                    'border-neutral-500 bg-neutral-700 hover:border-neutral-400 hover:bg-neutral-600',
-                    'dark:border-neutral-400 dark:bg-neutral-200 dark:hover:border-neutral-200 dark:hover:bg-neutral-100'
-                )}
-            >
-                <Icon icon="minus" className="size-2 text-neutral-1 dark:text-neutral-9" />
-            </motion.div>
-        </Tooltip>
-    );
-}

packages/gitbook/src/components/AdminToolbar/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

@@ -3,3 +3,4 @@ export * from './AdminToolbarClient';
 export * from './IframeWrapper';
 export * from './Toolbar';
 export * from './transitions';
+export * from './utils';

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

@@ -54,4 +54,7 @@ export type AdminToolbarContext = {
 
 export interface AdminToolbarClientProps {
     context: AdminToolbarContext;
+    onSessionClose?: () => void;
+    onPersistentClose?: () => void;
+    onToggleMinify?: () => void;
 }

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

@@ -1,11 +1,6 @@
-import { type MotionValue, motionValue } from 'framer-motion';
+import { type MotionValue, motionValue } from 'motion/react';
 import React from 'react';
 
-interface ButtonMotionValues {
-    scale: MotionValue<number>;
-    x: MotionValue<number>;
-}
-
 interface MagnificationConfig {
     /** Size of each button in pixels - used for spacing calculations */
     buttonSize?: number;
@@ -23,21 +18,16 @@ interface MagnificationConfig {
 
 const defaultConfig: Required<MagnificationConfig> = {
     buttonSize: 32, // Standard button size for 32px (size-8) buttons
-    maxScale: 1.3, // 30% scale increase - noticeable but not overwhelming
+    maxScale: 1.25, // 25% scale increase - noticeable but not overwhelming
     influenceRadius: 80, // ~2.5 button widths of influence
     spacingMultiplier: 1.3, // Creates proportional spacing to scale increase
     scaleExponent: 2.5, // Exponential curve for dramatic close-range scaling
     padding: 10, // Small buffer zone around container edges
 };
 
-// Helper functions for cleaner code
-const createMotionValues = (count: number): ButtonMotionValues[] =>
-    Array.from({ length: count }, () => ({
-        scale: motionValue(1),
-        x: motionValue(0),
-    }));
-
-const resetMotionValues = (motionValues: ButtonMotionValues[]) => {
+const resetMotionValues = (
+    motionValues: Array<{ scale: MotionValue<number>; x: MotionValue<number> }>
+) => {
     motionValues.forEach(({ scale, x }) => {
         scale.set(1);
         x.set(0);
@@ -46,10 +36,17 @@ const resetMotionValues = (motionValues: ButtonMotionValues[]) => {
 
 const captureButtonPositions = (buttons: HTMLElement[]) => {
     // Reset transforms to get original positions
-    buttons.forEach((button) => (button.style.transform = ''));
+    buttons.forEach((button) => {
+        button.style.transform = '';
+    });
     return buttons.map((button) => {
         const rect = button.getBoundingClientRect();
-        return { left: rect.left, width: rect.width };
+        return {
+            left: rect.left,
+            width: rect.width,
+            top: rect.top,
+            height: rect.height,
+        };
     });
 };
 
@@ -59,26 +56,46 @@ const calculateScale = (
     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;
 
-    // Edge influence to reduce scaling near container edges
-    const distanceFromEdge = Math.min(mouseX - containerRect.left, containerRect.right - mouseX);
-    const edgeInfluence = Math.min(distanceFromEdge / 20, 1);
+    // Calculate distance from container edge (X-axis only)
+    const distanceFromEdgeX = Math.min(mouseX - containerRect.left, containerRect.right - mouseX);
+    const distanceFromEdge = distanceFromEdgeX;
 
-    // Exponential scaling curve
-    const progress = distance / config.influenceRadius;
-    const exponentialProgress = (1 - progress) ** config.scaleExponent;
-    const baseScale = 1 + (config.maxScale - 1) * exponentialProgress;
+    // Define the "heart" zone - 8px from center (16x16px total area)
+    const heartZoneRadius = 8;
 
-    return 1 + (baseScale - 1) * edgeInfluence;
+    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 }>,
+    positions: Array<{ left: number; width: number; top: number; height: number }>,
     config: Required<MagnificationConfig>
 ) => {
     const currentPos = positions[buttonIndex];
@@ -119,14 +136,23 @@ const calculateSpacing = (
 
 export function useMagnificationEffect(props: {
     childrenCount: number;
-    containerRef: React.RefObject<HTMLElement>;
+    containerRef: React.RefObject<HTMLElement | null>;
     config?: MagnificationConfig;
 }) {
     const { childrenCount, containerRef, config } = props;
-    const [buttonMotionValues, setButtonMotionValues] = React.useState<ButtonMotionValues[]>([]);
-    const originalPositionsRef = React.useRef<Array<{ left: number; width: number }>>([]);
+    const originalPositionsRef = React.useRef<
+        Array<{ left: number; width: number; top: number; height: number }>
+    >([]);
 
-    const finalConfig = { ...defaultConfig, ...config };
+    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;
@@ -141,11 +167,6 @@ export function useMagnificationEffect(props: {
             return;
         }
 
-        // Initialize motion values if button count changed
-        if (buttonMotionValues.length !== buttons.length) {
-            setButtonMotionValues(createMotionValues(buttons.length));
-        }
-
         const handleMouseMove = (event: MouseEvent) => {
             const buttons = Array.from(
                 container.querySelectorAll('.toolbar-button')
@@ -210,17 +231,7 @@ export function useMagnificationEffect(props: {
             container.removeEventListener('mousemove', handleMouseMove);
             container.removeEventListener('mouseleave', handleMouseLeave);
         };
-    }, [
-        finalConfig.buttonSize,
-        finalConfig.maxScale,
-        finalConfig.influenceRadius,
-        finalConfig.spacingMultiplier,
-        finalConfig.scaleExponent,
-        finalConfig.padding,
-        containerRef,
-        buttonMotionValues,
-        childrenCount,
-    ]);
+    }, [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/DocumentView/Annotation/Annotation.tsx

@@ -27,7 +27,7 @@ export function Annotation(props: InlineProps<DocumentInlineAnnotation>) {
                     ancestorBlocks={[]}
                     context={context}
                     nodes={fragment.nodes}
-                    style={['space-y-4']}
+                    style={['contents']}
                 />
             }
         >

packages/gitbook/src/components/DocumentView/Annotation/AnnotationPopover.tsx

@@ -1,84 +1,30 @@
 'use client';
 
-import * as Popover from '@radix-ui/react-popover';
 import type React from 'react';
 
-import { tString, useLanguage } from '@/intl/client';
-import { tcls } from '@/lib/tailwind';
+import { Tooltip } from '@/components/primitives';
 
 export function AnnotationPopover(props: { children: React.ReactNode; body: React.ReactNode }) {
     const { children, body } = props;
-    const language = useLanguage();
 
     return (
-        <Popover.Root>
-            <Popover.Trigger asChild>
-                <button
-                    data-testid="annotation-button"
-                    aria-label={tString(language, 'annotation_button_label')}
-                    className={tcls(
-                        'decoration-dotted',
-                        'decoration-1',
-                        'underline',
-                        'underline-offset-2'
-                    )}
-                >
-                    {children}
-                </button>
-            </Popover.Trigger>
-            <Popover.Portal>
-                <Popover.Content
-                    className={tcls(
-                        'text-sm',
-                        'max-w-[280px]',
-                        'bg-tint',
-                        'ring-1',
-                        'ring-tint',
-                        'rounded-sm',
-                        'shadow-1xs',
-                        'shadow-tint-12/1',
-                        'dark:shadow-tint-1/2',
-                        'p-3',
-                        '[&_p]:leading-snug',
-                        '-outline-offset-2',
-                        'outline-2',
-                        'outline-primary/8',
-                        'z-20'
-                    )}
-                    sideOffset={4}
-                >
-                    {body}
-                    <Popover.Arrow asChild>
-                        <svg
-                            viewBox="0 0 8 5"
-                            className={tcls(
-                                'relative',
-                                'z-2',
-                                'fill-tint-3', // Same as bg-tint
-                                'stroke-tint-7', // Same as ring-tint
-                                '[paint-order:stroke_fill]'
-                            )}
-                            fill="none"
-                            xmlns="http://www.w3.org/2000/svg"
-                        >
-                            <g clip-path="url(#clipAnnotation)">
-                                <path
-                                    d="M0 0L4 4L8 0"
-                                    strokeWidth="2"
-                                    strokeLinecap="round"
-                                    stroke="inherit"
-                                    fill="inherit"
-                                />
-                            </g>
-                            <defs>
-                                <clipPath id="clipAnnotation">
-                                    <rect width="8" height="5" fill="white" />
-                                </clipPath>
-                            </defs>
-                        </svg>
-                    </Popover.Arrow>
-                </Popover.Content>
-            </Popover.Portal>
-        </Popover.Root>
+        <Tooltip
+            label={body}
+            contentProps={{
+                role: 'definition',
+            }}
+            className="bg-tint-base px-4 py-3 text-sm text-tint-strong shadow-lg shadow-tint-12/4 ring-1 ring-tint-subtle dark:shadow-tint-1"
+            arrow={true}
+            arrowProps={{ className: 'fill-tint-1' }}
+        >
+            <dfn
+                data-testid="annotation-button"
+                className="cursor-help underline decoration-1 decoration-dotted underline-offset-2"
+                // biome-ignore lint/a11y/noNoninteractiveTabindex: we want to be able to focus the definition to open the tooltip
+                tabIndex={0}
+            >
+                {children}
+            </dfn>
+        </Tooltip>
     );
 }

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

@@ -6,6 +6,7 @@ import {
     SkeletonImage,
     SkeletonParagraph,
     SkeletonSmall,
+    SkeletonUpdate,
 } from '@/components/primitives';
 import type { ClassValue } from '@/lib/tailwind';
 
@@ -34,6 +35,8 @@ import { Stepper } from './Stepper';
 import { StepperStep } from './StepperStep';
 import { Table } from './Table';
 import { Tabs } from './Tabs';
+import { Update } from './Update';
+import { Updates } from './Updates';
 
 export interface BlockProps<Block extends DocumentBlock> extends DocumentContextProps {
     block: Block;
@@ -105,6 +108,10 @@ export function Block<T extends DocumentBlock>(props: BlockProps<T>) {
                 return <Stepper {...props} block={block} />;
             case 'stepper-step':
                 return <StepperStep {...props} block={block} />;
+            case 'updates':
+                return <Updates {...props} block={block} />;
+            case 'update':
+                return <Update {...props} block={block} />;
             case 'if':
                 // If block should be processed by the API.
                 return null;
@@ -165,10 +172,13 @@ export function BlockSkeleton(props: { block: DocumentBlock; style: ClassValue }
         case 'images':
         case 'drawing':
             return <SkeletonImage id={id} style={style} />;
+        case 'updates':
+            return <SkeletonUpdate id={id} style={style} />;
         case 'image':
         case 'code-line':
         case 'tabs-item':
         case 'column':
+        case 'update':
             throw new Error(`Blocks (${block.type}) should be directly rendered by parent`);
         default:
             return nullIfNever(block);

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

@@ -1,9 +1,18 @@
-import { type DocumentBlockContentRef, SiteInsightsLinkPosition } from '@gitbook/api';
+import {
+    type ContentRef,
+    type DocumentBlockContentRef,
+    SiteInsightsLinkPosition,
+} from '@gitbook/api';
 
-import { Card } from '@/components/primitives';
-import { type ResolvedContentRef, resolveContentRef } from '@/lib/references';
+import { Card, type CardProps } from '@/components/primitives';
+import {
+    type ResolvedContentRef,
+    resolveContentRef,
+    resolveContentRefFallback,
+} from '@/lib/references';
 
 import type { BlockProps } from './Block';
+import { NotFoundRefHoverCard } from './NotFoundRefHoverCard';
 
 export async function BlockContentRef(props: BlockProps<DocumentBlockContentRef>) {
     const { block, context, style } = props;
@@ -16,51 +25,45 @@ export async function BlockContentRef(props: BlockProps<DocumentBlockContentRef>
         : null;
 
     if (!resolved) {
-        return null;
+        const fallback = resolveContentRefFallback(block.data.ref);
+        if (!fallback) {
+            return null;
+        }
+        return (
+            <NotFoundRefHoverCard context={context}>
+                <BlockContentRefCard
+                    contentRef={block.data.ref}
+                    resolved={fallback}
+                    style={style}
+                />
+            </NotFoundRefHoverCard>
+        );
     }
 
-    const isContentInOtherSpace =
-        context.contentContext?.space &&
-        'space' in block.data.ref &&
-        context.contentContext.space.id !== block.data.ref.space;
-    const kind = block?.data?.ref?.kind;
-    if ((resolved.active && kind === 'space') || isContentInOtherSpace) {
-        return <SpaceRefCard {...props} resolved={resolved} />;
-    }
+    return <BlockContentRefCard contentRef={block.data.ref} resolved={resolved} style={style} />;
+}
 
+function BlockContentRefCard(
+    props: {
+        resolved: ResolvedContentRef;
+        contentRef: ContentRef;
+    } & Omit<CardProps, 'href' | 'title'>
+) {
+    const { ref, resolved, contentRef, ...rest } = props;
     return (
         <Card
+            ref={ref}
             leadingIcon={resolved.icon ? resolved.icon : null}
             href={resolved.href}
             title={resolved.text}
-            style={style}
             insights={{
                 type: 'link_click',
                 link: {
-                    target: block.data.ref,
+                    target: contentRef,
                     position: SiteInsightsLinkPosition.Content,
                 },
             }}
-        />
-    );
-}
-
-async function SpaceRefCard(
-    props: { resolved: ResolvedContentRef } & BlockProps<DocumentBlockContentRef>
-) {
-    const { context, style, resolved } = props;
-    const spaceId = context.contentContext?.space.id;
-
-    if (!spaceId) {
-        return null;
-    }
-
-    return (
-        <Card
-            href={resolved.href}
-            title={resolved.text}
-            postTitle={resolved.subText}
-            style={style}
+            {...rest}
         />
     );
 }

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

@@ -51,11 +51,13 @@ type UnwrappedBlocksProps<TBlock extends DocumentBlock> = DocumentContextProps &
  * Ideally we'd rely on the block type to determine if it can be full width, but
  * the block's `fullWidth` property does not differentiate between `undefined` and `false`.
  * So instead we hardcode a list of blocks that can be full width. */
-const FULL_WIDTH_BLOCKS = [
+const FULL_WIDTH_BLOCKS: DocumentBlock['type'][] = [
     'table',
     'tabs',
     'integration',
-    'openapi',
+    'openapi-operation',
+    'openapi-schemas',
+    'openapi-webhook',
     'images',
     'embed',
     'columns',
@@ -64,6 +66,8 @@ const FULL_WIDTH_BLOCKS = [
     'hint',
 ];
 
+const LIST_BLOCKS: DocumentBlock['type'][] = ['list-ordered', 'list-tasks', 'list-unordered'];
+
 /**
  * Renders a list of blocks without a wrapper element.
  */
@@ -85,11 +89,12 @@ export function UnwrappedBlocks<TBlock extends DocumentBlock>(props: UnwrappedBl
                 key={node.key || `${node.type}-${index}`}
                 block={node}
                 style={[
-                    'mx-auto page-width-wide:mx-0 w-full decoration-primary/6 print:break-inside-avoid',
+                    'mx-auto page-width-wide:mx-0 w-full decoration-primary/6',
                     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',
+                    !LIST_BLOCKS.includes(node.type) && 'print:break-inside-avoid',
+                    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

@@ -1,30 +1,49 @@
 'use client';
 
 import type { DocumentBlockCode } from '@gitbook/api';
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
 
+import { useAdaptiveVisitor } from '@/components/Adaptive';
 import { useInViewportListener } from '@/components/hooks/useInViewportListener';
 import { useScrollListener } from '@/components/hooks/useScrollListener';
+import { Button } from '@/components/primitives';
+import { t, useLanguage } from '@/intl/client';
+import { tcls } from '@/lib/tailwind';
 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;
+    mode: BlockProps<DocumentBlockCode>['context']['mode'];
 };
 
+export const CODE_BLOCK_DEFAULT_COLLAPSED_LINE_COUNT = 10;
+
 /**
  * Render a code-block client-side by loading the highlighter asynchronously.
  * 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, mode, 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 +99,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,15 +117,86 @@ 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 (
+    const expandable = block.data.expandable;
+
+    const numberOfLinesOfCode = lines?.length ?? plainLines.length;
+    const collapsedLineCount =
+        block.data.collapsedLineCount || CODE_BLOCK_DEFAULT_COLLAPSED_LINE_COUNT;
+    const isExpandable = Boolean(
+        expandable && mode !== 'print' && numberOfLinesOfCode > collapsedLineCount
+    );
+
+    const codeBlockBodyId = useId();
+
+    const renderer = (
         <CodeBlockRenderer
             ref={blockRef}
             aria-busy={highlighting}
             block={block}
             style={style}
             lines={lines ?? plainLines}
+            id={codeBlockBodyId}
         />
     );
+
+    return isExpandable ? (
+        <CodeBlockExpandable
+            lines={lines ?? plainLines}
+            controls={codeBlockBodyId}
+            collapsedLineCount={collapsedLineCount}
+        >
+            {renderer}
+        </CodeBlockExpandable>
+    ) : (
+        renderer
+    );
+}
+
+function CodeBlockExpandable(props: {
+    children: React.ReactNode;
+    lines: HighlightLine[];
+    collapsedLineCount: number;
+    controls?: string;
+}) {
+    const { children, controls, lines = [], collapsedLineCount } = props;
+    const [isExpanded, setIsExpanded] = useState(false);
+    const language = useLanguage();
+    return (
+        <div className="group/codeblock-expandable relative">
+            <div
+                className={tcls(
+                    isExpanded
+                        ? '[&_pre]:after:opacity-0'
+                        : '[&_pre]:h-[calc(2rem+var(--line-count)*var(--line-height))] [&_pre]:overflow-y-hidden [&_pre]:after:opacity-100',
+                    '[&_pre]:after:pointer-events-none [&_pre]:after:absolute [&_pre]:after:inset-0 [&_pre]:after:z-1 [&_pre]:after:bg-gradient-to-t [&_pre]:after:from-0% [&_pre]:after:from-tint-2 [&_pre]:after:to-70% [&_pre]:after:to-transparent [&_pre]:after:content-[""]'
+                )}
+                style={
+                    {
+                        '--line-count': collapsedLineCount,
+                        '--line-height': '1.25rem',
+                    } as React.CSSProperties
+                }
+            >
+                {children}
+            </div>
+            <div className="pointer-events-none absolute bottom-0 flex w-full justify-center">
+                <Button
+                    icon={isExpanded ? 'chevron-up' : 'chevron-down'}
+                    size="xsmall"
+                    variant="blank"
+                    type="button"
+                    onClick={() => setIsExpanded(!isExpanded)}
+                    className="pointer-events-auto z-1 my-2 text-primary text-sm opacity-0 focus:opacity-11 group-hover/codeblock-expandable:opacity-11"
+                    aria-expanded={isExpanded}
+                    aria-controls={controls}
+                >
+                    {isExpanded
+                        ? t(language, 'code_block_expanded')
+                        : t(language, 'code_block_collapsed', lines.length)}
+                </Button>
+            </div>
+        </div>
+    );
 }

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,65 @@ 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 && !block.data.expandable) {
         // 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}
+                mode={context.mode}
+            />
+        </React.Suspense>
+    );
 }