Format

Load the AI assistant's streaming engine and tools on first use (RND-13530)
Follow site redirects in MCP getPage (RND-13551) (#4715 )
2026-10-29 16:47:01 +00:00 · 2026-10-28 20:04:09 +00:00 · 2026-10-28 20:02:36 +00:00 · 2026-10-28 18:46:59 +01:00 · 2026-10-28 16:55:21 +01:00 · 2026-10-28 14:25:00 +00:00
493 changed files with 22006 additions and 6017 deletions
@@ -0,0 +1,48 @@
+---
+name: write-pr-description
+description: Write a concise, product-focused PR description from the changes and available discussion. Use when asked for a PR summary or description.
+---
+
+# Write a PR description
+
+Read the full branch diff and commit history against the PR's base branch, not just the latest commit. Use the PR discussion and linked issues for context when available. The PR's changes are the source of truth for what ships if an issue describes something different.
+
+Write for contributors and reviewers who may not know the area. Lead with what changes, prefer user or product impact when supported, and include implementation details only when they help review. Keep the proposed changes short, using bullets only when useful.
+
+Include relevant validation and screenshots when available. Do not claim checks passed unless they ran. Use only information appropriate for a public repository; do not copy private issue details or customer information into the description.
+
+## Template and changelog
+
+Read `.github/pull_request_template.md` immediately before writing. Preserve its required section names and order. Include `Proposed changes` and `Changelog`; omit `Demo` when there is nothing to show. Add optional `Context` before `Changelog` only when it meets the rule below.
+
+Write a short changelog entry describing what shipped. Use `[Feature]` for user-facing additions or improvements, `[Fix]` for user-facing bug fixes, and `[Chore]` for internal maintenance. For features and fixes, say what users can do or what no longer goes wrong in plain words. Keep chores useful to teammates without inventing user impact. Remove unused examples and placeholders. Usually one entry is enough; use more only for distinct changes. The PR changelog does not replace any changeset required by `AGENTS.md`.
+
+## Optional context
+
+Write `Proposed changes` and `Changelog` first. Add `Context` only when it tells someone unfamiliar with the area something material that the changelog does not. `Problem` names a concrete failure or limitation supported by the PR or discussion. `Outcome` names what this PR delivers at its actual scope. Omit the section if either field would repeat the changelog, describe only implementation, or guess at an impact.
+
+```markdown
+## Context
+
+**Problem:** <concrete failure or limitation>
+
+**Outcome:** <result delivered by this PR>
+```
+
+Keep each field to 1–2 short, non-technical sentences. Prefer user or product impact when supported. For infrastructure changes, explain the failure or limitation they caused. Do not invent an actor, customer segment, ownership, or impact, or force the change into a user story. Do not turn a preparatory change into a claim that the whole workflow is fixed. Keep the roles distinct: `Context` explains why this matters, `Changelog` says what shipped, and `Proposed changes` can explain implementation.
+
+Examples:
+
+- A dependency bump with no demonstrated user effect needs no `Context`.
+- If creating the first change request leaves the user on an empty screen, say that it now opens after creation. Leave the animation-listener details in `Proposed changes`.
+- If a PR indexes links for later checks, describe the indexing result. Do not claim every link has already been checked.
+
+## Writing pass
+
+- Use plain words and direct verbs: "use" instead of "leverage", "help" instead of "facilitate". Prefer active voice when the actor is known.
+- Name the concrete behavior instead of saying "improves the experience" or "makes it more robust". Support performance claims with measurements.
+- Cut filler, promotional language, and generic conclusions. If a sentence could fit almost any PR, make it specific or delete it.
+- Keep one idea per sentence and use consistent names. Remove redundant hedging without hiding real uncertainty.
+- Avoid "not just X, but Y", forced groups of three, em dashes, decorative emojis, and unnecessary bold text.
+
+Return the description in a Markdown code block unless asked to update the PR. When asked to update it, apply the description with `gh pr edit` using a body file.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix "View activity" disclosure in AI Chat not opening after the Base UI migration.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Scroll to an in-page heading even when the URL hash is unchanged (e.g. clicking the same anchor again).
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Force software rendering (SwiftShader) in Playwright Chromium to eliminate image downscaling drift between GPU-equipped local runs and headless CI runs in Argos screenshots.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add an assistant tool to rate its own previous response when the user reacts to it.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add an assistant tool to submit feedback about the current page on behalf of the user.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Assistant: you can now send follow-up questions while an answer is still being written. Each one appears as your own message with a "Queued" badge (hover for when it will send, × to cancel), and they're sent automatically one at a time as each answer completes.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Keep the breadcrumbs from covering the page actions' hit area.
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Bump Next.js to 16.4.3, keeping the dev-mode OOM patch.
@@ -1,5 +0,0 @@
---
-"gitbook": minor
---
-
-Add a carousel layout option to cards blocks, rendering them as a horizontally-scrolling, scroll-snapping row instead of a wrapping grid.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Assistant: the "Explored briefly" activity heading no longer appears when there's nothing to show. It now renders only when the answer is preceded by a real preamble or one or more tool calls, so a simple answer with an empty reasoning step no longer surfaces an empty collapsible.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix host action buttons in the Docs Embed not reaching the assistant.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix the docs embed `navigateToPage` API on multi-space sites. Deep-linking to a page in a different space/section (e.g. `navigateToPage('/help-center/integrations')`) previously 404'd because the section base was not placed before `~gitbook/embed/page`. The target is now resolved to its space server-side, so pages in any space resolve correctly. The input accepts the page path, an absolute path, or the full published URL.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix suggested question clicks in the embed search not opening the assistant.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix switching from the Search tab to the Docs or Assistant tab in the embed doing nothing.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add configurable default visibility to Prompt block
@@ -1,6 +0,0 @@
---
-"@gitbook/colors": patch
-"gitbook": patch
---
-
-A near-white tint color (e.g. a warm `#F5F3EF`) is now taken as the exact page background, mirroring the existing behavior for near-black tints. The tint's exact lightness, hue and chroma are preserved, and the color is anchored to whichever scale step the active theme renders as the background — so it matches exactly on `muted` (which uses the second step) as well as `clean`. This applies only to near-neutral tints that are light enough to read as a background; saturated or merely light-ish colors keep their normal accent scale. The `bold` theme is unaffected: it already uses the tint for the header and stays intentionally two-tone.
@@ -1,7 +0,0 @@
---
-"gitbook": patch
---
-
-Introduce client-side content selection (`select`): a site-wide, recency-ordered list of selected slugs, persisted in localStorage and shareable via `?select=`, applied to `<html>` before first paint so the right variant renders with no flash. All variants stay server-rendered, so pages are byte-identical for every visitor (no cache impact).
-
-Tabs now use it: switching a tab activates its slug, and every tab group offering that slug follows, across pages. Tabs no longer write to the URL fragment (`#` returns to anchors only); deep-links into a tab still activate and scroll to it.
@@ -1,7 +0,0 @@
---
-"@gitbook/openapi-parser": patch
-"@gitbook/react-openapi": patch
-"gitbook": patch
---
-
-Add missing link reference to OpenAPI models
@@ -1,5 +0,0 @@
---
-'gitbook': patch
---
-
-Update the URL hash when a tab is selected, so a copied link scrolls back to that tab
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add cover image background mode and masks
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Button blocks now respect the `size` option, so you can render small, medium, or large buttons.
@@ -1,7 +0,0 @@
---
-"@gitbook/browser-types": patch
-"@gitbook/embed": patch
-"gitbook": patch
---
-
-Add an optional `context` property (string, up to 512 characters) to the `confirmation` of custom AI tools, shown above the confirmation dialog to help the user understand what they are approving or rejecting. The `confirmation` can now also be a function that receives the AI-provided input and returns the confirmation, so the context can be derived dynamically from the arguments the tool is about to run with. Available both to integrations (`GitBookIntegrationTool`) and to embed consumers (`GitBookToolDefinition`).
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Lazy-load the Mermaid code block so pages that have code blocks but no diagram no longer ship its rendering dependencies.
@@ -1,8 +0,0 @@
---
-"@gitbook/react-openapi": major
-"gitbook": patch
---
-
-Lazy load the Scalar API client modal and stop preloading the Scalar runtime. The modal is now code-split into its own chunk, fetched in parallel with the runtime only when a reader clicks "Test it", and a spinner is shown on the button until the client opens.
-
-Breaking: the package no longer ships the modal in its main entry — consumers must serve the emitted `ScalarApiModal` chunk and use a bundler that supports dynamic `import()`, and the Scalar runtime is no longer preloaded on page load. The internal `preloadScalarRuntime` helper is removed.
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Split llms-full.txt into parts by size so large sites no longer fail with "content too large"
@@ -1,5 +0,0 @@
---
-"gitbook": minor
---
-
-Add an `askQuestion` tool to the site MCP server. Alongside `searchDocumentation` and `getPage`, MCP clients can now ask a natural-language question and get a synthesized answer with links to the source pages, powered by the same AI search backend as the site's "ask a question" experience. The tool accepts an optional `goal` param so calling agents can attach the intent they're trying to accomplish, which tailors the answer and is tracked in analytics. The tool is only exposed on sites that have AI enabled.
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Follow site and space redirects when the MCP getPage tool resolves a page URL.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Submit `sendFeedback` MCP tool findings through the dedicated `submitSiteAgentFeedback` API endpoint. The `pageUrl` is now required and an optional `goal` can be provided.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Mermaid diagrams no longer hijack page scrolling: zooming with the wheel now requires holding Ctrl/Cmd inline, while the fullscreen view keeps free wheel zoom.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Migrate the headless UI primitives from Radix and react-aria to Base UI.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Persist content selection (tabs and other `select` blocks) in localStorage only, dropping the `?select=` query parameter from the URL. A tab click still writes the tab's hash, so a copied URL lands on that tab and reactivates it on load.
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Let analytics tools like GA4 track outbound link clicks by using native link navigation.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Serve `X-Robots-Tag: noindex` on internal search/assistant URLs (`?q=` / `?ask=`) and stop disallowing them in robots.txt, so Google can crawl the directive and drop them from the index instead of reporting "Indexed, though blocked by robots.txt".
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix the variant switcher linking to the wrong URL for non-default variants of the default section
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add an "On this page" table of contents on OpenAPI models pages. Each model in a grouped/multi-model "Models" section is now listed as its own section, matching operations and webhooks.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Improve cookie handling in the OpenAPI "Test it" request proxy.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Serve the OpenAPI "Test it" request proxy from GitBook's own domain.
@@ -1,6 +0,0 @@
---
-"gitbook": patch
-"@gitbook/react-openapi": minor
---
-
-Keep the OpenAPI renderer out of the initial bundle of pages that have no OpenAPI block, by building its context on the client behind a dynamic boundary.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix OpenAPI webhook payload and schema example panels being clipped instead of scrollable.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Align the Previous page navigation button to the left edge and the Next button to the right edge, including when only one of them is present.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix text disappearing in Firefox and iOS Safari on pages with a background cover
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Render a site-space custom home page at its placement root while preserving the full space and normal page URLs.
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Resolve the published content with the full URL in a single lookup and always send the visitor country.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Remove GBO's redundant re-selection of the best-scoring search section. The search API now returns a single highest-scoring section per page (and orders sections highest-score-first), so GBO no longer needs its own `getBestScoredResult` helper to pick the best section for the search and MCP previews. No user-visible change.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix the docs embed not applying `?theme=light`/`?theme=dark`. The theme was dropped when the embed redirected to its default tab, and the embed tabs couldn't read it because they render statically (their request headers are empty). The middleware now threads a forced embed theme through the embed route context (scoped to the embed, not the main site), so the embed tabs honor it while staying statically rendered, and the redirect forwards it to the default tab. The forced theme is also persisted to the embed's own theme storage so it is remembered across tab navigation instead of only applying while the query string is present.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Sync the API reference responses selector with the "Responses" collapsibles, and keep the selected response in sync across every operation on the page (like the code sample language selector). Selecting a status code now expands the matching response section and applies to all operations at once.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix a light/dark flash on published sites configured to respect the system default (no theme toggle). Such sites forced the `system` theme, but `next-themes`' pre-paint script applies a forced value verbatim without resolving `prefers-color-scheme`, so the page painted light and only switched to dark after hydration. We now leave the theme unforced when the default is `system` (only concrete light/dark themes are forced), letting `next-themes`' existing pre-paint script resolve the system preference before first paint.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add a `sendFeedback` MCP tool so AI agents can report documentation findings (outdated / incoherent / gap / other) as `agent_feedback` insights events. The tool only accepts finding categories, so it never records positive feedback.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Separate the prompt block actions into a primary "Open in" dropdown and a secondary "Copy prompt" button, instead of a single combined button group, and align the block's design with the expandable block (bordered frame, left disclosure chevron, and subtle elevation when expanded).
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix the docs embed widget shipping a stale script: declare the embed package's `standalone/` bundle as a Turbo build output. Because it wasn't declared, changes confined to the standalone widget (which compiles to `standalone/` but not `dist/`) didn't invalidate the downstream `generate` cache that copies it into the app, so the deployed widget could lag the source — e.g. the `clipboard-write` permission on the widget iframe never reached production, breaking the copy button in the Assistant embed.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix code block syntax highlighting so comment delimiters (e.g. `//`, `/*`) use the same color as the rest of the comment. Previously the delimiter fell through to the generic punctuation scope, making it a different color from the comment body (most visible in dark mode).
@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Keep lists, paragraphs and code blocks as HTML in Updates RSS feeds, instead of running all the text together
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix ScrollContainer scroll buttons not reflecting content overflow immediately or after dynamic content changes (e.g. search results).
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix the spacebar being ignored in the search bar, which made multi-word queries impossible.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Keep the last search query visible after closing search, and restore it when reopening, without breaking navigation when clicking a search result.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Link page-level search matches to the top of the page while preserving section anchors for section matches.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Keep Shiki out of the initial page bundle by splitting the highlighter from the plain-text token helpers, so client code no longer pulls the engine and language bundles in through a shared import.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Refine the per-paragraph AI ask button: shorten its tooltip to "Ask" (from "Ask <assistant> about this"), and hide it inside cards where it would otherwise be clipped by the card's overflow.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Split the default-scope site search into two parallel API requests — one restricted to the current site space and one for the other site spaces — rendering each result set as soon as its response arrives. All results are ranked together by score, with the current site space scores boosted.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Keep the "On this page" and "Ask" buttons pinned below the header while scrolling on desktop API reference pages, so the page outline stays reachable throughout long operations.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Hide unfocusable unlabelled button from screen readers
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Only show the "Back to [space]" shortcut for cross-space links in the table of contents, not for in-content text links or other ways of reaching another space.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Show image thumbnails, including SVG previews, for file attachments on published sites.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Make the table search "no results" empty state more prominent with vertical spacing so it no longer blends into the content below.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix heading anchor links being unreachable on touch devices by adding a tap-to-reveal state. The anchor icon now appears after the heading text without wrapping onto an orphan line while retaining its existing desktop placement. Use `pointerup` for the dismiss listener to fix unreliable dismissal on iOS Safari, and enlarge the anchor's touch tap target to a square 24px area (meeting the WCAG 2.5.8 minimum) so the icon stays centered instead of overflowing shorter headings' line height.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix search results from a previous scope staying stuck on top of the new results when switching the search filter.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Support localized custom AI Assistant greeting subtitles.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix chevrons and open-state styling incorrectly reacting to a tooltip opening on the same trigger, by switching from the shared Base UI `data-popup-open` attribute to `aria-expanded`.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-a11y screen reader fixes
@@ -1,6 +0,0 @@
---
-"@gitbook/react-contentkit": patch
-"gitbook": patch
---
-
-Let integration block webframes navigate the reader to another page in the site by posting a `@webframe.navigate` action with a `path` (and optional `anchor`). Resolved client-side against the site base path, so navigation stays in-site and drives the standard navigation progress bar.
@@ -1,6 +0,0 @@
---
-"@gitbook/react-contentkit": patch
-"gitbook": patch
---
-
-Expose the current page (`id`, `path`, `title`) to integration block webframes through the client-only webframe `state.page`, alongside adaptive visitor claims.
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Fix an issue where certain keywords could cause an exception when rendering emojis
@@ -1,5 +0,0 @@
---
-"gitbook": patch
---
-
-Add the `select` action to InlineButton. Clicking the button activates its slug, so any block containing that slug switches to it.
@@ -0,0 +1 @@
+../../.agents/skills/write-pr-description
@@ -0,0 +1 @@
+../../.agents/skills/write-pr-description
@@ -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
@@ -1,113 +1,89 @@
-# Welcome to GitBook's contributing guide!
+# Contributing to GitBook

-> _For help, support, feature requests, and product questions - head to our [GitHub Community](https://github.com/orgs/GitbookIO/discussions) 🤖_
+> _For help, support and product questions, head to our [GitHub Community](https://github.com/orgs/GitbookIO/discussions)._

-Thank you for investing your time in contributing to GitBook. Any contribution you make will be reviewed by our team. In this guide, you'll learn the different ways you can contribute.
+Thanks for helping make GitBook better. This repository holds the open source renderer behind every published GitBook site, and the team reads everything that comes in here.

-## Types of Contributions
+## Ways to contribute

-This repository contains code related to the rendering engine of GitBook's published content. Depending on what you'd like to contribute to, head to the section below to find the necessary steps.
+-   **Open an issue.** Report a bug, suggest a feature, or tell us when something feels off. This is the most useful thing you can do.
+-   **Join the conversation.** Share ideas and help others in [GitHub Community](https://github.com/orgs/GitbookIO/discussions).
+-   **Build with GitBook.** Publish your docs, try new features early, and tell us what works and what doesn't.

-### Add a feature
+## Issues instead of pull requests

-Because this portion of GitBook is open source and available for you to use - if you think you can provide extra value through a new feature - you're welcome to add it! If you plan to distribute the code, keep the source code public to comply with GNU GPLv3. To clone in a private repository, you must first acquire a [commercial license](https://www.gitbook.com/pricing).
+Pull requests are limited to the GitBook team. If you've found a bug or want something to change, please [open an issue](https://github.com/GitbookIO/gitbook/issues/new/choose) instead.

-### Create a new issue
+This isn't because we don't want your help. Every change here ships to every published GitBook site, so we need to own each one from start to finish. A clear issue often helps us more than a pull request: it tells us what's wrong and why, and lets us fix it in a way that fits the rest of the codebase.

-If you spot a problem within a repository, [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments). If a related issue doesn't exist, you can open a new issue here!Please make sure any added issues are
+A good issue includes:

-   Descriptive
-   Thoughtful
-   Organized
+-   What you expected to happen, and what happened instead
+-   A link to a published GitBook site that shows the problem, if you have one
+-   Steps to reproduce it, plus screenshots or a recording for anything visual
+-   Your browser and OS, if it looks like it might matter

-We recommend adding as many relevant links, minimal reproductions of the issue, and other materials that will help our team solve the issue fast.
+Before opening one, [search existing issues](https://github.com/GitbookIO/gitbook/issues). If someone has already reported it, add a 👍 or any extra details you have.

-### Solve an issue
+Already fixed it in your fork? Link the branch or commit in your issue. We may open a pull request from it, and your commits keep your name.

-If you're interested in solving an issue in our repository, start by scanning through it's exisiting issues to find one that you're interested in working on. If you find an issue to work on, you are welcome to open a PR with a fix. See the following sections below for more information on contributing for specific sections.
+If you open a pull request anyway, we'll close it and point you here. Nothing personal, and we'd still love the issue.

-### Documentation
+## Reach out

-The official documentation on GitBook open can be found directly in this Readme. Any updates or changes you would like to make, you can make directly to the README of this repository.
+Not sure if it's a bug? Have a half-formed idea? Open an issue or start a [discussion](https://github.com/orgs/GitbookIO/discussions) anyway. We'd much rather hear from you than not, and no report is too small.

-## Contributing
+Spotted a wrong or missing translation? Open an issue with the string and the wording you'd suggest.

-### Make changes locally
+## Using AI

-Any contribution you make can be made to the code located in this repository. In order to contribute, you'll need to start off of a local version of this repository.
+You're welcome to use AI to help you write an issue. Please read and check what it produces before you post: reports that are long, vague or unverified take time away from fixing real problems, and we may close them without a reply.

-#### 1. Fork the repository
+## Running locally

-##### Using GitHub Desktop:
+You don't need a local setup to open an issue, but it can help you reproduce a problem or self-host the renderer.

-   [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop.
-   Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)!
+### Prerequisites

-##### Using the command line:
+-   [Node.js](https://nodejs.org/en) (see "engines" in `package.json`)
+-   [Bun](https://bun.sh/) (see "packageManager" in `package.json`)

-   [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them.
+### Setup

-#### 2. Create a working branch and start with your changes
+1. Use the project's version of Node:

-After forking this repository, you'll want to [create a branch](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue) to work off of.
-
-#### 3. Install dependencies and run the project locally
-
-##### Prerequisites:
-
- [Node.js](https://nodejs.org/en) (see "engines" in `package.json`)
- [Bun](https://bun.sh/) (see "packageManager" in `package.json`)
-
-##### Setup steps:
-
-1. Ensure you are using the project's version of Node:
 ```bash
 nvm use
 ```

-2. Install dependencies using Bun:
+2. Install dependencies:
+
 ```bash
 bun install
 ```

 3. Start the development server:
+
 ```bash
 bun dev
 ```

-Additional development commands:
- `bun lint`: Lint the code using Oxlint
- `bun lint:fix`: Automatically fix lint issues using Oxlint
- `bun format`: Format the code using Oxfmt
- `bun format:check`: Check formatting without changing files
- `bun typecheck`: Run TypeScript type checking
- `bun unit`: Run unit tests
- `bun e2e`: Run end-to-end tests
+Other commands:

-#### 4. Preview your changes
+-   `bun lint`: Lint the code using Oxlint
+-   `bun lint:fix`: Automatically fix lint issues using Oxlint
+-   `bun format`: Format the code using Oxfmt
+-   `bun format:check`: Check formatting without changing files
+-   `bun typecheck`: Run TypeScript type checking
+-   `bun unit`: Run unit tests
+-   `bun e2e`: Run end-to-end tests

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

-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.
+With the development server running, any published GitBook site can be rendered through your local version at `http://localhost:3000/url/<published-url>`. For example, visit `http://localhost:3000/url/gitbook.com/docs` to see our own docs.

-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.
+The site must be [published publicly](https://gitbook.com/docs/published-documentation/publish-your-content-as-a-docs-site) to render locally.

-### Commit your update
+## License

-[Commit your changes](https://github.com/git-guides/git-commit) once you are happy with them. See [Atom's contributing guide](https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages) to know how to use emoji for commit messages!
-
-Once your changes are ready, don't forget to self-review your code to double check that your chagnes are ready to be added.
-
-### Pull Request
-
-When you're finished with the changes, [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request), also known as a PR.
-
-   Don't forget to [link PR to issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one.
-   Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge. Once you submit your PR, a GitBook team member will review your proposal. We may ask questions or request for additional information.
-   We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
-   As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
-   If you run into any merge issues, checkout this [git tutorial](https://lab.github.com/githubtraining/managing-merge-conflicts) to help you resolve merge conflicts and other issues.
-
-### Your PR is merged
-
-Congratulations 🎉 Thank you for your contribution! Once your PR is merged, your contributions will be publicly visible on the relevant repository.
+The renderer is distributed under the [GNU GPLv3 License](https://github.com/GitbookIO/gitbook/blob/main/LICENSE). If you distribute the code, you must keep the source code public. To use it in a private repository, you need a [commercial license](https://www.gitbook.com/pricing).
@@ -69,6 +69,7 @@ runs:
              GITBOOK_RUNTIME: cloudflare
              GITBOOK_BLOCK_SEARCH_INDEXATION: ${{ inputs.environment == 'preview' && 'true' || '' }}
              GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE: ${{ inputs.environment == 'preview' && 'true' || '' }}
+              GITBOOK_DISABLE_INSIGHTS: ${{ inputs.environment == 'preview' && 'true' || '' }}
          shell: bash

        - name: Upload the DO worker
@@ -75,6 +75,7 @@ runs:
              echo "GITBOOK_RUNTIME=vercel" >> .vercel/.env.${{ inputs.environment }}.local
              echo "GITBOOK_BLOCK_SEARCH_INDEXATION=true" >> .vercel/.env.${{ inputs.environment }}.local
              echo "GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE=true" >> .vercel/.env.${{ inputs.environment }}.local
+              echo "GITBOOK_DISABLE_INSIGHTS=true" >> .vercel/.env.${{ inputs.environment }}.local
              echo "--- .vercel/.env.${{ inputs.environment }}.local after inject ---"
              cat .vercel/.env.${{ inputs.environment }}.local
        - name: Build Project Artifacts
@@ -0,0 +1,17 @@
+## Proposed changes
+
+<!-- Briefly describe what changed. Include relevant validation. -->
+
+## Demo
+
+<!-- Add screenshots or a recording when useful. Otherwise, remove this section. -->
+
+<!-- Optional: add Context here only when it explains a concrete problem and result that the changelog does not. Remove this comment before submitting. -->
+
+## Changelog
+
+<!-- Keep the relevant entries and remove unused placeholders. Feature = user-facing addition or improvement; Fix = user-facing bug fix; Chore = internal maintenance. -->
+
+- [Feature] ...
+- [Fix] ...
+- [Chore] ...
@@ -0,0 +1,22 @@
+{
+    "display_information": {
+        "name": "PR Status",
+        "description": "Updates PR status reactions in engineering"
+    },
+    "features": {
+        "bot_user": {
+            "display_name": "PR Status",
+            "always_online": false
+        }
+    },
+    "oauth_config": {
+        "scopes": {
+            "bot": ["channels:history", "reactions:read", "reactions:write"]
+        }
+    },
+    "settings": {
+        "org_deploy_enabled": false,
+        "socket_mode_enabled": false,
+        "token_rotation_enabled": false
+    }
+}
@@ -0,0 +1,15 @@
+# Slack PR status
+
+[GitbookIO/slack-pr-status](https://github.com/GitbookIO/slack-pr-status) adds review-status reactions to PR links posted in [#engineering](https://gitbook.slack.com/archives/C01NXGWJELS). It runs from `.github/workflows/slack-pr-status.yml` in `GitbookIO/gitbook`, `GitbookIO/gitbook-x` and `GitbookIO/integrations`. Emojis and statuses are configured in that workflow; see the action's README for the options.
+
+Owner: Peter White.
+
+| Configuration | Value |
+| --- | --- |
+| Slack app | **PR Status** (`A0C2AGLAD0T`), created from `.github/slack-pr-status-app-manifest.json` |
+| Bot token | Repository Actions secret `SLAPR_SLACK_BOT_TOKEN` |
+| GitHub token | The workflow's `GITHUB_TOKEN`, read-only |
+
+Posts that link PRs from more than one repository are skipped, because each workflow's token can only read its own repository. PRs from forks get no reactions, because their workflows don't receive secrets.
+
+To disable it in one repository, run `gh workflow disable slack-pr-status.yml --repo GitbookIO/<repository>`. To stop it everywhere, revoke the PR Status app's token.
@@ -0,0 +1,33 @@
+name: Slack PR status
+
+on:
+    pull_request_review:
+        types: [submitted, dismissed]
+    pull_request:
+        types: [closed, reopened]
+
+permissions:
+    contents: read
+    pull-requests: read
+
+jobs:
+    slack-pr-status:
+        # Secrets aren't available to workflows triggered from forks.
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        runs-on: ubuntu-latest
+        steps:
+            - uses: GitbookIO/slack-pr-status@main
+              with:
+                  slack-token: ${{ secrets.SLAPR_SLACK_BOT_TOKEN }}
+                  config: |
+                      channels: [C01NXGWJELS]
+                      approvalsRequired: 1
+                      multiPr: aggregate
+                      emojis:
+                          commented: false
+                          partiallyApproved: next_track_button
+                          approved: pr-approved
+                          changesRequested: construction
+                          merged: merged
+                          closed: no_entry_sign
+                          partiallyReviewed: hourglass_flowing_sand
@@ -29,3 +29,6 @@ yarn-error.log*

 # Bun pack artifacts
 packages/*/*.tgz
+
+# Playwright MCP artifacts
+.playwright-mcp/
@@ -85,7 +85,7 @@ GitBook Open uses fontawesome. For self-hosting and local development, for licen

 ## Contributing

-GitBook's rendering engine is fully open source and built on top of [Next.js](https://nextjs.org/). Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to learn more about the workflow on adding your first Pull Request.
+GitBook's rendering engine is fully open source and built on top of [Next.js](https://nextjs.org/). Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to learn how to report bugs and suggest changes.

 ### Types of contributions

@@ -93,22 +93,22 @@ We encourage you to contribute to GitBook to help us build the best tool for doc

 #### Translations

-The GitBook UI is rendered using a set of translation files found in [`packages/gitbook/src/intl/translations`](/packages/gitbook/src/intl/translations/). We welcome all additional translations for the UI.
+The GitBook UI is rendered using a set of translation files found in [`packages/gitbook/src/intl/translations`](/packages/gitbook/src/intl/translations/). Spotted a wrong or missing translation? Open an issue and let us know.

 #### Bugs

-Encounter a bug or find an issue you'd like to fix? Helping us fix issues related to GitBook greatly improves the experience for everyone. Head to the issues section of this repository to learn more about the types of bugs you can already help out with.
+Encounter a bug? [Open an issue](https://github.com/GitbookIO/gitbook/issues/new/choose) with as much detail as you can. Clear reports help us fix things faster for everyone.

 ## Deployment

 > [!WARNING]  
 > While it is possible to self-host this project, we do not recommend this unless you are certain this option fits your need.
 >
-> _Looking to add a specific feature in GitBook? Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to get started._
+> _Looking for a specific feature in GitBook? Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to suggest it._
 >
 > Self-hosting this project puts the responsibility of maintaining and merging future updates on **you**. We cannot guarantee support, maintenance, or updates to forked and self-hosted instances of this project.
 >
-> We want to make it as easy as possible for our community to collaborate and push the future of GitBook, which is why we encourage you to contribute to our product directly instead of creating your own version.
+> We want to make it as easy as possible for our community to collaborate and push the future of GitBook, which is why we encourage you to share your ideas with us instead of creating your own version.

 This project allows you to self-host the rendering portion of your GitBook published content. Self-hosting has pros and cons.

@@ -5,10 +5,10 @@
        "node": "^22.3.0"
    },
    "devDependencies": {
-        "@changesets/cli": "^2.31.0",
+        "@changesets/cli": "^2.31.1",
        "oxfmt": "^0.62.0",
-        "oxlint": "^1.77.0",
-        "turbo": "^2.10.3",
+        "oxlint": "^1.90.0",
+        "turbo": "^2.11.10",
        "vercel": "50.37.3"
    },
    "packageManager": "bun@1.3.7",
@@ -48,7 +48,7 @@
            "@tsconfig/strictest": "^2.0.6",
            "@tsconfig/node20": "^20.1.6",
            "@base-ui/react": "^1.7.0",
-            "@gitbook/api": "0.195.0",
+            "@gitbook/api": "0.206.0",
            "@scalar/api-client-react": "^1.3.46",
            "@types/react": "^19.0.0",
            "@types/react-dom": "^19.0.0",
@@ -67,6 +67,7 @@
    "patchedDependencies": {
        "decode-named-character-reference@1.0.2": "patches/decode-named-character-reference@1.0.2.patch",
        "@vercel/next@4.4.2": "patches/@vercel%2Fnext@4.4.2.patch",
-        "next@16.2.11": "patches/next@16.2.11.patch"
+        "next@16.4.3": "patches/next@16.4.3.patch",
+        "mermaid@11.16.1": "patches/mermaid@11.16.1.patch"
    }
 }
@@ -1,5 +1,11 @@
 # @gitbook/browser-types

+## 0.1.6
+
+### Patch Changes
+
+- bf674a4: Add an optional `context` property (string, up to 512 characters) to the `confirmation` of custom AI tools, shown above the confirmation dialog to help the user understand what they are approving or rejecting. The `confirmation` can now also be a function that receives the AI-provided input and returns the confirmation, so the context can be derived dynamically from the arguments the tool is about to run with. Available both to integrations (`GitBookIntegrationTool`) and to embed consumers (`GitBookToolDefinition`).
+
 ## 0.1.5

 ### Patch Changes
@@ -9,7 +9,7 @@
        }
    },
    "sideEffects": false,
-    "version": "0.1.5",
+    "version": "0.1.6",
    "dependencies": {
        "@gitbook/api": "catalog:",
        "@gitbook/icons": "workspace:"
@@ -1,5 +1,11 @@
 # @gitbook/colors

+## 0.4.4
+
+### Patch Changes
+
+- a69a307: A near-white tint color (e.g. a warm `#F5F3EF`) is now taken as the exact page background, mirroring the existing behavior for near-black tints. The tint's exact lightness, hue and chroma are preserved, and the color is anchored to whichever scale step the active theme renders as the background — so it matches exactly on `muted` (which uses the second step) as well as `clean`. This applies only to near-neutral tints that are light enough to read as a background; saturated or merely light-ish colors keep their normal accent scale. The `bold` theme is unaffected: it already uses the tint for the header and stays intentionally two-tone.
+
 ## 0.4.3

 ### Patch Changes
@@ -8,7 +8,7 @@
        }
    },
    "sideEffects": false,
-    "version": "0.4.3",
+    "version": "0.4.4",
    "devDependencies": {
        "bun-types": "catalog:",
        "tsdown": "catalog:",
@@ -1,5 +1,16 @@
 # @gitbook/embed

+## 0.6.0
+
+### Minor Changes
+
+- f35be52: Add `defaultTab` and `defaultPage` options to the Docs Embed to choose where it opens. `defaultTab` opens the embed on the assistant, search or docs tab. `defaultPage` sets the page the docs tab opens on in place of the site's home page, and the embed opens on that page unless `defaultTab` says otherwise. Both work with the standalone script's `configure`, `frame.configure` and `<GitBookFrame>` props.
+
+### Patch Changes
+
+- 94a496c: Make the Docs Embed widget match the page it is embedded in rather than the visitor's OS: a widget on a light page stays light even when the visitor's system is in dark mode, and the widget's own chrome and the docs inside it always render in the same scheme. Sites published with a single theme impose it on the widget too, since they render in it regardless. The standalone script takes `?theme=light` on its URL, and calling `init` twice now updates the options instead of throwing.
+- bf674a4: Add an optional `context` property (string, up to 512 characters) to the `confirmation` of custom AI tools, shown above the confirmation dialog to help the user understand what they are approving or rejecting. The `confirmation` can now also be a function that receives the AI-provided input and returns the confirmation, so the context can be derived dynamically from the arguments the tool is about to run with. Available both to integrations (`GitBookIntegrationTool`) and to embed consumers (`GitBookToolDefinition`).
+
 ## 0.5.1

 ### Patch Changes
@@ -19,15 +19,27 @@ 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>
+```
+
+The script initializes the widget itself, so there is nothing to call. To pin the embed to one color
+scheme, put it on the script URL — it has to be known before the widget renders:
+
+```html
+<script src="https://docs.company.com/~gitbook/embed/script.js?theme=light"></script>
+```
+
+To authenticate the visitor, call `init` with their token. Keep tokens out of the script URL: it is
+publicly cacheable and ends up in server logs.
+
 ```html
 <script src="https://docs.company.com/~gitbook/embed/script.js"></script>
 <script>
-// Initialize with Authenticated Access (optional)
-window.GitBook('init', 
+window.GitBook('init',
    { siteURL: 'https://docs.company.com' },
    { visitor: { token: 'your-jwt-token' } }
 );
-window.GitBook('show');
 </script>
 ```

@@ -42,6 +54,7 @@ GitBook('configure', {
        icon: 'assistant' // 'assistant' | 'sparkle' | 'help' | 'book'
    },
    tabs: ['assistant', 'search', 'docs'],
+    defaultPage: '/getting-started',
    actions: [
        {
            icon: 'circle-question',
@@ -95,6 +108,7 @@ frame.clearChat();
 // Configure the embed (see Configuration section for all options)
 frame.configure({
    tabs: ['assistant', 'search', 'docs'],
+    defaultPage: '/getting-started',
    actions: [
        {
            icon: 'circle-question',
@@ -130,6 +144,7 @@ import { GitBookProvider, GitBookFrame } from '@gitbook/embed/react';
            unsignedClaims: { userId: '123' } // Optional: custom claims for dynamic expressions
        }}
        tabs={['assistant', 'search', 'docs']}
+        defaultPage="/getting-started"
        greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
        assistantName="Support Assistant"
        suggestions={['What is GitBook?', 'How do I get started?']}
@@ -237,6 +252,33 @@ Override which tabs are displayed. Defaults to your site's configuration.
 tabs: ['assistant', 'search', 'docs']
 ```

+### `defaultTab`
+
+Available in: Standalone script, NPM package, React components
+
+The tab the embed opens on. Without it, the embed opens on `defaultPage` if set, otherwise on the assistant (or the docs when the assistant isn't available). The tab must be one of the enabled `tabs`.
+
+- **Type**: `'assistant' | 'search' | 'docs'`
+
+```javascript
+tabs: ['assistant', 'search', 'docs'],
+defaultTab: 'search'
+```
+
+`defaultTab` and `defaultPage` apply when the embed first loads: the standalone widget keeps its place when it is closed and reopened. To move it later, use `navigateToPage` or `navigateToAssistant`.
+
+### `defaultPage`
+
+Available in: Standalone script, NPM package, React components
+
+The page the docs tab opens on, in place of your site's home page. Accepts the same references as `navigateToPage`: the page's path within the site, an absolute path, or its full published URL. Unless `defaultTab` says otherwise, the embed opens on this page.
+
+- **Type**: `string`
+
+```javascript
+defaultPage: '/getting-started/quickstart'
+```
+
 ### `closeButton`

 Available in: Standalone script, NPM package, React components
@@ -464,20 +506,25 @@ visitor: {

 Available in: Standalone script (via `init`), NPM package (via `getFrameURL()`), React components (as prop)

-Override the embed's color scheme. When omitted, the embed follows the iframe's CSS `color-scheme`, which lets it inherit the parent page or browser preference.
+Override the embed's color scheme.
+
+When omitted, the standalone widget follows the page it is embedded in — its `color-scheme`, falling back to the visitor's OS preference only when that page declares support for both. With the NPM package or the React components you own the iframe, so the embed follows the visitor's OS preference unless you pass this.

 **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)`
+**Standalone script**: `?theme=light` on the script URL
 **NPM package**: Pass to `getFrameURL({ colorScheme: 'dark' })`
 **React components**: Pass as the `colorScheme` prop on `<GitBookFrame>`

 - **Type**: `'light' | 'dark'`

-```javascript
-colorScheme: 'dark'
+```html
+<script src="https://docs.company.com/~gitbook/embed/script.js?theme=light"></script>
 ```

+Sites published with a single theme always render in that theme, so `colorScheme` has no effect on
+them — the widget follows the site instead, to keep its chrome and the docs inside it consistent.
+
 ### `button`

 Available in: Standalone script only
@@ -13,7 +13,7 @@
        }
    },
    "sideEffects": false,
-    "version": "0.5.1",
+    "version": "0.6.0",
    "dependencies": {
        "@gitbook/api": "catalog:",
        "@gitbook/icons": "workspace:",
@@ -10,7 +10,9 @@ export type CreateGitBookOptions = {
 export type GetFrameURLOptions = {
    /**
     * Override the color scheme used by the embedded docs.
-     * When omitted, the embed follows the iframe's CSS `color-scheme`.
+     * When omitted, the standalone widget follows the page it is embedded in, and only falls back
+     * to the visitor's OS preference when that page supports both schemes. Building the iframe
+     * yourself, the embed follows the visitor's OS preference unless you pass this.
     */
    colorScheme?: 'light' | 'dark';

@@ -62,6 +62,12 @@ export type GitBookEmbeddableConfiguration = {
    /** Tabs to display in the embed (if enabled on the site). */
    tabs: ('assistant' | 'docs' | 'search')[];

+    /** Tab to open the embed on. */
+    defaultTab?: 'assistant' | 'docs' | 'search';
+
+    /** Page to open the docs tab on, instead of the site's home page. */
+    defaultPage?: string;
+
    /** Additional buttons to be displayed in the header of the GitBook embed. */
    actions: GitBookEmbeddableActionDefinition[];

@@ -27,6 +27,8 @@ export function GitBookFrame(props: GitBookFrameProps) {
        suggestions = [],
        tools = [],
        tabs = ['assistant', 'search', 'docs'],
+        defaultTab,
+        defaultPage,
        trademark = true,
        closeButton = false,
        assistantName,
@@ -50,6 +52,8 @@ export function GitBookFrame(props: GitBookFrameProps) {
    useEffect(() => {
        gitbookFrame?.configure({
            tabs,
+            defaultTab,
+            defaultPage,
            actions,
            greeting,
            suggestions,
@@ -65,6 +69,8 @@ export function GitBookFrame(props: GitBookFrameProps) {
        suggestions,
        tools,
        tabs,
+        defaultTab,
+        defaultPage,
        closeButton,
        trademark,
        assistantName,
@@ -79,7 +85,6 @@ export function GitBookFrame(props: GitBookFrameProps) {
            height="100%"
            allow="clipboard-write"
            className={className}
-            style={colorScheme ? { colorScheme } : undefined}
        />
    );
 }
@@ -55,6 +55,7 @@ let widgetIframe: HTMLIFrameElement | undefined;
 let _client: GitBookClient | undefined;
 let _frame: GitBookFrameClient | undefined;
 let frameOptions: GetFrameURLOptions | undefined;
+let frameConfigured = false;
 let frameConfiguration: GitBookEmbeddableConfiguration & StandaloneConfiguration = {
    button: {
        label: 'Ask',
@@ -85,6 +86,47 @@ widgetWindow.classList.add('hidden');
 document.body.appendChild(widgetButton);
 document.body.appendChild(widgetWindow);

+/**
+ * The one scheme everything follows: the widget's chrome, the frame's URL and the docs inside it.
+ * Either it was configured, or we match the page we are embedded in (RND-12558).
+ */
+function resolveColorScheme(): 'light' | 'dark' {
+    const configured = frameOptions?.colorScheme;
+    // Callers are plain JS, so anything else — a typo, a `system` — falls back to the page rather
+    // than reaching the CSS and the frame's URL, where the two would disagree.
+    return configured === 'light' || configured === 'dark' ? configured : hostColorScheme();
+}
+
+/**
+ * The scheme the embedding page renders in, which is not the visitor's OS preference: a page that
+ * never opted into dark stays light however the OS is set.
+ *
+ * Resolving a `light-dark()` is the only way to read it. A page's *used* color scheme isn't exposed
+ * anywhere — the CSSOM gives computed values, and a `<meta name="color-scheme">` (the common way to
+ * declare it) never even reaches those.
+ */
+function hostColorScheme(): 'light' | 'dark' {
+    const probe = document.createElement('div');
+    // The first `color` is the fallback where `light-dark()` is unsupported: without it the probe
+    // would inherit the page's own text colour and a white one would read as dark.
+    probe.style.cssText =
+        'display:none;color:rgb(0,0,0);color:light-dark(rgb(0,0,0), rgb(255,255,255))';
+    document.body.appendChild(probe);
+    const used = getComputedStyle(probe).color;
+    probe.remove();
+
+    return used === 'rgb(255, 255, 255)' ? 'dark' : 'light';
+}
+
+/** Mirror the resolved scheme onto the widget's own chrome, and hand it back for the frame's URL. */
+function applyColorScheme(): 'light' | 'dark' {
+    const colorScheme = resolveColorScheme();
+    for (const element of [widgetButton, widgetWindow]) {
+        element.dataset.colorScheme = colorScheme;
+    }
+    return colorScheme;
+}
+
 function getClient() {
    if (!_client) {
        throw new Error(
@@ -102,12 +144,8 @@ function getIframe() {
        widgetIframe = document.createElement('iframe');
        widgetIframe.id = 'gitbook-widget-iframe';
        widgetIframe.allow = 'clipboard-write';
-        if (frameOptions?.colorScheme) {
-            widgetIframe.style.colorScheme = frameOptions.colorScheme;
-        }
-        widgetIframe.src = client.getFrameURL({
-            ...frameOptions,
-        });
+        // One read for both, so the docs can't come back in a different scheme than the panel.
+        widgetIframe.src = client.getFrameURL({ ...frameOptions, colorScheme: applyColorScheme() });
        widgetWindow.appendChild(widgetIframe);

        _frame = client.createFrame(widgetIframe);
@@ -115,25 +153,53 @@ function getIframe() {
            widgetWindow.classList.add('hidden');
            widgetButton.classList.remove('open');
        });
+        // A new frame starts from the site's own defaults, so replay whatever the host configured.
+        if (frameConfigured) {
+            _frame.configure(frameConfiguration);
+        }
    }
    return { iframe: widgetIframe, frame: _frame };
 }

 const GitBook = (...args: StandaloneCalls) => {
    switch (args[0]) {
-        case 'init':
-            if (_client) {
-                throw new Error(
-                    'GitBook client already initialized. Call GitBook("unload") first.'
-                );
-            }
+        case 'init': {
+            // `~gitbook/embed/script.js` already calls `init`, so an integrator following the docs
+            // ends up calling it a second time. Take the new options instead of throwing: throwing
+            // here dropped every call queued behind it (RND-12558).
            _client = createGitBook(args[1]);
-            frameOptions = args[2];
+            frameOptions = {
+                // Replace rather than merge: a call that leaves out `visitor` — a logout, another
+                // site — must not keep the token from the last one.
+                ...args[2],
+                // Except the scheme, where the first one wins: `script.js` passes the site's own
+                // theme when it pins one, and that is not the integrator's to override.
+                colorScheme: frameOptions?.colorScheme ?? args[2]?.colorScheme,
+            };
+            const colorScheme = applyColorScheme();
+
+            // Rebuild the frame only if the new options change its URL — reloading it on the
+            // loader's `init` plus the integrator's would throw away a chat for nothing.
+            const frameURL = _client.getFrameURL({ ...frameOptions, colorScheme });
+            if (widgetIframe && widgetIframe.src !== frameURL) {
+                const wasOpen = !widgetWindow.classList.contains('hidden');
+                widgetIframe.remove();
+                widgetIframe = undefined;
+                _frame = undefined;
+                if (wasOpen) {
+                    getIframe();
+                }
+            }
            break;
+        }
        case 'unload':
            _client = undefined;
            _frame = undefined;
            widgetIframe?.remove();
+            widgetIframe = undefined;
+            frameOptions = undefined;
+            frameConfigured = false;
+            applyColorScheme();
            widgetWindow.classList.add('hidden');
            break;
        case 'show':
@@ -192,6 +258,7 @@ const GitBook = (...args: StandaloneCalls) => {
                }
            }

+            frameConfigured = true;
            getIframe().frame.configure({
                ...frameConfiguration,
            });
@@ -214,4 +281,11 @@ const precalls = (window.GitBook as GitBookStandalone | undefined)?.q ?? [];

 // @ts-expect-error - GitBook is not defined in the global scope
 window.GitBook = GitBook;
-precalls.forEach((call) => GitBook(...call));
+// Replay each queued call on its own, so one that throws doesn't drop the rest.
+precalls.forEach((call) => {
+    try {
+        GitBook(...call);
+    } catch (error) {
+        console.error('[gitbook:embed]', error);
+    }
+});
@@ -29,14 +29,30 @@
    --gitbook-widget-easing-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
 }

-@media (prefers-color-scheme: dark) {
-    :root {
-        --gitbook-widget-text-color: #FFFFFF;
-        --gitbook-widget-border-color: #202020;
-        --gitbook-widget-background-translucent: rgba(15, 15, 15, 0.9);
-        --gitbook-widget-background-translucent-hover: rgba(20, 20, 20, 0.9);
-        --gitbook-widget-background-solid: #f0f0f0;
-    }
+/* The widget owns the panel's surface, so it renders in the same scheme as the docs inside the
+ * iframe. `data-color-scheme` carries that one resolved scheme — see `resolveColorScheme()` — and
+ * is always set, so the declaration below only shows before the widget initializes (RND-12558).
+ * The colours are declared here rather than on `:root` because `light-dark()` resolves against the
+ * color-scheme of the element that declares them. The bundler lowers it to a variable toggle, so
+ * browsers without `light-dark()` still get both schemes. */
+#gitbook-widget-button,
+#gitbook-widget-window {
+    color-scheme: light;
+
+    --gitbook-widget-text-color: light-dark(#656973, #FFFFFF);
+    --gitbook-widget-border-color: light-dark(#e5e5e5, #202020);
+    --gitbook-widget-background-translucent: light-dark(rgba(255, 255, 255, 0.9), rgba(15, 15, 15, 0.9));
+    --gitbook-widget-background-translucent-hover: light-dark(rgba(250, 250, 250, 0.9), rgba(20, 20, 20, 0.9));
+    --gitbook-widget-background-solid: light-dark(#FFFFFF, #0f0f0f);
+    --gitbook-widget-background-solid-hover: light-dark(#FBFBFB, #141414);
+}
+#gitbook-widget-button[data-color-scheme="light"],
+#gitbook-widget-window[data-color-scheme="light"] {
+    color-scheme: light;
+}
+#gitbook-widget-button[data-color-scheme="dark"],
+#gitbook-widget-window[data-color-scheme="dark"] {
+    color-scheme: dark;
 }

 * {
--- a/Show More
+++ b/Show More