Fix text fragment navigation

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

.changeset/happy-glasses-march.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Track opening of search results for records and in the assistant.

.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

@@ -52,6 +52,7 @@ runs:
             GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
             GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
             GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
+            GITBOOK_OAUTH_SERVER_URL: ${{ inputs.opItem }}/GITBOOK_OAUTH_SERVER_URL
             GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
             GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
             GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL
@@ -70,7 +71,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 +82,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 +105,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/composite/deploy-vercel/action.yaml

@@ -51,6 +51,7 @@ runs:
             GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
             GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
             GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
+            GITBOOK_OAUTH_SERVER_URL: ${{ inputs.opItem }}/GITBOOK_OAUTH_SERVER_URL
             GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
             GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
             GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL

.github/workflows/ci.yaml

@@ -4,8 +4,7 @@ on:
     push:
         branches:
             - main
-env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+            - changeset-release/main
 jobs:
     format:
         runs-on: ubuntu-latest
@@ -35,13 +34,10 @@ jobs:
               env:
                   PUPPETEER_SKIP_DOWNLOAD: 1
             - run: bun unit
-    build-oss:
-        # CI to check that the repository builds correctly on a machine without the credentials
+    build:
         runs-on: ubuntu-latest
-        name: Build (Open Source)
+        name: Build
         timeout-minutes: 6
-        env:
-            NPM_TOKEN_READONLY: ''
         steps:
             - name: Checkout
               uses: actions/checkout@v4

.github/workflows/deploy-preview.yaml

@@ -1,15 +1,25 @@
 name: Preview
 on:
-    pull_request:
+    pull_request_target:
     push:
-      branches:
-        - main
-env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
+        branches:
+            - main
 jobs:
+    approval:
+        # Ensure that external contributors' PRs are manually approved before deployment
+        name: Approve Preview Deployment
+        runs-on: ubuntu-latest
+        if: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.fork }}
+        environment:
+          name: preview-approval
+        steps:
+            - name: Approval gate
+              run: echo "Preview deployment approved."
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (preview)
         runs-on: ubuntu-latest
+        needs: approval
+        if: ${{ always() && (needs.approval.result == 'success' || needs.approval.result == 'skipped') }}
         environment:
           name: 2v-preview
           url: ${{ steps.deploy.outputs.deployment-url }}
@@ -18,6 +28,8 @@ jobs:
         steps:
             - name: Checkout
               uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha || github.sha }}
             - name: Deploy to Vercel
               id: deploy
               uses: ./.github/composite/deploy-vercel
@@ -31,6 +43,8 @@ jobs:
     deploy-v2-cloudflare:
         name: Deploy v2 to Cloudflare Worker (preview)
         runs-on: ubuntu-latest
+        needs: approval
+        if: ${{ always() && (needs.approval.result == 'success' || needs.approval.result == 'skipped') }}
         environment:
           name: 2c-preview
           url: ${{ steps.deploy.outputs.deployment-url }}
@@ -39,6 +53,8 @@ jobs:
         steps:
             - name: Checkout
               uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha || github.sha }}
             - name: Deploy to Cloudflare
               id: deploy
               uses: ./.github/composite/deploy-cloudflare
@@ -65,7 +81,7 @@ jobs:
     comment-deployments:
         runs-on: ubuntu-latest
         name: Comment Deployments (preview)
-        if: always() && !startsWith(github.ref, 'refs/heads/main')
+        if: always() && github.event_name != 'push'
         needs:
             - deploy-v2-vercel
             - deploy-v2-cloudflare
@@ -102,10 +118,13 @@ jobs:
         runs-on: ubuntu-latest
         name: Visual Testing v2
         needs: deploy-v2-vercel
+        if: ${{ always() && needs.deploy-v2-vercel.result == 'success' }}
         timeout-minutes: 15
         steps:
             - name: Checkout
               uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha || github.sha }}
             - name: Setup Bun
               uses: ./.github/composite/setup-bun
             - name: Install dependencies
@@ -118,15 +137,18 @@ jobs:
                   BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}
                   SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
                   ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
-                  ARGOS_BUILD_NAME: 'v2-vercel'
+                  ARGOS_BUILD_NAME: v2-vercel
     visual-testing-v2-cloudflare:
         runs-on: ubuntu-latest
         name: Visual Testing v2 (Cloudflare)
         needs: deploy-v2-cloudflare
+        if: ${{ always() && needs.deploy-v2-cloudflare.result == 'success' }}
         timeout-minutes: 15
         steps:
             - name: Checkout
               uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha || github.sha }}
             - name: Setup Bun
               uses: ./.github/composite/setup-bun
             - name: Install dependencies
@@ -139,15 +161,18 @@ jobs:
                   BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}
                   SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
                   ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
-                  ARGOS_BUILD_NAME: 'v2-cloudflare'
+                  ARGOS_BUILD_NAME: v2-cloudflare
     visual-testing-customers-v2:
         runs-on: ubuntu-latest
         name: Visual Testing Customers v2
         needs: deploy-v2-vercel
+        if: ${{ always() && needs.deploy-v2-vercel.result == 'success' }}
         timeout-minutes: 15
         steps:
             - name: Checkout
               uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha || github.sha }}
             - name: Setup Bun
               uses: ./.github/composite/setup-bun
             - name: Install dependencies
@@ -160,15 +185,18 @@ jobs:
                   BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}
                   SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
                   ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
-                  ARGOS_BUILD_NAME: 'customers-v2'
+                  ARGOS_BUILD_NAME: customers-v2-vercel
     visual-testing-customers-v2-cloudflare:
         runs-on: ubuntu-latest
         name: Visual Testing Customers v2 (Cloudflare)
         needs: deploy-v2-cloudflare
+        if: ${{ always() && needs.deploy-v2-cloudflare.result == 'success' }}
         timeout-minutes: 15
         steps:
             - name: Checkout
               uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha || github.sha }}
             - name: Setup Bun
               uses: ./.github/composite/setup-bun
             - name: Install dependencies
@@ -181,14 +209,17 @@ jobs:
                   BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}
                   SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
                   ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
-                  ARGOS_BUILD_NAME: 'customers-v2'
+                  ARGOS_BUILD_NAME: customers-v2-cloudflare
     browserless-testing-v2-vercel:
         runs-on: ubuntu-latest
         name: Browserless Testing v2 (Vercel)
         needs: deploy-v2-vercel
+        if: ${{ always() && needs.deploy-v2-vercel.result == 'success' }}
         steps:
             - name: Checkout
               uses: actions/checkout@v4
+              with:
+                  ref: ${{ github.event.pull_request.head.sha || github.sha }}
             - name: Setup Bun
               uses: ./.github/composite/setup-bun
             - name: Install dependencies
@@ -217,4 +248,4 @@ jobs:
     #           run: cd ./packages/gitbook && bun e2e-browserless
     #           env:
     #               BASE_URL: ${{needs.deploy-v2-cloudflare.outputs.deployment-url}}
-    #               SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
+    #               SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/

.github/workflows/deploy-production.yaml

@@ -3,8 +3,6 @@ on:
     push:
         branches:
             - main
-env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (production)

.github/workflows/deploy-staging.yaml

@@ -3,8 +3,6 @@ on:
     push:
         branches:
             - main
-env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (staging)

.github/workflows/publish.yaml

@@ -4,9 +4,6 @@ on:
     push:
         branches:
             - main
-
-env:
-    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
     
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
@@ -14,29 +11,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

AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS Instructions
+
+- After making code changes, run `bun format`.

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
@@ -77,23 +77,7 @@ All pull-requests will be tested against both visual and performances testing to
 
 ## Fonts and Icons
 
-GitBook Open uses fontawesome. During development, your local environment will use the free version. However, only the pro version will be accepted by CI. If you see the following error:
-
-```
-The GitBook icon is missing. It indicates that the dependencies were installed without the correct font-awesome package. These changes have probably been persisted in the Bun lockfile. Read the README for more information.
-```
-
-It means that you've changed the GBO dependencies and bundled in the free version. Only GitBook staff can help with this - if you're not on the GitBook team, please ping us in the PR and we'll help get things moving.
-
-If you are GitBook staff, you'll need our NPM token in your local environment.
-
-```
-.env.local
-
-NPM_TOKEN_READONLY=xxx
-```
-
-and then reinstall dependencies.
+GitBook Open uses fontawesome. For self-hosting and local development, for licensing reasons, only the icons from the free version should be used.
 
 ## Contributing
 

bunfig.toml

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

package.json

@@ -1,17 +1,22 @@
 {
     "name": "gitbook",
     "version": "0.1.0",
+    "engines": {
+        "node": "^22.3.0"
+    },
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
-        "@changesets/cli": "^2.29.7",
-        "turbo": "^2.5.8",
-        "vercel": "^39.4.2"
+        "@changesets/cli": "^2.29.8",
+        "turbo": "^2.8.10",
+        "vercel": "^50.23.2"
     },
-    "packageManager": "bun@1.2.15",
+    "packageManager": "bun@1.3.7",
     "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,
@@ -27,17 +32,28 @@
         "e2e-customers": "turbo run e2e-customers",
         "changeset": "changeset",
         "changeset-version": "changeset version && bun run format && bun update",
-        "release": "turbo run release && bun run publish-all-packages",
-        "publish-all-packages": "for dir in packages/*; do (cd \"$dir\" && bun publish || true); done && changeset tag",
+        "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.143.2",
+            "@tsconfig/strictest": "^2.0.6",
+            "@tsconfig/node20": "^20.1.6",
+            "@gitbook/api": "0.164.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",
-            "tsdown": "^0.15.6"
+            "bun-types": "^1.1.20",
+            "classnames": "^2.5.1",
+            "react": "^19.0.1",
+            "react-dom": "^19.0.1",
+            "tsdown": "^0.15.6",
+            "typescript": "^5.5.3",
+            "usehooks-ts": "^3.1.1"
         }
     },
     "patchedDependencies": {

packages/browser-types/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @gitbook/browser-types
 
+## 0.1.5
+
+### Patch Changes
+
+- 5f66860: Use isCookiesTrackingDisabled for cookie consent integrations
+- 2e495cb: Add Global Privacy Control (GPC) support
+
+## 0.1.4
+
+### Patch Changes
+
+- 7a11861: Add support for custom cookie banner registration
+- Updated dependencies [6f1db32]
+  - @gitbook/icons@0.4.3
+
+## 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.5",
     "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/browser-types/src/index.ts

@@ -46,6 +46,11 @@ export type GitBookAssistant = {
     ui?: boolean;
 };
 
+export type GitBookCookieBannerHandler = (options: {
+    onApprove: () => void;
+    onReject: () => void;
+}) => void;
+
 export type GitBookGlobal = {
     /**
      * Register an event listener.
@@ -72,6 +77,25 @@ export type GitBookGlobal = {
      * Register a custom assistant to be available on the site.
      */
     registerAssistant: (assistant: GitBookAssistant) => () => void;
+
+    /**
+     * Register a custom cookie banner handler.
+     * When registered, the built-in cookie banner will not be displayed.
+     */
+    registerCookieBanner: (handler: GitBookCookieBannerHandler) => void;
+
+    /**
+     * Indicates whether cookies tracking is disabled for the current user.
+     * Returns `true` when tracking is disabled, `false` when tracking is enabled,
+     * and `undefined` when the tracking preference is unknown or not yet determined.
+     */
+    isCookiesTrackingDisabled: () => boolean | undefined;
+
+    /**
+     * Indicates whether global privacy control is enabled for the current user.
+     * Returns `true` when global privacy control is enabled, `false` when it is disabled.
+     */
+    isGlobalPrivacyControlEnabled: () => boolean;
 };
 
 declare global {

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,55 @@
 # @gitbook/embed
 
+## 0.2.2
+
+### Patch Changes
+
+- b4b471f: Fix unexpected error thrown when using the embed in standalone mode
+
+## 0.2.1
+
+### Patch Changes
+
+- 96e24a1: Fix signed JWT token usage
+- 0aa34cc: Fix Embed options in React
+- Updated dependencies [6f1db32]
+  - @gitbook/icons@0.4.3
+
+## 0.2.0
+
+### Minor Changes
+
+- 1430cee: Improve Docs Embed with separate Assistant and Docs tabs
+
+### Patch Changes
+
+- Updated dependencies [62438f4]
+  - @gitbook/icons@0.4.0
+
+## 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

packages/embed/README.md

@@ -1,24 +1,62 @@
-# `@gitbook/embed`
+# GitBook Docs Embed (`@gitbook/embed`)
 
-Embed the GitBook Docs Assistant in your product or website.
+Embed your GitBook docs in your product or website.
+
+The Docs Embed can contain two tabs:
+- **Assistant**: The [GitBook Assistant](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) - an AI-powered chat interface to help users find answers
+- **Docs**: A browser for navigating your documentation site
+
+The embed is set up automatically based on your site's configuration. You can optionally customize and override the configuration with custom actions, tools, suggested questions, [Authenticated Access](https://gitbook.com/docs/publishing-documentation/authenticated-access), and more. See the [Configuration](#configuration) section for all available options.
 
 # Usage
 
-## As a script from your docs site
+## As a standalone script from your docs site
 
-All GitBook docs site includes a script to easily embed the docs assistant as a widget on your website.
+All GitBook docs sites include a script to easily add the Docs Embed as a widget on your website.
 
 The script is served at `https://docs.company.com/~gitbook/embed/script.js`.
 
-You can find the embed script from your docs site settings, or you can copy the following and replace the `docs.company.com` by your docs site hostname.
+You can find the embed script from your docs site settings, or you can copy the following and replace `docs.company.com` with your docs site hostname.
 
 ```html
 <script src="https://docs.company.com/~gitbook/embed/script.js"></script>
 <script>
+// Initialize with Authenticated Access (optional)
+window.GitBook('init', 
+    { siteURL: 'https://docs.company.com' },
+    { visitor: { token: 'your-jwt-token' } }
+);
 window.GitBook('show');
 </script>
 ```
 
+The standalone script provides a global `GitBook` function. See the [API Reference](#api-reference) section for all available methods.
+
+### Example: Configuring the widget
+
+```javascript
+GitBook('configure', {
+    button: {
+        label: 'Ask',
+        icon: 'assistant' // 'assistant' | 'sparkle' | 'help' | 'book'
+    },
+    tabs: ['assistant', 'docs'],
+    actions: [
+        {
+            icon: 'circle-question',
+            label: 'Contact Support',
+            onClick: () => window.open('https://support.example.com', '_blank')
+        }
+    ],
+    greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
+    suggestions: ['What is GitBook?', 'How do I get started?'],
+    tools: [/* ... */],
+    closeButton: true,
+});
+```
+
+See the [Configuration](#configuration) section for all available options.
+
 ## As a package from NPM
 
 Install the package: `npm install @gitbook/embed` and import it in your web application:
@@ -30,10 +68,47 @@ const gitbook = createGitBook({
     siteURL: 'https://docs.company.com'
 });
 
+// Create an iframe and get its URL
 const iframe = document.createElement('iframe');
-iframe.src = gitbook.getFrameURL();
+iframe.src = gitbook.getFrameURL({
+    visitor: {
+        token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
+        unsignedClaims: { // Optional: custom claims for dynamic expressions
+            userId: '123',
+            plan: 'premium'
+        }
+    }
+});
 
+// Create a frame client to communicate with the iframe
 const frame = gitbook.createFrame(iframe);
+
+// Use the frame client methods
+frame.navigateToPage('/getting-started'); // Navigate to a page in the docs tab
+frame.navigateToAssistant(); // Switch to the assistant tab
+frame.postUserMessage('How do I get started?');
+frame.clearChat();
+
+// Configure the embed (see Configuration section for all options)
+frame.configure({
+    tabs: ['assistant', 'docs'],
+    actions: [
+        {
+            icon: 'circle-question',
+            label: 'Contact Support',
+            onClick: () => window.open('https://support.example.com', '_blank')
+        }
+    ],
+    greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
+    suggestions: ['What is GitBook?', 'How do I get started?'],
+    tools: [/* ... */],
+    closeButton: true
+});
+
+// Listen to events
+frame.on('close', () => {
+    console.log('Frame closed');
+});
 ```
 
 ## As React components
@@ -41,9 +116,333 @@ const frame = gitbook.createFrame(iframe);
 After installing the NPM package, you can import prebuilt React components:
 
 ```tsx
-import { GitBookProvider, GitBookAssistantFrame } from '@gitbook/embed/react';
+import { GitBookProvider, GitBookFrame } from '@gitbook/embed/react';
 
 <GitBookProvider siteURL="https://docs.company.com">
-    <GitBookAssistantFrame />
+    <GitBookFrame
+        visitor={{
+            token: 'your-jwt-token', // Optional: for Adaptive Content or Authenticated Access
+            unsignedClaims: { userId: '123' } // Optional: custom claims for dynamic expressions
+        }}
+        tabs={['assistant', 'docs']}
+        greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
+        suggestions={['What is GitBook?', 'How do I get started?']}
+        actions={[
+            {
+                icon: 'circle-question',
+                label: 'Contact Support',
+                onClick: () => window.open('https://support.example.com', '_blank')
+            }
+        ]}
+        tools={[/* ... */]}
+        closeButton
+    />
 </GitBookProvider>
 ```
+
+You can also use the `useGitBook` hook to access the client:
+
+```tsx
+import { useGitBook } from '@gitbook/embed/react';
+
+function MyComponent() {
+    const gitbook = useGitBook();
+    const frameURL = gitbook.getFrameURL({ visitor: { token: '...' } });
+    // ...
+}
+```
+
+# API Reference
+
+## Method Comparison
+
+| Method | Standalone Script | NPM Package | React Components |
+|--------|------------------|-------------|------------------|
+| **Initialize** | `GitBook('init', options, frameOptions)` | `createGitBook(options)` | `<GitBookProvider siteURL="...">` |
+| **Get frame URL** | ❌ (handled internally) | `client.getFrameURL(options)` | `useGitBook().getFrameURL(options)` |
+| **Create frame client** | ❌ (handled internally) | `client.createFrame(iframe)` | `useGitBook().createFrame(iframe)` |
+| **Show/Hide widget** | `GitBook('show')` / `GitBook('hide')` | ❌ | ❌ |
+| **Open/Close window** | `GitBook('open')` / `GitBook('close')` / `GitBook('toggle')` | ❌ | ❌ |
+| **Navigate to page** | `GitBook('navigateToPage', path)` | `frame.navigateToPage(path)` | Via frame client |
+| **Navigate to assistant** | `GitBook('navigateToAssistant')` | `frame.navigateToAssistant()` | Via frame client |
+| **Post message** | `GitBook('postUserMessage', message)` | `frame.postUserMessage(message)` | Via frame client |
+| **Clear chat** | `GitBook('clearChat')` | `frame.clearChat()` | Via frame client |
+| **Configure** | `GitBook('configure', settings)` | `frame.configure(settings)` | Props on `<GitBookFrame>` |
+| **Event listeners** | ❌ | `frame.on(event, listener)` | Via frame client |
+| **Unload** | `GitBook('unload')` | ❌ | ❌ |
+
+## Method Signatures
+
+### Standalone Script
+
+- `GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} })` - Initialize widget
+- `GitBook('show')` - Show widget button
+- `GitBook('hide')` - Hide widget button
+- `GitBook('open')` - Open widget window
+- `GitBook('close')` - Close widget window
+- `GitBook('toggle')` - Toggle widget window
+- `GitBook('navigateToPage', path: string)` - Navigate to page
+- `GitBook('navigateToAssistant')` - Navigate to assistant tab
+- `GitBook('postUserMessage', message: string)` - Post message to chat
+- `GitBook('clearChat')` - Clear chat history
+- `GitBook('configure', settings: {...})` - Configure widget
+- `GitBook('unload')` - Unload widget
+
+### NPM Package
+
+**Client Factory:**
+- `createGitBook(options: { siteURL: string })` → `GitBookClient`
+- `client.getFrameURL(options?: { visitor?: {...} })` → `string`
+- `client.createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient`
+
+**Frame Client:**
+- `frame.navigateToPage(path: string)` → `void`
+- `frame.navigateToAssistant()` → `void`
+- `frame.postUserMessage(message: string)` → `void`
+- `frame.clearChat()` → `void`
+- `frame.configure(settings: Partial<GitBookEmbeddableConfiguration>)` → `void`
+- `frame.on(event: string, listener: Function)` → `() => void` (unsubscribe)
+
+### React Components
+
+**Components:**
+- `<GitBookProvider siteURL: string>` - Provider component
+- `<GitBookFrame {...props}>` - Frame component (accepts all config options as props)
+
+**Hooks:**
+- `useGitBook()` → `GitBookClient` (must be used within `<GitBookProvider>`)
+
+# Configuration
+
+Configuration options are available across usage methods as follows:
+- **Standalone script**: via `GitBook('configure', {...})`
+- **NPM package**: via `frame.configure({...})`
+- **React components**: via props on `<GitBookFrame>`
+
+### `tabs`
+
+Available in: Standalone script, NPM package, React components
+
+Override which tabs are displayed. Defaults to your site's configuration.
+
+- **Type**: `('assistant' | 'docs')[]`
+
+```javascript
+tabs: ['assistant', 'docs']
+```
+
+### `closeButton`
+
+Available in: Standalone script, NPM package, React components
+
+Display a close (`x`) button in the embed sidebar.
+
+- **Type**: `boolean`
+- **Default**: `false`
+
+```javascript
+closeButton: true
+```
+
+Behavior:
+- When clicked, the embed sends a `close` event to the parent page.
+- In the standalone script, this event is handled automatically and the widget closes.
+- In custom iframe integrations (NPM package), you must listen for the `close` event and decide how to hide/collapse your UI.
+- In React, this works automatically when using the standard widget flow. If you build custom frame wiring, handle `close` the same way as the NPM package.
+
+NPM package example:
+
+```typescript
+const frame = gitbook.createFrame(iframe);
+
+frame.configure({
+    closeButton: true
+});
+
+const unsubscribe = frame.on('close', () => {
+    // Hide your modal/drawer/container
+    container.classList.add('hidden');
+});
+```
+
+Notes:
+- The close button is rendered in the same sidebar area as tabs/actions.
+- If your UI hides that sidebar or doesn't render it, the button will not be visible.
+
+### `actions`
+
+Available in: Standalone script, NPM package, React components
+
+Custom action buttons rendered in the sidebar alongside tabs. Each action button triggers a callback when clicked.
+
+**Note**: This prop was previously named `buttons`. Use `actions` instead, it has the same functionality.
+
+- **Type**: `GitBookEmbeddableActionDefinition[]`
+- **Properties**:
+  - `icon`: `string` - Icon name. Any [FontAwesome icon](https://fontawesome.com/search) is supported. (e.g., `'rocket'`, `'comments'`, `'user-circle'`, ...)
+  - `label`: `string` - Button label text
+  - `onClick`: `() => void | Promise<void>` - Callback function when clicked
+
+```javascript
+actions: [
+    {
+        icon: 'comments',
+        label: 'Contact Support',
+        onClick: () => window.open('https://support.example.com', '_blank')
+    },
+    {
+        icon: 'rocket',
+        label: 'Get started',
+        onClick: () => {
+            GitBook('navigateToPage', '/getting-started');
+        }
+    }
+]
+```
+
+### `greeting`
+
+Available in: Standalone script, NPM package, React components
+
+Welcome message displayed in the [Assistant](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) tab.
+
+- **Type**: `{ title: string, subtitle: string }`
+
+```javascript
+greeting: {
+    title: 'Welcome!',
+    subtitle: 'How can I help you today?'
+}
+```
+
+### `suggestions`
+
+Available in: Standalone script, NPM package, React components
+
+Suggested questions displayed in the [Assistant](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant) welcome screen.
+
+- **Type**: `string[]`
+
+```javascript
+suggestions: [
+    'What is GitBook?',
+    'How do I get started?',
+    'What can you do?'
+]
+```
+
+### `tools`
+
+Available in: Standalone script, NPM package, React components
+
+Custom AI tools to extend the [Assistant](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant). Tools allow the assistant to execute functions and integrate with your own systems.
+
+**Note**: In addition to custom tools, the Assistant will always have access to any [MCP servers you define](https://gitbook.com/docs/publishing-documentation/gitbook-ai-assistant#extend-gitbook-assistant-with-mcp-servers) in your site's AI settings.
+
+- **Type**: `GitBookToolDefinition[]`
+- **Properties**:
+  - `name`: `string` - Unique tool identifier
+  - `description`: `string` - Description of what the tool does (used by the AI to decide when and how to use it).
+  - `inputSchema`: `object` - JSON schema defining the tool's input parameters
+  - `execute`: `(input: object) => Promise<{ output: any, summary: string }>` - Async function that executes the tool.
+    - `output`: The result of the tool execution, provided to the AI to continue working with. Not shown to the user.
+    - `summary`: The visual summary of the tool execution, shown in the user's chat window.
+  - `confirmation`: `{ icon?: string, label: string }` (optional) - Confirmation button shown before execution, useful for actions that require the user's express approval.
+
+```javascript
+tools: [
+    {
+        name: 'get_user_info',
+        description: 'Get information about the current user',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                userId: { 
+                    type: 'string', 
+                    description: 'The user ID to look up' 
+                }
+            },
+            required: ['userId']
+        },
+        execute: async (input) => {
+            const user = await fetch(`/api/users/${input.userId}`).then(r => r.json());
+            return {
+                output: { name: user.name, plan: user.plan },
+                summary: `Retrieved info for user ${user.name}`
+            };
+        }
+    },
+    {
+        name: 'create_ticket',
+        description: 'Create a support ticket',
+        confirmation: {
+            icon: 'circle-question',
+            label: 'Create support ticket?'
+        },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                subject: { type: 'string' },
+                description: { type: 'string' }
+            },
+            required: ['subject', 'description']
+        },
+        execute: async (input) => {
+            const ticket = await fetch('/api/tickets', {
+                method: 'POST',
+                body: JSON.stringify(input)
+            }).then(r => r.json());
+            return {
+                output: { ticketId: ticket.id },
+                summary: `Created ticket #${ticket.id}`
+            };
+        }
+    }
+]
+```
+
+### `visitor` (Authenticated Access)
+
+Available in: Standalone script (via `init`), NPM package (via `getFrameURL()`), React components (as prop)
+
+[Authenticated Access](https://gitbook.com/docs/publishing-documentation/authenticated-access) options passed when creating the frame URL. Used for [Adaptive Content](https://gitbook.com/docs/publishing-documentation/adaptive-content) and [Authenticated Access](https://gitbook.com/docs/publishing-documentation/authenticated-access).
+
+**Note**: This is not a configuration option but rather a parameter when initializing the frame or creating the frame URL.
+
+**Standalone script**: Pass as the second argument to `GitBook('init', options, frameOptions)`
+**NPM package**: Pass to `getFrameURL({ visitor: {...} })`
+**React components**: Pass as the `visitor` prop on `<GitBookFrame>`
+
+- **Type**: `{ token?: string, unsignedClaims?: Record<string, unknown> }`
+- **Properties**:
+  - `token`: `string` (optional) - Signed JWT token for [Adaptive Content](https://gitbook.com/docs/publishing-documentation/adaptive-content) or [Authenticated Access](https://gitbook.com/docs/publishing-documentation/authenticated-access)
+  - `unsignedClaims`: `Record<string, unknown>` (optional) - Unsigned claims that can be used in dynamic expressions via `visitor.claims.unsigned.<claim-name>`
+
+```javascript
+visitor: {
+    token: 'your-jwt-token',
+    unsignedClaims: {
+        userId: '123',
+        plan: 'premium',
+        role: 'admin'
+    }
+}
+```
+
+### `button`
+
+Available in: Standalone script only
+
+Configure the widget button for the standalone script. This option is not available when using the NPM package or React components, since they can be customized completely.
+
+- **Type**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }`
+- **Properties**:
+  - `label`: `string` - Button label text
+  - `icon`: `'assistant' | 'sparkle' | 'help' | 'book'` - Icon displayed on the button. Choose from one of 4 presets.
+
+```javascript
+button: {
+    label: 'Ask',
+    icon: 'assistant'
+}
+```

packages/embed/package.json

@@ -12,26 +12,39 @@
             "default": "./dist/react/index.js"
         }
     },
-    "version": "0.1.2",
+    "sideEffects": false,
+    "version": "0.2.2",
     "dependencies": {
         "@gitbook/api": "catalog:",
         "@gitbook/icons": "workspace:",
         "bidc": "catalog:"
     },
     "peerDependencies": {
-        "react": "^18.0.0"
+        "react": "*"
     },
     "devDependencies": {
+        "bun-types": "catalog:",
+        "@types/react": "catalog:",
         "tsdown": "catalog:",
-        "typescript": "^5.5.3",
-        "react": "^19.0.0"
+        "typescript": "catalog:",
+        "react": "catalog:"
     },
     "scripts": {
         "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"
+        "unit": "bun test",
+        "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/embed/src/client/createGitBook.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createGitBook } from './createGitBook';
+
+describe('createGitBook.getFrameURL', () => {
+    it('builds the embed URL when the site URL has no trailing slash', () => {
+        const client = createGitBook({ siteURL: 'https://example.com/docs' });
+
+        const url = new URL(client.getFrameURL({}));
+
+        expect(url.origin).toBe('https://example.com');
+        expect(url.pathname).toBe('/docs/~gitbook/embed');
+        expect(url.searchParams.toString()).toBe('');
+    });
+
+    it('handles a trailing slash and adds visitor parameters', () => {
+        const client = createGitBook({ siteURL: 'https://example.com/docs/' });
+
+        const url = new URL(
+            client.getFrameURL({
+                visitor: {
+                    token: 'signed-token',
+                    unsignedClaims: {
+                        role: 'editor',
+                        count: 3,
+                        enabled: false,
+                    },
+                },
+            })
+        );
+
+        expect(url.pathname).toBe('/docs/~gitbook/embed');
+        expect(url.searchParams.get('jwt_token')).toBe('signed-token');
+        expect(url.searchParams.get('visitor.role')).toBe('editor');
+        expect(url.searchParams.get('visitor.count')).toBe('3');
+        expect(url.searchParams.get('visitor.enabled')).toBe('false');
+    });
+});

packages/embed/src/client/createGitBook.ts

@@ -40,10 +40,10 @@ export function createGitBook(options: CreateGitBookOptions) {
     const client: GitBookClient = {
         getFrameURL: (frameOptions) => {
             const url = new URL(options.siteURL);
-            url.pathname = `${url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`}~gitbook/embed/assistant`;
+            url.pathname = `${url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`}~gitbook/embed`;
 
             if (frameOptions.visitor?.token) {
-                url.searchParams.set('token', frameOptions.visitor.token);
+                url.searchParams.set('jwt_token', frameOptions.visitor.token);
             }
 
             if (frameOptions.visitor?.unsignedClaims) {

packages/embed/src/client/createGitBookFrame.ts

@@ -64,8 +64,9 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
     const events = new Map<string, Array<(...args: any[]) => void>>();
 
     const configuration: GitBookEmbeddableConfiguration = {
-        buttons: [],
-        welcomeMessage: '',
+        tabs: ['assistant', 'docs'],
+        actions: [],
+        greeting: { title: '', subtitle: '' },
         suggestions: [],
         tools: [],
     };

packages/embed/src/client/protocol.ts

@@ -23,7 +23,7 @@ export type GitBookToolDefinition = AIToolDefinition & {
 /**
  * Custom button definition to be passed to the embeddable GitBook.
  */
-export type GitBookEmbeddableButtonDefinition = {
+export type GitBookEmbeddableActionDefinition = {
     /**
      * Icon to be displayed in the button.
      */
@@ -41,22 +41,37 @@ export type GitBookEmbeddableButtonDefinition = {
 };
 
 /**
- * Overall configuration for the layout of the embeddable GitBook.
+ * Overall configuration for the layout of the GitBook embed.
  */
 export type GitBookEmbeddableConfiguration = {
+    /** Tabs to display in the embed (if enabled on the site). */
+    tabs: ('assistant' | 'docs')[];
+
+    /** Additional buttons to be displayed in the header of the GitBook embed. */
+    actions: GitBookEmbeddableActionDefinition[];
+
     /**
-     * Buttons to be displayed in the header of the embeddable GitBook.
+     * Additional buttons to be displayed in the header of the GitBook embed.
+     * @deprecated Use `actions` instead.
      */
-    buttons: GitBookEmbeddableButtonDefinition[];
+    buttons?: GitBookEmbeddableActionDefinition[];
 
     /** Message to be displayed in the welcome page. */
-    welcomeMessage: string;
+    greeting: {
+        title: string;
+        subtitle: string;
+    };
 
     /** Suggestions of questions to be displayed in the welcome page. */
     suggestions: string[];
 
     /** Tools to be provided to the assistant. */
     tools: GitBookToolDefinition[];
+
+    /**
+     * Display a close button inside the assistant.
+     */
+    closeButton?: boolean;
 };
 
 /**

packages/embed/src/index.ts

@@ -1 +1,2 @@
 export * from './client';
+export * from './standalone';

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,
@@ -9,34 +11,45 @@ import { useGitBook } from './GitBookProvider';
 export type GitBookFrameProps = {
     className?: string;
 } & GetFrameURLOptions &
-    GitBookEmbeddableConfiguration;
+    Partial<GitBookEmbeddableConfiguration>;
 
 /**
  * Render a frame with the GitBook Assistant in it.
  */
 export function GitBookFrame(props: GitBookFrameProps) {
-    const { className, visitor, buttons, welcomeMessage, suggestions, tools } = props;
+    const {
+        className,
+        visitor,
+        actions = [],
+        greeting,
+        suggestions = [],
+        tools = [],
+        tabs = ['assistant', 'docs'],
+        closeButton = false,
+    } = 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,
+            tabs,
+            actions,
+            greeting,
             suggestions,
             tools,
+            closeButton,
         });
-    }, [gitbookFrame, buttons, welcomeMessage, suggestions, tools]);
+    }, [gitbookFrame, actions, greeting, suggestions, tools, tabs, closeButton]);
 
     return (
         <iframe

packages/embed/src/standalone/index.ts

@@ -31,24 +31,50 @@ type StandaloneCalls =
     // Clear the chat
     | ['clearChat']
     // Configure the embed
-    | ['configure', Partial<GitBookEmbeddableConfiguration>]
+    | ['configure', Partial<GitBookEmbeddableConfiguration & StandaloneConfiguration>]
     // Navigate to a page
     | ['navigateToPage', string]
     // Navigate to the assistant
     | ['navigateToAssistant'];
 
+type StandaloneConfiguration = {
+    /** Configure the button to open the embed */
+    button: {
+        /** Label to be displayed in the button. */
+        label: string;
+        /** Icon to be displayed in the button. */
+        icon: 'assistant' | 'sparkle' | 'help' | 'book';
+    };
+};
+
 export type GitBookStandalone = ((...args: StandaloneCalls) => void) & {
     q?: StandaloneCalls[];
 };
 
+let widgetIframe: HTMLIFrameElement | undefined;
+let _client: GitBookClient | undefined;
+let _frame: GitBookFrameClient | undefined;
+let frameOptions: GetFrameURLOptions | undefined;
+let frameConfiguration: GitBookEmbeddableConfiguration & StandaloneConfiguration = {
+    button: {
+        label: 'Ask',
+        icon: 'assistant',
+    },
+    actions: [],
+    greeting: { title: '', subtitle: '' },
+    suggestions: [],
+    tools: [],
+    tabs: ['assistant', 'docs'],
+};
+
 const widgetButton = document.createElement('button');
 widgetButton.id = 'gitbook-widget-button';
 widgetButton.addEventListener('click', () => {
     GitBook('toggle');
 });
 widgetButton.innerHTML = `
-    <span id="gitbook-widget-button-icon"></span>
-    <span id="gitbook-widget-button-label">Ask</span>
+    <span id="gitbook-widget-button-icon" data-icon="${frameConfiguration.button.icon}"></span>
+    <span id="gitbook-widget-button-label">${frameConfiguration.button.label}</span>
 `;
 
 const widgetWindow = document.createElement('div');
@@ -58,17 +84,6 @@ widgetWindow.classList.add('hidden');
 document.body.appendChild(widgetButton);
 document.body.appendChild(widgetWindow);
 
-let widgetIframe: HTMLIFrameElement | undefined;
-let _client: GitBookClient | undefined;
-let _frame: GitBookFrameClient | undefined;
-let frameOptions: GetFrameURLOptions | undefined;
-let frameConfiguration: GitBookEmbeddableConfiguration = {
-    buttons: [],
-    welcomeMessage: '',
-    suggestions: [],
-    tools: [],
-};
-
 function getClient() {
     if (!_client) {
         throw new Error(
@@ -91,6 +106,10 @@ function getIframe() {
         widgetWindow.appendChild(widgetIframe);
 
         _frame = client.createFrame(widgetIframe);
+        _frame.on('close', () => {
+            widgetWindow.classList.add('hidden');
+            widgetButton.classList.remove('open');
+        });
     }
     return { iframe: widgetIframe, frame: _frame };
 }
@@ -135,27 +154,31 @@ const GitBook = (...args: StandaloneCalls) => {
         case 'postUserMessage':
             getIframe().frame.postUserMessage(args[1]);
             break;
-        case 'configure':
+        case 'configure': {
+            const settings = args[1];
             frameConfiguration = {
                 ...frameConfiguration,
-                ...args[1],
+                ...settings,
             };
+            // Update the button label and icon
+            if (settings.button?.label) {
+                const label = widgetButton.querySelector('#gitbook-widget-button-label');
+                if (label) {
+                    label.textContent = settings.button.label;
+                }
+            }
+            if (settings.button?.icon) {
+                const icon = widgetButton.querySelector('#gitbook-widget-button-icon');
+                if (icon) {
+                    icon.setAttribute('data-icon', settings.button.icon);
+                }
+            }
+
             getIframe().frame.configure({
                 ...frameConfiguration,
-                buttons: [
-                    ...frameConfiguration.buttons,
-
-                    // Always include a close button
-                    {
-                        icon: 'close',
-                        label: 'Close',
-                        onClick: () => {
-                            GitBook('close');
-                        },
-                    },
-                ],
             });
             break;
+        }
         case 'clearChat':
             getIframe().frame.clearChat();
             break;
@@ -174,5 +197,3 @@ const precalls = (window.GitBook as GitBookStandalone | undefined)?.q ?? [];
 // @ts-expect-error - GitBook is not defined in the global scope
 window.GitBook = GitBook;
 precalls.forEach((call) => GitBook(...call));
-
-GitBook('configure', {});

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;
 }
@@ -103,6 +113,18 @@
     background-color: currentColor;
 }
 
+#gitbook-widget-button-icon[data-icon="sparkle"] {
+    mask-image: url("https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/sparkle.svg?v=2&token=a463935e93");
+}
+
+#gitbook-widget-button-icon[data-icon="help"] {
+    mask-image: url("https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/circle-question.svg?v=2&token=a463935e93");
+}
+
+#gitbook-widget-button-icon[data-icon="book"] {
+    mask-image: url("https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/book-open.svg?v=2&token=a463935e93");
+}
+
 #gitbook-widget-button.open #gitbook-widget-button-icon {
     mask-image: url('https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/close.svg?v=2&token=a463935e93');
 }
@@ -120,7 +142,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/tsconfig.json

@@ -15,7 +15,9 @@
         "isolatedModules": true,
         "jsx": "react-jsx",
         "incremental": true,
-        "types": []
+        "types": [
+            "bun-types" // add Bun global
+        ]
     },
     "include": ["src/**/*.ts", "src/**/*.tsx"],
     "exclude": ["node_modules"]

packages/embed/tsdown.config.ts

@@ -2,8 +2,12 @@ import { defineConfig } from 'tsdown';
 
 export default defineConfig([
     {
-        entry: ['src/index.ts', 'src/react/index.ts'],
-        dts: true,
-        format: ['esm'],
+        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,24 @@
 # @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

packages/expr/package.json

@@ -1,38 +1,47 @@
 {
     "name": "@gitbook/expr",
     "description": "Safely evaluate & parse user-defined GitBook expressions.",
-    "version": "1.2.1",
+    "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": "^8.15.0",
+        "acorn-loose": "^8.5.2",
         "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": "catalog:",
+        "@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",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
         "clean": "rm -rf ./dist",
-        "dev": "bun run build -- --watch"
+        "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/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,233 @@
 # gitbook
 
+## 0.22.1
+
+### Patch Changes
+
+- 9d5e397: Remove code syntax highlighting patch for Safari
+- 3d8e89c: Show favicon for record search results in the assistant.
+- 5f66860: Use isCookiesTrackingDisabled for cookie consent integrations
+- 426aabe: Fix TOC header logo on bold themes
+- ae30a57: Integrate Ask AI with upcoming insights by passing visitor session IDs.
+- f7c251e: Update Reddit social account rendering
+- e31a8f4: Hide cookie banner for AI user agents
+- 2e495cb: Add Global Privacy Control (GPC) support
+- Updated dependencies [1a7ef78]
+- Updated dependencies [93eea0b]
+- Updated dependencies [b4b471f]
+- Updated dependencies [5f66860]
+- Updated dependencies [2ebb18d]
+- Updated dependencies [11d9b80]
+- Updated dependencies [2e495cb]
+- Updated dependencies [f517035]
+  - @gitbook/react-openapi@1.5.8
+  - @gitbook/embed@0.2.2
+  - @gitbook/browser-types@0.1.5
+
+## 0.22.0
+
+### Minor Changes
+
+- e00d1c5: Support code themes customization
+- f294818: Serve a markdown version of the page when the "Accept" header contains "text/markdown".
+
+### Patch Changes
+
+- 9d6457f: OpenAPI styling tweaks
+- d738e11: Prevent form submission during IME composition
+- 1e53376: Add sidesheet component, use it for TOC and AIChat
+- f7f6f9d: Set <html lang> based on translated language
+- 89de966: Support social links
+- b53cb1d: Align styling of PageLinkItem and PageDocumentItem
+- 27a34b7: Support `defaultExpanded` in Expandable block
+- a5ef44a: Better conditional display of page actions
+- 07c02eb: Header & TOC tweaks
+- 29e2b22: Fix ordered list item index calculation
+- f6cf62a: Standardise toggle chevrons across the app
+- b57561d: Fix rendering of images in reusable content from an external space with the new dereferencing in the API.
+- e172b25: Grow InlineActionButton to take available width on line
+- 7a11861: Add support for custom cookie banner registration
+- 8f32f4f: Better handle huge section groups
+- 0aa34cc: Fix Embed options in React
+- Updated dependencies [e00d1c5]
+- Updated dependencies [96e24a1]
+- Updated dependencies [4e2d863]
+- Updated dependencies [d3f6c38]
+- Updated dependencies [3ba9e46]
+- Updated dependencies [717ad0b]
+- Updated dependencies [6f1db32]
+- Updated dependencies [7a11861]
+- Updated dependencies [0aa34cc]
+- Updated dependencies [48ca21e]
+  - @gitbook/react-openapi@1.5.7
+  - @gitbook/embed@0.2.1
+  - @gitbook/openapi-parser@3.0.8
+  - @gitbook/icons@0.4.3
+  - @gitbook/browser-types@0.1.4
+  - @gitbook/react-contentkit@0.7.12
+
+## 0.21.3
+
+### Patch Changes
+
+- Updated dependencies [bf63045]
+  - @gitbook/react-openapi@1.5.6
+
+## 0.21.2
+
+### Patch Changes
+
+- ca68236: Fix 404 when accessing rss.xml for the root page.
+- 21851d3: Round page cover corners on extrawide screens
+- 695e99f: Update button sizing
+- 7517e98: Clean up button and input across the app
+- 99d788e: Update page cover styling
+- ebf3b2b: Fix an issue where content refs to spaces outside of site was resolving with share links
+- 35efc9d: Fix TOCPageIcons backgrounds on gradient and bold themes
+- a7f58ab: Fix embed tab button size regression
+- 360b525: Switch icon masking method to fix visual cutoffs in FA7
+- Updated dependencies [985c1b4]
+- Updated dependencies [360b525]
+  - @gitbook/openapi-parser@3.0.7
+  - @gitbook/icons@0.4.2
+  - @gitbook/react-openapi@1.5.5
+  - @gitbook/react-contentkit@0.7.11
+
+## 0.21.1
+
+### Patch Changes
+
+- Updated dependencies [e7fb771]
+  - @gitbook/icons@0.4.1
+  - @gitbook/react-contentkit@0.7.10
+
+## 0.21.0
+
+### Minor Changes
+
+- 3553db0: Add a RSS feed to all pages with update blocks.
+
+### Patch Changes
+
+- f478ddc: Add Input component
+- 3817289: Fix overflowing section groups
+- 86e7aa6: Fix search results cursor
+- 1430cee: Improve Docs Embed with separate Assistant and Docs tabs
+- ed9e8fe: Add support for button actions
+- 9c69cc4: Add customizable suggested questions
+- c51076e: Fix links to other spaces and root page in embeddable view.
+- 6278a18: Support `greeting` and fix suggested questions if there are no custom ones defined
+- 04a4175: Remove hidden site spaces from navigation
+- 74f8931: Fix hidden section not found
+- 344842f: Improve OpenAPI circular references
+- Updated dependencies [4766092]
+- Updated dependencies [8761cee]
+- Updated dependencies [461e15f]
+- Updated dependencies [1430cee]
+- Updated dependencies [62438f4]
+- Updated dependencies [3e40b4d]
+- Updated dependencies [87d68ea]
+- Updated dependencies [344842f]
+  - @gitbook/react-openapi@1.5.4
+  - @gitbook/openapi-parser@3.0.6
+  - @gitbook/embed@0.2.0
+  - @gitbook/icons@0.4.0
+  - @gitbook/react-contentkit@0.7.9
+
+## 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

packages/gitbook/e2e/cookie-banner.spec.ts

@@ -0,0 +1,76 @@
+import { expect } from '@playwright/test';
+
+import { type TestsCase, getCustomizationURL, runTestCases } from './util';
+
+const testCases: TestsCase[] = [
+    {
+        name: 'Cookie Banner',
+        contentBaseURL: 'https://gitbook.com/docs/',
+        tests: [
+            {
+                name: 'should show built-in banner when no custom banner is registered',
+                url: getCustomizationURL({
+                    privacyPolicy: {
+                        url: 'https://policies.gitbook.com/privacy/cookies',
+                    },
+                }),
+                screenshot: false,
+                run: async (page) => {
+                    // Check that built-in banner is visible
+                    const dialog = page.getByTestId('cookies-dialog');
+                    await expect(dialog).toBeVisible({ timeout: 5000 });
+                },
+            },
+            {
+                name: 'should not show built-in banner when UserAgent is AI',
+                url: getCustomizationURL({
+                    privacyPolicy: {
+                        url: 'https://policies.gitbook.com/privacy/cookies',
+                    },
+                }),
+                screenshot: false,
+                run: async (page) => {
+                    // Override navigator.userAgent to simulate AI crawler (affects isAIUserAgent())
+                    await page.addInitScript(() => {
+                        Object.defineProperty(navigator, 'userAgent', {
+                            get: () =>
+                                'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot',
+                            configurable: true,
+                        });
+                    });
+                    await page.reload();
+
+                    // Check that built-in banner is not visible for AI UserAgent
+                    const dialog = page.getByTestId('cookies-dialog');
+                    await expect(dialog).not.toBeVisible({ timeout: 5000 });
+                },
+            },
+            {
+                name: 'should not show built-in banner when custom banner is registered',
+                url: getCustomizationURL({
+                    privacyPolicy: {
+                        url: 'https://policies.gitbook.com/privacy/cookies',
+                    },
+                }),
+                screenshot: false,
+                run: async (page) => {
+                    // Register a custom cookie banner handler
+                    await page.waitForFunction(() => {
+                        return typeof window !== 'undefined' && window.GitBook !== undefined;
+                    });
+                    await page.evaluate(() => {
+                        window.GitBook?.registerCookieBanner(() => {
+                            // Custom cookie banner handler - no-op for testing to avoid reload
+                        });
+                    });
+
+                    // Check that built-in banner is not visible
+                    const dialog = page.getByTestId('cookies-dialog');
+                    await expect(dialog).not.toBeVisible({ timeout: 5000 });
+                },
+            },
+        ],
+    },
+];
+
+runTestCases(testCases);

packages/gitbook/e2e/customers.spec.ts

@@ -10,18 +10,18 @@ const testCases: TestsCase[] = [
             { name: 'OpenAPI', url: '/snyk-api/reference/apps', run: waitForCookiesDialog },
         ],
     },
-    // {
-    //     name: 'Nexthink',
-    //     contentBaseURL: 'https://docs.nexthink.com',
-    //     tests: [
-    //         {
-    //             name: 'Home',
-    //             url: '/',
-    //             screenshot: { waitForTOCScrolling: false },
-    //             run: waitForCookiesDialog,
-    //         },
-    //     ],
-    // },
+    {
+        name: 'Nexthink',
+        contentBaseURL: 'https://docs.nexthink.com',
+        tests: [
+            {
+                name: 'Home',
+                url: '/',
+                screenshot: { waitForTOCScrolling: false },
+                run: waitForCookiesDialog,
+            },
+        ],
+    },
     {
         name: 'asiksupport-stg.dto.kemkes.go.id',
         contentBaseURL: 'https://asiksupport-stg.dto.kemkes.go.id',
@@ -37,11 +37,6 @@ const testCases: TestsCase[] = [
         contentBaseURL: 'https://faq.deltaemulator.com',
         tests: [{ name: 'Home', url: '/' }],
     },
-    {
-        name: 'docs.dify.ai',
-        contentBaseURL: 'https://docs.dify.ai',
-        tests: [{ name: 'Home', url: '/', run: waitForCookiesDialog }],
-    },
     {
         name: 'seeddao.gitbook.io',
         contentBaseURL: 'https://seeddao.gitbook.io',
@@ -112,11 +107,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 +167,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',
@@ -242,7 +232,6 @@ const testCases: TestsCase[] = [
     {
         name: 'run-ai-docs.nvidia.com',
         contentBaseURL: 'https://run-ai-docs.nvidia.com',
-        skip: process.env.ARGOS_BUILD_NAME !== 'customers-v2',
         tests: [
             { name: 'Home', url: '/' },
             { name: 'OG Image', url: '/~gitbook/ogimage/h17zQIFwy3MaafVNmItO', mode: 'image' },

packages/gitbook/e2e/pdf.spec.ts

@@ -29,7 +29,7 @@ test.describe('PDF export', () => {
         const printBtn = page.getByTestId('print-button');
         await expect(printBtn).toBeVisible();
 
-        await argosScreenshot(page, 'pdf - all pages', {
+        await argosScreenshot(page, 'pdf - e2e - all pages', {
             viewports: ['macbook-13'],
             argosCSS: `
                             /* Hide Intercom */
@@ -67,7 +67,7 @@ test.describe('PDF export', () => {
         const printBtn = page.getByTestId('print-button');
         await expect(printBtn).toBeVisible();
 
-        await argosScreenshot(page, 'pdf - all pages', {
+        await argosScreenshot(page, 'pdf - gb-docs - all pages', {
             viewports: ['macbook-13'],
             argosCSS: `
                             /* Hide Intercom */
@@ -109,7 +109,7 @@ test.describe('PDF export', () => {
         const printBtn = page.getByTestId('print-button');
         await expect(printBtn).toBeVisible();
 
-        await argosScreenshot(page, 'pdf - all pages', {
+        await argosScreenshot(page, 'pdf - e2e - single-page', {
             viewports: ['macbook-13'],
             argosCSS: `
                             /* Hide Intercom */
@@ -151,7 +151,7 @@ test.describe('PDF export', () => {
         const printBtn = page.getByTestId('print-button');
         await expect(printBtn).toBeVisible();
 
-        await argosScreenshot(page, 'pdf - all pages', {
+        await argosScreenshot(page, 'pdf - gb-docs - single-page', {
             viewports: ['macbook-13'],
             argosCSS: `
                             /* Hide Intercom */

packages/gitbook/e2e/util.ts

@@ -2,6 +2,7 @@ import { argosScreenshot } from '@argos-ci/playwright';
 import {
     CustomizationAIMode,
     CustomizationBackground,
+    CustomizationCodeTheme,
     CustomizationCorners,
     CustomizationDefaultFont,
     CustomizationDefaultMonospaceFont,
@@ -143,7 +144,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 +155,23 @@ export async function waitForNotFound(_page: Page, response: Response | null) {
     expect(response?.status()).toBe(404);
 }
 
+export async function setTimeToMorning(page: Page) {
+    const now = new Date();
+    now.setHours(8, 0, 0, 0); // 8:00:00.000 AM (local time)
+
+    await page.clock.install({ time: now });
+}
+
+export async function waitForCoverImages(page: Page, options?: { darkMode?: boolean }) {
+    const selector = options?.darkMode
+        ? 'img[alt="Page cover"].dark\\:inline'
+        : 'img[alt="Page cover"]:not(.dark\\:inline)';
+    // Wait for cover images to exist (not the shimmer placeholder)
+    await expect(page.locator(selector)).toBeVisible({
+        timeout: 10_000,
+    });
+}
+
 /**
  * Transform test cases into Playwright tests and run it.
  */
@@ -288,6 +309,16 @@ export function getCustomizationURL(partial: DeepPartial<SiteCustomizationSettin
             background: CustomizationBackground.Plain,
             icons: CustomizationIconsStyle.Regular,
             links: CustomizationLinksStyle.Default,
+            codeTheme: {
+                default: {
+                    light: CustomizationCodeTheme.DefaultLight,
+                    dark: CustomizationCodeTheme.DefaultDark,
+                },
+                openapi: {
+                    light: CustomizationCodeTheme.DefaultLight,
+                    dark: CustomizationCodeTheme.DefaultDark,
+                },
+            },
             sidebar: {
                 background: CustomizationSidebarBackgroundStyle.Default,
                 list: CustomizationSidebarListStyle.Default,
@@ -345,6 +376,7 @@ export function getCustomizationURL(partial: DeepPartial<SiteCustomizationSettin
             url: 'https://www.gitbook.com/privacy',
         },
         socialPreview: {},
+        socialAccounts: [],
     };
 
     const encoded = rison.encode_object(deepMerge(DEFAULT_CUSTOMIZATION, partial));
@@ -407,14 +439,15 @@ export async function waitForIcons(page: Page) {
                 return true;
             }
 
-            // url("https://ka-p.fontawesome.com/releases/v6.6.0/svgs/light/moon.svg?v=2&token=a463935e93")
-            const maskImage = window.getComputedStyle(icon).getPropertyValue('mask-image');
-            const urlMatch = maskImage.match(/url\("([^"]+)"\)/);
-            const url = urlMatch?.[1];
+            const maskImage = icon.querySelector('[data-testid="mask-image"]');
+            if (!maskImage) {
+                throw new Error('No mask-image element');
+            }
 
+            const url = maskImage.getAttribute('href');
             // If URL is invalid we throw an error.
             if (!url) {
-                throw new Error('No mask-image');
+                throw new Error('No mask-image url');
             }
 
             // If the URL is already queued for loading, we return the state.
@@ -444,7 +477,8 @@ export async function waitForIcons(page: Page) {
  */
 async function waitForTOCScrolling(page: Page) {
     const viewport = await page.viewportSize();
-    if (viewport && viewport.width >= 1024) {
+    if (viewport && viewport.width >= 1024 && !page.url().includes('~gitbook/embed/demo')) {
+        // The embed demo is an iframe, which means the viewport is only a fraction of the main document. So there is no open TOC to scroll to.
         const toc = page.getByTestId('table-of-contents');
         await expect(toc).toBeVisible();
         await page.evaluate(() => {

packages/gitbook/next.config.mjs

@@ -4,6 +4,7 @@
  * @type {import('next').NextConfig}
  */
 const nextConfig = {
+    deploymentId: process.env.GITHUB_SHA || Date.now().toString(), // Needed because we use a custom deployment method i.e. https://vercel.com/docs/skew-protection#custom-deployment-id
     experimental: {
         // This is needed to throw "forbidden" when the api token expired during revalidation
         authInterrupts: true,
@@ -25,6 +26,7 @@ const nextConfig = {
         // GitBook envs
         GITBOOK_API_URL: process.env.GITBOOK_API_URL,
         GITBOOK_APP_URL: process.env.GITBOOK_APP_URL,
+        GITBOOK_OAUTH_SERVER_URL: process.env.GITBOOK_OAUTH_SERVER_URL,
         GITBOOK_INTEGRATIONS_HOST: process.env.GITBOOK_INTEGRATIONS_HOST,
         GITBOOK_IMAGE_RESIZE_URL: process.env.GITBOOK_IMAGE_RESIZE_URL,
         GITBOOK_ICONS_URL: process.env.GITBOOK_ICONS_URL,

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

@@ -7,8 +7,6 @@ import type {
 } from '@opennextjs/aws/types/overrides.js';
 import { getCloudflareContext } from '@opennextjs/cloudflare';
 
-import { withRegionalCache } from '@opennextjs/cloudflare/overrides/incremental-cache/regional-cache';
-
 import type { DurableObjectNamespace, Rpc } from '@cloudflare/workers-types';
 
 export const BINDING_NAME = 'NEXT_INC_CACHE_R2_BUCKET';
@@ -23,7 +21,7 @@ export type KeyOptions = {
  * 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';
 
     async get<CacheType extends CacheEntryType = 'cache'>(
@@ -137,12 +135,3 @@ class GitbookIncrementalCache implements 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/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/openNext/tagCache/middleware.ts

@@ -6,12 +6,13 @@ import { softTagFilter } from '@opennextjs/cloudflare/overrides/tag-cache/tag-ca
 const originalTagCache = doShardedTagCache({
     baseShardSize: 12,
     regionalCache: true,
-    regionalCacheTtlSec: 60 * 5 /* 5 minutes */,
+    // We can set a long TTL for the regional cache, as we invalidate it on update
+    regionalCacheTtlSec: 24 * 60 * 60, // 1 day
     // Because we invalidate the Cache API on update, we can safely set this to true
     regionalCacheDangerouslyPersistMissingTags: true,
     shardReplication: {
         numberOfSoftReplicas: 2,
-        numberOfHardReplicas: 1,
+        numberOfHardReplicas: 2,
         regionalReplication: {
             defaultRegion: 'enam',
         },

packages/gitbook/package.json

@@ -1,22 +1,26 @@
 {
     "name": "gitbook",
-    "version": "0.19.0",
+    "version": "0.22.1",
     "private": true,
     "dependencies": {
+        "@cloudflare/workers-types": "^4.20251011.0",
         "@gitbook/api": "catalog:",
-        "@gitbook/expr": "workspace:*",
         "@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:*",
-        "@modelcontextprotocol/sdk": "^1.17.5",
-        "@opennextjs/cloudflare": "^1.8.3",
+        "@mermaid-js/mermaid-zenuml": "^0.2.2",
+        "@modelcontextprotocol/sdk": "1.17.5",
+        "@opennextjs/aws": "^3.8.5",
+        "@opennextjs/cloudflare": "^1.14.4",
         "@radix-ui/react-checkbox": "^1.0.4",
         "@radix-ui/react-dropdown-menu": "^2.1.12",
         "@radix-ui/react-hover-card": "^1.1.15",
@@ -25,32 +29,30 @@
         "@radix-ui/react-tooltip": "^1.1.8",
         "@sindresorhus/fnv1a": "^3.1.0",
         "@tailwindcss/container-queries": "^0.1.1",
-        "@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",
         "mdast-util-to-markdown": "^2.1.2",
         "memoizee": "^0.4.17",
+        "mermaid": "^11.12.3",
         "micromark-extension-frontmatter": "^2.0.0",
         "micromark-extension-gfm": "^3.0.0",
-        "motion": "^12.23.12",
-        "next": "15.4.0",
+        "motion": "^12.23.24",
+        "negotiator": "^1.0.0",
+        "next": "15.4.11",
         "next-themes": "^0.4.6",
         "nuqs": "^2.2.3",
         "object-hash": "^3.0.0",
@@ -58,6 +60,8 @@
         "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",
@@ -66,21 +70,22 @@
         "remark-rehype": "^11.1.1",
         "rison": "^0.1.1",
         "server-only": "^0.0.1",
-        "shiki": "^3.2.0",
+        "shiki": "^3.21.0",
         "tailwind-merge": "^2.2.0",
         "tailwind-shades": "^1.1.2",
         "unified": "^11.0.5",
         "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",
         "zod": "^3",
         "zustand": "^5.0.3"
     },
     "devDependencies": {
-        "@argos-ci/playwright": "^5.0.9",
-        "@playwright/test": "^1.54.2",
+        "@argos-ci/playwright": "^6.4.2",
+        "@playwright/test": "^1.58.2",
+        "@scalar/api-client-react": "catalog:",
         "@tailwindcss/postcss": "^4.1.11",
         "@types/js-cookie": "^3.0.6",
         "@types/jsontoxml": "^1.0.5",
@@ -89,9 +94,11 @@
         "@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",
+        "@types/negotiator": "^0.6.4",
+        "bun-types": "catalog:",
         "deepmerge": "^4.3.1",
         "env-cmd": "^10.1.0",
         "jsonwebtoken": "^9.0.2",
@@ -99,8 +106,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": "^50.15.1",
+        "wrangler": "^4.43.0",
+        "rss-parser": "^3.13.0"
     },
     "scripts": {
         "generate": "./scripts/generate.sh",
@@ -113,7 +122,7 @@
         "dev:cloudflare": "wrangler dev --port 8771 --env preview",
         "dev:cf:middleware": "wrangler dev --port 8771 --inspector-port 9230 --env dev --config ./openNext/customWorkers/middlewareWrangler.jsonc",
         "dev:cf:server": "wrangler dev --port 8772 --env dev --config ./openNext/customWorkers/defaultWrangler.jsonc",
-        "e2e": "playwright test e2e/internal.spec.ts e2e/pdf.spec.ts --project=chromium",
+        "e2e": "playwright test e2e/internal.spec.ts e2e/cookie-banner.spec.ts e2e/pdf.spec.ts --project=chromium",
         "e2e-customers": "playwright test e2e/customers.spec.ts --project=chromium",
         "unit": "bun test {src,packages} --preload ./tests/preload-bun.ts",
         "e2e-browserless": "bun test ./tests/",
@@ -121,5 +130,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)/[pagePath]/page.tsx

@@ -16,7 +16,7 @@ export default async function Page(props: PageProps) {
     const { context } = await getDynamicSiteContext(params);
     const pathname = getPagePathFromParams(params);
 
-    return <SitePage context={context} pageParams={{ pathname }} />;
+    return <SitePage context={context} pageParams={{ pathname }} staticRoute={false} />;
 }
 
 export async function generateViewport(props: PageProps): Promise<Viewport> {

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

@@ -22,7 +22,12 @@ export default async function SiteDynamicLayout({
     const withTracking = shouldTrackEvents(await headers());
 
     return (
-        <CustomizationRootLayout forcedTheme={forcedTheme} context={context}>
+        <CustomizationRootLayout
+            htmlClassName="sheet-open:gutter-stable"
+            bodyClassName="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,28 @@
 import type { RouteLayoutParams } from '@/app/utils';
 import { EmbeddableAssistantPage } from '@/components/Embeddable';
 import { getEmbeddableDynamicContext } from '@/lib/embeddable';
-
-export const dynamic = 'force-static';
+import { CustomizationAIMode } from '@gitbook/api';
+import { redirect } from 'next/navigation';
 
 type PageProps = {
     params: Promise<RouteLayoutParams>;
 };
 
+export const dynamic = 'force-static';
+
 export default async function Page(props: PageProps) {
     const params = await props.params;
     const { context } = await getEmbeddableDynamicContext(params);
 
-    return <EmbeddableAssistantPage context={context} />;
+    // If the assistant is not enabled, redirect to the docs
+    if (context.customization.ai.mode !== CustomizationAIMode.Assistant) {
+        redirect(`${context.linker.toPathInSite('~gitbook/embed/page/')}`);
+    }
+
+    return (
+        <EmbeddableAssistantPage
+            baseURL={context.linker.toPathInSite('~gitbook/embed/')}
+            siteTitle={context.site.title}
+        />
+    );
 }

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

@@ -0,0 +1,21 @@
+import type { RouteLayoutParams } from '@/app/utils';
+import { getEmbeddableDynamicContext } from '@/lib/embeddable';
+import { CustomizationAIMode } from '@gitbook/api';
+import { redirect } from 'next/navigation';
+
+type PageProps = {
+    params: Promise<RouteLayoutParams>;
+};
+
+export default async function Page(props: PageProps) {
+    const params = await props.params;
+    const { context } = await getEmbeddableDynamicContext(params);
+    const baseURL = context.linker.toPathInSite('~gitbook/embed/');
+
+    // If assistant is enabled, redirect to assistant, otherwise to docs
+    if (context.customization.ai.mode === CustomizationAIMode.Assistant) {
+        redirect(`${baseURL}/assistant`);
+    } else {
+        redirect(`${baseURL}/page/`);
+    }
+}

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

@@ -12,7 +12,7 @@ export default async function Page(props: PageProps) {
     const { context } = await getEmbeddableDynamicContext(params);
     const pathname = getPagePathFromParams(params);
 
-    return <EmbeddableDocsPage context={context} pageParams={{ pathname }} />;
+    return <EmbeddableDocsPage context={context} pageParams={{ pathname }} staticRoute={false} />;
 }
 
 export async function generateMetadata(props: PageProps): Promise<Metadata> {

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

@@ -18,7 +18,7 @@ export default async function Page(props: PageProps) {
     const { context } = await getStaticSiteContext(params);
     const pathname = getPagePathFromParams(params);
 
-    return <SitePage context={context} pageParams={{ pathname }} />;
+    return <SitePage context={context} pageParams={{ pathname }} staticRoute />;
 }
 
 export async function generateViewport(props: PageProps): Promise<Viewport> {

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

@@ -19,7 +19,11 @@ export default async function SiteStaticLayout({
     const withTracking = shouldTrackEvents();
 
     return (
-        <CustomizationRootLayout context={context}>
+        <CustomizationRootLayout
+            htmlClassName="sheet-open:gutter-stable"
+            bodyClassName="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,28 @@
-import type { RouteLayoutParams } from '@/app/utils';
+import type { RouteParams } from '@/app/utils';
 import { EmbeddableAssistantPage } from '@/components/Embeddable';
 import { getEmbeddableStaticContext } from '@/lib/embeddable';
+import { CustomizationAIMode } from '@gitbook/api';
+import { redirect } from 'next/navigation';
 
 export const dynamic = 'force-static';
 
 type PageProps = {
-    params: Promise<RouteLayoutParams>;
+    params: Promise<RouteParams>;
 };
 
 export default async function Page(props: PageProps) {
     const params = await props.params;
     const { context } = await getEmbeddableStaticContext(params);
 
-    return <EmbeddableAssistantPage context={context} />;
+    // If the assistant is not enabled, redirect to the docs
+    if (context.customization.ai.mode !== CustomizationAIMode.Assistant) {
+        redirect(`${context.linker.toPathInSite('~gitbook/embed/page/')}`);
+    }
+
+    return (
+        <EmbeddableAssistantPage
+            baseURL={context.linker.toPathInSite('~gitbook/embed/')}
+            siteTitle={context.site.title}
+        />
+    );
 }

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

@@ -18,6 +18,14 @@ export async function GET(
 <html>
     <head>
         <meta name="color-scheme" content="light dark">
+        <style type="text/css">
+          .control {
+            display: none;
+          }
+          .custom-trigger .control {
+            display: inline-flex;
+          }
+        </style>
     </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">
@@ -105,17 +113,29 @@ export async function GET(
                 <line x1="658.186" y1="444" x2="635.471" y2="444" stroke="#A4A7B0" stroke-width="8" stroke-linecap="round"/>
             </g>
         </svg>
+        <button type="button" class="control" onclick="window.GitBook('open')">Open</button>
+        <button type="button" class="control" onclick="window.GitBook('close')">Close</button>
     </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');
+        const useCustomTrigger = new URLSearchParams(window.location.search).get('trigger') === 'custom';
+        window.GitBook('configure', {
+            suggestions: [
+                'Help me get started',
+                'What can I ask you?',
+                'Show me tips and tricks',
+            ],
+            tabs: ['assistant', 'docs'],
+            closeButton: useCustomTrigger
+        });
+
+        if (useCustomTrigger) {
+          document.body.classList.add('custom-trigger');
+          window.GitBook('hide');
+        } else {
+            window.GitBook('open');
+        }
+
     </script>
 </html>
 `,

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

@@ -0,0 +1,23 @@
+import type { RouteLayoutParams } from '@/app/utils';
+import { getEmbeddableStaticContext } from '@/lib/embeddable';
+import { CustomizationAIMode } from '@gitbook/api';
+import { redirect } from 'next/navigation';
+
+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);
+    const baseURL = context.linker.toPathInSite('~gitbook/embed/');
+
+    // If assistant is enabled, redirect to assistant, otherwise to docs
+    if (context.customization.ai.mode === CustomizationAIMode.Assistant) {
+        redirect(`${baseURL}/assistant`);
+    } else {
+        redirect(`${baseURL}/page/`);
+    }
+}

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

@@ -14,7 +14,7 @@ export default async function Page(props: PageProps) {
     const { context } = await getEmbeddableStaticContext(params);
     const pathname = getPagePathFromParams(params);
 
-    return <EmbeddableDocsPage context={context} pageParams={{ pathname }} />;
+    return <EmbeddableDocsPage context={context} pageParams={{ pathname }} staticRoute />;
 }
 
 export async function generateMetadata(props: PageProps): Promise<Metadata> {

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

@@ -24,10 +24,22 @@ export async function GET(
 (function () {
   const w = window;
   const gb = w.GitBook;
+
+  function getScriptSearchParams() {
+    const script = document.currentScript;
+    if (!script) return new URLSearchParams();
+
+    const url = new URL(script.src);
+    return url.searchParams;
+  }
+
+  const searchParams = getScriptSearchParams()
+  const token = searchParams.get('jwt_token');
   const initOptions = window.gitbookSettings || ${JSON.stringify(initOptions)};
+  const initFrameOptions = token ? { visitor: { token } } : undefined;
 
   if (typeof gb === "function") {
-    gb('init', initOptions);
+    gb('init', initOptions, initFrameOptions);
   } else {
     var d = document;
 
@@ -40,7 +52,7 @@ export async function GET(
     };
     w.GitBook = g;
 
-    g('init', initOptions);
+    g('init', initOptions, initFrameOptions);
 
     const load = function () {
       const style = document.createElement('link');

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

@@ -32,17 +32,30 @@ async function handler(
                     );
 
                     return {
-                        content: results.flatMap((spaceResult) => {
+                        content: results.flatMap((result) => {
+                            if (result.type === 'record') {
+                                return {
+                                    type: 'text',
+                                    text: [
+                                        `Title: ${result.title}`,
+                                        `Link: ${result.url}`,
+                                        result.description ? `Content: ${result.description}` : '',
+                                    ]
+                                        .filter(Boolean)
+                                        .join('\n'),
+                                };
+                            }
+
                             const found = findSiteSpaceBy(
                                 context.structure,
-                                (siteSpace) => siteSpace.space.id === spaceResult.id
+                                (siteSpace) => siteSpace.space.id === result.id
                             );
                             const spaceURL = found?.siteSpace.urls.published;
                             if (!spaceURL) {
                                 return [];
                             }
 
-                            return spaceResult.pages.map((pageResult) => {
+                            return result.pages.map((pageResult) => {
                                 const pageURL = linker.toAbsoluteURL(
                                     linker.toLinkForContent(
                                         joinPathWithBaseURL(spaceURL, pageResult.path)

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

@@ -3,7 +3,7 @@ import { type SiteURLData, fetchSiteContextByURLLookup, getBaseContext } from '@
 import { getDynamicCustomizationSettings } from '@/lib/customization';
 import type { SiteAPIToken } from '@gitbook/api';
 import { jwtDecode } from 'jwt-decode';
-import { forbidden } from 'next/navigation';
+import { forbidden, notFound } from 'next/navigation';
 import rison from 'rison';
 
 export type RouteParamMode = 'url-host' | 'url';
@@ -80,14 +80,32 @@ export async function getDynamicSiteContext(params: RouteLayoutParams) {
  * Get the decoded page path from the params.
  */
 export function getPagePathFromParams(params: RouteParams) {
-    const decoded = decodeURIComponent(params.pagePath);
-    return decoded;
+    // If decoding the param fails, return a 404 instead of crashing
+    try {
+        const decoded = decodeURIComponent(params.pagePath);
+
+        // For the root page, we encode '/' to avoid an empty param being passed.
+        if (decoded === '/') {
+            return '';
+        }
+        return decoded;
+    } catch (error) {
+        console.error(
+            `Returning 404 after failing to decode page path ${params.pagePath}: ${error}`
+        );
+        notFound();
+    }
 }
 
 function getSiteURLFromParams(params: RouteLayoutParams) {
-    const decoded = decodeURIComponent(params.siteURL);
-    const url = new URL(`https://${decoded}`);
-    return url;
+    try {
+        const decoded = decodeURIComponent(params.siteURL);
+        const url = new URL(`https://${decoded}`);
+        return url;
+    } catch (error) {
+        console.error(`Returning 404 after failing to decode site URL ${params.siteURL}: ${error}`);
+        notFound();
+    }
 }
 
 function getModeFromParams(mode: string): RouteParamMode {
@@ -102,6 +120,13 @@ function getModeFromParams(mode: string): RouteParamMode {
  * Get the decoded site data from the params.
  */
 function getSiteURLDataFromParams(params: RouteLayoutParams): SiteURLData {
-    const decoded = decodeURIComponent(params.siteData);
-    return rison.decode(decoded);
+    try {
+        const decoded = decodeURIComponent(params.siteData);
+        return rison.decode(decoded);
+    } catch (error) {
+        console.error(
+            `Returning 404 after failing to decode site data ${params.siteData}: ${error}`
+        );
+        notFound();
+    }
 }

packages/gitbook/src/app/~gitbook/env/route.ts

@@ -11,6 +11,7 @@ import {
     GITBOOK_ICONS_URL,
     GITBOOK_IMAGE_RESIZE_SIGNING_KEY,
     GITBOOK_INTEGRATIONS_HOST,
+    GITBOOK_OAUTH_SERVER_URL,
     GITBOOK_SECRET,
     GITBOOK_URL,
     GITBOOK_USER_AGENT,
@@ -25,6 +26,7 @@ export async function GET(_req: NextRequest) {
         GITBOOK_APP_URL,
         GITBOOK_API_URL,
         GITBOOK_API_PUBLIC_URL,
+        GITBOOK_OAUTH_SERVER_URL,
         GITBOOK_ASSETS_URL,
         GITBOOK_FONTS_URL,
         GITBOOK_ICONS_URL,

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

@@ -1,5 +1,6 @@
 import { HighlightQuery } from '@/components/Search/HighlightQuery';
 import { Link, StyledLink } from '@/components/primitives';
+import { Favicon } from '@/components/utils';
 import { getSpaceLanguage } from '@/intl/server';
 import { t } from '@/intl/translate';
 import type { GitBookSiteContext } from '@/lib/context';
@@ -15,6 +16,7 @@ import type {
     ContentRef,
 } from '@gitbook/api';
 import { Icon, type IconName } from '@gitbook/icons';
+import assertNever from 'assert-never';
 import type * as React from 'react';
 
 /**
@@ -39,7 +41,10 @@ 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
+            data-testid="ai-chat-tool-summary"
+            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"
@@ -135,32 +140,44 @@ async function DescriptionForSearchToolCall(props: {
     // Resolve all hrefs for search results in parallel
     const searchResultsWithHrefs = await Promise.all(
         toolCall.results.map(async (result) => {
-            const resolved = await resolveContentRef(
-                result.anchor
-                    ? {
-                          kind: 'anchor',
-                          page: result.pageId,
-                          space: result.spaceId,
-                          anchor: result.anchor,
-                      }
-                    : {
-                          kind: 'page',
-                          page: result.pageId,
-                          space: result.spaceId,
-                      },
-                context
-            );
-            return {
-                ...result,
-                href: resolved?.href || '#',
-            };
+            switch (result.type) {
+                case 'page': {
+                    const resolved = await resolveContentRef(
+                        result.anchor
+                            ? {
+                                  kind: 'anchor',
+                                  page: result.pageId,
+                                  space: result.spaceId,
+                                  anchor: result.anchor,
+                              }
+                            : {
+                                  kind: 'page',
+                                  page: result.pageId,
+                                  space: result.spaceId,
+                              },
+                        context
+                    );
+
+                    return {
+                        ...result,
+                        href: resolved?.href || '#',
+                    };
+                }
+                case 'record':
+                    return {
+                        ...result,
+                        href: result.url ?? '#',
+                    };
+                default:
+                    assertNever(result);
+            }
         })
     );
 
     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,47 +204,82 @@ 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
-                                key={`${result.pageId}-${index}`}
-                                className="animate-fade-in-slow"
-                                style={{
-                                    animationDelay: `${index * 25}ms`,
-                                }}
-                            >
-                                <Link
-                                    href={result.href}
-                                    className="flex items-start gap-2 circular-corners:rounded-2xl rounded-corners:rounded-md px-3 py-2 transition-colors hover:bg-primary-hover"
+                        {searchResultsWithHrefs.map((result, index) => {
+                            const resultKey = (() => {
+                                switch (result.type) {
+                                    case 'page':
+                                        return `${result.spaceId}/${result.pageId}`;
+                                    case 'record':
+                                        return result.recordId;
+                                    default:
+                                        assertNever(result);
+                                }
+                            })();
+
+                            const iconClassName = 'mt-1 size-3 shrink-0 text-tint-subtle';
+                            const icon = <Icon icon="memo" className={iconClassName} />;
+
+                            return (
+                                <li
+                                    key={`${resultKey}-${index}`}
+                                    className="animate-fade-in-slow"
+                                    style={{
+                                        animationDelay: `${index * 25}ms`,
+                                    }}
                                 >
-                                    <Icon
-                                        icon="memo"
-                                        className="mt-1 size-3 shrink-0 text-tint-subtle"
-                                    />
-                                    <div className="flex flex-col gap-1 text-tint">
-                                        <h3 className="line-clamp-2 font-medium text-sm text-tint">
-                                            <HighlightQuery
-                                                query={toolCall.query}
-                                                text={result.title}
-                                            />
-                                        </h3>
-                                        {result.description && (
-                                            <p className="line-clamp-2 text-tint-subtle text-xs">
+                                    <Link
+                                        href={result.href}
+                                        className="flex items-start gap-2 circular-corners:rounded-2xl rounded-corners:rounded-md px-3 py-2 transition-colors hover:bg-primary-hover"
+                                        insights={
+                                            result.type === 'record'
+                                                ? {
+                                                      type: 'search_open_result',
+                                                      query: toolCall.query,
+                                                      result: {
+                                                          recordId: result.recordId,
+                                                      },
+                                                  }
+                                                : {
+                                                      type: 'search_open_result',
+                                                      query: toolCall.query,
+                                                      result: {
+                                                          spaceId: result.spaceId,
+                                                          pageId: result.pageId,
+                                                      },
+                                                  }
+                                        }
+                                    >
+                                        {result.type === 'record' ? (
+                                            <Favicon url={result.href} className={iconClassName} />
+                                        ) : (
+                                            icon
+                                        )}
+                                        <div className="flex flex-col gap-1 text-tint">
+                                            <h3 className="line-clamp-2 font-medium text-sm text-tint">
                                                 <HighlightQuery
                                                     query={toolCall.query}
-                                                    text={result.description}
+                                                    text={result.title}
                                                 />
-                                            </p>
-                                        )}
-                                    </div>
-                                    <Icon
-                                        icon="chevron-right"
-                                        className="ml-auto size-3 shrink-0 self-center"
-                                    />
-                                </Link>
-                            </li>
-                        ))}
+                                            </h3>
+                                            {result.description && (
+                                                <p className="line-clamp-2 text-tint-subtle text-xs">
+                                                    <HighlightQuery
+                                                        query={toolCall.query}
+                                                        text={result.description}
+                                                    />
+                                                </p>
+                                            )}
+                                        </div>
+                                        <Icon
+                                            icon="chevron-right"
+                                            className="ml-auto size-3 shrink-0 self-center"
+                                        />
+                                    </Link>
+                                </li>
+                            );
+                        })}
                     </ol>
                 </div>
             ) : null}

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

@@ -128,10 +128,10 @@ function parseResponse<T>(
     parse: (response: AIStreamResponse) => T | undefined | Promise<T | undefined>
 ): {
     stream: EventIterator<T>;
-    response: Promise<{ responseId: string }>;
+    response: Promise<{ responseId: string | null }>;
 } {
-    let resolveResponse: (value: { responseId: string }) => void;
-    const response = new Promise<{ responseId: string }>((resolve) => {
+    let resolveResponse: (value: { responseId: string | null }) => void;
+    const response = new Promise<{ responseId: string | null }>((resolve) => {
         resolveResponse = resolve;
     });
 
@@ -147,7 +147,7 @@ function parseResponse<T>(
 
                 if (event.type === 'response_finish') {
                     foundResponse = true;
-                    resolveResponse({ responseId: event.responseId });
+                    resolveResponse({ responseId: event.response.id ?? null });
                 }
             }
 

packages/gitbook/src/components/AI/server-actions/chat.ts

@@ -9,6 +9,7 @@ import {
     AIModel,
     type AIToolCallResult,
     type AIToolDefinition,
+    type SiteInsightsSession,
 } from '@gitbook/api';
 import { streamRenderAIMessage } from './api';
 import type { RenderAIMessageOptions } from './types';
@@ -22,6 +23,7 @@ export async function* streamAIChatResponse({
     previousResponseId,
     toolCall,
     tools,
+    session,
     options,
 }: {
     message?: string;
@@ -29,6 +31,7 @@ export async function* streamAIChatResponse({
     previousResponseId?: string;
     toolCall?: AIToolCallResult;
     tools?: AIToolDefinition[];
+    session: SiteInsightsSession;
     options?: RenderAIMessageOptions;
 }) {
     const { stream } = await traceErrorOnly('AI.streamAIChatResponse', async () => {
@@ -57,6 +60,7 @@ export async function* streamAIChatResponse({
                 previousResponseId,
                 toolCall,
                 tools,
+                session,
             }
         );
 

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

@@ -1,21 +1,26 @@
 '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';
+import { useSetSearchState } from '../Search/useSearch';
 
 // Unify assistants configuration context with the assistants hook in one place
 export type AIConfig = {
     aiMode: CustomizationAIMode;
+    suggestions?: string[];
     trademark: boolean;
+    greeting?: {
+        title: string;
+        subtitle: string;
+    };
 };
 
 export type Assistant = Omit<GitBookAssistant, 'icon'> & {
@@ -49,8 +54,11 @@ export type Assistant = Omit<GitBookAssistant, 'icon'> & {
 const AIContext = React.createContext<AIConfig | null>(null);
 
 export function AIContextProvider(props: React.PropsWithChildren<AIConfig>): React.ReactElement {
-    const { aiMode, trademark, children } = props;
-    const value = React.useMemo(() => ({ aiMode, trademark }), [aiMode, trademark]);
+    const { aiMode, trademark, suggestions, greeting, children } = props;
+    const value = React.useMemo(
+        () => ({ aiMode, trademark, suggestions, greeting }),
+        [aiMode, trademark, suggestions, greeting]
+    );
     return <AIContext.Provider value={value}>{children}</AIContext.Provider>;
 }
 
@@ -76,7 +84,7 @@ export function useAI(): AIContext {
     const chat = useAIChatState();
     const chatController = useAIChatController();
     const language = useLanguage();
-    const [, setSearchState] = useSearch();
+    const setSearchState = useSetSearchState();
 
     const assistants: Assistant[] = [];
 
@@ -88,6 +96,7 @@ export function useAI(): AIContext {
                 <AIChatIcon
                     state={chat.loading ? 'thinking' : 'default'}
                     trademark={config.trademark}
+                    className="size-text-lg"
                 />
             ),
             open: (query?: string) => {
@@ -104,16 +113,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

@@ -11,9 +11,10 @@ import {
 } from '@gitbook/api';
 import type { IconName } from '@gitbook/icons';
 import * as React from 'react';
-import { useTrackEvent } from '../Insights';
+import { getVisitor, useTrackEvent } from '../Insights';
+import { getSession } from '../Insights/sessions';
 import { integrationsAssistantTools } from '../Integrations';
-import { useSearch } from '../Search';
+import { useSetSearchState } from '../Search';
 import { type RenderAIMessageOptions, streamAIChatResponse } from './server-actions';
 import { useAIMessageContextRef } from './useAIMessageContext';
 
@@ -87,6 +88,19 @@ export type AIChatState = {
     error: boolean;
 };
 
+export type AIChatEvent =
+    | { type: 'open' }
+    | { type: 'postMessage'; message: string }
+    | { type: 'clear' }
+    | { type: 'close' };
+
+type AIChatEventData<T extends AIChatEvent['type']> = Omit<
+    Extract<AIChatEvent, { type: T }>,
+    'type'
+>;
+
+type AIChatEventListener = (input?: Omit<AIChatEvent, 'type'>) => void;
+
 export type AIChatController = {
     /** Open the dialog */
     open: () => void;
@@ -96,6 +110,11 @@ export type AIChatController = {
     postMessage: (input: { message: string }) => void;
     /** Clear the conversation */
     clear: () => void;
+    /** Register an event listener */
+    on: <T extends AIChatEvent['type']>(
+        event: T,
+        listener: (input?: AIChatEventData<T>) => void
+    ) => () => void;
 };
 
 const AIChatControllerContext = React.createContext<AIChatController | null>(null);
@@ -123,6 +142,17 @@ export function useAIChatState(): AIChatState {
     return state;
 }
 
+function notify(
+    listeners: AIChatEventListener[] | undefined,
+    input: Omit<AIChatEvent, 'type'>
+): void {
+    if (!listeners) return;
+    // Defer event listeners to next tick so React can process state updates first
+    setTimeout(() => {
+        listeners.forEach((listener) => listener(input));
+    }, 0);
+}
+
 /**
  * Provide the controller to interact with the AI chat.
  */
@@ -134,9 +164,12 @@ export function AIChatProvider(props: {
 
     const messageContextRef = useAIMessageContextRef();
     const trackEvent = useTrackEvent();
-    const [, setSearchState] = useSearch();
+    const setSearchState = useSetSearchState();
     const language = useLanguage();
 
+    // Event listeners storage
+    const eventsRef = React.useRef<Map<AIChatEvent['type'], AIChatEventListener[]>>(new Map());
+
     // Open AI chat and sync with search state
     const onOpen = React.useCallback(() => {
         const { initialQuery } = globalState.getState();
@@ -149,6 +182,8 @@ export function AIChatProvider(props: {
             scope: prev?.scope ?? 'default',
             open: false, // Close search popover when opening chat
         }));
+
+        notify(eventsRef.current.get('open'), {});
     }, [setSearchState]);
 
     // Close AI chat and clear ask parameter
@@ -162,6 +197,8 @@ export function AIChatProvider(props: {
             scope: prev?.scope ?? 'default',
             open: false,
         }));
+
+        notify(eventsRef.current.get('close'), {});
     }, [setSearchState]);
 
     // Stream a message with the AI backend
@@ -233,6 +270,10 @@ export function AIChatProvider(props: {
                     toolCall: input.toolCall,
                     messageContext: messageContextRef.current,
                     previousResponseId: globalState.getState().responseId ?? undefined,
+                    session: {
+                        sessionId: getSession().id,
+                        visitorId: (await getVisitor()).deviceId,
+                    },
                     tools: integrationTools.map((tool) => ({
                         name: tool.name,
                         description: tool.description,
@@ -260,7 +301,7 @@ export function AIChatProvider(props: {
                         case 'response_finish': {
                             globalState.setState((state) => ({
                                 ...state,
-                                responseId: event.responseId,
+                                responseId: event.response.id ?? null,
                                 // Mark as not loading when the response is finished
                                 // Even if the stream might continue as we receive 'response_followup_suggestion'
                                 loading: false,
@@ -379,8 +420,14 @@ export function AIChatProvider(props: {
                 }));
             }
 
+            notify(eventsRef.current.get('postMessage'), { message: input.message });
+
             if (query === input.message) {
                 // Return early if the message is the same as the previous message
+                globalState.setState((state) => ({
+                    ...state,
+                    opened: true,
+                }));
                 return;
             }
 
@@ -440,14 +487,34 @@ export function AIChatProvider(props: {
         }));
     }, [setSearchState]);
 
+    const onEvent = React.useCallback(
+        <T extends AIChatEvent['type']>(
+            event: T,
+            listener: (input?: AIChatEventData<T>) => void
+        ) => {
+            const listeners = eventsRef.current.get(event) || [];
+            listeners.push(listener as AIChatEventListener);
+            eventsRef.current.set(event, listeners);
+            return () => {
+                const currentListeners = eventsRef.current.get(event) || [];
+                eventsRef.current.set(
+                    event,
+                    currentListeners.filter((l) => l !== listener)
+                );
+            };
+        },
+        []
+    );
+
     const controller = React.useMemo(() => {
         return {
             open: onOpen,
             close: onClose,
             clear: onClear,
             postMessage: onPostMessage,
+            on: onEvent,
         };
-    }, [onOpen, onClose, onClear, onPostMessage]);
+    }, [onOpen, onClose, onClear, onPostMessage, onEvent]);
 
     return (
         <AIChatControllerContext.Provider value={controller}>

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';
@@ -17,21 +19,23 @@ import {
     EmbeddableFrameButtons,
     EmbeddableFrameHeader,
     EmbeddableFrameHeaderMain,
+    EmbeddableFrameMain,
     EmbeddableFrameSubtitle,
     EmbeddableFrameTitle,
 } from '../Embeddable/EmbeddableFrame';
 import { useTrackEvent } from '../Insights';
 import { useNow } from '../hooks';
 import { Button } from '../primitives';
+import { ScrollContainer } from '../primitives/ScrollContainer';
+import { SideSheet } from '../primitives/SideSheet';
 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,41 +69,53 @@ 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"
+        <SideSheet
+            side="right"
+            open={chat.opened}
+            onOpenChange={(open) => {
+                if (open) {
+                    chatController.open();
+                } else {
+                    chatController.close();
+                }
+            }}
+            withOverlay={true}
+            className={tcls(
+                'ai-chat mx-auto ml-8 not-hydrated:hidden w-96 transition-[width] duration-300 ease-quint lg:max-xl:w-80'
+            )}
         >
-            <EmbeddableFrame className="relative circular-corners:rounded-3xl rounded-corners:rounded-md depth-subtle:shadow-lg shadow-tint ring-1 ring-tint-subtle">
-                <EmbeddableFrameHeader>
-                    <AIChatDynamicIcon trademark={trademark} />
-                    <EmbeddableFrameHeaderMain>
-                        <EmbeddableFrameTitle>
-                            {getAIChatName(language, trademark)}
-                        </EmbeddableFrameTitle>
-                        <AIChatSubtitle chat={chat} />
-                    </EmbeddableFrameHeaderMain>
-                    <EmbeddableFrameButtons>
-                        <AIChatControlButton />
-                        <Button
-                            onClick={() => chatController.close()}
-                            iconOnly
-                            icon="close"
-                            label={tString(language, 'close')}
-                            variant="blank"
-                            size="default"
+            <EmbeddableFrame className="relative shrink-0 border-tint-subtle border-l to-tint-base">
+                <EmbeddableFrameMain data-testid="ai-chat">
+                    <EmbeddableFrameHeader className="not-embed:px-4">
+                        <AIChatDynamicIcon trademark={config.trademark} />
+                        <EmbeddableFrameHeaderMain>
+                            <EmbeddableFrameTitle>
+                                {getAIChatName(language, config.trademark)}
+                            </EmbeddableFrameTitle>
+                            <AIChatSubtitle chat={chat} />
+                        </EmbeddableFrameHeaderMain>
+                        <EmbeddableFrameButtons>
+                            <AIChatControlButton />
+                            <Button
+                                onClick={() => chatController.close()}
+                                iconOnly
+                                icon="close"
+                                label={tString(language, 'close')}
+                                variant="blank"
+                            />
+                        </EmbeddableFrameButtons>
+                    </EmbeddableFrameHeader>
+                    <EmbeddableFrameBody className="not-embed:px-4">
+                        <AIChatBody
+                            chatController={chatController}
+                            chat={chat}
+                            suggestions={config.suggestions}
                         />
-                    </EmbeddableFrameButtons>
-                </EmbeddableFrameHeader>
-                <EmbeddableFrameBody>
-                    <AIChatBody chatController={chatController} chat={chat} trademark={trademark} />
-                </EmbeddableFrameBody>
+                    </EmbeddableFrameBody>
+                </EmbeddableFrameMain>
             </EmbeddableFrame>
-        </div>
+        </SideSheet>
     );
 }
 
@@ -108,13 +124,14 @@ export function AIChat(props: { trademark: boolean }) {
  */
 export function AIChatDynamicIcon(props: {
     trademark: boolean;
+    className?: string;
 }) {
-    const { trademark } = props;
+    const { trademark, className } = props;
     const chat = useAIChatState();
 
     return (
         <AIChatIcon
-            className="size-5 text-tint"
+            className={tcls('size-5 text-tint', className)}
             trademark={trademark}
             state={
                 chat.error
@@ -143,10 +160,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 +197,16 @@ export function AIChatSubtitle(props: {
 export function AIChatBody(props: {
     chatController: AIChatController;
     chat: AIChatState;
-    trademark: boolean;
     welcomeMessage?: string;
     suggestions?: string[];
+    greeting?: {
+        title: string;
+        subtitle: string;
+    };
 }) {
-    const { chatController, chat, trademark, suggestions } = props;
+    const { chatController, chat, suggestions, greeting } = 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 +220,45 @@ 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="py-4 gutter-stable flex flex-col gap-4"
+                orientation="vertical"
+                trailing={{ fade: false, button: true }}
+                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 gap-1 [@container(min-height:400px)]:items-center">
+                                <h5
+                                    className="animate-blur-in-slow font-bold text-lg text-tint-strong leading-tight [@container(min-height:400px)]:text-center"
+                                    style={{ animationDelay: '.5s' }}
+                                    data-testid="ai-chat-greeting-title"
+                                >
+                                    {greeting?.title || timeGreeting}
+                                </h5>
+                                <p
+                                    className="animate-blur-in-slow text-tint leading-tight [@container(min-height:400px)]:text-center"
+                                    style={{ animationDelay: '.6s' }}
+                                    data-testid="ai-chat-greeting-subtitle"
+                                >
+                                    {greeting?.subtitle ||
+                                        t(language, 'ai_chat_assistant_description')}
+                                </p>
+                            </div>
                         </div>
                         {!chat.error ? (
                             <AIChatSuggestedQuestions
@@ -254,28 +268,19 @@ 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 pb-4">
                 {/* Display an error banner when something went wrong. */}
                 {chat.error ? <AIChatError chatController={chatController} /> : null}
 
                 <AIChatInput
-                    value={input}
-                    onChange={setInput}
                     loading={chat.loading}
                     disabled={chat.loading || chat.error}
-                    onSubmit={() => {
-                        chatController.postMessage({ message: input });
-                        setInput('');
+                    onSubmit={(value) => {
+                        chatController.postMessage({ message: value });
                     }}
                 />
             </div>

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

@@ -2,9 +2,12 @@
 import { useLanguage } from '@/intl/client';
 import { t } from '@/intl/translate';
 import type { Assistant } from '../AI';
+import { useIsMobile } from '../hooks/useIsMobile';
 import { Button } from '../primitives';
 import { KeyboardShortcut } from '../primitives/KeyboardShortcut';
 
+const MOBILE_BREAKPOINT = 672; // 42rem, equal to Tailwind's @max-2xl container breakpoint
+
 /**
  * Button to open/close the AI chat.
  */
@@ -15,15 +18,15 @@ export function AIChatButton(props: {
 }) {
     const { assistant, showLabel = true, withShortcut = true } = props;
     const language = useLanguage();
+    const isMobile = useIsMobile(MOBILE_BREAKPOINT, '[data-gb-header-content]');
 
     return (
         <Button
             icon={assistant.icon}
             data-testid="ai-chat-button"
-            iconOnly={!showLabel}
+            iconOnly={!showLabel || isMobile}
             size="medium"
             variant="header"
-            className="h-9 px-2.5 max-md:[&_.button-content]:hidden"
             label={
                 <div className="flex items-center gap-2">
                     {t(language, 'ai_chat_ask', assistant.label)}

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

@@ -1,10 +1,9 @@
 'use client';
 
 import { useLanguage } from '@/intl/client';
-import { t, tString } from '@/intl/translate';
-import { Icon } from '@gitbook/icons';
+import { t } from '@/intl/translate';
 import { useAIChatController, useAIChatState } from '../AI';
-import { Button, DropdownMenu, DropdownMenuItem } from '../primitives';
+import { Button } from '../primitives';
 
 /**
  * Button to control the chat (clear, etc.)
@@ -15,26 +14,15 @@ export function AIChatControlButton() {
     const chatController = useAIChatController();
 
     return chat.messages.length > 0 ? (
-        <DropdownMenu
-            button={
-                <Button
-                    onClick={() => {}}
-                    iconOnly
-                    icon="ellipsis"
-                    label={tString(language, 'actions')}
-                    variant="blank"
-                    size="default"
-                />
-            }
-        >
-            <DropdownMenuItem
-                onClick={() => {
-                    chatController.clear();
-                }}
-            >
-                <Icon icon="broom-wide" className="size-3 shrink-0 text-tint-subtle" />
-                {t(language, 'ai_chat_clear_conversation')}
-            </DropdownMenuItem>
-        </DropdownMenu>
+        <Button
+            onClick={() => {
+                chatController.clear();
+            }}
+            iconOnly
+            icon="trash-can"
+            label={t(language, 'ai_chat_clear_conversation')}
+            variant="blank"
+            className="animate-blur-in-slow"
+        />
     ) : null;
 }

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

@@ -1,5 +1,4 @@
-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,23 +8,30 @@ 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"
-                className={tcls(
-                    className,
-                    (state === 'thinking' || state === 'working') &&
-                        'animate-[spin_2s_infinite_forwards_cubic-bezier(0.16,1,0.3,1)]',
-                    state === 'intro' && 'animate-[spin_2s_forwards_cubic-bezier(0.16,1,0.3,1)]'
-                )}
+                {...props}
+                className={className}
+                style={{
+                    animation: {
+                        intro: 'spin 2s forwards cubic-bezier(0.16,1,0.3,1)',
+                        thinking: 'spin 2s infinite forwards cubic-bezier(0.16,1,0.3,1)',
+                        working: 'spin 2s infinite forwards cubic-bezier(0.16,1,0.3,1)',
+                        done: '',
+                        confirm: '',
+                        default: '',
+                        error: '',
+                    }[state],
+                }}
             />
         );
     }
@@ -49,28 +55,36 @@ export const AIChatIcon = ({
             <path
                 d="M12.8916 1.06265C12.921 0.979101 13.0392 0.979127 13.0685 1.06267C13.239 1.5478 13.3439 1.84646 13.516 2.1032C13.6683 2.33042 13.8578 2.53033 14.0766 2.6945C14.3239 2.88 14.6165 3.00068 15.0919 3.19671C15.1761 3.23142 15.1761 3.3506 15.0919 3.38531C14.6165 3.58134 14.3239 3.70203 14.0766 3.88752C13.8578 4.05169 13.6683 4.2516 13.516 4.47882C13.3439 4.73556 13.239 5.03423 13.0685 5.51937C13.0392 5.60291 12.921 5.60292 12.8916 5.51938C12.7212 5.03423 12.6162 4.73557 12.4442 4.47882C12.2919 4.2516 12.1023 4.05169 11.8835 3.88752C11.6363 3.70202 11.3436 3.58134 10.8682 3.38531C10.7841 3.3506 10.7841 3.23141 10.8683 3.1967C11.3436 3.00067 11.6363 2.87999 11.8835 2.6945C12.1023 2.53033 12.2919 2.33042 12.4442 2.1032C12.6162 1.84646 12.7212 1.54779 12.8916 1.06265Z"
                 stroke="currentColor"
-                strokeWidth="1.2"
+                strokeWidth={state === 'intro' ? '1.2' : '1'}
                 strokeLinejoin="round"
-                className={tcls(
-                    state === 'intro' &&
-                        'animate-[fadeIn_.5s_.7s_both,spin_2s_1s_forwards_cubic-bezier(.43,1.54,.64,1)]',
-                    (state === 'working' || state === 'thinking') &&
-                        'animate-[fadeIn_.5s_.3s_both,spin_2s_1s_infinite_forwards_cubic-bezier(0.16,1,0.3,1)]',
-                    state === 'done' && 'animate-[fadeOut_.5s_both]',
-                    state === 'confirm' && 'animate-[fadeOut_.5s_both]',
-                    state === 'default' && 'animate-[fadeIn_0s_both]',
-                    state === 'error' && 'hidden'
-                )}
-                style={{ transformOrigin: '13px 3.5px' }}
+                shapeRendering="crispEdges"
+                className="transition-opacity duration-300"
+                style={{
+                    animation: {
+                        intro: 'fadeIn .5s .5s backwards, spin 2s .5s forwards cubic-bezier(0.43,1.54,0.64,1)',
+                        thinking: 'spin 2s 1s infinite forwards cubic-bezier(0.16,1,0.3,1)',
+                        working: 'spin 2s 1s infinite forwards cubic-bezier(0.16,1,0.3,1)',
+                        done: '',
+                        confirm: '',
+                        default: '',
+                        error: '',
+                    }[state],
+                    transitionDelay:
+                        state === 'default' || state === 'thinking' ? '.3s' : undefined,
+                    opacity: ['done', 'confirm', 'error'].includes(state) ? 0 : 1,
+                    transformOrigin: '13px 3.5px',
+                }}
             />
 
             {/* Error */}
             <g
                 clipPath="url(#clip0_153_2034)"
-                className={tcls(
-                    'text-danger-subtle',
-                    state === 'error' ? 'animate-[fadeIn_.5s_.3s_both]' : 'hidden'
-                )}
+                className="transition-opacity duration-300"
+                style={{
+                    color: 'rgb(var(--danger-9))',
+                    opacity: state === 'error' ? 1 : 0,
+                    transitionDelay: state === 'error' ? '.3s' : undefined,
+                }}
             >
                 <path
                     d="M13.0312 1.42059L13.0312 3.95184"
@@ -93,29 +107,34 @@ export const AIChatIcon = ({
                 strokeWidth="1.2"
                 strokeLinecap="round"
                 strokeLinejoin="round"
-                className={tcls(
-                    state === 'done'
-                        ? 'animate-[fadeIn_.5s_.3s_both]'
-                        : 'animate-[fadeOut_.5s_both]',
-                    state === 'intro' && 'hidden',
-                    state === 'confirm' && 'hidden'
-                )}
+                className="transition-opacity duration-300"
+                style={{
+                    opacity: state === 'done' ? 1 : 0,
+                    transitionDelay: state === 'done' ? '.3s' : undefined,
+                }}
             />
 
             {/* Confirm */}
             <path
-                className={tcls(
-                    'fill-primary-9',
-                    state === 'confirm'
-                        ? 'animate-[fadeIn_.5s_.3s_both,bounceSmall_1s_infinite_both]'
-                        : state === 'thinking'
-                          ? 'animate-[fadeOut_.5s_both]'
-                          : 'hidden'
-                )}
+                className="transition-opacity duration-300"
+                style={{
+                    fill: 'rgb(var(--primary-9))',
+                    opacity: state === 'confirm' ? 1 : 0,
+                    transitionDelay: state === 'confirm' ? '.3s' : undefined,
+                    animation: {
+                        intro: '',
+                        thinking: '',
+                        working: '',
+                        done: '',
+                        confirm: 'bounceSmall 1s infinite both',
+                        default: '',
+                        error: '',
+                    }[state],
+                }}
                 d="M12.9463 5.24512C13.3688 5.24422 13.713 5.58625 13.7139 6.00879C13.7146 6.43114 13.3725 6.77338 12.9502 6.77441C12.5279 6.77505 12.1845 6.43408 12.1836 6.01172C12.1828 5.58953 12.5242 5.24649 12.9463 5.24512ZM13.0391 0.0751953C14.0688 0.0730893 14.9049 0.90586 14.9072 1.93555C14.9084 2.5063 14.6484 3.04679 14.2012 3.40137L13.7773 3.7373C13.6151 3.86604 13.5201 4.06239 13.5205 4.26953V4.30371C13.5211 4.62139 13.2639 4.879 12.9463 4.87988C12.6288 4.88032 12.3701 4.62417 12.3691 4.30664V4.27246C12.3679 3.71272 12.6238 3.18263 13.0625 2.83496L13.4854 2.49902C13.6565 2.36341 13.7562 2.1568 13.7559 1.93848C13.755 1.54463 13.4358 1.22503 13.042 1.22559H12.9385C12.488 1.22679 12.1225 1.59352 12.123 2.04395L12.124 2.21875C12.1245 2.53649 11.8676 2.79522 11.5498 2.7959C11.2321 2.79653 10.9746 2.53928 10.9736 2.22168L10.9727 2.04688C10.9706 0.960578 11.8493 0.0778178 12.9355 0.0751953H13.0391Z"
             />
 
-            {/* Background */}
+            {/* Background  */}
             <path
                 d="M3.5625 8.78512L7.26347 10.9219C7.88227 11.2791 8.64467 11.2791 9.26347 10.9219L14.25 8.0429C14.5833 7.85045 15 8.09101 15 8.47591V10.2777C15 10.4563 14.9047 10.6214 14.75 10.7107L9.26347 13.8784C8.64467 14.2356 7.88228 14.2356 7.26347 13.8784L3.5625 11.7416C2.70833 11.2978 1 9.93199 1 8.01949M1 8.01949C1 6.6448 1.84765 5.98698 2.62903 5.71701C3.15426 5.53555 3.71577 5.70568 4.19701 5.98353L7.26347 7.75395C7.88228 8.11122 8.64467 8.11122 9.26347 7.75395L10.9095 6.80362M1 8.01949C1 6.4945 2.03973 5.30731 2.5596 4.90434L7.37937 2.12165C7.79013 1.88449 8.26417 1.80476 8.71747 1.88245"
                 stroke="currentColor"
@@ -123,7 +142,17 @@ export const AIChatIcon = ({
                 strokeWidth="1.2"
                 strokeLinecap="round"
                 strokeLinejoin="round"
-                className={tcls(state === 'intro' && 'animate-[fadeIn_2s_forwards]')}
+                style={{
+                    animation: {
+                        intro: 'fadeIn 2s forwards',
+                        thinking: '',
+                        working: '',
+                        done: '',
+                        confirm: '',
+                        default: '',
+                        error: '',
+                    }[state],
+                }}
             />
 
             {/* Logo */}
@@ -153,14 +182,66 @@ export const AIChatIcon = ({
                     strokeWidth="1.2"
                     strokeLinecap="round"
                     strokeLinejoin="round"
-                    className={tcls(
-                        (state === 'thinking' || state === 'working') &&
-                            'animate-[pathLoading_2s_infinite_both]',
-                        state === 'intro' && 'animate-[pathEnter_2s_both]',
-                        state === 'done' && 'animate-[pathEnter_1s_forwards_ease]'
-                    )}
+                    style={{
+                        animation: {
+                            intro: 'pathEnter 1.5s both ease-out',
+                            thinking: 'pathLoading 2s infinite both',
+                            working: 'pathLoading 2s infinite both',
+                            done: 'pathEnter 1s forwards ease',
+                            confirm: '',
+                            default: '',
+                            error: '',
+                        }[state],
+                    }}
                 />
             </g>
         </svg>
     );
-};
+}
+
+interface AISearchIconProps extends React.SVGProps<SVGSVGElement> {
+    className?: string;
+    state?: 'default' | 'intro' | 'thinking' | 'working' | 'done' | 'error' | 'confirm';
+}
+
+export function AISearchIcon({ className = 'size-4', state = 'default' }: AISearchIconProps) {
+    return (
+        <div
+            style={{
+                position: 'relative',
+                animation: {
+                    intro: 'fadeIn 1s both, orbit 1s cubic-bezier(0.16,1,0.3,1)',
+                    thinking:
+                        'fadeIn 1s both, orbit 1s orbit 2s 1s infinite forwards linear ease-out,',
+                    working: '',
+                    done: '',
+                    confirm: '',
+                    default: '',
+                    error: '',
+                }[state],
+            }}
+        >
+            <Icon icon="search" className={className} />
+            <Icon
+                icon="sparkle"
+                iconStyle={IconStyle.Solid}
+                style={{
+                    position: 'absolute',
+                    top: '15.7%',
+                    left: '15.6%',
+                    width: '50%',
+                    height: '50%',
+                    animation: {
+                        intro: 'spin 2s .5s forwards cubic-bezier(0.16,1,0.3,1)',
+                        thinking: 'spin 2s infinite forwards cubic-bezier(0.16,1,0.3,1)',
+                        working: 'spin 2s infinite forwards cubic-bezier(0.16,1,0.3,1)',
+                        done: '',
+                        confirm: '',
+                        default: '',
+                        error: '',
+                    }[state],
+                }}
+            />
+        </div>
+    );
+}

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

@@ -1,38 +1,28 @@
 import { t, tString, useLanguage } from '@/intl/client';
-import { tcls } from '@/lib/tailwind';
 import { Icon } from '@gitbook/icons';
 import { useEffect, useRef } from 'react';
 import { useHotkeys } from 'react-hotkeys-hook';
-import { Button, HoverCard, HoverCardRoot, HoverCardTrigger } from '../primitives';
-import { KeyboardShortcut } from '../primitives/KeyboardShortcut';
+import { useAIChatState } from '../AI/useAIChat';
+import { HoverCard, HoverCardRoot, HoverCardTrigger } from '../primitives';
+import { Input } from '../primitives/Input';
 
 export function AIChatInput(props: {
-    value: string;
     disabled?: boolean;
     /**
      * When true, the input is disabled
      */
     loading: boolean;
-    onChange: (value: string) => void;
     onSubmit: (value: string) => void;
 }) {
-    const { value, onChange, onSubmit, disabled, loading } = props;
+    const { onSubmit, disabled, loading } = props;
 
     const language = useLanguage();
+    const chat = useAIChatState();
 
     const inputRef = useRef<HTMLTextAreaElement>(null);
 
-    const handleInput = (event: React.ChangeEvent<HTMLTextAreaElement>) => {
-        const textarea = event.currentTarget;
-        onChange(textarea.value);
-
-        // Auto-resize
-        textarea.style.height = 'auto';
-        textarea.style.height = `${textarea.scrollHeight}px`;
-    };
-
     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 +31,7 @@ export function AIChatInput(props: {
 
             return () => clearTimeout(timeout);
         }
-    }, [disabled, loading]);
+    }, [disabled, loading, chat.opened]);
 
     useHotkeys(
         'mod+i',
@@ -55,58 +45,35 @@ 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">
-            <textarea
-                ref={inputRef}
-                disabled={disabled || loading}
-                data-loading={loading}
-                data-testid="ai-chat-input"
-                className={tcls(
-                    'resize-none',
-                    'focus:outline-hidden',
-                    'focus:ring-0',
-                    'w-full',
-                    'px-3',
-                    'py-3',
-                    'pb-12',
-                    'h-auto',
-                    'bg-transparent',
-                    'peer',
-                    'max-h-64',
-                    'placeholder:text-tint/8',
-                    'transition-colors',
-                    'disabled:bg-tint-subtle',
-                    'delay-300',
-                    'disabled:delay-0',
-                    'disabled:cursor-not-allowed',
-                    'data-[loading=true]:cursor-progress',
-                    'data-[loading=true]:opacity-50'
-                )}
-                value={value}
-                rows={1}
-                placeholder={tString(language, 'ai_chat_input_placeholder')}
-                onChange={handleInput}
-                onKeyDown={(event) => {
-                    if (event.key === 'Escape') {
-                        event.preventDefault();
-                        event.currentTarget.blur();
-                        return;
-                    }
-
-                    if (event.key === 'Enter' && !event.shiftKey && value.trim()) {
-                        event.preventDefault();
-                        event.currentTarget.style.height = 'auto';
-                        onSubmit(value);
-                    }
-                }}
-            />
-            {!disabled ? (
-                <div className="absolute top-2.5 right-3 animate-[fadeIn_0.2s_0.5s_ease-in-out_both] peer-focus:hidden">
-                    <KeyboardShortcut keys={['mod', 'i']} className="bg-tint-base" />
-                </div>
-            ) : null}
-            <div className="absolute inset-x-0 bottom-0 flex items-center gap-2 px-2 py-2">
-                <HoverCardRoot>
+        <Input
+            data-testid="ai-chat-input"
+            name="ai-chat-input"
+            multiline
+            resize
+            sizing="large"
+            label="Assistant chat input"
+            placeholder={tString(language, 'ai_chat_input_placeholder')}
+            onSubmit={(val) => onSubmit(val as string)}
+            submitButton={{
+                size: 'small',
+                label: tString(language, 'send'),
+            }}
+            className="animate-blur-in-slow bg-tint-base/9 backdrop-blur-lg contrast-more:bg-tint-base"
+            rows={1}
+            maxLength={2048}
+            keyboardShortcut={
+                !disabled && !loading
+                    ? {
+                          keys: ['mod', 'i'],
+                          className: 'bg-tint-base group-focus-within/input:hidden',
+                      }
+                    : undefined
+            }
+            disabled={disabled || loading}
+            aria-busy={loading}
+            ref={inputRef}
+            trailing={
+                <HoverCardRoot openDelay={500}>
                     <HoverCard
                         className="max-w-xs bg-tint p-2 text-sm text-tint"
                         arrow={{ className: 'fill-tint-3' }}
@@ -133,7 +100,8 @@ export function AIChatInput(props: {
                         </div>
                     </HoverCard>
                     <HoverCardTrigger>
-                        <div className="flex cursor-help items-center gap-1 circular-corners:rounded-2xl rounded-corners:rounded-md px-2.5 py-1.5 text-tint/7 text-xs transition-all hover:bg-tint">
+                        {/* Negative margin to compensate for Input's padding, so the badge appears flush with the cursor */}
+                        <div className="-ml-1 flex cursor-help items-center gap-1 circular-corners:rounded-2xl rounded-corners:rounded-md px-2.5 py-1.5 text-tint/7 text-xs transition-all hover:bg-tint">
                             <span className="-ml-1 circular-corners:rounded-2xl rounded-corners:rounded-sm bg-tint-11/7 px-1 py-0.5 font-mono font-semibold text-[0.65rem] text-contrast-tint-11 leading-none">
                                 {t(language, 'ai_chat_context_badge')}
                             </span>{' '}
@@ -144,14 +112,7 @@ export function AIChatInput(props: {
                         </div>
                     </HoverCardTrigger>
                 </HoverCardRoot>
-                <Button
-                    label={tString(language, 'send')}
-                    size="medium"
-                    className="ml-auto"
-                    disabled={disabled || !value.trim()}
-                    onClick={() => onSubmit(value)}
-                />
-            </div>
-        </div>
+            }
+        />
     );
 }

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

@@ -2,7 +2,6 @@ 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';
@@ -11,87 +10,133 @@ import { AIChatFollowupSuggestions } from './AiChatFollowupSuggestions';
 export function AIChatMessages(props: {
     chat: AIChatState;
     chatController: AIChatController;
-    lastUserMessageRef?: React.RefObject<HTMLDivElement>;
 }) {
-    const { chat, chatController, 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 (
-                    <div
-                        ref={isLastUserMessage ? lastUserMessageRef : undefined}
-                        data-testid="ai-chat-message"
-                        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',
-                            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'
-                        )}
-                        style={{
-                            animationDelay: `${Math.min(index * 0.05, 0.5)}s`,
-                        }}
-                        key={index}
-                    >
-                        {message.content ? message.content : 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 });
+        }
+    });
 
-                        {isLastMessage && chat.loading ? (
-                            <div className="flex w-full animate-fade-in-slow flex-col gap-2">
-                                {!message.content ? <HoldMessage /> : null}
-                                <LoadingSkeleton />
-                            </div>
-                        ) : null}
+    // Add the last group if it exists
+    if (currentGroup.length > 0) {
+        messageGroups.push(currentGroup);
+    }
 
-                        {isLastMessage ? (
-                            <>
-                                {!chat.loading &&
-                                !chat.error &&
-                                chat.query &&
-                                chat.responseId &&
-                                chat.pendingTools.length === 0 ? (
-                                    <AIResponseFeedback
-                                        responseId={chat.responseId}
-                                        query={chat.query}
-                                        className="-ml-1 -mt-4"
+    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
+                            key={originalIndex}
+                            data-testid={
+                                message.role === AIMessageRole.User
+                                    ? 'ai-chat-message-user'
+                                    : 'ai-chat-message-assistant'
+                            }
+                            id={`message-${originalIndex}`}
+                            className={tcls(
+                                'flex flex-col gap-6',
+                                'break-words',
+                                'group/message',
+                                'animate-blur-in-slow',
+                                isLastMessage ? 'basis-full' : '',
+                                message.role === AIMessageRole.User
+                                    ? '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(originalIndex * 0.1, 0.6)}s`,
+                            }}
+                        >
+                            {message.content}
+
+                            {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}
+
+                            {isLastMessage ? (
+                                <>
+                                    {!chat.loading &&
+                                    !chat.error &&
+                                    chat.query &&
+                                    chat.responseId &&
+                                    chat.pendingTools.length === 0 ? (
+                                        <AIResponseFeedback
+                                            responseId={chat.responseId}
+                                            query={chat.query}
+                                            className="-ml-1 -mt-4"
+                                        />
+                                    ) : null}
+                                    <AIChatToolConfirmations chat={chat} />
+                                    <AIChatFollowupSuggestions
+                                        chat={chat}
+                                        chatController={chatController}
                                     />
-                                ) : null}
-                                <AIChatToolConfirmations chat={chat} />
-                                <AIChatFollowupSuggestions
-                                    chat={chat}
-                                    chatController={chatController}
-                                />
-                            </>
-                        ) : null}
-                    </div>
-                );
-            })}
-        </>
-    );
+                                </>
+                            ) : 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`,
                         }}
@@ -99,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`,
                         }}
@@ -122,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

@@ -7,25 +7,32 @@ export default function AIChatSuggestedQuestions(props: {
     suggestions?: string[];
 }) {
     const language = useLanguage();
-    const {
-        chatController,
-        suggestions = [
-            tString(language, 'ai_chat_suggested_questions_about_this_page'),
-            tString(language, 'ai_chat_suggested_questions_read_next'),
-            tString(language, 'ai_chat_suggested_questions_example'),
-        ],
-    } = props;
+    const { chatController, suggestions: _suggestions } = props;
+
+    const suggestions =
+        _suggestions && _suggestions.length > 0
+            ? _suggestions
+            : [
+                  tString(language, 'ai_chat_suggested_questions_about_this_page'),
+                  tString(language, 'ai_chat_suggested_questions_read_next'),
+                  tString(language, 'ai_chat_suggested_questions_example'),
+              ];
 
     return (
-        <div className="flex flex-col items-center gap-2">
+        <div
+            className="flex max-w-full max-w-full flex-col items-start gap-2 self-start"
+            data-testid="ai-chat-suggested-questions"
+        >
             {suggestions.map((question, index) => (
                 <Button
+                    truncate={false}
+                    data-testid="ai-chat-suggested-question"
                     key={question}
-                    variant="secondary"
-                    size="medium"
-                    className="max-w-full animate-[present_500ms_both] whitespace-normal"
+                    variant="blank"
+                    size="small"
+                    className="max-w-full animate-blur-in-slow border-none bg-primary-solid/1 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"
@@ -37,13 +37,14 @@ export function AIChatToolConfirmations(props: {
                     style={{ animationDelay: `${0.5 + index * 0.1}s` }}
                 >
                     <Button
+                        data-testid="ai-chat-tool-confirmation"
                         onClick={() => {
                             tool.confirm();
                         }}
                         tabIndex={index}
                         label={tool.label}
                         className="w-full justify-center"
-                        size={index === 0 ? 'default' : 'medium'}
+                        size={index === 0 ? 'medium' : 'small'}
                         variant={index === 0 ? 'primary' : 'secondary'}
                         icon={tool.icon}
                     />

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
@@ -34,8 +36,8 @@ export function AIResponseFeedback(props: {
                     'animate-fade-in overflow-hidden text-tint-subtle transition-all',
                     rating !== null && rating !== 1 && 'px-0 text-[0rem] opacity-0'
                 )}
-                size="medium"
-                style={{ animationDuration: '.5s' }}
+                size="small"
+                style={{ animationDelay: '.5s', animationDuration: '.5s' }}
                 onClick={() => handleRating(1)}
                 disabled={rating !== null}
                 active={rating === 1}
@@ -50,8 +52,8 @@ export function AIResponseFeedback(props: {
                     'animate-fade-in overflow-hidden text-tint-subtle transition-all',
                     rating !== null && rating !== -1 && 'px-0 text-[0rem] opacity-0'
                 )}
-                size="medium"
-                style={{ animationDelay: '.2s', animationDuration: '.5s' }}
+                size="small"
+                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,29 @@ 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 max-w-full flex-col items-start gap-2"
+                data-testid="ai-chat-followup-suggestions"
+            >
+                {chat.followUpSuggestions.map((suggestion, index) => (
+                    <Button
+                        truncate={false}
+                        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 border-none bg-primary-11/1 starting:py-0 text-left transition-all transition-discrete duration-500 hover:bg-primary-hover"
+                        size="small"
+                        variant="blank"
+                        style={{
+                            animationDelay: `${250 + Math.min(index * 50, 150)}ms`,
+                        }}
+                    />
+                ))}
+            </div>
         </div>
     );
 }

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

@@ -1,10 +1,9 @@
 'use client';
 import { Icon } from '@gitbook/icons';
-import { MotionConfig } from 'motion/react';
+import { MotionConfig, motion } from 'motion/react';
 import { useCheckForContentUpdate } from '../AutoRefreshContent';
-import { useVisitorSession } from '../Insights';
+import { useVisitor } from '../Insights';
 import { useCurrentPagePath } from '../hooks';
-import { DateRelative } from '../primitives';
 import { HideToolbarButton } from './HideToolbarButton';
 import { IframeWrapper } from './IframeWrapper';
 import { RefreshContentButton } from './RefreshContentButton';
@@ -14,7 +13,6 @@ import {
     ToolbarButton,
     ToolbarButtonGroup,
     type ToolbarButtonProps,
-    ToolbarSeparator,
     ToolbarSubtitle,
     ToolbarTitle,
 } from './Toolbar';
@@ -22,6 +20,7 @@ import {
     type ToolbarControlsContextValue,
     ToolbarControlsProvider,
 } from './ToolbarControlsContext';
+import { ToolbarDate } from './ToolbarDate';
 import type { AdminToolbarClientProps, AdminToolbarContext } from './types';
 import { useToolbarVisibility } from './utils';
 
@@ -41,7 +40,7 @@ export function AdminToolbarClient(props: AdminToolbarClientProps) {
         onToggleMinify,
     });
 
-    const visitorSession = useVisitorSession();
+    const visitor = useVisitor();
 
     const toolbarControls: ToolbarControlsContextValue = {
         minimize,
@@ -81,7 +80,7 @@ export function AdminToolbarClient(props: AdminToolbarClientProps) {
     }
 
     // If the user is authenticated and part of the organization owning this site, show the authenticated user toolbar
-    if (visitorSession?.organizationId === context.organizationId) {
+    if (visitor?.organizationId === context.organizationId) {
         return (
             <ToolbarControlsWrapper value={toolbarControls}>
                 <AuthenticatedUserToolbar
@@ -132,7 +131,7 @@ function ChangeRequestToolbar(props: ToolbarViewProps) {
     });
 
     return (
-        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange} label="Site preview">
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange}>
             <ToolbarBody>
                 <ToolbarTitle
                     prefix={`Change #${changeRequest.number}:`}
@@ -141,14 +140,13 @@ function ChangeRequestToolbar(props: ToolbarViewProps) {
                 <ToolbarSubtitle
                     subtitle={
                         <>
-                            <DateRelative value={changeRequest.updatedAt} /> by {author}
+                            <ToolbarDate value={changeRequest.updatedAt} />{' '}
+                            <motion.span layout="position">by {author}</motion.span>
                         </>
                     }
                 />
             </ToolbarBody>
 
-            <ToolbarSeparator />
-
             <ToolbarActions>
                 {/* Refresh to retrieve latest changes */}
                 {updated ? <RefreshContentButton refreshForUpdates={refreshForUpdates} /> : null}
@@ -167,10 +165,10 @@ function ChangeRequestToolbar(props: ToolbarViewProps) {
                     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,
@@ -207,18 +205,11 @@ function RevisionToolbar(props: ToolbarViewProps) {
     const gitProvider = isGitHub ? 'GitHub' : 'GitLab';
 
     return (
-        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange} label="Site preview">
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange}>
             <ToolbarBody>
-                <ToolbarTitle prefix="Site version" suffix={context.site.title} />
-                <ToolbarSubtitle
-                    subtitle={
-                        <>
-                            Created <DateRelative value={revision.createdAt} />
-                        </>
-                    }
-                />
+                <ToolbarTitle prefix="Prior version of " suffix={context.site.title} />
+                <ToolbarSubtitle subtitle={<ToolbarDate value={revision.createdAt} />} />
             </ToolbarBody>
-            <ToolbarSeparator />
             <ToolbarActions>
                 {/* Open commit in Git client */}
                 <ToolbarButton
@@ -249,7 +240,7 @@ function RevisionToolbar(props: ToolbarViewProps) {
                 />
                 {site.urls.published ? (
                     <ToolbarButton
-                        title="Open production site"
+                        title="Open live site"
                         href={getToolbarHref({
                             href: site.urls.published,
                             siteId: site.id,
@@ -280,22 +271,11 @@ function AuthenticatedUserToolbar(props: ToolbarViewProps) {
     });
 
     return (
-        <Toolbar
-            minified={minified}
-            onMinifiedChange={onMinifiedChange}
-            label="Only visible to your GitBook organization"
-        >
+        <Toolbar minified={minified} onMinifiedChange={onMinifiedChange}>
             <ToolbarBody>
                 <ToolbarTitle suffix={context.site.title} />
-                <ToolbarSubtitle
-                    subtitle={
-                        <>
-                            Updated <DateRelative value={revision.createdAt} />
-                        </>
-                    }
-                />
+                <ToolbarSubtitle subtitle={<ToolbarDate value={revision.createdAt} />} />
             </ToolbarBody>
-            <ToolbarSeparator />
             <ToolbarActions>
                 {/* Refresh to retrieve latest changes */}
                 {updated ? <RefreshContentButton refreshForUpdates={refreshForUpdates} /> : null}
@@ -305,18 +285,18 @@ function AuthenticatedUserToolbar(props: ToolbarViewProps) {
 
                 {/* Open site in GitBook */}
                 <ToolbarButton
-                    title="Open site in GitBook"
+                    title="View site configuration"
                     href={getToolbarHref({
                         href: site.urls.app,
                         siteId: site.id,
                         buttonId: 'site',
                     })}
-                    icon="gears"
+                    icon="folder-gear"
                 />
 
                 {/* Customize in GitBook */}
                 <ToolbarButton
-                    title="Customize in GitBook"
+                    title="Customize site"
                     href={getToolbarHref({
                         href: `${site.urls.app}/customization/general`,
                         siteId: site.id,
@@ -327,7 +307,7 @@ function AuthenticatedUserToolbar(props: ToolbarViewProps) {
 
                 {/* Open insights in GitBook */}
                 <ToolbarButton
-                    title="Open insights in GitBook"
+                    title="Open insights"
                     href={getToolbarHref({
                         href: `${site.urls.app}/insights`,
                         siteId: site.id,
@@ -361,13 +341,13 @@ function EditPageButton(props: {
 
     return (
         <ToolbarButton
-            title="Edit in GitBook"
+            title="Edit this page"
             href={getToolbarHref({
                 href: `${href}${pagePath.startsWith('/') ? pagePath.slice(1) : pagePath}`,
                 siteId,
                 buttonId: 'edit',
             })}
-            icon="pencil"
+            icon="pen-to-square"
             motionValues={motionValues}
         />
     );

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

@@ -8,10 +8,21 @@ 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;
+// Params for the expanding arc defined separately for easier tweaking.
+const ARC_PARAMS = {
+    arcWidth: 505,
+    arcHeight: 400,
+    arcRadius: 34,
+    startDistance: -240,
+    spreadDistance: 45,
+    fromDistance: -286,
+    fromSpread: 0,
+    durationSeconds: 0.6,
+    staggerMs: 80,
+    baseRotationDeg: 95,
+    rotationStepDeg: 18,
+    offsetAnchorY: 40,
+} as const;
 
 interface HideToolbarButtonProps {
     motionValues?: ToolbarButtonProps['motionValues'];
@@ -23,29 +34,56 @@ interface HideToolbarButtonProps {
 export function HideToolbarButton(props: HideToolbarButtonProps) {
     const { motionValues } = props;
     const [open, setOpen] = React.useState(false);
+    const [closing, setClosing] = React.useState(false);
     const controls = useToolbarControls();
+    const closingTimeoutRef = useRef(0);
 
     const ref = useRef<HTMLDivElement>(null);
     const buttonRef = useRef<HTMLDivElement>(null);
 
+    const closeArcMenu = React.useCallback(() => {
+        if (!open || closing) return;
+        setClosing(true);
+
+        // Clear any existing timeout
+        window.clearTimeout(closingTimeoutRef.current);
+
+        // Wait for the exit animation to complete before unmounting
+        const totalDuration = ARC_PARAMS.durationSeconds * 1000 + 3 * ARC_PARAMS.staggerMs;
+        closingTimeoutRef.current = window.setTimeout(() => {
+            setOpen(false);
+            setClosing(false);
+        }, totalDuration);
+    }, [open, closing]);
+
+    // Clean up timeout on unmount
+    React.useEffect(() => {
+        return () => window.clearTimeout(closingTimeoutRef.current);
+    }, []);
+
     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);
+        closeArcMenu();
     };
+    // @ts-expect-error wrong type for ref
     useOnClickOutside(ref, handleClickOutsideArcMenu);
 
-    // Close arc menu on scroll
+    // Close arc menu on scroll or resize
     React.useEffect(() => {
         if (!open) return;
 
-        const handleScroll = () => setOpen(false);
-        window.addEventListener('scroll', handleScroll, { passive: true });
+        const handleClose = () => closeArcMenu();
+        window.addEventListener('scroll', handleClose, { passive: true });
+        window.addEventListener('resize', handleClose, { passive: true });
 
-        return () => window.removeEventListener('scroll', handleScroll);
-    }, [open]);
+        return () => {
+            window.removeEventListener('scroll', handleClose);
+            window.removeEventListener('resize', handleClose);
+        };
+    }, [open, closeArcMenu]);
 
     const items = [
         controls?.minimize
@@ -83,18 +121,36 @@ export function HideToolbarButton(props: HideToolbarButtonProps) {
     return (
         <ToolbarButton
             ref={buttonRef}
-            title={open ? 'Hide options' : 'Hide toolbar'}
+            title={open ? undefined : 'Hide toolbar'}
+            className={
+                open || closing
+                    ? 'border-[0.5px] border-neutral-5 border-solid dark:border-neutral-8'
+                    : undefined
+            }
             onClick={() => {
-                setOpen((v) => !v);
+                if (open || closing) {
+                    closeArcMenu();
+                } else {
+                    setOpen(true);
+                }
             }}
             motionValues={motionValues}
-            icon="eye-slash"
+            icon="gear"
         >
             {/* Expanding arc menu */}
-            {open && (
+            {(open || closing) && (
                 <motion.div
                     className={tcls('pointer-events-none absolute inset-0', styles.arcMenu)}
-                    style={sharedMotionStyle as React.CSSProperties | undefined}
+                    style={
+                        {
+                            ...sharedMotionStyle,
+                            '--arc-width': `${ARC_PARAMS.arcWidth}px`,
+                            '--arc-height': `${ARC_PARAMS.arcHeight}px`,
+                            '--arc-radius': `${ARC_PARAMS.arcRadius}%`,
+                            '--start-distance': `${ARC_PARAMS.startDistance}px`,
+                            '--spread-distance': `${ARC_PARAMS.spreadDistance}px`,
+                        } as React.CSSProperties
+                    }
                 >
                     <div
                         className={tcls(
@@ -106,11 +162,12 @@ export function HideToolbarButton(props: HideToolbarButtonProps) {
                         {items.map((item, index) => (
                             <ArcToolbarButton
                                 index={index}
-                                staggerIndex={items.length - 1 - index}
-                                key={item.icon}
+                                staggerIndex={closing ? index : items.length - 1 - index}
+                                key={item.id}
+                                closing={closing}
                                 {...item}
                                 onClick={() => {
-                                    setOpen(false);
+                                    closeArcMenu();
                                     item.onClick?.();
                                 }}
                             />
@@ -126,13 +183,13 @@ type ArcMenuItem = {
     id: string;
     icon: IconName;
     label: string;
-    description: string;
     onClick?: () => void;
 };
 
 type ArcToolbarButtonProps = Pick<ArcMenuItem, 'label' | 'icon' | 'onClick'> & {
     index: number;
     staggerIndex?: number;
+    closing?: boolean;
     disabled?: boolean;
     className?: string;
     iconClassName?: string;
@@ -142,40 +199,36 @@ export function ArcToolbarButton(props: ArcToolbarButtonProps) {
     const {
         index,
         staggerIndex = index,
+        closing = false,
         label,
         disabled,
         className,
-        onClick = () => {},
+        onClick,
         icon,
         iconClassName,
     } = props;
 
     const targetOffset = `calc(var(--start-distance) + ${index} * var(--spread-distance))`;
+    const fromOffset = `calc(${ARC_PARAMS.fromDistance}px + ${index} * ${ARC_PARAMS.fromSpread}px)`;
 
-    // Calculate rotation based on position along the arc
-    const calculateRotation = () => {
-        return BASE_ROTATION_DEG - index * ROTATION_STEP_DEG;
-    };
-
-    const itemRotation = calculateRotation();
+    const itemRotation = ARC_PARAMS.baseRotationDeg - index * ARC_PARAMS.rotationStepDeg;
 
     return (
         <div className="pointer-events-none">
             <button
                 type="button"
-                onClick={() => {
-                    onClick();
-                }}
+                onClick={onClick ? () => onClick() : undefined}
                 style={
                     {
+                        '--from-offset-distance': fromOffset,
                         '--target-offset-distance': targetOffset,
-                        '--arc-duration': `${ARC_DURATION_SECONDS}s`,
-                        '--arc-delay': `${(staggerIndex ?? 0) * ARC_STAGGER_MS}ms`,
+                        '--arc-duration': `${ARC_PARAMS.durationSeconds}s`,
+                        '--arc-delay': `${(staggerIndex ?? 0) * ARC_PARAMS.staggerMs}ms`,
                         '--rotation-offset': `${itemRotation}deg`,
                         offsetPath: 'border-box',
-                        offsetDistance: targetOffset,
-                        offsetAnchor: '0% 40%',
-                        offsetRotate: `auto ${itemRotation}deg`,
+                        offsetDistance: fromOffset,
+                        offsetAnchor: `0% ${ARC_PARAMS.offsetAnchorY}%`,
+                        offsetRotate: 'auto 90deg',
                     } as React.CSSProperties
                 }
                 className={tcls(
@@ -184,48 +237,43 @@ export function ArcToolbarButton(props: ArcToolbarButtonProps) {
                     'top-0',
                     'left-0',
                     'w-40',
-                    'opacity-0',
                     'pointer-events-auto',
                     'flex',
                     'items-center',
                     'gap-2',
-                    styles.arcMenuItem,
+                    closing ? styles.arcMenuItemExit : 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 className="flex items-center gap-2">
+                    <div
+                        className={tcls(
+                            'flex h-8 w-8 shrink-0 cursor-pointer items-center justify-center gap-1 truncate rounded-full text-sm transition-colors',
+                            'border-[0.5px] border-neutral-5 border-solid dark:border-neutral-8',
+                            'group-hover:scale-105',
+                            disabled ? 'cursor-not-allowed opacity-50' : '',
+                            'bg-[var(--toolbar-bg)] text-tint-7 hover:text-tint-1 dark:text-tint-12',
+                            'group-hover:bg-[color-mix(in_srgb,var(--toolbar-bg)_90%,white)]'
+                        )}
+                    >
+                        <Icon
+                            icon={icon as IconName}
+                            iconStyle={IconStyle.Solid}
+                            className={tcls(
+                                'size-3.5 shrink-0 group-hover:scale-110',
+                                iconClassName
+                            )}
+                        />
+                    </div>
+                    <span
+                        className={tcls(
+                            'whitespace-nowrap rounded-lg border-[0.5px] border-neutral-5 border-solid bg-[var(--toolbar-bg)] px-3 py-1 font-normal text-neutral-1 text-sm transition-[background-color,transform] group-hover:scale-105 group-hover:bg-[color-mix(in_srgb,var(--toolbar-bg)_90%,white)] dark:border-neutral-8 dark:text-neutral-12',
+                            closing ? styles.arcLabelFadeOut : styles.arcLabelFadeIn
+                        )}
+                    >
+                        {label}
+                    </span>
                 </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

@@ -17,7 +17,7 @@
 .arcMenuItem {
     animation-name: hide-toolbar-arc-enter;
     animation-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
-    animation-fill-mode: forwards;
+    animation-fill-mode: both;
     animation-duration: var(--arc-duration, 0.4s);
     animation-delay: var(--arc-delay, 0s);
     transform-origin: center left;
@@ -28,13 +28,53 @@
 
 @keyframes hide-toolbar-arc-enter {
     from {
-        offset-distance: var(--start-distance);
-        transform: scale(0.5);
-        opacity: 0;
+        offset-distance: var(--from-offset-distance);
+        offset-rotate: auto 90deg;
     }
     to {
         offset-distance: var(--target-offset-distance);
-        transform: scale(1);
-        opacity: 1;
+        offset-rotate: auto var(--rotation-offset);
     }
 }
+
+@keyframes hide-toolbar-arc-exit {
+    from {
+        offset-distance: var(--target-offset-distance);
+        offset-rotate: auto var(--rotation-offset);
+    }
+    to {
+        offset-distance: var(--from-offset-distance);
+        offset-rotate: auto 90deg;
+    }
+}
+
+.arcMenuItemExit {
+    animation-name: hide-toolbar-arc-exit;
+    animation-timing-function: cubic-bezier(0.22, 1, 0.36, 1);
+    animation-fill-mode: both;
+    animation-duration: var(--arc-duration, 0.3s);
+    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);
+}
+
+/* ── Arc label fade ── */
+@keyframes arc-label-fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+}
+
+@keyframes arc-label-fade-out {
+    from { opacity: 1; }
+    to { opacity: 0; }
+}
+
+.arcLabelFadeIn {
+    animation: arc-label-fade-in 0.3s ease-out 0.2s both;
+}
+
+.arcLabelFadeOut {
+    animation: arc-label-fade-out 0.2s ease-out forwards;
+}

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

@@ -6,9 +6,10 @@ import {
     useReducedMotion,
     useSpring,
 } from 'motion/react';
-import React from 'react';
+import React, { isValidElement } from 'react';
 import { AnimatedLogo } from './AnimatedLogo';
 import { useToolbarControls } from './ToolbarControlsContext';
+import { ToolbarVisibilityHint } from './ToolbarVisibilityHint';
 
 import { tcls } from '@/lib/tailwind';
 import { Icon, type IconName, IconStyle } from '@gitbook/icons';
@@ -19,15 +20,20 @@ import { useMagnificationEffect } from './useMagnificationEffect';
 const DURATION_LOGO_APPEARANCE = 2000;
 const DELAY_BETWEEN_LOGO_AND_CONTENT = 100;
 
+const PILL_STYLE = {
+    '--toolbar-bg': '#1f1d1b',
+    borderRadius: '100px', // Set on `style` so Framer Motion can correct for distortions
+    zIndex: 1, // Ensure pill stacks above the peek label sibling
+} as React.CSSProperties;
+
 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 { children, minified, onMinifiedChange } = props;
     const controls = useToolbarControls();
     const [isReady, setIsReady] = React.useState(false);
     const autoExpandTriggeredRef = React.useRef(false);
@@ -35,6 +41,10 @@ export function Toolbar(props: ToolbarProps) {
     const shouldAutoExpand = Boolean(controls?.shouldAutoExpand);
     const [shouldAnimateLogo, setShouldAnimateLogo] = React.useState(shouldAutoExpand);
 
+    // Track when the pill's layout animation finishes so the hint label
+    // only appears once the toolbar is fully expanded.
+    const [showHint, setShowHint] = React.useState(!minified);
+
     // Wait for page to be ready, then show the toolbar
     React.useEffect(() => {
         const handleLoad = () => {
@@ -82,6 +92,10 @@ export function Toolbar(props: ToolbarProps) {
             // Any manual expansion should stop the logo animation so the icon stays in its
             // “settled” state once the toolbar is open.
             setShouldAnimateLogo(false);
+        } else {
+            // Hide the hint immediately when minimizing — it will reappear
+            // once the next expand animation completes.
+            setShowHint(false);
         }
     }, [minified]);
 
@@ -91,47 +105,57 @@ export function Toolbar(props: ToolbarProps) {
     }
 
     return (
-        <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 className="-translate-x-1/2 fixed bottom-5 left-1/2 z-40 w-auto max-w-xl transform px-4">
+            <ToolbarVisibilityHint show={showHint} />
+
+            <AnimatePresence mode="wait">
+                <motion.div
+                    onClick={() => {
+                        if (minified) {
+                            setShouldAnimateLogo(false);
+                            onMinifiedChange(false);
+                        }
+                    }}
+                    layout
+                    onLayoutAnimationComplete={() => {
+                        if (!minified) {
+                            setShowHint(true);
+                        }
+                    }}
+                    transition={toolbarEasings.spring}
+                    className={tcls(
+                        minified ? 'cursor-pointer' : 'pr-2 pl-3.5',
+                        'relative',
+                        'flex',
+                        'items-center',
+                        'justify-center',
+                        'min-h-11',
+                        'min-w-12',
+                        'h-12',
+                        'py-2',
+                        'origin-center',
+                        'border-[0.5px] border-neutral-5 border-solid dark:border-neutral-8',
+                        'bg-[var(--toolbar-bg)]'
+                    )}
+                    style={PILL_STYLE}
+                >
+                    {/* Logo — double-click to minimize */}
                     <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
+                        onDoubleClick={(e) => {
+                            if (minified) return;
+                            e.stopPropagation();
+                            window.getSelection()?.removeAllRanges();
+                            onMinifiedChange(true);
                         }}
                     >
-                        {/* Logo with stroke segments animation in blue-tints */}
-                        <motion.div layout>
-                            <AnimatedLogo shouldAnimate={shouldAnimateLogo} />
-                        </motion.div>
-
-                        {!minified ? children : null}
+                        <AnimatedLogo shouldAnimate={shouldAnimateLogo} />
                     </motion.div>
-                </AnimatePresence>
-            </motion.div>
-        </Tooltip>
+
+                    {!minified ? children : null}
+                </motion.div>
+            </AnimatePresence>
+        </motion.div>
     );
 }
 
@@ -198,62 +222,51 @@ export const ToolbarButton = React.forwardRef<HTMLDivElement, ToolbarButtonProps
     } = props;
     const reduceMotion = useReducedMotion();
 
+    const anchor = (
+        <motion.a
+            href={href}
+            onClick={onClick}
+            target="_blank"
+            rel="noopener noreferrer"
+            style={
+                reduceMotion
+                    ? undefined
+                    : {
+                          scale: motionValues?.scale,
+                          x: motionValues?.x,
+                          transformOrigin: 'bottom center',
+                          zIndex: motionValues?.scale ? 10 : 'auto',
+                          ...style,
+                      }
+            }
+            transition={{
+                type: 'spring',
+                stiffness: 400,
+                damping: 30,
+            }}
+            className={tcls(
+                'toolbar-button',
+                className,
+                'relative flex size-8 cursor-pointer items-center justify-center gap-1 truncate rounded-full text-sm transition-colors',
+                'text-tint-7 hover:text-tint-1',
+                'dark:text-tint-12',
+                disabled ? 'cursor-not-allowed opacity-50' : '',
+                'bg-[var(--toolbar-bg)]',
+                'hover:bg-[color-mix(in_srgb,var(--toolbar-bg)_90%,white)]'
+            )}
+        >
+            <Icon
+                icon={icon}
+                iconStyle={IconStyle.Solid}
+                className={tcls('size-3.5 shrink-0 group-hover:scale-110', iconClassName)}
+            />
+        </motion.a>
+    );
+
     return (
         <motion.div variants={toolbarEasings.staggeringChild} className="relative" ref={ref}>
             {children ? children : null}
-            <Tooltip label={title}>
-                <motion.a
-                    href={href}
-                    onClick={onClick}
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    style={
-                        reduceMotion
-                            ? undefined
-                            : {
-                                  scale: motionValues?.scale,
-                                  x: motionValues?.x,
-                                  transformOrigin: 'bottom center',
-                                  zIndex: motionValues?.scale ? 10 : 'auto',
-                                  ...style,
-                              }
-                    }
-                    transition={{
-                        type: 'spring',
-                        stiffness: 400,
-                        damping: 30,
-                    }}
-                    className={tcls(
-                        'toolbar-button',
-                        className,
-                        'flex',
-                        'relative',
-                        'items-center',
-                        'justify-center',
-                        'gap-1',
-                        'text-sm',
-                        'rounded-full',
-                        'truncate',
-                        'text-tint-1',
-                        'dark:text-tint-12',
-                        'cursor-pointer',
-                        'transition-colors',
-                        'size-8',
-                        disabled ? 'cursor-not-allowed opacity-50' : '',
-                        'border border-[rgba(256,_256,_256,_0.06)] border-solid',
-                        'bg-[linear-gradient(45deg,rgba(51,53,57,1)_0%,rgba(50,52,56,1)_100%)]'
-                    )}
-                >
-                    <Icon
-                        icon={icon}
-                        iconStyle={IconStyle.Solid}
-                        className={tcls(
-                            'size-4 shrink-0 group-hover:scale-110 group-hover:text-tint-3',
-                            iconClassName
-                        )}
-                    />
-                </motion.a>
-            </Tooltip>
+            {title ? <Tooltip label={title}>{anchor}</Tooltip> : anchor}
         </motion.div>
     );
 });
@@ -291,15 +304,15 @@ function ToolbarButtonWrapper(props: {
         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 }) {
     return (
         <div className="flex items-center gap-1 text-xs ">
@@ -324,7 +337,7 @@ function ToolbarTitleSuffix(props: { title: string }) {
     return (
         <motion.span
             {...getCopyVariants(1)}
-            className="max-w-[20ch] truncate text-neutral-1 dark:text-neutral-12"
+            className="max-w-[20ch] truncate font-bold text-neutral-1 dark:text-neutral-12"
         >
             {props.title}
         </motion.span>
@@ -335,7 +348,7 @@ export function ToolbarSubtitle(props: { subtitle: React.ReactNode }) {
     return (
         <motion.span
             {...getCopyVariants(1)}
-            className="text-neutral-1/80 text-xxs dark:text-neutral-12/80"
+            className="inline-flex items-center gap-1 text-neutral-1/80 text-xxs dark:text-neutral-12/80"
         >
             {props.subtitle}
         </motion.span>

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

@@ -0,0 +1,94 @@
+'use client';
+
+import React from 'react';
+
+import { useLanguage } from '@/intl/client';
+import { AnimatePresence, motion } from 'motion/react';
+import { formatDateTime, formatDateWeekday, formatRelative } from '../utils/dates';
+
+type DateFormat = 'relative' | 'weekday' | 'full';
+
+const DATE_FORMATS: DateFormat[] = ['relative', 'weekday', 'full'];
+
+/**
+ * Toolbar-specific date display that cycles between relative, weekday, and full formats on click.
+ */
+export function ToolbarDate(props: { value: string }) {
+    const { value } = props;
+    const language = useLanguage();
+    const [formatIndex, setFormatIndex] = React.useState(0);
+    const [hovered, setHovered] = React.useState(false);
+
+    const format = DATE_FORMATS[formatIndex] as DateFormat;
+
+    const formatted = React.useMemo(() => {
+        const date = new Date(value);
+        switch (format) {
+            case 'relative':
+                return formatRelative(language.locale, Date.now() - date.getTime());
+            case 'weekday':
+                return formatDateWeekday(date, language.locale);
+            case 'full':
+                return formatDateTime(date, language.locale);
+        }
+    }, [format, language.locale, value]);
+
+    return (
+        <motion.div
+            className="inline-flex items-center gap-1"
+            onMouseEnter={() => setHovered(true)}
+            onMouseLeave={() => setHovered(false)}
+        >
+            {/* Vertical dots indicating cycleable formats */}
+            <AnimatePresence>
+                {hovered && (
+                    <motion.div
+                        initial={{ width: 0, opacity: 0 }}
+                        animate={{ width: 'auto', opacity: 1 }}
+                        exit={{ width: 0, opacity: 0 }}
+                        transition={{ type: 'spring', stiffness: 300, damping: 25 }}
+                        className="overflow-hidden"
+                    >
+                        <div className="flex flex-col items-center gap-[1px]">
+                            {DATE_FORMATS.map((fmt, i) => (
+                                <motion.span
+                                    key={fmt}
+                                    animate={{
+                                        opacity: i === formatIndex ? 1 : 0.3,
+                                        scale: i === formatIndex ? 1 : 0.75,
+                                    }}
+                                    transition={{ type: 'spring', stiffness: 300, damping: 25 }}
+                                    className="block size-[3px] rounded-full bg-current"
+                                />
+                            ))}
+                        </div>
+                    </motion.div>
+                )}
+            </AnimatePresence>
+            <motion.time
+                layout="position"
+                data-visual-test="transparent"
+                suppressHydrationWarning={true}
+                dateTime={value}
+                onClick={(e) => {
+                    e.stopPropagation();
+                    setFormatIndex((i) => (i + 1) % DATE_FORMATS.length);
+                }}
+                transition={{ type: 'spring', stiffness: 300, damping: 25 }}
+                className="relative inline-flex cursor-pointer select-none overflow-hidden font-semibold transition-colors hover:text-white" // `text-white` is used insead of dark-mode adapting values because the date is always in a dark-tinted toolbar
+            >
+                <AnimatePresence mode="popLayout" initial={false}>
+                    <motion.span
+                        key={formatIndex}
+                        initial={{ y: '-100%', opacity: 0 }}
+                        animate={{ y: 0, opacity: 1 }}
+                        exit={{ y: '100%', opacity: 0 }}
+                        transition={{ type: 'spring', stiffness: 300, damping: 25 }}
+                    >
+                        {formatted}
+                    </motion.span>
+                </AnimatePresence>
+            </motion.time>
+        </motion.div>
+    );
+}

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

@@ -0,0 +1,51 @@
+'use client';
+
+import { motion } from 'motion/react';
+import React from 'react';
+import { getVisibilityHintDismissed, setVisibilityHintDismissed } from './utils';
+
+interface ToolbarVisibilityHintProps {
+    show: boolean;
+}
+
+export function ToolbarVisibilityHint(props: ToolbarVisibilityHintProps) {
+    const { show } = props;
+    const [dismissed, setDismissed] = React.useState(() =>
+        typeof window !== 'undefined' ? getVisibilityHintDismissed() : false
+    );
+
+    if (dismissed) {
+        return null;
+    }
+
+    return (
+        <motion.div
+            initial={false}
+            animate={{
+                y: show ? 0 : 10,
+                opacity: show ? 1 : 0,
+            }}
+            transition={{
+                type: 'spring',
+                stiffness: 300,
+                damping: 25,
+            }}
+            className="-translate-x-1/2 pointer-events-none absolute bottom-full left-1/2 flex items-center gap-1.5 rounded-t-xl border border-[#eaeaea] border-b-0 border-solid bg-white px-3 py-0.5"
+        >
+            <span className="whitespace-nowrap text-[11px] text-neutral-9">
+                Only visible to your GitBook organization
+            </span>
+            <button
+                type="button"
+                className="pointer-events-auto cursor-pointer rounded border border-tint-5 bg-tint-2 px-1 py-px text-[10px] text-tint-12 transition-colors hover:scale-102 hover:bg-tint-3 dark:border-tint-11/50 dark:bg-white dark:text-tint-1 dark:hover:bg-tint-11/20"
+                onClick={(e) => {
+                    e.stopPropagation();
+                    setVisibilityHintDismissed();
+                    setDismissed(true);
+                }}
+            >
+                Dismiss
+            </button>
+        </motion.div>
+    );
+}