Version Packages (#3646 )

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Fix exports in gitbook/expr package.json after removing src (#3648 )
2026-09-16 07:35:16 +00:00 · 2025-09-12 16:40:28 +02:00 · 2025-09-12 16:20:29 +02:00 · 2025-09-12 14:59:47 +02:00 · 2025-09-12 13:19:16 +02:00 · 2025-09-12 11:37:22 +02:00
473 changed files with 21754 additions and 6693 deletions
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix UX issue about highlighting the search term in search result sections
@@ -1,9 +0,0 @@
---
-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
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Respect fullWidth and defaultWidth for images
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Hide scrollbar on sections
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Add docs.testgitbook.com to ADAPTIVE_CONTENT_HOSTS list
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-fix nested a tag causing hydration error
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-fix href being empty in TOC
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix navigation between sections/variants when previewing a site in v2
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Add support for inline icons.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix revision id for computed content
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Add circular corners and depth styling
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix crash when integration script fails to render block.
@@ -1,5 +0,0 @@
---
-'@gitbook/react-openapi': patch
---
-
-Add authorization header for OAuth2
@@ -1,6 +0,0 @@
---
-'@gitbook/react-openapi': patch
-'gitbook': patch
---
-
-Improve support for OAuth2 security type
@@ -1,6 +0,0 @@
---
-gitbook: patch
-gitbook: patch
---
-
-Adds Columns layout block to GBO
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Support dark-mode specific page cover image
@@ -1,5 +0,0 @@
---
-'gitbook': patch
---
-
-Update Models page styling
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Show scrollbars
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Optimize performances by using a smarter per-request cache arround data cached functions
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-add a force-revalidate api route to force bust the cache in case of errors
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Add support for icons in buttons.
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Fix rendering of ogimage with SVG logos.
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Best effort at preserving current variant when navigating between sections by matching the pathname against site spaces in the new section.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix crash when integration is triggering invalid requests.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Optimize the fetch of revision files by using only the getRevision cache.
@@ -1,6 +0,0 @@
---
-gitbook: patch
-gitbook: patch
---
-
-encode customization header
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Rework full-width layout, add support for full-width page option
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix CodeBlock layout
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Scroll to active TOC when clicking a link
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-fix ISR on preview env
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Add support for text alignment for headings and paragraphs.
@@ -1,6 +0,0 @@
---
-gitbook: patch
-gitbook: patch
---
-
-Fix concurrent execution in Vercel causing pages to not be attached to the proper tags.
@@ -1,5 +0,0 @@
---
-"@gitbook/react-contentkit": patch
---
-
-Add basic error handling when transitioning between states.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Generate a llms-full.txt version of the docs site
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Don't crash ogimage generation on RTL text, as a workaround until we can support it.
@@ -1,5 +0,0 @@
---
-gitbook: minor
---
-
-Add support for site customization option to change how external links open.
@@ -1,5 +0,0 @@
---
-"@gitbook/fonts": minor
---
-
-Initial version of the package
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix rendering of ogimage when logo or icon are AVIF images.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Add margin to adjacent buttons
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix ogimage generation failing with some JPEG images.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix page group not expanded by default
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Don't cache unexpected API errors for more than a few minutes.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix an issue where PDF export URLs were not keeping their query params.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-add a global error boundary
@@ -1,5 +0,0 @@
---
-'@gitbook/react-openapi': patch
---
-
-Indent JSON python code sample
@@ -1,6 +0,0 @@
---
-'@gitbook/react-openapi': patch
-'gitbook': patch
---
-
-Handle nullish OpenAPI mediaTypeObject
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix missing title on button to close the announcement banner.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Make icons for page groups more contrasting
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Ignore case while highlighting search results.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Consistently show variant selector in section bar if site has sections
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Make TOC height dynamic based on visible header and footer elements
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Clicking an active TOC item toggles its descendants
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix viewing a page from a revision
@@ -1,6 +0,0 @@
---
-gitbook: patch
-gitbook: patch
---
-
-Fix InlineLinkTooltip having a negative impact on performance, especially on larger pages.
@@ -1,6 +0,0 @@
---
-'@gitbook/openapi-parser': patch
-'@gitbook/react-openapi': patch
---
-
-Optional label in OpenAPI x-codeSamples
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix bold header links hover color
@@ -1,5 +0,0 @@
---
-'gitbook': minor
---
-
-Support external images in cards cover
@@ -1,6 +0,0 @@
---
-gitbook: patch
-gitbook: patch
---
-
-cache fonts and static image used in OGImage in memory
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix border being added to cards
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Add metadata for adding site to Apple devices home
@@ -1,5 +0,0 @@
---
-'@gitbook/react-openapi': patch
---
-
-Handle nested deprecated properties in generateSchemaExample
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix crash during rendering of ogimage for VA sites with default icon.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Add `urlObject.hash` to `linker.toLinkForContent` to pass through URL fragment identifiers, used in search
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Allow to zoom images on mobile if relevant
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-apply customization for dynamic context
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Reverse order of feedback smileys
@@ -1,5 +0,0 @@
---
-'@gitbook/react-openapi': patch
---
-
-Deduplicate path parameters from OpenAPI spec
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-Fix ogimage using incorrect Google Font depending on language.
@@ -1,5 +0,0 @@
---
-gitbook: patch
---
-
-remove trailing slash from linker
@@ -1,37 +0,0 @@
-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
@@ -102,7 +102,7 @@ jobs:
        runs-on: ubuntu-latest
        name: Visual Testing v2
        needs: deploy-v2-vercel
-        timeout-minutes: 10
+        timeout-minutes: 15
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -110,8 +110,8 @@ jobs:
              uses: ./.github/composite/setup-bun
            - name: Install dependencies
              run: bun install --frozen-lockfile
-            - name: Setup Playwright
-              uses: ./.github/actions/setup-playwright
+              env:
+                  PUPPETEER_SKIP_DOWNLOAD: 1
            - name: Run Playwright tests
              run: bun e2e
              env:
@@ -123,7 +123,7 @@ jobs:
        runs-on: ubuntu-latest
        name: Visual Testing v2 (Cloudflare)
        needs: deploy-v2-cloudflare
-        timeout-minutes: 10
+        timeout-minutes: 15
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -131,8 +131,8 @@ jobs:
              uses: ./.github/composite/setup-bun
            - name: Install dependencies
              run: bun install --frozen-lockfile
-            - name: Setup Playwright
-              uses: ./.github/actions/setup-playwright
+              env:
+                  PUPPETEER_SKIP_DOWNLOAD: 1
            - name: Run Playwright tests
              run: bun e2e
              env:
@@ -144,7 +144,7 @@ jobs:
        runs-on: ubuntu-latest
        name: Visual Testing Customers v2
        needs: deploy-v2-vercel
-        timeout-minutes: 10
+        timeout-minutes: 15
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -152,8 +152,8 @@ jobs:
              uses: ./.github/composite/setup-bun
            - name: Install dependencies
              run: bun install --frozen-lockfile
-            - name: Setup Playwright
-              uses: ./.github/actions/setup-playwright
+              env:
+                  PUPPETEER_SKIP_DOWNLOAD: 1
            - name: Run Playwright tests
              run: bun e2e-customers
              env:
@@ -165,7 +165,7 @@ jobs:
        runs-on: ubuntu-latest
        name: Visual Testing Customers v2 (Cloudflare)
        needs: deploy-v2-cloudflare
-        timeout-minutes: 10
+        timeout-minutes: 15
        steps:
            - name: Checkout
              uses: actions/checkout@v4
@@ -173,8 +173,8 @@ jobs:
              uses: ./.github/composite/setup-bun
            - name: Install dependencies
              run: bun install --frozen-lockfile
-            - name: Setup Playwright
-              uses: ./.github/actions/setup-playwright
+              env:
+                  PUPPETEER_SKIP_DOWNLOAD: 1
            - name: Run Playwright tests
              run: bun e2e-customers
              env:
@@ -182,9 +182,9 @@ jobs:
                  SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
                  ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
                  ARGOS_BUILD_NAME: 'customers-v2'
-    pagespeed-testing-v2:
+    browserless-testing-v2-vercel:
        runs-on: ubuntu-latest
-        name: PageSpeed Testing v1
+        name: Browserless Testing v2 (Vercel)
        needs: deploy-v2-vercel
        steps:
            - name: Checkout
@@ -195,8 +195,26 @@ jobs:
              run: bun install --frozen-lockfile
              env:
                  PUPPETEER_SKIP_DOWNLOAD: 1
-            - name: Run pagespeed tests
-              run: bun ./packages/gitbook/tests/pagespeed-testing.ts
+            - name: Run tests
+              run: cd ./packages/gitbook && bun e2e-browserless
              env:
                  BASE_URL: ${{needs.deploy-v2-vercel.outputs.deployment-url}}
-                  PAGESPEED_API_KEY: ${{ secrets.PAGESPEED_API_KEY }}
+                  SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
+    # browserless-testing-v2-cloudflare:
+    #     runs-on: ubuntu-latest
+    #     name: Browserless Testing v2 (Cloudflare)
+    #     needs: deploy-v2-cloudflare
+    #     steps:
+    #         - name: Checkout
+    #           uses: actions/checkout@v4
+    #         - name: Setup Bun
+    #           uses: ./.github/composite/setup-bun
+    #         - name: Install dependencies
+    #           run: bun install --frozen-lockfile
+    #           env:
+    #               PUPPETEER_SKIP_DOWNLOAD: 1
+    #         - name: Run tests
+    #           run: cd ./packages/gitbook && bun e2e-browserless
+    #           env:
+    #               BASE_URL: ${{needs.deploy-v2-cloudflare.outputs.deployment-url}}
+    #               SITE_BASE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/
@@ -35,10 +35,10 @@ To run a local version of this project, please follow these simple steps.

 ### Prerequisites

-   Node.js (Version: >=20.6)
+- 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
+- [Bun](https://bun.sh/) (Version: >=1.2.15)
+  - We use a text-based lockfile which isn't supported below 1.2.15

 ### Set up

@@ -18,10 +18,12 @@
            "**/.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"
+            "packages/gitbook/worker-configuration.d.ts",
+            "**/*.css"
        ]
    },
    "formatter": {
@@ -34,7 +34,8 @@
    "workspaces": {
        "packages": ["packages/*"],
        "catalog": {
-            "@gitbook/api": "^0.123.0"
+            "@gitbook/api": "^0.141.0",
+            "bidc": "^0.0.2"
        }
    },
    "patchedDependencies": {
@@ -0,0 +1 @@
+dist/
@@ -0,0 +1,13 @@
+# @gitbook/browser-types
+
+## 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
@@ -0,0 +1,3 @@
+# `@gitbook/browser-types`
+
+Typescript types for the global variables available in a GitBook website. These types can be used by integrations embedding scripts.
@@ -0,0 +1,24 @@
+{
+    "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"
+        }
+    },
+    "version": "0.1.0",
+    "dependencies": {
+        "@gitbook/api": "catalog:",
+        "@gitbook/icons": "workspace:"
+    },
+    "devDependencies": {
+        "typescript": "^5.5.3"
+    },
+    "scripts": {
+        "build": "tsc",
+        "typecheck": "tsc --noEmit"
+    },
+    "files": ["dist", "README.md", "CHANGELOG.md"]
+}
@@ -0,0 +1,84 @@
+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;
+    }
+}
@@ -0,0 +1,25 @@
+{
+    "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"]
+}
@@ -90,7 +90,7 @@ export function getCacheTag(
        | {
              tag: 'translation';
              organization: string;
-              translationSettings: string;
+              translation: string;
          }
 ): string {
    switch (spec.tag) {
@@ -115,23 +115,12 @@ export function getCacheTag(
        case 'openapi':
            return `organization:${spec.organization}:openapi:${spec.openAPISpec}`;
        case 'translation':
-            return `organization:${spec.organization}:translation:${spec.translationSettings}`;
+            return `organization:${spec.organization}:translation:${spec.translation}`;
        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.
 */
@@ -144,6 +133,10 @@ 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 ?? {});
@@ -167,18 +160,18 @@ export function getComputedContentSourceCacheTags(
                        })
                    );
                    break;
-                case 'translation-language':
+                case 'translation':
                    tags.push(
                        getCacheTag({
                            tag: 'translation',
                            organization: inContext.organizationId,
-                            translationSettings: dependency.ref.translationSettings,
+                            translation: dependency.ref.translation,
                        })
                    );
                    break;
                default:
                    // Do not throw for unknown dependency types
-                    // as it might mean we are lacking behind the API version
+                    // as it might mean we are lagging behind the API version
                    break;
            }
        });
@@ -194,9 +187,8 @@ 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,6 +5,7 @@
        "allowJs": true,
        "skipLibCheck": true,
        "strict": true,
+        "noUncheckedIndexedAccess": true,
        "noEmit": false,
        "declaration": true,
        "outDir": "dist",
@@ -1,5 +1,15 @@
 # @gitbook/colors

+## 0.4.0
+
+### Minor Changes
+
+- 17dd382: Add `original` background color step
+
+### Patch Changes
+
+- 193d591: Fix return type for `colorContrast`
+
 ## 0.3.3

 ### Patch Changes
@@ -8,7 +8,7 @@
            "default": "./dist/index.js"
        }
    },
-    "version": "0.3.3",
+    "version": "0.4.0",
    "devDependencies": {
        "typescript": "^5.5.3"
    },
@@ -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]; // Reference white (D65)
+const D65 = [95.047, 100.0, 108.883] as const; // Reference white (D65)

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

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

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

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

        if (
            index === 8 &&
@@ -295,7 +297,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);
@@ -392,14 +394,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!),
    };
 }

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

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

    const best: { color?: RGBColor; contrast: number } = {
@@ -436,5 +441,5 @@ export function colorContrast(background: string, foreground: string[] = [LIGHT_
        }
    }

-    return best.color ? rgbArrayToHex(best.color) : foreground[0];
+    return best.color ? rgbArrayToHex(best.color) : foreground[0] || LIGHT_BASE;
 }
@@ -5,6 +5,7 @@
        "allowJs": true,
        "skipLibCheck": true,
        "strict": true,
+        "noUncheckedIndexedAccess": true,
        "noEmit": false,
        "declaration": true,
        "outDir": "dist",
@@ -0,0 +1,2 @@
+dist/
+standalone/
@@ -0,0 +1,19 @@
+# @gitbook/embed
+
+## 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
@@ -0,0 +1,49 @@
+# `@gitbook/embed`
+
+Embed the GitBook Docs Assistant in your product or website.
+
+# Usage
+
+## As a script from your docs site
+
+All GitBook docs site includes a script to easily embed the docs assistant 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.
+
+```html
+<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
+<script>
+window.GitBook('show');
+</script>
+```
+
+## 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'
+});
+
+const iframe = document.createElement('iframe');
+iframe.src = gitbook.getFrameURL();
+
+const frame = gitbook.createFrame(iframe);
+```
+
+## As React components
+
+After installing the NPM package, you can import prebuilt React components:
+
+```tsx
+import { GitBookProvider, GitBookAssistantFrame } from '@gitbook/embed/react';
+
+<GitBookProvider siteURL="https://docs.company.com">
+    <GitBookAssistantFrame />
+</GitBookProvider>
+```
@@ -0,0 +1,31 @@
+{
+    "name": "@gitbook/embed",
+    "description": "Embeddable components for GitBook",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js",
+            "standalone": "./dist/standalone/index.js",
+            "react": "./dist/react/index.js"
+        }
+    },
+    "version": "0.1.1",
+    "dependencies": {
+        "@gitbook/api": "catalog:",
+        "@gitbook/icons": "workspace:",
+        "bidc": "catalog:"
+    },
+    "peerDependencies": {
+        "react": "^18.0.0"
+    },
+    "devDependencies": {
+        "typescript": "^5.5.3",
+        "react": "^19.0.0"
+    },
+    "scripts": {
+        "build": "tsc && bun build src/standalone/index.ts --bundle --minify --outdir=standalone",
+        "typecheck": "tsc --noEmit"
+    },
+    "files": ["dist", "README.md", "CHANGELOG.md", "standalone"]
+}
@@ -0,0 +1,61 @@
+import { type GitBookFrameClient, createGitBookFrame } from './createGitBookFrame';
+
+export type CreateGitBookOptions = {
+    /**
+     * URL of the GitBook site to embed.
+     */
+    siteURL: string;
+};
+
+export type GetFrameURLOptions = {
+    /**
+     * Authentication to use for the frame.
+     */
+    visitor?: {
+        /**
+         * Signed JWT token for Adaptive Content or Visitor Authentication to use.
+         */
+        token?: string;
+
+        /**
+         * Unsigned claims to pass to the frame.
+         * You can use these claims in dynamic expressions using `visitor.claims.unsigned.<claim-name>`.
+         */
+        unsignedClaims?: Record<string, unknown>;
+    };
+};
+
+export type GitBookClient = {
+    /**
+     * Get the URL for a GitBook frame.
+     */
+    getFrameURL: (options: GetFrameURLOptions) => string;
+    /**
+     * Create a new GitBook frame.
+     */
+    createFrame: (iframe: HTMLIFrameElement) => GitBookFrameClient;
+};
+
+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`;
+
+            if (frameOptions.visitor?.token) {
+                url.searchParams.set('token', frameOptions.visitor.token);
+            }
+
+            if (frameOptions.visitor?.unsignedClaims) {
+                Object.entries(frameOptions.visitor.unsignedClaims).forEach(([key, value]) => {
+                    url.searchParams.set(`visitor.${key}`, String(value));
+                });
+            }
+
+            return url.toString();
+        },
+        createFrame: (iframe) => createGitBookFrame(iframe),
+    };
+
+    return client;
+}
@@ -0,0 +1,98 @@
+import { createChannel } from 'bidc';
+import type {
+    FrameToParentMessage,
+    GitBookEmbeddableConfiguration,
+    ParentToFrameMessage,
+} from './protocol';
+
+export type GitBookFrameClient = {
+    /**
+     * Navigate to a page by its path.
+     */
+    navigateToPage: (path: string) => void;
+
+    /**
+     * Navigate to the assistant.
+     */
+    navigateToAssistant: () => void;
+
+    /**
+     * Post a message to the chat.
+     */
+    postUserMessage: (message: string) => void;
+
+    /**
+     * Clear the chat.
+     */
+    clearChat: () => void;
+
+    /**
+     * Set the placeholder settings.
+     */
+    configure: (settings: Partial<GitBookEmbeddableConfiguration>) => void;
+
+    /**
+     * Register an event listener.
+     */
+    on: (event: string, listener: (...args: any[]) => void) => () => void;
+};
+
+/**
+ * Create a client to communicate with the GitBook Assistant frame.
+ */
+export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClient {
+    if (!iframe.contentWindow) {
+        throw new Error('Iframe must have a content window');
+    }
+    const channel = createChannel(iframe.contentWindow);
+
+    channel.receive((message: FrameToParentMessage) => {
+        console.log('[gitbook:embed] received message', message);
+        if (message.type === 'close') {
+            const listeners = events.get('close') || [];
+            if (listeners) {
+                listeners.forEach((listener) => listener());
+            }
+        }
+    });
+
+    const sendToFrame = (message: ParentToFrameMessage) => {
+        console.log('[gitbook:embed] send message', message);
+        channel.send(message);
+    };
+
+    const events = new Map<string, Array<(...args: any[]) => void>>();
+
+    const configuration: GitBookEmbeddableConfiguration = {
+        buttons: [],
+        welcomeMessage: '',
+        suggestions: [],
+        tools: [],
+    };
+
+    return {
+        navigateToPage: (pagePath) => {
+            sendToFrame({ type: 'navigateToPage', pagePath });
+        },
+        navigateToAssistant: () => {
+            sendToFrame({ type: 'navigateToAssistant' });
+        },
+        postUserMessage: (message) => sendToFrame({ type: 'postUserMessage', message }),
+        configure: (settings) => {
+            Object.assign(configuration, settings);
+            sendToFrame({ type: 'configure', settings: configuration });
+        },
+        clearChat: () => sendToFrame({ type: 'clearChat' }),
+        on: (event, listener) => {
+            const listeners = events.get(event) || [];
+            listeners.push(listener);
+            events.set(event, listeners);
+            return () => {
+                events.set(
+                    event,
+                    listeners.filter((l) => l !== listener)
+                );
+            };
+        },
+    };
+}
@@ -0,0 +1,3 @@
+export * from './createGitBook';
+export * from './createGitBookFrame';
+export * from './protocol';
@@ -0,0 +1,90 @@
+import type { AIToolCallResult, AIToolDefinition } from '@gitbook/api';
+import type { IconName } from '@gitbook/icons';
+
+/**
+ * Custom tool definition to be passed to the AI assistant.
+ */
+export type GitBookToolDefinition = 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'>>;
+};
+
+/**
+ * Custom button definition to be passed to the embeddable GitBook.
+ */
+export type GitBookEmbeddableButtonDefinition = {
+    /**
+     * Icon to be displayed in the button.
+     */
+    icon: IconName;
+
+    /**
+     * Label to be displayed in the button.
+     */
+    label: string;
+
+    /**
+     * Callback when the button is clicked.
+     */
+    onClick: () => void | Promise<void>;
+};
+
+/**
+ * Overall configuration for the layout of the embeddable GitBook.
+ */
+export type GitBookEmbeddableConfiguration = {
+    /**
+     * Buttons to be displayed in the header of the embeddable GitBook.
+     */
+    buttons: GitBookEmbeddableButtonDefinition[];
+
+    /** Message to be displayed in the welcome page. */
+    welcomeMessage: string;
+
+    /** Suggestions of questions to be displayed in the welcome page. */
+    suggestions: string[];
+
+    /** Tools to be provided to the assistant. */
+    tools: GitBookToolDefinition[];
+};
+
+/**
+ * Messages sent from the parent to the frame.
+ */
+export type ParentToFrameMessage =
+    | {
+          type: 'postUserMessage';
+          message: string;
+      }
+    | {
+          type: 'clearChat';
+      }
+    | {
+          type: 'configure';
+          settings: GitBookEmbeddableConfiguration;
+      }
+    | {
+          type: 'navigateToPage';
+          pagePath: string;
+      }
+    | {
+          type: 'navigateToAssistant';
+      };
+
+/**
+ * Messages sent from the frame to the parent.
+ */
+export type FrameToParentMessage = {
+    type: 'close';
+};
@@ -0,0 +1 @@
+export * from './client';
@@ -0,0 +1,51 @@
+import React from 'react';
+import type {
+    GetFrameURLOptions,
+    GitBookEmbeddableConfiguration,
+    GitBookFrameClient,
+} from '../client';
+import { useGitBook } from './GitBookProvider';
+
+export type GitBookFrameProps = {
+    className?: string;
+} & GetFrameURLOptions &
+    GitBookEmbeddableConfiguration;
+
+/**
+ * Render a frame with the GitBook Assistant in it.
+ */
+export function GitBookFrame(props: GitBookFrameProps) {
+    const { className, visitor, buttons, welcomeMessage, suggestions, tools } = props;
+
+    const frameRef = React.useRef<HTMLIFrameElement>(null);
+    const gitbook = useGitBook();
+    const [gitbookFrame, setGitbookFrame] = React.useState<GitBookFrameClient | null>(null);
+
+    const frameURL = React.useMemo(() => gitbook.getFrameURL({ visitor }), [gitbook, visitor]);
+
+    React.useEffect(() => {
+        if (frameRef.current) {
+            setGitbookFrame(gitbook.createFrame(frameRef.current));
+        }
+    }, [gitbook]);
+
+    React.useEffect(() => {
+        gitbookFrame?.configure({
+            buttons,
+            welcomeMessage,
+            suggestions,
+            tools,
+        });
+    }, [gitbookFrame, buttons, welcomeMessage, suggestions, tools]);
+
+    return (
+        <iframe
+            title="GitBook"
+            ref={frameRef}
+            src={frameURL}
+            width="100%"
+            height="100%"
+            className={className}
+        />
+    );
+}
@@ -0,0 +1,36 @@
+'use client';
+
+import * as React from 'react';
+import { type CreateGitBookOptions, createGitBook } from '../client';
+import { GitBookContext } from './context';
+
+/**
+ * Provider for the GitBook client.
+ */
+export function GitBookProvider(props: React.PropsWithChildren<CreateGitBookOptions>) {
+    const { siteURL, children } = props;
+
+    const options = React.useMemo(
+        () => ({
+            siteURL,
+        }),
+        [siteURL]
+    );
+
+    const client = React.useMemo(() => createGitBook(options), [options]);
+
+    return <GitBookContext.Provider value={client}>{children}</GitBookContext.Provider>;
+}
+
+/**
+ * Hook to access the GitBook client.
+ */
+export function useGitBook() {
+    const context = React.useContext(GitBookContext);
+
+    if (!context) {
+        throw new Error('This component must be used within a <GitBookProvider />');
+    }
+
+    return context;
+}
@@ -0,0 +1,6 @@
+'use client';
+
+import * as React from 'react';
+import type { GitBookClient } from '../client';
+
+export const GitBookContext = React.createContext<GitBookClient | null>(null);
@@ -0,0 +1,2 @@
+export * from './GitBookProvider';
+export * from './GitBookFrame';
--- a/Show More
+++ b/Show More