review fix

fix e2e test
add toggleable link
2026-09-14 06:35:17 +00:00 · 2025-06-17 23:19:09 +02:00 · 2025-06-17 10:43:16 +02:00 · 2025-06-17 10:03:14 +02:00 · 2025-06-17 09:44:46 +02:00 · 2025-06-16 21:46:21 +02:00
792 changed files with 17524 additions and 38388 deletions
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix UX issue about highlighting the search term in search result sections
@@ -0,0 +1,9 @@
+---
+"gitbook": patch
+---
+
+Fix three small visual issues
+
+- Fix sidebar showing on `no-toc` pages in the gradient theme
+- Fix variant selector truncating incorrectly in header when sections are present
+- Fix page cover alignment on `lg` screens without TOC
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Respect fullWidth and defaultWidth for images
@@ -1,5 +0,0 @@
---
-'@gitbook/react-openapi': patch
---
-
-Fix missing properties in allOf/oneOf
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+Add docs.testgitbook.com to ADAPTIVE_CONTENT_HOSTS list
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+fix nested a tag causing hydration error
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+fix href being empty in TOC
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add Input component
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix navigation between sections/variants when previewing a site in v2
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add sidesheet component, use it for TOC and AIChat
@@ -1,5 +0,0 @@
---
-'@gitbook/react-openapi': patch
---
-
-Enhance discriminator handling in OpenAPISchema
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Add circular corners and depth styling
@@ -2,4 +2,4 @@
 '@gitbook/react-openapi': patch
 ---

-Fix OpenAPI basic auth placeholder
+Add authorization header for OAuth2
@@ -3,4 +3,4 @@
 'gitbook': patch
 ---

-Improve OpenAPI circular references
+Improve support for OAuth2 security type
@@ -1,6 +0,0 @@
---
-'@gitbook/openapi-parser': patch
-'@gitbook/react-openapi': patch
---
-
-Add x-gitbook-prefix and x-gitbook-token-placeholder for OpenAPI security scheme
@@ -0,0 +1,6 @@
+---
+"gitbook-v2": patch
+"gitbook": patch
+---
+
+Adds Columns layout block to GBO
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Support dark-mode specific page cover image
@@ -0,0 +1,5 @@
+---
+'gitbook': patch
+---
+
+Update Models page styling
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix overflowing section groups
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix search results cursor
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+Optimize performances by using a smarter per-request cache arround data cached functions
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+add a force-revalidate api route to force bust the cache in case of errors
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Fix rendering of ogimage with SVG logos.
@@ -1,6 +0,0 @@
---
-"@gitbook/embed": minor
-"gitbook": patch
---
-
-Improve Docs Embed with separate Assistant and Docs tabs
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Best effort at preserving current variant when navigating between sections by matching the pathname against site spaces in the new section.
@@ -0,0 +1,6 @@
+---
+"gitbook-v2": patch
+"gitbook": patch
+---
+
+encode customization header
@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Rework full-width layout, add support for full-width page option
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+fix ISR on preview env
@@ -0,0 +1,6 @@
+---
+"gitbook-v2": patch
+"gitbook": patch
+---
+
+Fix concurrent execution in Vercel causing pages to not be attached to the proper tags.
@@ -1,5 +0,0 @@
---
-"@gitbook/icons": minor
---
-
-Update to FontAwesome 7.1.0
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+Generate a llms-full.txt version of the docs site
@@ -0,0 +1,5 @@
+---
+"@gitbook/fonts": minor
+---
+
+Initial version of the package
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add margin to adjacent buttons
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add customizable suggested questions
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+add a global error boundary
@@ -2,4 +2,4 @@
 '@gitbook/react-openapi': patch
 ---

-Fix OpenAPI oneOf/allOf merge
+Indent JSON python code sample
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix missing title on button to close the announcement banner.
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Make icons for page groups more contrasting
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Ignore case while highlighting search results.
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Make TOC height dynamic based on visible header and footer elements
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix links to other spaces and root page in embeddable view.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Support `greeting` and fix suggested questions if there are no custom ones defined
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix bold header links hover color
@@ -0,0 +1,6 @@
+---
+"gitbook": patch
+"gitbook-v2": patch
+---
+
+cache fonts and static image used in OGImage in memory
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix border being added to cards
@@ -1,5 +0,0 @@
---
-"gitbook": minor
---
-
-Add a RSS feed to all pages with update blocks.
@@ -0,0 +1,5 @@
+---
+'@gitbook/react-openapi': patch
+---
+
+Handle nested deprecated properties in generateSchemaExample
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+Add `urlObject.hash` to `linker.toLinkForContent` to pass through URL fragment identifiers, used in search
@@ -1,5 +0,0 @@
---
-'gitbook': patch
---
-
-Remove hidden site spaces from navigation
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+apply customization for dynamic context
@@ -1,5 +0,0 @@
---
-'gitbook': patch
---
-
-Fix hidden section not found
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Reverse order of feedback smileys
@@ -0,0 +1,5 @@
+---
+'@gitbook/react-openapi': patch
+---
+
+Deduplicate path parameters from OpenAPI spec
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix ogimage using incorrect Google Font depending on language.
@@ -0,0 +1,5 @@
+---
+"gitbook-v2": patch
+---
+
+remove trailing slash from linker
@@ -1,3 +0,0 @@
-# Changes to the API data cache functions can invalidate all existing data cache
-# causing a massive amount of revalidation, impacting our API.
-packages/gitbook/src/lib/data/api.ts   @SamyPesse
@@ -53,39 +53,17 @@ After forking this repository, you'll want to [create a branch](https://docs.git

 #### 3. Install dependencies and run the project locally

-##### Prerequisites:
+GitBook uses [Bun](https://bun.sh/) to run the project. Make sure you're using the specified version of `node` before running any of the development commands to ensure a smooth development experience.

- [Node.js](https://nodejs.org/en) (see "engines" in `package.json`)
- [Bun](https://bun.sh/) (see "packageManager" in `package.json`)
+You can easily do this by running the command `nvm use`.

-##### Setup steps:
-
-1. Ensure you are using the project's version of Node:
-```bash
-nvm use
-```
-
-2. Install dependencies using Bun:
-```bash
-bun install
-```
-
-3. Start the development server:
-```bash
-bun dev
-```
-
-Additional development commands:
- `bun format`: Format the code using Biome
- `bun typecheck`: Run TypeScript type checking
- `bun unit`: Run unit tests
- `bun e2e`: Run end-to-end tests
+To start your local version of GitBook, run the command `bun dev`.

 #### 4. Preview your changes

-When running the development server, published GitBook sites can be rendered through your local version at `http://localhost:3000/url`.
+When running the development server, published GitBook sites can be rendered through your local version at `http://localhost:3000/`.

-For example, our published docs can be viewed using the local version by visiting `http://localhost:3000/url/gitbook.com/docs` after running the development server.
+For example, our published docs can be viewed using the local version by visiting `http://localhost:3000/gitbook.com/docs` after running the development server.

 You can visit any published GitBook site behind your development server. Please make sure your site is [published publicly](https://gitbook.com/docs/published-documentation/publish-your-content-as-a-docs-site) to ensure you can view the site correctly in your development version.

@@ -30,9 +30,9 @@ runs:
            apiToken: ${{ inputs.apiToken }}
            accountId: ${{ inputs.accountId }}
            workingDirectory: ./
-            wranglerVersion: '4.43.0'
+            wranglerVersion: '4.10.0'
            environment: ${{ inputs.environment }}
-            command: deployments status --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
+            command: deployments status --config ./packages/gitbook-v2/openNext/customWorkers/defaultWrangler.jsonc

      # This step is used to get the version ID that is currently deployed to Cloudflare.
      - id: extract_current_version
@@ -49,9 +49,9 @@ runs:
            apiToken: ${{ inputs.apiToken }}
            accountId: ${{ inputs.accountId }}
            workingDirectory: ./
-            wranglerVersion: '4.43.0'
+            wranglerVersion: '4.10.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
+            command: versions deploy ${{ steps.extract_current_version.outputs.version_id }}@100% ${{ inputs.serverVersionId }}@0% -y --config ./packages/gitbook-v2/openNext/customWorkers/defaultWrangler.jsonc

      # Since we use version overrides headers, we can directly deploy the middleware to 100%.
      - id: deploy_middleware
@@ -61,9 +61,9 @@ runs:
            apiToken: ${{ inputs.apiToken }}
            accountId: ${{ inputs.accountId }}
            workingDirectory: ./
-            wranglerVersion: '4.43.0'
+            wranglerVersion: '4.10.0'
            environment: ${{ inputs.environment }}
-            command: versions deploy ${{ inputs.middlewareVersionId }}@100% -y --config ./packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc
+            command: versions deploy ${{ inputs.middlewareVersionId }}@100% -y --config ./packages/gitbook-v2/openNext/customWorkers/middlewareWrangler.jsonc

      - name: Deploy server to Cloudflare at 100%
        uses: cloudflare/wrangler-action@v3.14.0
@@ -71,9 +71,9 @@ runs:
            apiToken: ${{ inputs.apiToken }}
            accountId: ${{ inputs.accountId }}
            workingDirectory: ./
-            wranglerVersion: '4.43.0'
+            wranglerVersion: '4.10.0'
            environment: ${{ inputs.environment }}
-            command: versions deploy ${{ inputs.serverVersionId }}@100% -y --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
+            command: versions deploy ${{ inputs.serverVersionId }}@100% -y --config ./packages/gitbook-v2/openNext/customWorkers/defaultWrangler.jsonc

      - name: Outputs
        shell: bash
@@ -0,0 +1,37 @@
+name: 'Setup Playwright'
+description: 'Install Playwright and dependencies'
+runs:
+    using: 'composite'
+    steps:
+        # Run npm ci and get Playwright version
+        - name: 🏗 Prepare Playwright env
+          shell: bash
+          run: |
+              PLAYWRIGHT_VERSION=$(npm ls --json @playwright/test | jq --raw-output '.dependencies["gitbook"].dependencies["@playwright/test"].version')
+              echo "PLAYWRIGHT_VERSION=$PLAYWRIGHT_VERSION" >> $GITHUB_ENV
+
+        # Cache browser binaries, cache key is based on Playwright version and OS
+        - name: 🧰 Cache Playwright browser binaries
+          uses: actions/cache@v4
+          id: playwright-cache
+          with:
+              path: '~/.cache/ms-playwright'
+              key: '${{ runner.os }}-playwright-${{ env.PLAYWRIGHT_VERSION }}'
+              restore-keys: |
+                  ${{ runner.os }}-playwright-
+
+        # Install browser binaries & OS dependencies if cache missed
+        - name: 🏗 Install Playwright browser binaries & OS dependencies
+          if: steps.playwright-cache.outputs.cache-hit != 'true'
+          shell: bash
+          working-directory: packages/gitbook
+          run: |
+              bun x playwright install --with-deps chromium
+
+        # Install only the OS dependencies if cache hit
+        - name: 🏗 Install Playwright OS dependencies
+          if: steps.playwright-cache.outputs.cache-hit == 'true'
+          shell: bash
+          working-directory: packages/gitbook
+          run: |
+              bun x playwright install-deps
@@ -59,7 +59,7 @@ runs:
            GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
            GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
        - name: Build worker
-          run: bun run turbo build:cloudflare
+          run: bun run turbo build:v2:cloudflare
          env:
            GITBOOK_RUNTIME: cloudflare
          shell: bash
@@ -70,9 +70,9 @@ runs:
              apiToken: ${{ inputs.apiToken }}
              accountId: ${{ inputs.accountId }}
              workingDirectory: ./
-              wranglerVersion: '4.43.0'
+              wranglerVersion: '4.10.0'
              environment: ${{ inputs.environment }}
-              command: deploy --config ./packages/gitbook/openNext/customWorkers/doWrangler.jsonc
+              command: deploy --config ./packages/gitbook-v2/openNext/customWorkers/doWrangler.jsonc

        - id: upload_server
          name: Upload server to Cloudflare
@@ -81,9 +81,9 @@ runs:
              apiToken: ${{ inputs.apiToken }}
              accountId: ${{ inputs.accountId }}
              workingDirectory: ./
-              wranglerVersion: '4.43.0'
+              wranglerVersion: '4.10.0'
              environment: ${{ inputs.environment }}
-              command: ${{ format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
+              command: ${{ format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook-v2/openNext/customWorkers/defaultWrangler.jsonc

        - name: Extract server version worker ID
          shell: bash
@@ -95,7 +95,7 @@ runs:
        - name: Run updateWrangler scripts
          shell: bash
          run: |
-              bun run ./packages/gitbook/openNext/customWorkers/script/updateWrangler.ts ${{ steps.extract_server_version_id.outputs.version_id }}
+              bun run ./packages/gitbook-v2/openNext/customWorkers/script/updateWrangler.ts ${{ steps.extract_server_version_id.outputs.version_id }}

        - id: upload_middleware
          name: Upload middleware to Cloudflare
@@ -104,9 +104,9 @@ runs:
              apiToken: ${{ inputs.apiToken }}
              accountId: ${{ inputs.accountId }}
              workingDirectory: ./
-              wranglerVersion: '4.43.0'
+              wranglerVersion: '4.10.0'
              environment: ${{ inputs.environment }}
-              command: ${{ format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc
+              command: ${{ format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook-v2/openNext/customWorkers/middlewareWrangler.jsonc
        
        - name: Extract middleware version worker ID
          shell: bash
@@ -4,9 +4,8 @@ on:
    push:
        branches:
            - main
-            - changeset-release/main
 env:
-    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
+    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
    format:
        runs-on: ubuntu-latest
@@ -42,7 +41,7 @@ jobs:
        name: Build (Open Source)
        timeout-minutes: 6
        env:
-            BUN_NPM_TOKEN: ''
+            NPM_TOKEN_READONLY: ''
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -5,8 +5,55 @@ on:
      branches:
        - main
 env:
-    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
+    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
+    deploy-v1-cloudflare:
+        name: Deploy v1 to Cloudflare Pages
+        runs-on: ubuntu-latest
+        environment:
+          name: ${{ github.ref == 'refs/heads/main' && '1c-production' || '1c-preview' }}
+          url: ${{ steps.deploy.outputs.deployment-url }}
+        permissions:
+            contents: read
+            deployments: write
+            issues: write
+            pull-requests: write
+            checks: write
+            statuses: write
+        outputs:
+            deployment-url: ${{ steps.deploy.outputs.deployment-url }}
+            deployment-alias-url: ${{ steps.deploy.outputs.deployment-alias-url }}
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+            - name: Setup Bun
+              uses: ./.github/composite/setup-bun
+            - name: Install dependencies
+              run: bun install --frozen-lockfile
+              env:
+                  PUPPETEER_SKIP_DOWNLOAD: 1
+            - name: Sets env vars for production
+              if: github.ref == 'refs/heads/main'
+              run: |
+                echo "GITBOOK_ASSETS_PREFIX=https://static.gitbook.com" >> $GITHUB_ENV
+            - name: Build Next.js with next-on-pages
+              run: bun run turbo gitbook#build:cloudflare
+              env:
+                  NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: ${{ secrets.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY }}
+                  GITBOOK_RUNTIME: cloudflare
+            - id: deploy
+              name: Deploy to Cloudflare
+              uses: cloudflare/wrangler-action@v3.14.0
+              with:
+                  apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+                  accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+                  workingDirectory: ./
+                  wranglerVersion: '3.112.0'
+                  command: pages deploy ./packages/gitbook/.vercel/output/static --project-name=${{ vars.CLOUDFLARE_PROJECT_NAME }} --branch=${{ github.ref == 'refs/heads/main' && 'main' || format('pr{0}', github.event.pull_request.number) }}
+            - name: Outputs
+              run: |
+                  echo "URL: ${{ steps.deploy.outputs.deployment-url }}"
+                  echo "Alias URL: ${{ steps.deploy.outputs.deployment-alias-url }}"
    deploy-v2-vercel:
        name: Deploy v2 to Vercel (preview)
        runs-on: ubuntu-latest
@@ -67,6 +114,7 @@ jobs:
        name: Comment Deployments (preview)
        if: always() && !startsWith(github.ref, 'refs/heads/main')
        needs:
+            - deploy-v1-cloudflare
            - deploy-v2-vercel
            - deploy-v2-cloudflare
        steps:
@@ -86,6 +134,15 @@ jobs:
                  body: |
                      Summary of the deployments:

+                      ### Version 1
+
+                      | Version | URL | Status |
+                      | --- | --- | --- |
+                      | Latest commit | [${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}](${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}) | ${{ needs.deploy-v1-cloudflare.result == 'success' && '✅' || '❌' }} |
+                      | PR | [${{ needs.deploy-v1-cloudflare.outputs.deployment-alias-url }}](${{ needs.deploy-v1-cloudflare.outputs.deployment-alias-url }}) | ${{ needs.deploy-v1-cloudflare.result == 'success' && '✅' || '❌' }} |
+
+                      ### Version 2
+
                      | Version | URL | Status |
                      | --- | --- | --- |
                      | Vercel | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}](${{ needs.deploy-v2-vercel.outputs.deployment-url }}) | ${{ needs.deploy-v2-vercel.result == 'success' && '✅' || '❌' }} |
@@ -93,16 +150,16 @@ jobs:

                      ### Test content

-                      | Site | `2v` | `2c` |
-                      | --- | --- | --- |
-                      | GitBook | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.com/docs](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.com/docs) | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.com/docs](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.com/docs) |
-                      | E2E | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) |
+                      | Site | `v1` | `2v` | `2c` |
+                      | --- | --- | --- | --- |
+                      | GitBook | [${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.com/docs](${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.com/docs) | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.com/docs](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.com/docs) | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.com/docs](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.com/docs) |
+                      | E2E | [${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}/gitbook.gitbook.io/test-gitbook-open) | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) |
                  edit-mode: replace
-    visual-testing-v2-vercel:
+    visual-testing-v1:
        runs-on: ubuntu-latest
-        name: Visual Testing v2
-        needs: deploy-v2-vercel
-        timeout-minutes: 15
+        name: Visual Testing v1
+        needs: deploy-v1-cloudflare
+        timeout-minutes: 10
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -110,8 +167,27 @@ jobs:
              uses: ./.github/composite/setup-bun
            - name: Install dependencies
              run: bun install --frozen-lockfile
+            - name: Setup Playwright
+              uses: ./.github/actions/setup-playwright
+            - name: Run Playwright tests
+              run: bun e2e
              env:
-                  PUPPETEER_SKIP_DOWNLOAD: 1
+                  BASE_URL: ${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}
+                  ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+    visual-testing-v2-vercel:
+        runs-on: ubuntu-latest
+        name: Visual Testing v2
+        needs: deploy-v2-vercel
+        timeout-minutes: 10
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+            - name: Setup Bun
+              uses: ./.github/composite/setup-bun
+            - name: Install dependencies
+              run: bun install --frozen-lockfile
+            - name: Setup Playwright
+              uses: ./.github/actions/setup-playwright
            - name: Run Playwright tests
              run: bun e2e
              env:
@@ -123,7 +199,7 @@ jobs:
        runs-on: ubuntu-latest
        name: Visual Testing v2 (Cloudflare)
        needs: deploy-v2-cloudflare
-        timeout-minutes: 15
+        timeout-minutes: 10
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -131,8 +207,8 @@ jobs:
              uses: ./.github/composite/setup-bun
            - name: Install dependencies
              run: bun install --frozen-lockfile
-              env:
-                  PUPPETEER_SKIP_DOWNLOAD: 1
+            - name: Setup Playwright
+              uses: ./.github/actions/setup-playwright
            - name: Run Playwright tests
              run: bun e2e
              env:
@@ -140,11 +216,11 @@ jobs:
                  SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
                  ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
                  ARGOS_BUILD_NAME: 'v2-cloudflare'
-    visual-testing-customers-v2:
+    visual-testing-customers-v1:
        runs-on: ubuntu-latest
-        name: Visual Testing Customers v2
-        needs: deploy-v2-vercel
-        timeout-minutes: 15
+        name: Visual Testing Customers v1
+        needs: deploy-v1-cloudflare
+        timeout-minutes: 10
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -152,8 +228,28 @@ jobs:
              uses: ./.github/composite/setup-bun
            - name: Install dependencies
              run: bun install --frozen-lockfile
+            - name: Setup Playwright
+              uses: ./.github/actions/setup-playwright
+            - name: Run Playwright tests
+              run: bun e2e-customers
              env:
-                  PUPPETEER_SKIP_DOWNLOAD: 1
+                  BASE_URL: ${{ needs.deploy-v1-cloudflare.outputs.deployment-url }}
+                  ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
+                  ARGOS_BUILD_NAME: 'customers-v1'
+    visual-testing-customers-v2:
+        runs-on: ubuntu-latest
+        name: Visual Testing Customers v2
+        needs: deploy-v2-vercel
+        timeout-minutes: 10
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v4
+            - name: Setup Bun
+              uses: ./.github/composite/setup-bun
+            - name: Install dependencies
+              run: bun install --frozen-lockfile
+            - name: Setup Playwright
+              uses: ./.github/actions/setup-playwright
            - name: Run Playwright tests
              run: bun e2e-customers
              env:
@@ -165,7 +261,7 @@ jobs:
        runs-on: ubuntu-latest
        name: Visual Testing Customers v2 (Cloudflare)
        needs: deploy-v2-cloudflare
-        timeout-minutes: 15
+        timeout-minutes: 10
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -173,8 +269,8 @@ jobs:
              uses: ./.github/composite/setup-bun
            - name: Install dependencies
              run: bun install --frozen-lockfile
-              env:
-                  PUPPETEER_SKIP_DOWNLOAD: 1
+            - name: Setup Playwright
+              uses: ./.github/actions/setup-playwright
            - name: Run Playwright tests
              run: bun e2e-customers
              env:
@@ -182,10 +278,10 @@ jobs:
                  SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
                  ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
                  ARGOS_BUILD_NAME: 'customers-v2'
-    browserless-testing-v2-vercel:
+    pagespeed-testing-v1:
        runs-on: ubuntu-latest
-        name: Browserless Testing v2 (Vercel)
-        needs: deploy-v2-vercel
+        name: PageSpeed Testing v1
+        needs: deploy-v1-cloudflare
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -195,26 +291,8 @@ jobs:
              run: bun install --frozen-lockfile
              env:
                  PUPPETEER_SKIP_DOWNLOAD: 1
-            - name: Run tests
-              run: cd ./packages/gitbook && bun e2e-browserless
+            - name: Run pagespeed tests
+              run: bun ./packages/gitbook/tests/pagespeed-testing.ts
              env:
-                  BASE_URL: ${{needs.deploy-v2-vercel.outputs.deployment-url}}
-                  SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
-    # browserless-testing-v2-cloudflare:
-    #     runs-on: ubuntu-latest
-    #     name: Browserless Testing v2 (Cloudflare)
-    #     needs: deploy-v2-cloudflare
-    #     steps:
-    #         - name: Checkout
-    #           uses: actions/checkout@v4
-    #         - name: Setup Bun
-    #           uses: ./.github/composite/setup-bun
-    #         - name: Install dependencies
-    #           run: bun install --frozen-lockfile
-    #           env:
-    #               PUPPETEER_SKIP_DOWNLOAD: 1
-    #         - name: Run tests
-    #           run: cd ./packages/gitbook && bun e2e-browserless
-    #           env:
-    #               BASE_URL: ${{needs.deploy-v2-cloudflare.outputs.deployment-url}}
-    #               SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
+                  BASE_URL: ${{needs.deploy-v1-cloudflare.outputs.deployment-url}}
+                  PAGESPEED_API_KEY: ${{ secrets.PAGESPEED_API_KEY }}
@@ -4,7 +4,7 @@ on:
        branches:
            - main
 env:
-    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
+    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
    deploy-v2-vercel:
        name: Deploy v2 to Vercel (production)
@@ -4,7 +4,7 @@ on:
        branches:
            - main
 env:
-    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
+    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
 jobs:
    deploy-v2-vercel:
        name: Deploy v2 to Vercel (staging)
@@ -6,7 +6,7 @@ on:
            - main

 env:
-    BUN_NPM_TOKEN: ${{ secrets.NPM_TOKEN_READONLY }}
+    NPM_TOKEN_READONLY: ${{ secrets.NPM_TOKEN_READONLY }}
    
 concurrency: ${{ github.workflow }}-${{ github.ref }}

@@ -14,38 +14,47 @@ 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
+            - name: Create Release Pull Request or Publish to npm
              id: changesets
              uses: changesets/action@v1
              with:
-                  publish: bun run publish-all-packages
-                  version: bun run changeset-version
+                  publish: npm run release
+                  version: npm 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 }}
+    release-preview:
+        # For now it releases the cache-do to both preview and production
+        # Once we changed to deploy the app only on release, we should change `release:preview` in `cache-do`
+        name: Release Preview
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout Repo
+              uses: actions/checkout@v3
+            - name: Setup Bun
+              uses: ./.github/composite/setup-bun
+            - name: Install dependencies
+              run: bun install --frozen-lockfile
+              env:
+                  PUPPETEER_SKIP_DOWNLOAD: 1
+            - name: Release preview packages
+              run: bun run release:preview
+              env:
+                  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+                  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
@@ -25,7 +25,3 @@ yarn-error.log*

 # TypeScript
 *.tsbuildinfo
-.npmrc
-
-# Bun pack artifacts
-packages/*/*.tgz
@@ -1 +1 @@
-v22.3
+v20.6
@@ -1,7 +1,7 @@
 <h1 align="center">GitBook</h1>

 <p align="center">
-  <a href="https://gitbook.com/docs/">Docs</a> - <a href="https://github.com/GitbookIO/community">Community</a> - <a href="https://developer.gitbook.com/">Developer Docs</a> - <a href="https://changelog.gitbook.com/">Changelog</a> - <a href="https://github.com/GitbookIO/gitbook/issues/new?assignees=&labels=bug&template=bug_report.md">Bug reports</a> - <a href="https://github.com/orgs/GitbookIO/discussions/categories/feature-requests">Feature requests</a> 
+  <a href="https://gitbook.com/docs/">Docs</a> - <a href="https://github.com/GitbookIO/community">Community</a> - <a href="https://developer.gitbook.com/">Developer Docs</a> - <a href="https://changelog.gitbook.com/">Changelog</a> - <a href="https://github.com/GitbookIO/gitbook/issues/new?assignees=&labels=bug&template=bug_report.md">Bug reports</a> 
 </p>

 <p align="center">
@@ -35,10 +35,10 @@ To run a local version of this project, please follow these simple steps.

 ### Prerequisites

- 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
+-   Node.js (Version: >=20.6)
+  - Use nvm for easy Node management
+-   Bun (Version: >=1.2.1)
+  - We use a text-based lockfile which isn't supported below 1.2.1

 ### Set up

@@ -56,13 +56,19 @@ git clone https://github.com/gitbookIO/gitbook.git
 bun install
 ```

-4. Start your local development server.
+4. Run build.

 ```
-bun dev
+bun build:v2
 ```

-6. Open a published GitBook space in your web browser, prefixing it with `http://localhost:3000/url`.
+5. Start your local development server.
+
+```
+bun dev:v2
+```
+
+6. Open a published GitBook space in your web browser, prefixing it with `http://localhost:3000/`.

 examples:

@@ -71,6 +77,11 @@ examples:

 Any published GitBook site can be accessed through your local development instance, and any updates you make to the codebase will be reflected in your browser.

+### Other development commands
+
+-   `bun format`: format the code
+-   `bun lint`: lint the code
+
 ### CI and testing

 All pull-requests will be tested against both visual and performances testing to prevent regressions.
@@ -90,7 +101,7 @@ If you are GitBook staff, you'll need our NPM token in your local environment.
 ```
 .env.local

-BUN_NPM_TOKEN=xxx
+NPM_TOKEN_READONLY=xxx
 ```

 and then reinstall dependencies.
@@ -18,12 +18,10 @@
            "**/.vercel/**/*",
            "**/.cache/**/*",
            "**/.wrangler/**/*",
-            "packages/embed/standalone/**/*",
            "packages/openapi-parser/src/fixtures/**/*",
            "packages/emoji-codepoints/index.ts",
            "packages/icons/src/data/*.json",
-            "packages/gitbook/worker-configuration.d.ts",
-            "**/*.css"
+            "packages/cache-do/worker-configuration.d.ts"
        ]
    },
    "formatter": {
@@ -129,6 +127,7 @@
        {
            "include": [
                "packages/gitbook/**/*",
+                "packages/gitbook-v2/**/*",
                "packages/react-openapi/**/*",
                "packages/react-math/**/*",
                "packages/react-contentkit/**/*",
@@ -1,2 +1,2 @@
 [install.scopes]
-"gitbook" = { token = "$BUN_NPM_TOKEN", url = "https://registry.npmjs.org" }
+"gitbook" = { token = "$NPM_TOKEN_READONLY", url = "https://registry.npmjs.org" }
@@ -1,28 +1,24 @@
 {
    "name": "gitbook",
    "version": "0.1.0",
-    "engines": {
-        "node": "^22.3.0"
-    },
    "devDependencies": {
        "@biomejs/biome": "^1.9.4",
-        "@changesets/cli": "^2.29.7",
-        "turbo": "^2.6.1",
-        "vercel": "^39.4.2"
+        "@changesets/cli": "^2.27.12",
+        "turbo": "^2.5.0",
+        "vercel": "^39.3.0"
    },
-    "packageManager": "bun@1.3.2",
+    "packageManager": "bun@1.2.15",
    "overrides": {
        "@codemirror/state": "6.4.1",
-        "@types/react": "catalog:",
-        "@types/react-dom": "catalog:",
-        "react": "catalog:",
-        "react-dom": "catalog:",
-        "esbuild": "0.24.2"
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
    },
    "private": true,
    "scripts": {
-        "dev": "turbo run dev --concurrency 20",
+        "dev": "turbo run dev",
+        "dev:v2": "turbo run dev:v2",
        "build": "turbo run build",
+        "build:v2": "turbo run build:v2",
        "clean-deps": "rm -rf node_modules && rm -rf packages/*/node_modules",
        "typecheck": "turbo run typecheck",
        "format": "biome check --write ./",
@@ -31,29 +27,16 @@
        "e2e": "turbo run e2e",
        "e2e-customers": "turbo run e2e-customers",
        "changeset": "changeset",
-        "changeset-version": "changeset version && bun run format && bun update",
-        "publish-all-packages": "turbo run publish-to-npm --continue=dependencies-successful",
+        "changeset-version": "changeset version && bun run format",
+        "release": "turbo run release && changeset publish",
+        "release:preview": "turbo run release:preview",
        "download:env": "op read op://gitbook-x-dev/gitbook-open/.env.local >> .env.local",
        "clean": "turbo run clean"
    },
    "workspaces": {
        "packages": ["packages/*"],
        "catalog": {
-            "@tsconfig/strictest": "^2.0.6",
-            "@tsconfig/node20": "^20.1.6",
-            "@gitbook/api": "0.154.0",
-            "@scalar/api-client-react": "^1.3.46",
-            "@types/react": "^19.0.0",
-            "@types/react-dom": "^19.0.0",
-            "assert-never": "^1.4.0",
-            "bidc": "^0.0.2",
-            "bun-types": "^1.1.20",
-            "classnames": "^2.5.1",
-            "react": "^19.0.1",
-            "react-dom": "^19.0.1",
-            "tsdown": "^0.15.6",
-            "typescript": "^5.5.3",
-            "usehooks-ts": "^3.1.1"
+            "@gitbook/api": "^0.120.0"
        }
    },
    "patchedDependencies": {
@@ -1 +0,0 @@
-dist/
@@ -1,37 +0,0 @@
-# @gitbook/browser-types
-
-## 0.1.3
-
-### Patch Changes
-
- 10995e0: Use NPM Trusted publishing for publishing the package.
- Updated dependencies [10995e0]
-  - @gitbook/icons@0.3.4
-
-## 0.1.2
-
-### Patch Changes
-
- 6142d6b: Mark as sideEffects, fix all package bundles
- Updated dependencies [6142d6b]
-  - @gitbook/icons@0.3.3
-
-## 0.1.1
-
-### Patch Changes
-
- 295f03d: Republish packages
- Updated dependencies [295f03d]
-  - @gitbook/icons@0.3.2
-
-## 0.1.0
-
-### Minor Changes
-
- cbc71a5: First version of the public package for typing script integrations.
-
-### Patch Changes
-
- 854c448: Custom assistants followup
- Updated dependencies [25e2b40]
-  - @gitbook/icons@0.3.0
@@ -1,3 +0,0 @@
-# `@gitbook/browser-types`
-
-Typescript types for the global variables available in a GitBook website. These types can be used by integrations embedding scripts.
@@ -1,36 +0,0 @@
-{
-    "name": "@gitbook/browser-types",
-    "description": "Typescript types for the global variables available in a GitBook website. These types can be used by integrations embedding scripts.",
-    "type": "module",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "default": "./dist/index.js"
-        }
-    },
-    "sideEffects": false,
-    "version": "0.1.3",
-    "dependencies": {
-        "@gitbook/api": "catalog:",
-        "@gitbook/icons": "workspace:"
-    },
-    "devDependencies": {
-        "bun-types": "catalog:",
-        "tsdown": "catalog:",
-        "typescript": "catalog:"
-    },
-    "scripts": {
-        "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"],
-    "publishConfig": {
-        "access": "public",
-        "registry": "https://registry.npmjs.org/"
-    },
-    "repository": {
-        "url": "https://github.com/GitbookIO/gitbook"
-    }
-}
@@ -1,84 +0,0 @@
-import type { AIToolCallResult, AIToolDefinition } from '@gitbook/api';
-import type { IconName } from '@gitbook/icons';
-
-export type GitBookIntegrationEvent = 'load' | 'unload';
-
-export type GitBookIntegrationEventCallback = (...args: any[]) => void;
-
-export type GitBookIntegrationTool = AIToolDefinition & {
-    /**
-     * Confirmation action to be displayed to the user before executing the tool.
-     */
-    confirmation?: {
-        icon?: IconName;
-        label: string;
-    };
-
-    /**
-     * Callback when the tool is executed.
-     * The input is provided by the AI assistant following the input schema of the tool.
-     */
-    execute: (input: object) => Promise<Pick<AIToolCallResult, 'output' | 'summary'>>;
-};
-
-export type GitBookAssistant = {
-    /**
-     * Name of the assistant displayed in the UI.
-     */
-    label: string;
-
-    /**
-     * Icon of the assistant displayed in the UI.
-     * Any FontAwesome icon name is supported.
-     * @example 'sparkle'
-     */
-    icon: string;
-
-    /**
-     * Callback when the assistant is opened.
-     */
-    open: (query?: string) => void;
-
-    /**
-     * Whether to display the triggers for this assistant in the UI.
-     * @default true
-     */
-    ui?: boolean;
-};
-
-export type GitBookGlobal = {
-    /**
-     * Register an event listener.
-     */
-    addEventListener: (
-        type: GitBookIntegrationEvent,
-        func: GitBookIntegrationEventCallback
-    ) => void;
-
-    /**
-     * Remove an event listener.
-     */
-    removeEventListener: (
-        type: GitBookIntegrationEvent,
-        func: GitBookIntegrationEventCallback
-    ) => void;
-
-    /**
-     * Register a custom tool to be exposed to the AI assistant.
-     */
-    registerTool: (tool: GitBookIntegrationTool) => void;
-
-    /**
-     * Register a custom assistant to be available on the site.
-     */
-    registerAssistant: (assistant: GitBookAssistant) => () => void;
-};
-
-declare global {
-    interface Window {
-        /**
-         * Global `window.GitBook` object accessible by integrations.
-         */
-        GitBook?: GitBookGlobal;
-    }
-}
@@ -1,25 +0,0 @@
-{
-    "compilerOptions": {
-        "target": "esnext",
-        "lib": ["dom", "dom.iterable", "esnext"],
-        "allowJs": true,
-        "skipLibCheck": true,
-        "strict": true,
-        "noUncheckedIndexedAccess": true,
-        "noEmit": false,
-        "declaration": true,
-        "outDir": "dist",
-        "esModuleInterop": true,
-        "module": "esnext",
-        "moduleResolution": "bundler",
-        "resolveJsonModule": true,
-        "isolatedModules": true,
-        "jsx": "react-jsx",
-        "incremental": true,
-        "types": [
-            "bun-types" // add Bun global
-        ]
-    },
-    "include": ["src/**/*.ts", "src/**/*.tsx"],
-    "exclude": ["node_modules"]
-}
@@ -0,0 +1,3 @@
+.wrangler
+worker-configuration.d.ts
+dist/
@@ -0,0 +1,18 @@
+# @gitbook/cache-do
+
+## 0.1.1
+
+### Patch Changes
+
+-   b7a5106: Disable cloudflare observability in production
+
+## 0.1.0
+
+### Minor Changes
+
+-   9b8d519: Experiment with optimizing billable duration in Cloudflare by using multiple RPC sessions instead of one
+-   636b868: First version of a new cache backend powered by Cloudflare Durable Objects
+
+### Patch Changes
+
+-   56f5fa1: Enable Workers observability with a sampling of 0.1
@@ -0,0 +1,22 @@
+# `@gitbook/cache-do`
+
+Cache backend, powered by Cloudflare Durable Objects. The cache is optimized for GitBook use-cases.
+
+### Performances
+
+The cache backend is optimized for performances by being distributed and accessible close to the worker locations that are reading it.
+
+### Geo-distribution
+
+To achieve a good balance between **performances** and **consistency**, cache objects are distributed over 7 locations, representing continents.
+
+It makes it possible to purge all 7 locations in one go and achieve fast consistency.
+
+### Concepts
+
+**Cache tag**: unique tag in the cache environment. A cache tag groups multiple keys that should be purged together in one operation.
+Cache tags should not contain a large set of unique keys. Exceeding thousands could lead to performances or reliability issues.
+
+**Cache key**: unique key in the cache environment. Each key should be assigned to a `tag`.
+
+**Location**: cache is distributed over 7 unique locations, one for each continent.
@@ -0,0 +1,35 @@
+{
+    "name": "@gitbook/cache-do",
+    "type": "module",
+    "private": true,
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "development": "./src/index.ts",
+            "default": "./dist/index.js"
+        },
+        "./api": {
+            "types": "./dist/api.d.ts",
+            "development": "./src/api.ts",
+            "default": "./dist/api.js"
+        }
+    },
+    "version": "0.1.1",
+    "dependencies": {
+        "@msgpack/msgpack": "^3.0.0-beta2",
+        "lru_map": "^0.4.1"
+    },
+    "devDependencies": {
+        "typescript": "^5.5.3",
+        "wrangler": "^4.10.0"
+    },
+    "scripts": {
+        "generate": "wrangler types",
+        "build": "tsc",
+        "typecheck": "tsc --noEmit",
+        "dev": "tsc -w",
+        "release": "wrangler deploy",
+        "release:preview": "wrangler deploy && wrangler deploy --env preview"
+    },
+    "files": ["dist", "src", "bin", "data", "README.md", "CHANGELOG.md"]
+}
@@ -0,0 +1,292 @@
+import { DurableObject } from 'cloudflare:workers';
+import { decode, encode } from '@msgpack/msgpack';
+import { LRUMap } from 'lru_map';
+
+export interface CacheObjectDescriptor {
+    get: <Value = unknown>(key: string) => Promise<Value | undefined>;
+    set: <Value = unknown>(key: string, value: Value, expiresAt: number) => Promise<void>;
+}
+
+/**
+ * Value stored in a chunked binary msgpack format.
+ * Stored under the key `prop.${key}.${index}`.
+ */
+interface CacheObjectProp<Value = unknown> {
+    value: Value;
+    expiresAt: number;
+}
+
+/**
+ * Expiration clock stored under the key `exp.${expiresAt}.${key}`.
+ */
+interface CacheObjectExp {
+    /** Key of the property */
+    k: string;
+    /** Number of chunks */
+    c: number;
+}
+
+/**
+ * Durable Object class being deployed as a distributed cache.
+ */
+export class CacheObject extends DurableObject {
+    private lru = new LRUMap<string, { match: CacheObjectProp | undefined }>(500);
+
+    /**
+     * Open a descriptor to access the cache object.
+     * The goal is to minimize the amount of RPC sessions between the client and the cache object.
+     * One session is opened per request on the client side and used to perform multiple operations.
+     * https://developers.cloudflare.com/workers/runtime-apis/rpc/#return-functions-from-rpc-methods
+     */
+    public open(): CacheObjectDescriptor {
+        return {
+            get: async <Value = unknown>(key: string) => {
+                return this.get<Value>(key);
+            },
+            set: async <Value = unknown>(key: string, value: Value, expiresAt: number) => {
+                await this.set(key, value, expiresAt);
+            },
+        };
+    }
+
+    /**
+     * Get the value of a property.
+     */
+    public async get<Value = unknown>(key: string) {
+        return this.logOperation({ operation: 'get', key }, async (setLog) => {
+            // Try the memory state first.
+            const memoryEntry = this.lru.get(key);
+            if (memoryEntry) {
+                setLog({ memory: true });
+                setLog({ memoryMatch: !!memoryEntry.match });
+                if (!memoryEntry.match) {
+                    return;
+                }
+
+                const isExpired = memoryEntry.match.expiresAt < Date.now();
+                setLog({ memoryExpired: isExpired });
+
+                if (!isExpired) {
+                    return memoryEntry.match.value as Value;
+                }
+            }
+
+            return await this.getFromStorage<Value>(key);
+        });
+    }
+
+    /**
+     * Get the value of a property from the DO storage.
+     */
+    public async getFromStorage<Value = unknown>(key: string) {
+        return this.logOperation({ operation: 'getFromStorage', key }, async (setLog) => {
+            const entries = await this.ctx.storage.list<Uint8Array>({
+                prefix: getStoragePropKey(key),
+                noCache: true,
+            });
+            if (entries.size) {
+                const entry = decodeChunks<CacheObjectProp<Value>>(entries);
+                setLog({ chunks: entries.size, chunksSize: entry?.size ?? 0 });
+                if (entry && entry.value.expiresAt > Date.now()) {
+                    // Found
+                    this.lru.set(key, { match: entry.value });
+                    return entry.value.value;
+                }
+            }
+
+            // Not found
+            this.lru.set(key, { match: undefined });
+        });
+    }
+
+    /**
+     * Set a value in the cache object.
+     */
+    public async set<Value = unknown>(key: string, value: Value, expiresAt: number) {
+        return this.logOperation({ operation: 'set', key }, async (setLog) => {
+            const prop: CacheObjectProp<Value> = {
+                value,
+                expiresAt,
+            };
+
+            this.lru.set(key, { match: prop });
+            await this.ctx.storage.transaction(async (tx) => {
+                const entries = encodeChunks(key, prop);
+                const chunks = Object.keys(entries).length;
+                setLog({ chunks });
+
+                const clockValue: CacheObjectExp = {
+                    k: key,
+                    c: chunks,
+                };
+
+                await tx.put(getGCClockKey(key, expiresAt), clockValue);
+                await tx.put(entries);
+
+                const currentAlarm = await tx.getAlarm();
+                if (!currentAlarm) {
+                    // Set an alarm to garbage collect all entries that have expired in 12h.
+                    await tx.setAlarm(Date.now() + 12 * 60 * 60 * 1000);
+                }
+            });
+        });
+    }
+
+    /**
+     * Purge all keys in the cache object.
+     */
+    public async purge() {
+        return this.logOperation({ operation: 'purge' }, async (setLog) => {
+            const result = new Set<string>();
+
+            try {
+                // List all the keys in the cache object.
+                const entries = await this.ctx.storage.list<CacheObjectExp>({
+                    prefix: 'exp.',
+                    noCache: true,
+                });
+                setLog({ entries: entries.size });
+                entries.forEach((exp) => {
+                    result.add(exp.k);
+                });
+            } catch (_error) {}
+
+            await this.reset();
+            return Array.from(result);
+        });
+    }
+
+    /**
+     * Alarm to garbage collect all entries that have expired.
+     */
+    async alarm() {
+        return this.logOperation({ operation: 'alarm' }, async (setLog) => {
+            try {
+                const entries = await this.ctx.storage.list<CacheObjectExp>({
+                    prefix: 'exp.',
+                    noCache: true,
+                });
+                setLog({ entries: entries.size });
+                const toDeleteSet = new Set<string>();
+
+                for (const [key, exp] of entries) {
+                    const timestamp = Number.parseInt(key.split('.')[1]);
+                    if (timestamp < Date.now()) {
+                        toDeleteSet.add(key);
+                        for (let i = 0; i < exp.c; i++) {
+                            toDeleteSet.add(getStoragePropChunkKey(exp.k, i));
+                        }
+                    }
+                }
+
+                // Delete the keys by batch of 128.
+                const toDelete = Array.from(toDeleteSet);
+                setLog({ toDelete: toDelete.length });
+                for (let i = 0; i < toDelete.length; i += 128) {
+                    await this.ctx.storage.delete(toDelete.slice(i, i + 128));
+                }
+
+                // If there are still keys to delete, set an alarm to continue the deletion in 12h.
+                if (toDelete.length) {
+                    await this.ctx.storage.setAlarm(Date.now() + 12 * 60 * 60 * 1000);
+                }
+            } catch (_error) {
+                await this.reset();
+            }
+        });
+    }
+
+    /**
+     * Reset the cache object.
+     */
+    async reset() {
+        return this.logOperation({ operation: 'reset' }, async () => {
+            this.lru.clear();
+            await this.ctx.storage.deleteAll();
+        });
+    }
+
+    /**
+     * Time and log an operation.
+     */
+    async logOperation<T>(
+        log: Record<string, unknown>,
+        fn: (update: (log: Record<string, unknown>) => void) => Promise<T>
+    ): Promise<T> {
+        const objectId = this.ctx.id.name ?? this.ctx.id.toString();
+        const update: Record<string, unknown> = {};
+        const start = performance.now();
+        try {
+            return await fn((arg) => {
+                Object.assign(update, arg);
+            });
+        } finally {
+            const duration = performance.now() - start;
+            console.log({ ...log, ...update, objectId, duration });
+        }
+    }
+}
+
+function getStoragePropKey(key: string): string {
+    return `prop.${key}.`;
+}
+
+function getStoragePropChunkKey(key: string, index: number): string {
+    return `${getStoragePropKey(key)}${index}`;
+}
+
+function getGCClockRootKey(timestamp: number): string {
+    return `exp.${timestamp}.`;
+}
+
+function getGCClockKey(key: string, expiresAt: number): string {
+    return `${getGCClockRootKey(expiresAt)}${key}`;
+}
+
+function encodeChunks<T>(key: string, value: T): Record<string, Uint8Array> {
+    const buf = encode(value);
+    const entries: Record<string, Uint8Array> = {};
+    const chunks = chunkUint8Array(buf, 128 * 1024);
+
+    for (let index = 0; index < chunks.length; index++) {
+        entries[getStoragePropChunkKey(key, index)] = chunks[index];
+    }
+
+    return entries;
+}
+
+function decodeChunks<T>(entries: Map<string, Uint8Array>): { value: T; size: number } | undefined {
+    const chunks = Array.from(entries.entries())
+        .map(([key, value]) => {
+            const index = Number.parseInt(key.split('.').pop()!);
+            return [index, value] as const;
+        })
+        .sort(([a], [b]) => a - b)
+        .map(([, value]) => value);
+
+    if (chunks.length === 0) {
+        return;
+    }
+
+    const buf = mergeUint8Array(chunks);
+    return { value: decode(buf) as T, size: buf.length };
+}
+
+function chunkUint8Array(input: Uint8Array, chunkSize: number): Uint8Array[] {
+    const chunks: Uint8Array[] = [];
+    for (let i = 0; i < input.length; i += chunkSize) {
+        chunks.push(input.slice(i, i + chunkSize));
+    }
+    return chunks;
+}
+
+function mergeUint8Array(chunks: Uint8Array[]): Uint8Array {
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}
@@ -0,0 +1,97 @@
+import type { CacheObject } from './CacheObject';
+
+export type CacheLocationId = ContinentCode;
+const allLocations: CacheLocationId[] = ['AF', 'AS', 'NA', 'SA', 'AN', 'EU', 'OC'];
+
+/**
+ * Location hint for the CacheObject durable object.
+ */
+const doLocationHints: {
+    [key in CacheLocationId]: DurableObjectLocationHint;
+} = {
+    AF: 'afr',
+    AS: 'apac',
+    NA: 'wnam',
+    SA: 'sam',
+    AN: 'oc',
+    EU: 'weur',
+    OC: 'oc',
+};
+
+/**
+ * Client to access a cache tag.
+ */
+export class CacheObjectStub {
+    private stub: DurableObjectStub<CacheObject>;
+
+    constructor(
+        /** Binding to the CacheObject durable object */
+        private doNamespace: DurableObjectNamespace<CacheObject>,
+        /** ID of the location to target */
+        private locationId: CacheLocationId,
+        /** Name of the tag */
+        private tag: string
+    ) {
+        const groupId = getCacheObjectIdName(this.locationId, this.tag);
+        this.stub = this.doNamespace.get(this.doNamespace.idFromName(groupId), {
+            // Initialize the object with a locaiton hint,
+            // as we might want to purge all locations before the object is created.
+            // https://developers.cloudflare.com/durable-objects/reference/data-location/
+            locationHint: doLocationHints[this.locationId],
+        });
+    }
+
+    /**
+     * Open a descriptor to the cache object.
+     * It can be used to perform multiple operations in a single RPC session.
+     * Ex:
+     * ```ts
+     * using desc = cache.open();
+     * await desc.set('key', 'value', Date.now() + 1000);
+     * await desc.get('key');
+     * ```
+     */
+    async open() {
+        return await this.stub.open();
+    }
+
+    /**
+     * Get a value from the cache.
+     */
+    async get<Value = unknown>(key: string) {
+        return (await this.stub.get(key)) as Value | undefined;
+    }
+
+    /**
+     * Set a value in the cache.
+     */
+    async set<Value = unknown>(key: string, value: Value, expiresAt: number) {
+        return await this.stub.set(key, value, expiresAt);
+    }
+
+    /**
+     * Purge all keys in the cache tag.
+     */
+    async purge() {
+        const keys = new Set<string>();
+        await Promise.all(
+            allLocations.map(async (locationId) => {
+                const groupId = getCacheObjectIdName(locationId, this.tag);
+                const cacheGroup = this.doNamespace.get(this.doNamespace.idFromName(groupId), {
+                    // Initialize the object with a locaiton hint,
+                    // as we might want to purge all locations before the object is created.
+                    // https://developers.cloudflare.com/durable-objects/reference/data-location/
+                    locationHint: doLocationHints[this.locationId],
+                });
+                const locationkeys = await cacheGroup.purge();
+                locationkeys.forEach((key) => keys.add(key));
+            })
+        );
+
+        return keys;
+    }
+}
+
+function getCacheObjectIdName(locationId: CacheLocationId, tag: string): string {
+    return `${locationId}:${tag}`;
+}
@@ -0,0 +1 @@
+export * from './CacheObjectStub';
@@ -0,0 +1,9 @@
+import { WorkerEntrypoint } from 'cloudflare:workers';
+
+export * from './CacheObject';
+
+export default class Worker extends WorkerEntrypoint {
+    fetch() {
+        return new Response('Hello, world!');
+    }
+}
@@ -13,10 +13,9 @@
        "moduleResolution": "bundler",
        "resolveJsonModule": true,
        "isolatedModules": true,
-        "jsx": "react-jsx",
        "incremental": true,
-        "types": []
+        "types": ["./worker-configuration.d.ts"]
    },
-    "include": ["src/**/*.ts", "src/**/*.tsx"],
+    "include": ["src/**/*.ts"],
    "exclude": ["node_modules"]
 }
@@ -0,0 +1,8 @@
+{
+    "extends": ["//"],
+    "tasks": {
+        "generate": {
+            "outputs": ["worker-configuration.d.ts"]
+        }
+    }
+}
@@ -0,0 +1,27 @@
+main = "./src/index.ts"
+name = "gitbook-open-cache"
+compatibility_date = "2024-09-02"
+
+durable_objects.bindings = [
+  {name = "CACHE", class_name = "CacheObject"}
+]
+
+migrations = [
+  {tag = "v1", new_classes = ["CacheObject"]}
+]
+
+[observability]
+enabled = false
+
+[env.preview]
+name = "gitbook-open-cache-preview"
+durable_objects.bindings = [
+  {name = "CACHE", class_name = "CacheObject"}
+]
+migrations = [
+  {tag = "v1", new_classes = ["CacheObject"]}
+]
+
+[env.preview.observability]
+enabled = true
+head_sampling_rate = 0.1
@@ -1,23 +1,5 @@
 # @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
@@ -4,32 +4,22 @@
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
+            "development": "./src/index.ts",
            "default": "./dist/index.js"
        }
    },
-    "sideEffects": false,
-    "version": "0.3.4",
+    "version": "0.3.1",
    "dependencies": {
        "@gitbook/api": "catalog:",
-        "assert-never": "catalog:"
+        "assert-never": "^1.2.1"
    },
    "devDependencies": {
-        "bun-types": "catalog:",
-        "tsdown": "catalog:",
-        "typescript": "catalog:"
+        "typescript": "^5.5.3"
    },
    "scripts": {
-        "build": "tsdown",
+        "build": "tsc",
        "typecheck": "tsc --noEmit",
-        "dev": "bun run build -- --watch ./src",
-        "publish-to-npm": "../../scripts/publish-if-new.sh"
+        "dev": "tsc -w"
    },
-    "files": ["dist", "README.md", "CHANGELOG.md"],
-    "publishConfig": {
-        "access": "public",
-        "registry": "https://registry.npmjs.org/"
-    },
-    "repository": {
-        "url": "https://github.com/GitbookIO/gitbook"
-    }
+    "files": ["dist", "src", "README.md", "CHANGELOG.md"]
 }
@@ -90,7 +90,7 @@ export function getCacheTag(
        | {
              tag: 'translation';
              organization: string;
-              translation: string;
+              translationSettings: string;
          }
 ): string {
    switch (spec.tag) {
@@ -115,12 +115,23 @@ export function getCacheTag(
        case 'openapi':
            return `organization:${spec.organization}:openapi:${spec.openAPISpec}`;
        case 'translation':
-            return `organization:${spec.organization}:translation:${spec.translation}`;
+            return `organization:${spec.organization}:translation:${spec.translationSettings}`;
        default:
            assertNever(spec);
    }
 }

+/**
+ * Get the cache tag for a given URL.
+ */
+export function getCacheTagForURL(url: string | URL) {
+    const parsedURL = url instanceof URL ? url : new URL(url);
+    return getCacheTag({
+        tag: 'url',
+        hostname: parsedURL.hostname,
+    });
+}
+
 /**
 * Get the tags for a computed content source.
 */
@@ -133,10 +144,6 @@ export function getComputedContentSourceCacheTags(
 ) {
    const tags: string[] = [];

-    if (!('dependencies' in source)) {
-        return tags;
-    }
-
    // We add the dependencies as tags, to ensure that the computed content is invalidated
    // when the dependencies are updated.
    const dependencies = Object.values(source.dependencies ?? {});
@@ -160,18 +167,18 @@ export function getComputedContentSourceCacheTags(
                        })
                    );
                    break;
-                case 'translation':
+                case 'translation-language':
                    tags.push(
                        getCacheTag({
                            tag: 'translation',
                            organization: inContext.organizationId,
-                            translation: dependency.ref.translation,
+                            translationSettings: dependency.ref.translationSettings,
                        })
                    );
                    break;
                default:
                    // Do not throw for unknown dependency types
-                    // as it might mean we are lagging behind the API version
+                    // as it might mean we are lacking behind the API version
                    break;
            }
        });
@@ -187,8 +194,9 @@ export function getComputedContentSourceCacheTags(
    }

    // We invalidate the computed content when a new version of the integration is deployed.
+
    if (source.type.startsWith('integration:')) {
-        const integration = source.type.split(':')[1]!;
+        const integration = source.type.split(':')[1];
        tags.push(
            getCacheTag({
                tag: 'integration',
@@ -5,7 +5,6 @@
        "allowJs": true,
        "skipLibCheck": true,
        "strict": true,
-        "noUncheckedIndexedAccess": true,
        "noEmit": false,
        "declaration": true,
        "outDir": "dist",
@@ -1,33 +1,5 @@
 # @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
-
- 17dd382: Add `original` background color step
-
-### Patch Changes
-
- 193d591: Fix return type for `colorContrast`
-
 ## 0.3.3

 ### Patch Changes
@@ -4,28 +4,18 @@
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
+            "development": "./src/index.ts",
            "default": "./dist/index.js"
        }
    },
-    "sideEffects": false,
-    "version": "0.4.3",
+    "version": "0.3.3",
    "devDependencies": {
-        "bun-types": "catalog:",
-        "tsdown": "catalog:",
-        "typescript": "catalog:"
+        "typescript": "^5.5.3"
    },
    "scripts": {
-        "build": "tsdown",
+        "build": "tsc",
        "typecheck": "tsc --noEmit",
-        "dev": "bun run build -- --watch ./src",
-        "publish-to-npm": "../../scripts/publish-if-new.sh"
+        "dev": "tsc -w"
    },
-    "files": ["dist", "README.md", "CHANGELOG.md"],
-    "publishConfig": {
-        "access": "public",
-        "registry": "https://registry.npmjs.org/"
-    },
-    "repository": {
-        "url": "https://github.com/GitbookIO/gitbook"
-    }
+    "files": ["dist", "src", "README.md", "CHANGELOG.md"]
 }
@@ -8,7 +8,7 @@ type RGBColor = [number, number, number];
 type OKLABColor = { L: number; A: number; B: number };
 type OKLCHColor = { L: number; C: number; H: number };

-const D65 = [95.047, 100.0, 108.883] as const; // Reference white (D65)
+const D65 = [95.047, 100.0, 108.883]; // Reference white (D65)

 export enum ColorCategory {
    backgrounds = 'backgrounds',
@@ -19,7 +19,7 @@ export enum ColorCategory {
 }

 type ColorSubScale = {
-    [key: string]: number | string;
+    [key: string]: number;
 };

 /**
@@ -56,8 +56,6 @@ export const scale: Record<ColorCategory, ColorSubScale> = {
        solid: 9,
        /** Hovered solid backgrounds */
        'solid-hover': 10,
-        /** Original color */
-        original: 'original',
    },
    [ColorCategory.text]: {
        /** Very low-contrast text
@@ -213,8 +211,8 @@ export function colorScale(
    const result = [];

    for (let index = 0; index < mapping.length; index++) {
-        const step = mapping[index]!;
-        const targetL = foregroundColor.L * step + backgroundColor.L * (1 - step);
+        const targetL =
+            foregroundColor.L * mapping[index] + backgroundColor.L * (1 - mapping[index]);

        if (
            index === 8 &&
@@ -297,7 +295,7 @@ export function rgbArrayToHex(rgb: RGBColor): string {

 export function getColor(percentage: number, start: RGBColor, end: RGBColor) {
    const rgb = end.map((channel, index) => {
-        return Math.round(channel + percentage * (start[index]! - channel));
+        return Math.round(channel + percentage * (start[index] - channel));
    });

    return rgbArrayToHex(rgb as RGBColor);
@@ -394,14 +392,14 @@ export function xyzToLab65(xyz: [number, number, number]): {
    B: number;
 } {
    const [x, y, z] = xyz.map((v, i) => {
-        const scaled = v / D65[i]!;
+        const scaled = v / D65[i];
        return scaled > 0.008856 ? Math.cbrt(scaled) : 7.787 * scaled + 16 / 116;
    });

    return {
-        L: 116 * y! - 16,
-        A: 500 * (x! - y!),
-        B: 200 * (y! - z!),
+        L: 116 * y - 16,
+        A: 500 * (x - y),
+        B: 200 * (y - z),
    };
 }

@@ -421,10 +419,7 @@ export function dpsContrast(a: RGBColor, b: RGBColor) {
    return contrast < 7.5 ? 0 : contrast;
 }

-export function colorContrast(
-    background: string,
-    foreground: string[] = [LIGHT_BASE, DARK_BASE]
-): string {
+export function colorContrast(background: string, foreground: string[] = [LIGHT_BASE, DARK_BASE]) {
    const bg = hexToRgbArray(background);

    const best: { color?: RGBColor; contrast: number } = {
@@ -441,5 +436,5 @@ export function colorContrast(
        }
    }

-    return best.color ? rgbArrayToHex(best.color) : foreground[0] || LIGHT_BASE;
+    return best.color ? rgbArrayToHex(best.color) : foreground[0];
 }
@@ -5,7 +5,6 @@
        "allowJs": true,
        "skipLibCheck": true,
        "strict": true,
-        "noUncheckedIndexedAccess": true,
        "noEmit": false,
        "declaration": true,
        "outDir": "dist",
@@ -1,2 +0,0 @@
-dist/
-standalone/
@@ -1,49 +0,0 @@
-# @gitbook/embed
-
-## 0.1.5
-
-### Patch Changes
-
- 10995e0: Use NPM Trusted publishing for publishing the package.
- Updated dependencies [10995e0]
-  - @gitbook/icons@0.3.4
-
-## 0.1.4
-
-### Patch Changes
-
- 6142d6b: Mark as sideEffects, fix all package bundles
- Updated dependencies [6142d6b]
-  - @gitbook/icons@0.3.3
-
-## 0.1.3
-
-### Patch Changes
-
- 295f03d: Republish packages
- Updated dependencies [295f03d]
-  - @gitbook/icons@0.3.2
-
-## 0.1.2
-
-### Patch Changes
-
- 7508674: Fix bundling of packages
-
-## 0.1.1
-
-### Patch Changes
-
- 6f368b5: Fix embed assistant window width on small screens
-
-## 0.1.0
-
-### Minor Changes
-
- 81a6bd7: Improve API to control the GitBook embed
-
-### Patch Changes
-
- 8927e8f: Initial version of the embed SDK.
- Updated dependencies [25e2b40]
-  - @gitbook/icons@0.3.0
@@ -1,411 +0,0 @@
-# GitBook Docs Embed (`@gitbook/embed`)
-
-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 standalone script from your docs site
-
-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 `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: [/* ... */]
-});
-```
-
-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:
-
-```tsx
-import { createGitBook } from '@gitbook/embed';
-
-const gitbook = createGitBook({
-    siteURL: 'https://docs.company.com'
-});
-
-// Create an iframe and get its URL
-const iframe = document.createElement('iframe');
-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: [/* ... */]
-});
-
-// Listen to events
-frame.on('close', () => {
-    console.log('Frame closed');
-});
-```
-
-## As React components
-
-After installing the NPM package, you can import prebuilt React components:
-
-```tsx
-import { GitBookProvider, GitBookFrame } from '@gitbook/embed/react';
-
-<GitBookProvider siteURL="https://docs.company.com">
-    <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={[/* ... */]}
-    />
-</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')[]`
- **Options**:
-  - `['assistant', 'docs']` - Show both tabs
-  - `['assistant']` - Show only the assistant tab
-  - `['docs']` - Show only the docs tab
-
-```javascript
-tabs: ['assistant', 'docs']
-```
-
-### `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'
-}
-```
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Nicolas Dorseuil	8a3fdcfd3c	review fix	2025-06-17 23:19:09 +02:00
Nicolas Dorseuil	a3ddf7d575	fix e2e test	2025-06-17 10:43:16 +02:00
Nicolas Dorseuil	447c6f602f	add toggleable link	2025-06-17 10:03:14 +02:00
Nicolas Dorseuil	71e52f7b0d	add more primitives	2025-06-17 09:44:46 +02:00
Nicolas Dorseuil	6703dae4ea	initial replacement of tailwind class with css modules for client components	2025-06-16 21:46:21 +02:00