Update memory allocation for Cloudflare's container instances to meet minimum requirements

- Introduced build ID management in cache set and delete operations to ensure entries are namespaced correctly.
- Updated the `getReadUrl` function to include build ID in the request URL.
- Enhanced tests to validate build ID inclusion in cache operations.

.changeset/ai-chat-view-activity-toggle.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix "View activity" disclosure in AI Chat not opening after the Base UI migration.

.changeset/anchor-scroll-unchanged-hash.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Scroll to an in-page heading even when the URL hash is unchanged (e.g. clicking the same anchor again).

.changeset/argos-image-rendering-drift.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/assistant-submit-assistant-feedback-tool.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add an assistant tool to rate its own previous response when the user reacts to it.

.changeset/assistant-submit-page-feedback-tool.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add an assistant tool to submit feedback about the current page on behalf of the user.

.changeset/assistant-type-while-answering.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/breadcrumbs-clear-page-actions.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Keep the breadcrumbs from covering the page actions' hit area.

.changeset/cache-tier-in-container-worker.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Move the incremental cache tier from the DO worker into the container worker.

.changeset/cards-carousel-layout.md

@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Add a carousel layout option to cards blocks, rendering them as a horizontally-scrolling, scroll-snapping row instead of a wrapping grid.

.changeset/collapsible-reasoning-heading.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/container-server-tier.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add a container server tier: an `@opennextjs/aws` node build of the app running inside a Cloudflare Container, reaching the cache worker through the container Durable Object's outbound handler. Build it with `bun run build:all` and run it locally with `bun run dev:cf:container`.

.changeset/deploy-container-tier.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Deploy the container server tier from CI to preview, staging and production. Preview and staging serve their traffic from the container; production deploys it but keeps serving from the workerd tier.

.changeset/embed-host-actions.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix host action buttons in the Docs Embed not reaching the assistant.

.changeset/embed-navigate-to-page-normalize.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/embed-search-suggestions.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix suggested question clicks in the embed search not opening the assistant.

.changeset/embed-search-tab-navigation.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix switching from the Search tab to the Docs or Assistant tab in the embed doing nothing.

.changeset/empty-bears-cheat.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add configurable default visibility to Prompt block

.changeset/exact-light-tint-background.md

@@ -0,0 +1,6 @@
+---
+"@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.

.changeset/fancy-webs-sneeze.md

@@ -0,0 +1,7 @@
+---
+"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.

.changeset/few-parts-lead.md

@@ -0,0 +1,7 @@
+---
+"@gitbook/openapi-parser": patch
+"@gitbook/react-openapi": patch
+"gitbook": patch
+---
+
+Add missing link reference to OpenAPI models

.changeset/funky-jobs-know.md

@@ -0,0 +1,5 @@
+---
+'gitbook': patch
+---
+
+Update the URL hash when a tab is selected, so a copied link scrolls back to that tab

.changeset/hot-views-judge.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add cover image background mode and masks

.changeset/inline-button-size.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Button blocks now respect the `size` option, so you can render small, medium, or large buttons.

.changeset/integration-tool-context.md

@@ -0,0 +1,7 @@
+---
+"@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`).

.changeset/lazy-mermaid-code-block.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Lazy-load the Mermaid code block so pages that have code blocks but no diagram no longer ship its rendering dependencies.

.changeset/lazy-scalar-modal.md

@@ -0,0 +1,8 @@
+---
+"@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.

.changeset/markdown-ask-goal-param.md

@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Support an optional `goal` query parameter on the markdown ask interface (`?ask=…&goal=…`), letting agents describe the broader end goal they are working towards so the answer can be steered towards it.

.changeset/mcp-ask-question-tool.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/mcp-send-feedback-endpoint.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/mermaid-scroll-zoom-modifier.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/migrate-headless-primitives-to-base-ui.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Migrate the headless UI primitives from Radix and react-aria to Base UI.

.changeset/moody-nails-admire.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/noindex-search-ask-urls.md

@@ -0,0 +1,5 @@
+---
+"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".

.changeset/olive-pumas-invite.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix the variant switcher linking to the wrong URL for non-default variants of the default section

.changeset/openapi-models-on-this-page.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/openapi-scalar-proxy-cookies.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Improve cookie handling in the OpenAPI "Test it" request proxy.

.changeset/openapi-scalar-proxy-origin.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Serve the OpenAPI "Test it" request proxy from GitBook's own domain.

.changeset/openapi-serializable-context.md

@@ -0,0 +1,6 @@
+---
+"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.

.changeset/openapi-webhook-payload-scroll.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix OpenAPI webhook payload and schema example panels being clipped instead of scrollable.

.changeset/prev-next-alignment.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/quiet-pans-listen.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix text disappearing in Firefox and iOS Safari on pages with a background cover

.changeset/quiet-rivers-render.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Render a site-space custom home page at its placement root while preserving the full space and normal page URLs.

.changeset/rnd-11356-remove-gbo-bestsection.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/rnd-11571-embed-light-theme.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/rnd-11616-responses-selector-sync.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/rnd-11643-fix-system-theme-flash.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/rnd-11847-mcp-send-feedback.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/rnd-11847-separate-prompt-block-actions.md

@@ -0,0 +1,5 @@
+---
+"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).

.changeset/rnd-11876-embed-standalone-turbo-output.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/rnd-12204-comment-punctuation-color.md

@@ -0,0 +1,5 @@
+---
+"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).

.changeset/scroll-container-overflow-state.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix ScrollContainer scroll buttons not reflecting content overflow immediately or after dynamic content changes (e.g. search results).

.changeset/search-input-spacebar.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix the spacebar being ignored in the search bar, which made multi-word queries impossible.

.changeset/search-last-query.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Keep the last search query visible after closing search, and restore it when reopening, without breaking navigation when clicking a search result.

.changeset/search-result-page-target.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Link page-level search matches to the top of the page while preserving section anchors for section matches.

.changeset/section-dropdown-embedded-empty.md

@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Fix grouped top-nav section dropdowns rendering empty when the site is embedded in an iframe (visitor-auth embeds, editor preview) or shown in the embeddable view. The dropdown viewport is composited and animated, and a clipped composited layer fails to rasterize its text in Chromium when painted inside a sub compositing root; the rounded-corner clipping is now done on an inner wrapper so the viewport itself is no longer clipped.

.changeset/shiki-out-of-initial-bundle.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/shorten-paragraph-ask-tooltip.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/split-site-search-requests.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/sticky-api-page-actions.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/strict-jokes-play.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Hide unfocusable unlabelled button from screen readers

.changeset/stricter-back-to-space.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/svg-file-attachment-previews.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Show image thumbnails, including SVG previews, for file attachments on published sites.

.changeset/table-search-empty-padding.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Make the table search "no results" empty state more prominent with vertical spacing so it no longer blends into the content below.

.changeset/tap-to-reveal-heading-anchor.md

@@ -0,0 +1,5 @@
+---
+"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.

.changeset/tidy-donkeys-shave.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix search results from a previous scope staying stuck on top of the new results when switching the search filter.

.changeset/tired-mails-fall.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Support localized custom AI Assistant greeting subtitles.

.changeset/tooltip-disclosure-open-state-conflict.md

@@ -0,0 +1,5 @@
+---
+"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`.

.changeset/wacky-eyes-post.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+a11y screen reader fixes

.changeset/webframe-navigate.md

@@ -0,0 +1,6 @@
+---
+"@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.

.changeset/webframe-page-context.md

@@ -0,0 +1,6 @@
+---
+"@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.

.changeset/whole-hands-report.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix an issue where certain keywords could cause an exception when rendering emojis

.changeset/wild-suns-relate.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Add the `select` action to InlineButton. Clicking the button activates its slug, so any block containing that slug switches to it.

.editorconfig

@@ -0,0 +1,10 @@
+# Stop editors from looking for .editorconfig files in parent directories.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+max_line_length = 100

.github/CONTRIBUTING.md

@@ -76,7 +76,10 @@ bun dev
 ```
 
 Additional development commands:
-- `bun format`: Format the code using Biome
+- `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

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

@@ -1,83 +1,83 @@
 name: Gradual Deploy to Cloudflare
 description: Use gradual deployment to deploy to Cloudflare. This action will upload the middleware and server versions to Cloudflare and kept them bound together
 inputs:
-  apiToken:
-    description: 'Cloudflare API token'
-    required: true
-  accountId:
-    description: 'Cloudflare account ID'
-    required: true
-  environment:
-    description: 'Cloudflare environment to deploy to (staging, production, preview)'
-    required: true
-  middlewareVersionId:
-    description: 'Middleware version ID to deploy'
-    required: true
-  serverVersionId:
-    description: 'Server version ID to deploy'
-    required: true
+    apiToken:
+        description: 'Cloudflare API token'
+        required: true
+    accountId:
+        description: 'Cloudflare account ID'
+        required: true
+    environment:
+        description: 'Cloudflare environment to deploy to (staging, production, preview)'
+        required: true
+    middlewareVersionId:
+        description: 'Middleware version ID to deploy'
+        required: true
+    serverVersionId:
+        description: 'Server version ID to deploy'
+        required: true
 outputs:
-  deployment-url: 
-    description: "Deployment URL"
-    value: ${{ steps.deploy_middleware.outputs.deployment-url }}
+    deployment-url:
+        description: 'Deployment URL'
+        value: ${{ steps.deploy_middleware.outputs.deployment-url }}
 runs:
-  using: 'composite'
-  steps:
-      - id: wrangler_status
-        name: Check wrangler deployment status
-        uses: cloudflare/wrangler-action@v3.14.0
-        with:
-            apiToken: ${{ inputs.apiToken }}
-            accountId: ${{ inputs.accountId }}
-            workingDirectory: ./
-            wranglerVersion: '4.43.0'
-            environment: ${{ inputs.environment }}
-            command: deployments status --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
+    using: 'composite'
+    steps:
+        - id: wrangler_status
+          name: Check wrangler deployment status
+          uses: cloudflare/wrangler-action@v3.14.0
+          with:
+              apiToken: ${{ inputs.apiToken }}
+              accountId: ${{ inputs.accountId }}
+              workingDirectory: ./
+              wranglerVersion: '4.122.0'
+              environment: ${{ inputs.environment }}
+              command: deployments status --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
 
-      # This step is used to get the version ID that is currently deployed to Cloudflare.
-      - id: extract_current_version
-        name: Extract current version
-        shell: bash
-        run: |
-          version_id=$(echo "${{ steps.wrangler_status.outputs.command-output }}" | grep -A 3 "(100%)" | grep -oP '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}')
-          echo "version_id=$version_id" >> $GITHUB_OUTPUT
+        # This step is used to get the version ID that is currently deployed to Cloudflare.
+        - id: extract_current_version
+          name: Extract current version
+          shell: bash
+          run: |
+              version_id=$(echo "${{ steps.wrangler_status.outputs.command-output }}" | grep -A 3 "(100%)" | grep -oP '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}')
+              echo "version_id=$version_id" >> $GITHUB_OUTPUT
 
-      - id: deploy_server
-        name: Deploy server to Cloudflare at 0%
-        uses: cloudflare/wrangler-action@v3.14.0
-        with:
-            apiToken: ${{ inputs.apiToken }}
-            accountId: ${{ inputs.accountId }}
-            workingDirectory: ./
-            wranglerVersion: '4.43.0'
-            environment: ${{ inputs.environment }}
-            command: versions deploy ${{ steps.extract_current_version.outputs.version_id }}@100% ${{ inputs.serverVersionId }}@0% -y --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
+        - id: deploy_server
+          name: Deploy server to Cloudflare at 0%
+          uses: cloudflare/wrangler-action@v3.14.0
+          with:
+              apiToken: ${{ inputs.apiToken }}
+              accountId: ${{ inputs.accountId }}
+              workingDirectory: ./
+              wranglerVersion: '4.122.0'
+              environment: ${{ inputs.environment }}
+              command: versions deploy ${{ steps.extract_current_version.outputs.version_id }}@100% ${{ inputs.serverVersionId }}@0% -y --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
 
-      # Since we use version overrides headers, we can directly deploy the middleware to 100%.
-      - id: deploy_middleware
-        name: Deploy middleware to Cloudflare at 100%
-        uses: cloudflare/wrangler-action@v3.14.0
-        with:
-            apiToken: ${{ inputs.apiToken }}
-            accountId: ${{ inputs.accountId }}
-            workingDirectory: ./
-            wranglerVersion: '4.43.0'
-            environment: ${{ inputs.environment }}
-            command: versions deploy ${{ inputs.middlewareVersionId }}@100% -y --config ./packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc
+        # Since we use version overrides headers, we can directly deploy the middleware to 100%.
+        - id: deploy_middleware
+          name: Deploy middleware to Cloudflare at 100%
+          uses: cloudflare/wrangler-action@v3.14.0
+          with:
+              apiToken: ${{ inputs.apiToken }}
+              accountId: ${{ inputs.accountId }}
+              workingDirectory: ./
+              wranglerVersion: '4.122.0'
+              environment: ${{ inputs.environment }}
+              command: versions deploy ${{ inputs.middlewareVersionId }}@100% -y --config ./packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc
 
-      - name: Deploy server to Cloudflare at 100%
-        uses: cloudflare/wrangler-action@v3.14.0
-        with:
-            apiToken: ${{ inputs.apiToken }}
-            accountId: ${{ inputs.accountId }}
-            workingDirectory: ./
-            wranglerVersion: '4.43.0'
-            environment: ${{ inputs.environment }}
-            command: versions deploy ${{ inputs.serverVersionId }}@100% -y --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
+        - name: Deploy server to Cloudflare at 100%
+          uses: cloudflare/wrangler-action@v3.14.0
+          with:
+              apiToken: ${{ inputs.apiToken }}
+              accountId: ${{ inputs.accountId }}
+              workingDirectory: ./
+              wranglerVersion: '4.122.0'
+              environment: ${{ inputs.environment }}
+              command: versions deploy ${{ inputs.serverVersionId }}@100% -y --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
 
-      - name: Outputs
-        shell: bash
-        env:
-          DEPLOYMENT_URL: ${{ steps.deploy_middleware.outputs.deployment-url }}
-        run: |
-            echo "URL: ${{ steps.deploy_middleware.outputs.deployment-url }}"
+        - name: Outputs
+          shell: bash
+          env:
+              DEPLOYMENT_URL: ${{ steps.deploy_middleware.outputs.deployment-url }}
+          run: |
+              echo "URL: ${{ steps.deploy_middleware.outputs.deployment-url }}"

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

@@ -1,34 +1,37 @@
 name: 'Deploy cloudflare'
 description: 'Deploy GitBook to Cloudflare'
 inputs:
-  opItem:
-    description: '1Password item to load secrets from'
-    required: true
-  opServiceAccount:
-    description: '1Password service account token'
-    required: true
-  apiToken:
-    description: 'Cloudflare API token'
-    required: true
-  accountId:
-    description: 'Cloudflare account ID'
-    required: true
-  environment:
-    description: 'Cloudflare environment to deploy to (staging, production, preview)'
-    required: true
-  deploy:
-    description: 'Deploy as main version for all traffic instead of uploading versions'
-    required: true
-  commitTag:
-    description: 'Commit branch to associate with the deployment'
-    required: true
-  commitMessage:
-    description: 'Commit message to associate with the deployment'
-    required: true
+    opItem:
+        description: '1Password item to load secrets from'
+        required: true
+    opServiceAccount:
+        description: '1Password service account token'
+        required: true
+    apiToken:
+        description: 'Cloudflare API token'
+        required: true
+    accountId:
+        description: 'Cloudflare account ID'
+        required: true
+    environment:
+        description: 'Cloudflare environment to deploy to (staging, production, preview)'
+        required: true
+    deploy:
+        description: 'Deploy as main version for all traffic instead of uploading versions'
+        required: true
+    commitTag:
+        description: 'Commit branch to associate with the deployment'
+        required: true
+    commitMessage:
+        description: 'Commit message to associate with the deployment'
+        required: true
+    headSha:
+        description: 'Git ref being deployed, used for the deploymentId. Falls back to GITHUB_SHA'
+        required: false
 outputs:
     deployment-url:
-      description: "Deployment URL"
-      value: ${{ steps.upload_middleware.outputs.deployment-url }}
+        description: 'Deployment URL'
+        value: ${{ steps.upload_middleware.outputs.deployment-url }}
 runs:
     using: 'composite'
     steps:
@@ -42,41 +45,80 @@ runs:
         - name: Load secret
           uses: 1password/load-secrets-action@v2
           env:
-            OP_SERVICE_ACCOUNT_TOKEN: ${{ inputs.opServiceAccount }}
-            GITBOOK_URL: ${{ inputs.opItem }}/GITBOOK_URL
-            GITBOOK_ICONS_URL: ${{ inputs.opItem }}/GITBOOK_ICONS_URL
-            GITBOOK_ICONS_TOKEN: ${{ inputs.opItem }}/GITBOOK_ICONS_TOKEN
-            NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: ${{ inputs.opItem }}/NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
-            GITBOOK_SECRET: ${{ inputs.opItem }}/GITBOOK_SECRET
-            GITBOOK_APP_URL: ${{ inputs.opItem }}/GITBOOK_APP_URL
-            GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
-            GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
-            GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
-            GITBOOK_OAUTH_SERVER_URL: ${{ inputs.opItem }}/GITBOOK_OAUTH_SERVER_URL
-            GITBOOK_PREVIEW_BASE_URL: ${{ inputs.opItem }}/GITBOOK_PREVIEW_BASE_URL
-            GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
-            GITBOOK_INTEGRATIONS_CONTENT_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_CONTENT_HOST
-            GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
-            GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL
-            GITBOOK_IMAGE_RESIZE_MODE: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_MODE
-            GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
-            GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
+              OP_SERVICE_ACCOUNT_TOKEN: ${{ inputs.opServiceAccount }}
+              GITBOOK_URL: ${{ inputs.opItem }}/GITBOOK_URL
+              GITBOOK_ICONS_URL: ${{ inputs.opItem }}/GITBOOK_ICONS_URL
+              GITBOOK_ICONS_TOKEN: ${{ inputs.opItem }}/GITBOOK_ICONS_TOKEN
+              NEXT_SERVER_ACTIONS_ENCRYPTION_KEY: ${{ inputs.opItem }}/NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
+              GITBOOK_SECRET: ${{ inputs.opItem }}/GITBOOK_SECRET
+              GITBOOK_APP_URL: ${{ inputs.opItem }}/GITBOOK_APP_URL
+              GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
+              GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
+              GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
+              GITBOOK_OAUTH_SERVER_URL: ${{ inputs.opItem }}/GITBOOK_OAUTH_SERVER_URL
+              GITBOOK_SITE_OAUTH_SIGNING_SECRET: ${{ inputs.opItem }}/GITBOOK_SITE_OAUTH_SIGNING_SECRET
+              GITBOOK_PREVIEW_BASE_URL: ${{ inputs.opItem }}/GITBOOK_PREVIEW_BASE_URL
+              GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
+              GITBOOK_INTEGRATIONS_CONTENT_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_CONTENT_HOST
+              GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
+              GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL_2
+              GITBOOK_IMAGE_RESIZE_SALT: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SALT
+              GITBOOK_IMAGE_RESIZE_MODE: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_MODE
+              GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
+              GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
+        # `build:all` shares a single `next build` between the workerd tier (.open-next) and the
+        # container tier (.open-next-container), so both are built from the same bundle.
         - name: Build worker
-          run: bun run turbo build:cloudflare
+          run: bun run turbo build:all
           env:
-            GITBOOK_RUNTIME: cloudflare
-            GITBOOK_BLOCK_SEARCH_INDEXATION: ${{ inputs.environment == 'preview' && 'true' || '' }}
+              GITBOOK_RUNTIME: cloudflare
+              # `pull_request_target` sets GITHUB_SHA to the base branch tip, identical for every
+              # commit of a PR, which would keep the deployment ID (and its cache) unchanged.
+              GITBOOK_HEAD_SHA: ${{ inputs.headSha }}
+              VERCEL_TARGET_ENV: ${{ inputs.environment }}
+              GITBOOK_BLOCK_SEARCH_INDEXATION: ${{ inputs.environment == 'preview' && 'true' || '' }}
+              GITBOOK_ALLOW_CUSTOMIZATION_OVERRIDE: ${{ inputs.environment == 'preview' && 'true' || '' }}
           shell: bash
 
+        - id: extract_deployment_id
+          name: Extract Next deployment ID
+          shell: bash
+          run: |
+              deployment_id=$(bun -e '
+                  const buildOutput = await Bun.file("packages/gitbook/.open-next/server-functions/default/packages/gitbook/.next/required-server-files.json").json();
+                  const deploymentId = buildOutput.config?.deploymentId;
+                  if (!deploymentId) throw new Error("Next build did not emit a deployment ID");
+                  console.log(deploymentId);
+              ')
+              echo "deployment_id=$deployment_id" >> $GITHUB_OUTPUT
+
         - name: Upload the DO worker
           uses: cloudflare/wrangler-action@v3.14.0
           with:
               apiToken: ${{ inputs.apiToken }}
               accountId: ${{ inputs.accountId }}
               workingDirectory: ./
-              wranglerVersion: '4.43.0'
+              wranglerVersion: '4.122.0'
               environment: ${{ inputs.environment }}
-              command: deploy --config ./packages/gitbook/openNext/customWorkers/doWrangler.jsonc
+              command: ${{ format('deploy --var OPEN_NEXT_BUILD_ID:{0} --config ./packages/gitbook/openNext/customWorkers/doWrangler.jsonc', steps.extract_deployment_id.outputs.deployment_id) }}
+
+        # `versions upload` never builds or pushes the container image, so the container tier uses
+        # `deploy` like the DO worker. It runs after the DO worker (whose Durable Objects it binds)
+        # and before the server and middleware (which read the cache tier it now hosts).
+        #
+        # `--x-provision=false` disables Wrangler's resource provisioning. It is on by default and
+        # probes the R2 API for any binding the deployed Worker does not already have, which our
+        # API token has no permission for. Every bucket here already exists, so there is nothing to
+        # provision.
+        - name: Deploy the container worker
+          uses: cloudflare/wrangler-action@v3.14.0
+          with:
+              apiToken: ${{ inputs.apiToken }}
+              accountId: ${{ inputs.accountId }}
+              workingDirectory: ./
+              wranglerVersion: '4.122.0'
+              environment: ${{ inputs.environment }}
+              command: ${{ format('deploy --x-provision=false --var OPEN_NEXT_BUILD_ID:{0} --config ./packages/gitbook/openNext/customWorkers/containerWrangler.jsonc', steps.extract_deployment_id.outputs.deployment_id) }}
 
         - id: upload_server
           name: Upload server to Cloudflare
@@ -85,7 +127,7 @@ runs:
               apiToken: ${{ inputs.apiToken }}
               accountId: ${{ inputs.accountId }}
               workingDirectory: ./
-              wranglerVersion: '4.43.0'
+              wranglerVersion: '4.122.0'
               environment: ${{ inputs.environment }}
               command: ${{ format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook/openNext/customWorkers/defaultWrangler.jsonc
 
@@ -108,7 +150,7 @@ runs:
               apiToken: ${{ inputs.apiToken }}
               accountId: ${{ inputs.accountId }}
               workingDirectory: ./
-              wranglerVersion: '4.43.0'
+              wranglerVersion: '4.122.0'
               environment: ${{ inputs.environment }}
               command: ${{ format('versions upload --tag {0} --message "{1}"', inputs.commitTag, inputs.commitMessage) }} --config ./packages/gitbook/openNext/customWorkers/middlewareWrangler.jsonc
 
@@ -132,11 +174,10 @@ runs:
               middlewareVersionId: ${{ steps.extract_middleware_version_id.outputs.version_id }}
               deploy: ${{ inputs.deploy }}
 
-
         - name: Outputs
           shell: bash
           env:
-            DEPLOYMENT_URL: ${{ steps.upload_middleware.outputs.deployment-url }}
+              DEPLOYMENT_URL: ${{ steps.upload_middleware.outputs.deployment-url }}
           run: |
               echo "URL: ${{ steps.upload_middleware.outputs.deployment-url }}"
-              echo "Output server: ${{ steps.upload_server.outputs.command-output }}"
+              echo "Output server: ${{ steps.upload_server.outputs.command-output }}"

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

@@ -1,31 +1,31 @@
 name: 'Deploy vercel'
 description: 'Deploy GitBook to Vercel'
 inputs:
-  vercelOrg:
-    description: 'Vercel organization'
-    required: true
-  vercelProject:
-    description: 'Vercel project'
-    required: true
-  vercelToken:
-    description: 'Vercel token'
-    required: true
-  opItem:
-    description: '1Password item to load secrets from'
-    required: true
-  opServiceAccount:
-    description: '1Password service account token'
-    required: true
-  environment:
-    description: 'Environment to deploy to'
-    required: true
-  headSha:
-    description: 'Git ref to deploy, used for the deploymentId'
-    required: false
+    vercelOrg:
+        description: 'Vercel organization'
+        required: true
+    vercelProject:
+        description: 'Vercel project'
+        required: true
+    vercelToken:
+        description: 'Vercel token'
+        required: true
+    opItem:
+        description: '1Password item to load secrets from'
+        required: true
+    opServiceAccount:
+        description: '1Password service account token'
+        required: true
+    environment:
+        description: 'Environment to deploy to'
+        required: true
+    headSha:
+        description: 'Git ref to deploy, used for the deploymentId'
+        required: false
 outputs:
     deployment-url:
-      description: "Deployment URL"
-      value: ${{ steps.deploy.outputs.deployment-url }}
+        description: 'Deployment URL'
+        value: ${{ steps.deploy.outputs.deployment-url }}
 runs:
     using: 'composite'
     steps:
@@ -40,48 +40,51 @@ runs:
           run: bun run vercel pull --yes --environment=${{ inputs.environment }} --token=${{ inputs.vercelToken }}
           shell: bash
           env:
-            VERCEL_ORG_ID: ${{ inputs.vercelOrg }}
-            VERCEL_PROJECT_ID: ${{ inputs.vercelProject }}
+              VERCEL_ORG_ID: ${{ inputs.vercelOrg }}
+              VERCEL_PROJECT_ID: ${{ inputs.vercelProject }}
         - name: Load secret
           uses: 1password/load-secrets-action@v2
           env:
-            OP_SERVICE_ACCOUNT_TOKEN: ${{ inputs.opServiceAccount }}
-            GITBOOK_URL: ${{ inputs.opItem }}/GITBOOK_URL
-            GITBOOK_ICONS_URL: ${{ inputs.opItem }}/GITBOOK_ICONS_URL
-            GITBOOK_ICONS_TOKEN: ${{ inputs.opItem }}/GITBOOK_ICONS_TOKEN
-            GITBOOK_SECRET: ${{ inputs.opItem }}/GITBOOK_SECRET
-            GITBOOK_APP_URL: ${{ inputs.opItem }}/GITBOOK_APP_URL
-            GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
-            GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
-            GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
-            GITBOOK_OAUTH_SERVER_URL: ${{ inputs.opItem }}/GITBOOK_OAUTH_SERVER_URL
-            GITBOOK_PREVIEW_BASE_URL: ${{ inputs.opItem }}/GITBOOK_PREVIEW_BASE_URL
-            GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
-            GITBOOK_INTEGRATIONS_CONTENT_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_CONTENT_HOST
-            GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
-            GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL
-            GITBOOK_IMAGE_RESIZE_MODE: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_MODE
-            GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
-            GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
+              OP_SERVICE_ACCOUNT_TOKEN: ${{ inputs.opServiceAccount }}
+              GITBOOK_URL: ${{ inputs.opItem }}/GITBOOK_URL
+              GITBOOK_ICONS_URL: ${{ inputs.opItem }}/GITBOOK_ICONS_URL
+              GITBOOK_ICONS_TOKEN: ${{ inputs.opItem }}/GITBOOK_ICONS_TOKEN
+              GITBOOK_SECRET: ${{ inputs.opItem }}/GITBOOK_SECRET
+              GITBOOK_APP_URL: ${{ inputs.opItem }}/GITBOOK_APP_URL
+              GITBOOK_API_URL: ${{ inputs.opItem }}/GITBOOK_API_URL
+              GITBOOK_API_PUBLIC_URL: ${{ inputs.opItem }}/GITBOOK_API_PUBLIC_URL
+              GITBOOK_API_TOKEN: ${{ inputs.opItem }}/GITBOOK_API_TOKEN
+              GITBOOK_OAUTH_SERVER_URL: ${{ inputs.opItem }}/GITBOOK_OAUTH_SERVER_URL
+              GITBOOK_SITE_OAUTH_SIGNING_SECRET: ${{ inputs.opItem }}/GITBOOK_SITE_OAUTH_SIGNING_SECRET
+              GITBOOK_PREVIEW_BASE_URL: ${{ inputs.opItem }}/GITBOOK_PREVIEW_BASE_URL
+              GITBOOK_INTEGRATIONS_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_HOST
+              GITBOOK_INTEGRATIONS_CONTENT_HOST: ${{ inputs.opItem }}/GITBOOK_INTEGRATIONS_CONTENT_HOST
+              GITBOOK_IMAGE_RESIZE_SIGNING_KEY: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SIGNING_KEY
+              GITBOOK_IMAGE_RESIZE_URL: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_URL_2
+              GITBOOK_IMAGE_RESIZE_SALT: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_SALT
+              GITBOOK_IMAGE_RESIZE_MODE: ${{ inputs.opItem }}/GITBOOK_IMAGE_RESIZE_MODE
+              GITBOOK_ASSETS_PREFIX: ${{ inputs.opItem }}/GITBOOK_ASSETS_PREFIX
+              GITBOOK_FONTS_URL: ${{ inputs.opItem }}/GITBOOK_FONTS_URL
         - name: Inject build env vars
           if: ${{ inputs.environment == 'preview' }}
           shell: bash
           run: |
-            HEAD_SHA=$(git rev-parse HEAD)
-            echo "resolved HEAD_SHA: $HEAD_SHA"
-            echo "GITBOOK_HEAD_SHA=$HEAD_SHA" >> .vercel/.env.${{ inputs.environment }}.local
-            echo "GITBOOK_RUNTIME=vercel" >> .vercel/.env.${{ inputs.environment }}.local
-            echo "GITBOOK_BLOCK_SEARCH_INDEXATION=true" >> .vercel/.env.${{ inputs.environment }}.local
-            echo "--- .vercel/.env.${{ inputs.environment }}.local after inject ---"
-            cat .vercel/.env.${{ inputs.environment }}.local
+              HEAD_SHA=$(git rev-parse HEAD)
+              echo "resolved HEAD_SHA: $HEAD_SHA"
+              echo "GITBOOK_HEAD_SHA=$HEAD_SHA" >> .vercel/.env.${{ inputs.environment }}.local
+              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 "--- .vercel/.env.${{ inputs.environment }}.local after inject ---"
+              cat .vercel/.env.${{ inputs.environment }}.local
         - name: Build Project Artifacts
           run: bun run vercel build --target=${{ inputs.environment }} --token=${{ inputs.vercelToken }}
           shell: bash
           env:
-            VERCEL_ORG_ID: ${{ inputs.vercelOrg }}
-            VERCEL_PROJECT_ID: ${{ inputs.vercelProject }}
-            GITBOOK_RUNTIME: vercel
-            GITBOOK_HEAD_SHA: ${{ inputs.headSha }}
+              VERCEL_ORG_ID: ${{ inputs.vercelOrg }}
+              VERCEL_PROJECT_ID: ${{ inputs.vercelProject }}
+              GITBOOK_RUNTIME: vercel
+              GITBOOK_HEAD_SHA: ${{ inputs.headSha }}
         - name: Deploy Project Artifacts to Vercel
           id: deploy
           shell: bash
@@ -89,10 +92,9 @@ runs:
               DEPLOYMENT_URL=$(bun run vercel deploy --prebuilt --target=${{ inputs.environment }} --token=${{ inputs.vercelToken }})
               echo "deployment-url=$DEPLOYMENT_URL" >> "$GITHUB_OUTPUT"
           env:
-            VERCEL_ORG_ID: ${{ inputs.vercelOrg }}
-            VERCEL_PROJECT_ID: ${{ inputs.vercelProject }}
+              VERCEL_ORG_ID: ${{ inputs.vercelOrg }}
+              VERCEL_PROJECT_ID: ${{ inputs.vercelProject }}
         - name: Outputs
           shell: bash
           run: |
               echo "URL: ${{ steps.deploy.outputs.deployment-url }}"
-

.github/workflows/ci.yaml

@@ -20,6 +20,20 @@ jobs:
               env:
                   PUPPETEER_SKIP_DOWNLOAD: 1
             - run: bun format:check
+    lint:
+        runs-on: ubuntu-latest
+        name: Lint
+        timeout-minutes: 6
+        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
+            - run: bun lint
     test:
         runs-on: ubuntu-latest
         name: Test

.github/workflows/css-browser-compatibility.yaml

@@ -0,0 +1,34 @@
+name: CSS browser compatibility
+
+on:
+    pull_request_target:
+        types: [opened, reopened, synchronize]
+
+permissions:
+    contents: read
+    pull-requests: read
+
+concurrency:
+    group: css-browser-compatibility-${{ github.event.pull_request.number }}
+    cancel-in-progress: true
+
+jobs:
+    check:
+        name: Check newly added CSS declarations
+        runs-on: ubuntu-latest
+        timeout-minutes: 6
+        steps:
+            # pull_request_target checks out the trusted base branch by default. Never use the PR ref here.
+            - name: Checkout trusted checker
+              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: Check CSS browser compatibility
+              working-directory: packages/gitbook
+              run: bun run check:css-browser-compatibility
+              env:
+                  GITHUB_TOKEN: ${{ github.token }}

.github/workflows/deploy-preview.yaml

@@ -11,7 +11,7 @@ jobs:
         runs-on: ubuntu-latest
         if: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.fork }}
         environment:
-          name: preview-approval
+            name: preview-approval
         steps:
             - name: Approval gate
               run: echo "Preview deployment approved."
@@ -21,8 +21,8 @@ jobs:
         needs: approval
         if: ${{ always() && (needs.approval.result == 'success' || needs.approval.result == 'skipped') }}
         environment:
-          name: 2v-preview
-          url: ${{ steps.deploy.outputs.deployment-url }}
+            name: 2v-preview
+            url: ${{ steps.deploy.outputs.deployment-url }}
         outputs:
             deployment-url: ${{ steps.deploy.outputs.deployment-url }}
         steps:
@@ -47,8 +47,8 @@ jobs:
         needs: approval
         if: ${{ always() && (needs.approval.result == 'success' || needs.approval.result == 'skipped') }}
         environment:
-          name: 2c-preview
-          url: ${{ steps.deploy.outputs.deployment-url }}
+            name: 2c-preview
+            url: ${{ steps.deploy.outputs.deployment-url }}
         outputs:
             deployment-url: ${{ steps.deploy.outputs.deployment-url || steps.extract-worker-id.outputs.worker-url }}
         steps:
@@ -68,14 +68,15 @@ jobs:
                   opServiceAccount: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
                   commitTag: ${{ github.ref == 'refs/heads/main' && 'main' || format('pr{0}', github.event.pull_request.number) }}
                   commitMessage: ${{ github.sha }}
+                  headSha: ${{ github.event.pull_request.head.sha || github.sha }}
             - name: Extract Worker ID
               id: extract-worker-id
               if: ${{ !steps.deploy.outputs.deployment-url }}
               run: |
-                if [[ "${{ steps.deploy.outputs.command-output }}" =~ Worker\ Version\ ID:\ ([0-9a-f]{8})-([0-9a-f-]+) ]]; then
-                  WORKER_ID_FIRST_PART="${BASH_REMATCH[1]}"
-                  echo "worker-url=https://${WORKER_ID_FIRST_PART}-gitbook-open-v2-preview.gitbook.workers.dev/" >> $GITHUB_OUTPUT
-                fi
+                  if [[ "${{ steps.deploy.outputs.command-output }}" =~ Worker\ Version\ ID:\ ([0-9a-f]{8})-([0-9a-f-]+) ]]; then
+                    WORKER_ID_FIRST_PART="${BASH_REMATCH[1]}"
+                    echo "worker-url=https://${WORKER_ID_FIRST_PART}-gitbook-open-v2-preview.gitbook.workers.dev/" >> $GITHUB_OUTPUT
+                  fi
             - name: Outputs
               run: |
                   echo "URL: ${{ steps.deploy.outputs.deployment-url || steps.extract-worker-id.outputs.worker-url }}"
@@ -168,7 +169,7 @@ jobs:
         name: Visual Testing Customers v2
         needs: deploy-v2-vercel
         if: ${{ always() && needs.deploy-v2-vercel.result == 'success' }}
-        timeout-minutes: 15
+        timeout-minutes: 30
         steps:
             - name: Checkout
               uses: actions/checkout@v4
@@ -187,12 +188,60 @@ jobs:
                   SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
                   ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
                   ARGOS_BUILD_NAME: customers-v2-vercel
+
+            # Style recalc depends on the client bundle, not the host, so this runs here only and
+            # not in the Cloudflare job. Kept out of `e2e-customers`, which is a visual suite.
+            - name: Run style invalidation tests
+              if: always()
+              working-directory: packages/gitbook
+              run: bun run e2e-style-perf
+              env:
+                  BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}
+                  SITE_BASE_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/
+
+            # Runs on failure too: a blown style budget is exactly when the numbers are worth seeing.
+            - name: Build style invalidation report
+              if: always() && github.event_name != 'push'
+              id: style-perf
+              working-directory: packages/gitbook
+              run: |
+                  rows=$(cat test-results/style-perf.md 2>/dev/null || true)
+                  if [ -z "$rows" ]; then exit 0; fi
+                  {
+                    echo 'body<<STYLE_PERF_EOF'
+                    echo '### Style invalidation on a large API reference'
+                    echo
+                    echo 'Elements restyled by opening one popup on [the Snyk API reference](https://docs.snyk.io/snyk-api/reference/apps). A share near or above 100% means the insertion restyles the whole document.'
+                    echo
+                    echo '| interaction | restyled | page | share | budget | |'
+                    echo '| --- | ---: | ---: | ---: | ---: | :-: |'
+                    echo "$rows"
+                    echo 'STYLE_PERF_EOF'
+                  } >> "$GITHUB_OUTPUT"
+
+            - name: Find style invalidation comment
+              if: always() && github.event_name != 'push' && steps.style-perf.outputs.body != ''
+              uses: peter-evans/find-comment@v3
+              id: fc-style-perf
+              with:
+                  issue-number: ${{ github.event.pull_request.number }}
+                  comment-author: 'github-actions[bot]'
+                  body-includes: 'Style invalidation on a large API reference'
+
+            - name: Create or update style invalidation comment
+              if: always() && github.event_name != 'push' && steps.style-perf.outputs.body != ''
+              uses: peter-evans/create-or-update-comment@v4
+              with:
+                  comment-id: ${{ steps.fc-style-perf.outputs.comment-id }}
+                  issue-number: ${{ github.event.pull_request.number }}
+                  body: ${{ steps.style-perf.outputs.body }}
+                  edit-mode: replace
     visual-testing-customers-v2-cloudflare:
         runs-on: ubuntu-latest
         name: Visual Testing Customers v2 (Cloudflare)
         needs: deploy-v2-cloudflare
         if: ${{ always() && needs.deploy-v2-cloudflare.result == 'success' }}
-        timeout-minutes: 15
+        timeout-minutes: 30
         steps:
             - name: Checkout
               uses: actions/checkout@v4

.github/workflows/deploy-production.yaml

@@ -7,7 +7,7 @@ jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (production)
         runs-on: ubuntu-latest
-        environment: 
+        environment:
             name: 2v-production
             url: ${{ steps.deploy.outputs.deployment-url }}
         outputs:
@@ -19,16 +19,16 @@ jobs:
               id: deploy
               uses: ./.github/composite/deploy-vercel
               with:
-                environment: production
-                vercelOrg: ${{ secrets.VERCEL_ORG_ID }}
-                vercelProject: ${{ secrets.VERCEL_PROJECT_ID }}
-                vercelToken: ${{ secrets.VERCEL_TOKEN }}
-                opItem: op://gitbook-open/2v-production
-                opServiceAccount: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+                  environment: production
+                  vercelOrg: ${{ secrets.VERCEL_ORG_ID }}
+                  vercelProject: ${{ secrets.VERCEL_PROJECT_ID }}
+                  vercelToken: ${{ secrets.VERCEL_TOKEN }}
+                  opItem: op://gitbook-open/2v-production
+                  opServiceAccount: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
     deploy-v2-cloudflare:
         name: Deploy v2 to Cloudflare Worker (production)
         runs-on: ubuntu-latest
-        environment: 
+        environment:
             name: 2c-production
             url: ${{ steps.deploy.outputs.deployment-url }}
         outputs:
@@ -50,4 +50,4 @@ jobs:
                   commitMessage: ${{ github.sha }}
             - name: Outputs
               run: |
-                  echo "URL: ${{ steps.deploy.outputs.deployment-url }}"
+                  echo "URL: ${{ steps.deploy.outputs.deployment-url }}"

.github/workflows/deploy-staging.yaml

@@ -7,7 +7,7 @@ jobs:
     deploy-v2-vercel:
         name: Deploy v2 to Vercel (staging)
         runs-on: ubuntu-latest
-        environment: 
+        environment:
             name: 2v-staging
             url: ${{ steps.deploy.outputs.deployment-url }}
         outputs:
@@ -19,16 +19,16 @@ jobs:
               id: deploy
               uses: ./.github/composite/deploy-vercel
               with:
-                environment: staging
-                vercelOrg: ${{ secrets.VERCEL_ORG_ID }}
-                vercelProject: ${{ secrets.VERCEL_PROJECT_ID }}
-                vercelToken: ${{ secrets.VERCEL_TOKEN }}
-                opItem: op://gitbook-open/2v-staging
-                opServiceAccount: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+                  environment: staging
+                  vercelOrg: ${{ secrets.VERCEL_ORG_ID }}
+                  vercelProject: ${{ secrets.VERCEL_PROJECT_ID }}
+                  vercelToken: ${{ secrets.VERCEL_TOKEN }}
+                  opItem: op://gitbook-open/2v-staging
+                  opServiceAccount: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
     deploy-v2-cloudflare:
         name: Deploy v2 to Cloudflare Worker (staging)
         runs-on: ubuntu-latest
-        environment: 
+        environment:
             name: 2c-staging
             url: ${{ steps.deploy.outputs.deployment-url }}
         outputs:
@@ -50,4 +50,4 @@ jobs:
                   commitMessage: ${{ github.sha }}
             - name: Outputs
               run: |
-                  echo "URL: ${{ steps.deploy.outputs.deployment-url }}"
+                  echo "URL: ${{ steps.deploy.outputs.deployment-url }}"

.github/workflows/publish.yaml

@@ -4,7 +4,7 @@ on:
     push:
         branches:
             - main
-    
+
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 jobs:

.oxfmtrc.json

@@ -0,0 +1,70 @@
+{
+    "$schema": "./node_modules/oxfmt/configuration_schema.json",
+    "printWidth": 100,
+    "tabWidth": 4,
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": true,
+    "jsxSingleQuote": false,
+    "quoteProps": "as-needed",
+    "trailingComma": "es5",
+    "bracketSpacing": true,
+    "bracketSameLine": false,
+    "arrowParens": "always",
+    "endOfLine": "lf",
+    "sortImports": {
+        "customGroups": [
+            {
+                "groupName": "workspace",
+                "elementNamePattern": ["@gitbook/**"]
+            }
+        ],
+        "groups": [
+            ["value-builtin", "value-external", "type-builtin", "type-external"],
+            { "newlinesBetween": true },
+            "workspace",
+            { "newlinesBetween": true },
+            [
+                "value-internal",
+                "type-internal",
+                "value-parent",
+                "type-parent",
+                "value-sibling",
+                "type-sibling",
+                "value-index",
+                "type-index"
+            ],
+            "type-import",
+            "unknown"
+        ]
+    },
+    "sortPackageJson": false,
+    "sortTailwindcss": {
+        "config": "./packages/gitbook/tailwind.config.ts",
+        "attributes": ["class", "className", "style"],
+        "functions": ["clsx", "tw"]
+    },
+    "ignorePatterns": [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/public/**",
+        "**/.next/**",
+        "**/.open-next/**",
+        "**/.turbo/**",
+        "**/.vercel/**",
+        "**/.cache/**",
+        "**/.wrangler/**",
+        "**/*.log",
+        "**/*.MD",
+        "**/*.md",
+        "**/*.mdx",
+        "**/*.html",
+        "**/*.css",
+        "packages/embed/standalone/**",
+        "packages/openapi-parser/src/fixtures/**",
+        "packages/emoji-codepoints/index.ts",
+        "packages/icons/src/data/*.json",
+        "packages/gitbook/worker-configuration.d.ts"
+    ]
+}

.oxlintrc.json

@@ -0,0 +1,87 @@
+{
+    "$schema": "./node_modules/oxlint/configuration_schema.json",
+    "categories": {
+        "correctness": "warn",
+        "suspicious": "warn",
+        "perf": "warn"
+    },
+    "plugins": ["eslint", "typescript", "unicorn", "oxc", "react", "jsx-a11y", "vitest"],
+    "env": {
+        "builtin": true,
+        "browser": true,
+        "node": true,
+        "shared-node-browser": true,
+        "worker": true
+    },
+    "globals": {
+        "Bun": "readonly",
+        "GitBookIntegrationEvent": "readonly",
+        "React": "readonly"
+    },
+    "rules": {
+        "eslint/no-console": [
+            "warn",
+            {
+                "allow": ["assert", "error", "warn"]
+            }
+        ],
+        "eslint/no-control-regex": "warn",
+        "eslint/no-prototype-builtins": "warn",
+        "eslint/no-cond-assign": "warn",
+        "eslint/no-undef": "error",
+        "eslint/no-unused-vars": [
+            "error",
+            {
+                "argsIgnorePattern": "^_",
+                "caughtErrorsIgnorePattern": "^_",
+                "ignoreRestSiblings": true,
+                "varsIgnorePattern": "^_"
+            }
+        ],
+        "react/button-has-type": "warn",
+        "react/exhaustive-deps": "warn",
+        "react/jsx-key": "warn",
+        "react/jsx-no-useless-fragment": "warn",
+        "react/no-array-index-key": "warn",
+        "react/void-dom-elements-no-children": "warn",
+        "react/rules-of-hooks": "error",
+        "jsx-a11y/alt-text": "warn",
+        "jsx-a11y/anchor-is-valid": "warn",
+        "jsx-a11y/click-events-have-key-events": "warn",
+        "jsx-a11y/iframe-has-title": "warn",
+        "jsx-a11y/interactive-supports-focus": "warn",
+        "jsx-a11y/label-has-associated-control": "warn",
+        "jsx-a11y/no-noninteractive-tabindex": "warn",
+        "jsx-a11y/role-has-required-aria-props": "warn",
+        "jsx-a11y/tabindex-no-positive": "warn",
+        "typescript/array-type": "error",
+        "typescript/no-explicit-any": "warn",
+        "typescript/no-non-null-assertion": "warn",
+        "typescript/no-confusing-void-expression": "warn",
+        "typescript/only-throw-error": "error",
+        "vitest/no-focused-tests": "error",
+        "no-delete-var": "warn",
+        "no-debugger": "error",
+        "no-throw-literal": "error",
+        "use-isnan": "error",
+        "valid-typeof": "error"
+    },
+    "ignorePatterns": [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/public/**",
+        "**/.next/**",
+        "**/.open-next/**",
+        "**/.turbo/**",
+        "**/.vercel/**",
+        "**/.cache/**",
+        "**/.wrangler/**",
+        "packages/embed/standalone/**",
+        "packages/openapi-parser/src/fixtures/**",
+        "packages/emoji-codepoints/index.ts",
+        "packages/icons/src/data/*.json",
+        "packages/gitbook/worker-configuration.d.ts",
+        "**/*.css"
+    ]
+}

.vscode/extensions.json

@@ -1,3 +1,3 @@
 {
-    "recommendations": ["biomejs.biome"]
+    "recommendations": ["oxc.oxc-vscode"]
 }

.vscode/settings.json

@@ -8,14 +8,12 @@
         ["style \\=([^;]*);", "\\`([^\\`]*)\\`"]
     ],
     "tailwindCSS.classAttributes": ["class", "className", "style", ".*Style"],
-    "prettier.enable": false,
     "editor.formatOnSave": true,
-    "editor.defaultFormatter": "biomejs.biome",
+    "editor.defaultFormatter": "oxc.oxc-vscode",
     "editor.codeActionsOnSave": {
-        "source.organizeImports.biome": "explicit",
-        "source.fixAll.biome": "explicit"
+        "source.fixAll.oxc": "always"
     },
     "[typescript]": {
-        "editor.defaultFormatter": "biomejs.biome"
+        "editor.defaultFormatter": "oxc.oxc-vscode"
     }
 }

AGENTS.md

@@ -6,7 +6,8 @@
 bun install          # Install dependencies
 bun dev              # Start dev server (all packages)
 bun run build        # Build all packages
-bun run format       # Format with Biome (run after every change)
+bun run lint         # Lint with Oxlint
+bun run format       # Format with Oxfmt (run after every change)
 bun run typecheck    # Type-check all packages
 bun run unit         # Run unit tests
 ```
@@ -74,4 +75,8 @@ Save as `.changeset/<name>.md`, then commit it separately with message: `changes
 
 ## Formatting
 
-Uses Biome (not ESLint/Prettier). Always run `bun run format` before committing.
+Linting uses Oxlint and formatting uses Oxfmt. Always run `bun run format` before committing.
+
+## Comments
+
+Comment to explain *why*, not *what* — the code already shows what it does. Keep comments short, ideally a single line. Avoid multi-line block comments that narrate mechanics a reader can follow from the code; they add noise and go stale. Reserve longer comments for genuinely non-obvious rationale: a subtle invariant, or a workaround and the reason it exists.

README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="./assets/gitbook_icon_dark.svg" alt="GitBook" width="48" />
+</p>
+
 <h1 align="center">GitBook</h1>
 
 <p align="center">

assets/gitbook_icon_dark.svg

@@ -0,0 +1,3 @@
+<svg width="65" height="65" viewBox="0 0 65 65" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M27.3963 34.2195C30.5255 36.0255 32.09 36.9285 33.8082 36.93C35.5265 36.9315 37.0926 36.0313 40.2249 34.2308L60.1913 22.7534C61.0927 22.2353 61.6484 21.2749 61.6484 20.2352C61.6484 19.1955 61.0927 18.2351 60.1913 17.717L40.2177 6.23554C37.0888 4.43695 35.5243 3.53766 33.8078 3.53833C32.0912 3.539 30.5275 4.43951 27.4 6.24053L10.2292 16.1286C10.102 16.2019 10.0383 16.2385 9.97905 16.2732C4.11368 19.7068 0.489862 25.9754 0.441408 32.7717C0.440918 32.8404 0.440918 32.9138 0.440918 33.0607C0.440918 33.2074 0.440918 33.2807 0.441407 33.3494C0.489754 40.138 4.10549 46.4008 9.96041 49.837C10.0196 49.8718 10.0831 49.9085 10.2101 49.9818L20.9658 56.1918C27.2331 59.8104 30.3668 61.6197 33.808 61.6208C37.2493 61.622 40.3842 59.8148 46.6539 56.2005L58.008 49.6551C61.1474 47.8454 62.7171 46.9405 63.579 45.4487C64.4409 43.957 64.4409 42.1451 64.4409 38.5215V31.5212C64.4409 30.5159 63.8965 29.5895 63.0182 29.1004C62.1683 28.627 61.1325 28.6341 60.2891 29.1189L37.0074 42.5019C35.4453 43.3998 34.6643 43.8487 33.8072 43.849C32.9501 43.8493 32.1688 43.4008 30.6062 42.5038L14.8487 33.4586C14.0593 33.0055 13.6647 32.7789 13.3477 32.738C12.625 32.6448 11.9301 33.0497 11.6548 33.7244C11.534 34.0203 11.5365 34.4753 11.5414 35.3855C11.545 36.0555 11.5468 36.3905 11.6094 36.6987C11.7496 37.3887 12.1127 38.0136 12.6428 38.4771C12.8795 38.6842 13.1696 38.8516 13.7499 39.1866L30.5974 48.9103C32.164 49.8145 32.9473 50.2666 33.8075 50.2668C34.6677 50.267 35.4512 49.8154 37.0184 48.912L57.6684 37.0085C58.2037 36.7 58.4713 36.5457 58.672 36.6616C58.8727 36.7776 58.8727 37.0865 58.8727 37.7044V40.8796C58.8727 41.7855 58.8727 42.2385 58.6572 42.6114C58.4417 42.9844 58.0493 43.2106 57.2644 43.663L40.2322 53.4811C37.0966 55.2885 35.5288 56.1923 33.8078 56.1915C32.0869 56.1907 30.5199 55.2855 27.386 53.4752L11.4509 44.2701C11.4003 44.2409 11.375 44.2262 11.3514 44.2125C8.0102 42.26 5.94856 38.6882 5.92922 34.8185C5.92909 34.7911 5.92909 34.7619 5.92909 34.7035V31.7889C5.92909 29.6526 7.06686 27.678 8.9151 26.6067C10.5483 25.66 12.5628 25.6582 14.1977 26.6018L27.3963 34.2195Z" fill="#181C1F"/>
+</svg>

biome.json

@@ -1,178 +0,0 @@
-{
-    "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-    "vcs": {
-        "enabled": false,
-        "clientKind": "git",
-        "useIgnoreFile": false
-    },
-    "files": {
-        "ignoreUnknown": false,
-        "ignore": [
-            "**/node_modules/**/*",
-            "**/dist/**/*",
-            "**/build/**/*",
-            "**/public/**/*",
-            "**/.next/**/*",
-            "**/.open-next/**/*",
-            "**/.turbo/**/*",
-            "**/.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",
-            "gitbook/tsconfig.json",
-            "**/*.css"
-        ]
-    },
-    "formatter": {
-        "enabled": true,
-        "useEditorconfig": true,
-        "formatWithErrors": false,
-        "indentStyle": "space",
-        "indentWidth": 4,
-        "lineEnding": "lf",
-        "lineWidth": 100,
-        "attributePosition": "auto",
-        "bracketSpacing": true
-    },
-    "organizeImports": {
-        "enabled": true
-    },
-    "linter": {
-        "enabled": true,
-        "rules": {
-            "recommended": true,
-            "performance": {
-                "noDelete": "warn"
-            },
-            "security": {
-                "noDangerouslySetInnerHtml": "off"
-            },
-            "complexity": {
-                "noForEach": "off",
-                "noUselessFragments": "warn",
-                "noBannedTypes": "warn"
-            },
-            "correctness": {
-                "noUndeclaredVariables": "error",
-                "noUnusedVariables": "error",
-                "useArrayLiterals": "error",
-                "useHookAtTopLevel": "error",
-                "noUnusedImports": "error",
-                "noVoidElementsWithChildren": "warn",
-                "useJsxKeyInIterable": "warn",
-                "useExhaustiveDependencies": "warn",
-                "noUnknownFunction": "warn"
-            },
-            "style": {
-                "noNonNullAssertion": "warn",
-                "noParameterAssign": "off",
-                "useThrowOnlyError": "error"
-            },
-            "suspicious": {
-                "noConsole": {
-                    "level": "warn",
-                    "options": {
-                        "allow": ["assert", "error", "warn"]
-                    }
-                },
-                "noExplicitAny": "warn",
-                "noImplicitAnyLet": "warn",
-                "noConfusingVoidType": "warn",
-                "noControlCharactersInRegex": "warn",
-                "noPrototypeBuiltins": "warn",
-                "noAssignInExpressions": "warn",
-                "noArrayIndexKey": "warn"
-            },
-            "a11y": {
-                "useSemanticElements": "warn",
-                "useKeyWithClickEvents": "warn",
-                "noSvgWithoutTitle": "warn",
-                "useButtonType": "warn",
-                "useIframeTitle": "warn",
-                "useAltText": "warn",
-                "noPositiveTabindex": "warn",
-                "useFocusableInteractive": "warn",
-                "useAriaPropsForRole": "warn",
-                "useValidAnchor": "warn",
-                "noLabelWithoutControl": "warn",
-                "noNoninteractiveTabindex": "warn"
-            },
-            "nursery": {
-                "useSortedClasses": {
-                    "level": "error",
-                    "fix": "safe",
-                    "options": {
-                        "attributes": ["class", "className", "style"],
-                        "functions": ["clsx", "tw"]
-                    }
-                }
-            }
-        }
-    },
-    "javascript": {
-        "formatter": {
-            "jsxQuoteStyle": "double",
-            "quoteProperties": "asNeeded",
-            "trailingCommas": "es5",
-            "semicolons": "always",
-            "arrowParentheses": "always",
-            "bracketSameLine": false,
-            "quoteStyle": "single",
-            "attributePosition": "auto",
-            "bracketSpacing": true
-        }
-    },
-    "overrides": [
-        {
-            "include": [
-                "packages/gitbook/**/*",
-                "packages/react-openapi/**/*",
-                "packages/react-math/**/*",
-                "packages/react-contentkit/**/*",
-                "packages/icons/**/*"
-            ],
-            "javascript": {
-                "globals": ["React"]
-            }
-        },
-        {
-            "include": ["packages/gitbook/**/*"],
-            "javascript": {
-                "globals": ["React", "GitBookIntegrationEvent"]
-            }
-        },
-        {
-            "include": ["*.css"],
-            "javascript": {
-                "globals": ["theme"]
-            }
-        },
-        {
-            "include": ["*.test.ts", "packages/gitbook/tests/**/*"],
-            "javascript": {
-                "globals": ["Bun"]
-            }
-        },
-        {
-            "include": [
-                "packages/cache-do/**/*",
-                "packages/gitbook/cf-env.d.ts",
-                "packages/gitbook/src/cloudflare-entrypoint.ts"
-            ],
-            "javascript": {
-                "globals": [
-                    "DurableObjectLocationHint",
-                    "DurableObjectNamespace",
-                    "DurableObjectStub",
-                    "ContinentCode",
-                    "Fetcher",
-                    "ExportedHandler"
-                ]
-            }
-        }
-    ]
-}

package.json

@@ -5,9 +5,10 @@
         "node": "^22.3.0"
     },
     "devDependencies": {
-        "@biomejs/biome": "^1.9.4",
         "@changesets/cli": "^2.31.0",
-        "turbo": "^2.9.18",
+        "oxfmt": "^0.62.0",
+        "oxlint": "^1.77.0",
+        "turbo": "^2.10.3",
         "vercel": "50.37.3"
     },
     "packageManager": "bun@1.3.7",
@@ -18,8 +19,7 @@
         "react": "catalog:",
         "react-dom": "catalog:",
         "esbuild": "0.27.3",
-        "axios": "1.8.4",
-        "@radix-ui/react-slot": "1.2.4"
+        "axios": "1.8.4"
     },
     "private": true,
     "scripts": {
@@ -27,8 +27,10 @@
         "build": "turbo run build",
         "clean-deps": "rm -rf node_modules && rm -rf packages/*/node_modules",
         "typecheck": "turbo run typecheck",
-        "format": "biome check --write ./",
-        "format:check": "biome check --diagnostic-level=error ./",
+        "lint": "oxlint --quiet",
+        "lint:fix": "oxlint --fix --quiet",
+        "format": "oxfmt",
+        "format:check": "oxfmt --check",
         "unit": "turbo run unit",
         "e2e": "turbo run e2e",
         "e2e-customers": "turbo run e2e-customers",
@@ -39,11 +41,14 @@
         "clean": "turbo run clean"
     },
     "workspaces": {
-        "packages": ["packages/*"],
+        "packages": [
+            "packages/*"
+        ],
         "catalog": {
             "@tsconfig/strictest": "^2.0.6",
             "@tsconfig/node20": "^20.1.6",
-            "@gitbook/api": "0.185.0",
+            "@base-ui/react": "^1.7.0",
+            "@gitbook/api": "0.195.0",
             "@scalar/api-client-react": "^1.3.46",
             "@types/react": "^19.0.0",
             "@types/react-dom": "^19.0.0",
@@ -62,6 +67,6 @@
     "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.6": "patches/next@16.2.6.patch"
+        "next@16.2.11": "patches/next@16.2.11.patch"
     }
 }

packages/browser-types/package.json

@@ -25,7 +25,11 @@
         "dev": "bun run build -- --watch ./src",
         "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "files": [
+        "dist",
+        "README.md",
+        "CHANGELOG.md"
+    ],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"

packages/browser-types/src/index.ts

@@ -5,14 +5,28 @@ export type GitBookIntegrationEvent = 'load' | 'unload';
 
 export type GitBookIntegrationEventCallback = (...args: any[]) => void;
 
+export type GitBookIntegrationToolConfirmation = {
+    icon?: IconName;
+    label: string;
+
+    /**
+     * Supporting context displayed to the user above the confirmation dialog,
+     * to help them understand what they are approving or rejecting.
+     * Limited to 512 characters.
+     */
+    context?: string;
+};
+
 export type GitBookIntegrationTool = AIToolDefinition & {
     /**
      * Confirmation action to be displayed to the user before executing the tool.
+     * Provide a static object, or a function that receives the input provided by
+     * the AI assistant and returns the confirmation — useful to display dynamic
+     * context based on the arguments the tool is about to be executed with.
      */
-    confirmation?: {
-        icon?: IconName;
-        label: string;
-    };
+    confirmation?:
+        | GitBookIntegrationToolConfirmation
+        | ((input: object) => GitBookIntegrationToolConfirmation);
 
     /**
      * Callback when the tool is executed.

packages/cache-tags/package.json

@@ -24,7 +24,11 @@
         "dev": "bun run build -- --watch ./src",
         "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "files": [
+        "dist",
+        "README.md",
+        "CHANGELOG.md"
+    ],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"

packages/cache-tags/src/index.ts

@@ -1,14 +1,15 @@
-import type { ComputedContentSource } from '@gitbook/api';
 import assertNever from 'assert-never';
 
+import type { ComputedContentSource } from '@gitbook/api';
+
 /**
  * Get a stringified cache tag for a given object.
  */
 export function getCacheTag(
     spec: /**
-     * All data related to a user
-     * @deprecated - in v2, no tag as this is an immutable data
-     */
+         * All data related to a user
+         * @deprecated - in v2, no tag as this is an immutable data
+         */
         | {
               tag: 'user';
               user: string;

packages/colors/package.json

@@ -17,10 +17,15 @@
     "scripts": {
         "build": "tsdown",
         "typecheck": "tsc --noEmit",
+        "unit": "bun test",
         "dev": "bun run build -- --watch ./src",
         "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
-    "files": ["dist", "README.md", "CHANGELOG.md"],
+    "files": [
+        "dist",
+        "README.md",
+        "CHANGELOG.md"
+    ],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"

packages/colors/src/transformations.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'bun:test';
+
+import { colorScale } from './transformations';
+
+describe('colorScale exact base', () => {
+    it('takes a very light tint as the exact background on step 1 (clean/bold)', () => {
+        const scale = colorScale('#F5F3EF', { baseStep: 1 });
+        expect(scale[0]).toBe('#F5F3EF');
+    });
+
+    it('anchors a very light tint to step 2 when the theme uses the subtle step (muted)', () => {
+        const scale = colorScale('#F5F3EF', { baseStep: 2 });
+        expect(scale[1]).toBe('#F5F3EF');
+        // Step 1 sits just above the exact base, toward white.
+        expect(scale[0]).not.toBe('#F5F3EF');
+        expect(scale[0]).not.toBe('#ffffff');
+    });
+
+    it('takes a darker-than-dark tint as the exact background, preserving hue and chroma', () => {
+        const scale = colorScale('#0B0F19', { darkMode: true, baseStep: 1 });
+        expect(scale[0]).toBe('#0B0F19');
+    });
+
+    it('does not trigger for a normal mid-lightness tint', () => {
+        const scale = colorScale('#787878', { baseStep: 2 });
+        // The default white background is kept; the tint only colors the scale.
+        expect(scale[0]).toBe('#ffffff');
+        expect(scale[1]).not.toBe('#787878');
+    });
+
+    it('does not trigger for a saturated light color, keeping the normal accent ramp', () => {
+        // Light enough (L≈0.93) to pass the lightness bound, but too chromatic to read as a
+        // background — emitting it verbatim would leave a vivid step 1 above a near-gray scale.
+        const scale = colorScale('#FFEB3B', { baseStep: 1 });
+        expect(scale[0]).toBe('#ffffff');
+        expect(scale[0]).not.toBe('#FFEB3B');
+    });
+
+    it('respects a custom light background instead of overriding it with the tint', () => {
+        // The color is darker than the requested background, so it is not the extreme end and the
+        // supplied base must be preserved rather than overwritten.
+        const scale = colorScale('#eeeeee', { baseStep: 1, background: '#f8f8f8' });
+        expect(scale[0]).not.toBe('#eeeeee');
+    });
+
+    it('anchors an exact base even when a neutral mix is supplied (tint === primary)', () => {
+        // getTintMixColor blends neutral into the tint when it equals the primary color; that must
+        // not darken a near-white tint out of the exact-base path.
+        const scale = colorScale('#F5F3EF', {
+            baseStep: 1,
+            mix: { color: '#787878', ratio: 0.4 },
+        });
+        expect(scale[0]).toBe('#F5F3EF');
+    });
+
+    it('does not trigger for a light accent color below the near-white threshold', () => {
+        // #D8DEEC (light blue-gray, L≈0.90) is a UI accent, not a background, so it must not anchor.
+        const scale = colorScale('#D8DEEC', { baseStep: 1 });
+        expect(scale[0]).toBe('#ffffff');
+        expect(scale[0]).not.toBe('#D8DEEC');
+    });
+
+    it('never anchors when no baseStep is given (accent scales and the bold theme)', () => {
+        // A scale that does not define the page background opts out of the exact base entirely.
+        const scale = colorScale('#F5F3EF', {});
+        expect(scale[0]).toBe('#ffffff');
+        expect(scale[0]).not.toBe('#F5F3EF');
+    });
+});

packages/colors/src/transformations.ts

@@ -82,6 +82,22 @@ export const colorMixMapping = {
     dark: [0, 0.03, 0.08, 0.1, 0.13, 0.15, 0.2, 0.25, 0.5, 0.55, 0.75, 1],
 };
 
+/**
+ * Light mode has no equivalent to the dark base bound (nothing is lighter than white), so a tint
+ * at or above this lightness is treated as an explicit, near-white background (e.g. a warm `#F5F3EF`
+ * at L≈0.96). Kept high so light UI accent colors (around L≈0.90) aren't mistaken for backgrounds.
+ */
+const EXACT_BASE_LIGHT_THRESHOLD = 0.95;
+
+/**
+ * Only a near-neutral tint reads as a background. A saturated color would keep the exact hue at the
+ * anchored step while the rest of the low scale stays ~gray, so those keep the normal accent ramp.
+ */
+const EXACT_BASE_NEUTRAL_CHROMA = 0.05;
+
+/** Lightness of the default white light background (≈0.99999, not exactly 1). */
+const LIGHT_BASE_L = rgbToOklch(hexToRgbArray(LIGHT_BASE)).L;
+
 /**
  * Convert a hex color to an RGB color.
  */
@@ -159,6 +175,14 @@ export type ColorScaleOptions = {
     /** Define a custom foreground color to use. If left undefined, the global `light`/`dark` values (in `colors.ts`) will be used. */
     foreground?: string;
 
+    /**
+     * The 1-indexed scale step this scale renders as the page background (1 = `tint-base` for
+     * `clean`, 2 = `tint-subtle` for `muted`). When set, an extreme near-neutral tint is taken as
+     * the exact background, anchored to this step so it matches exactly. Omit for scales that don't
+     * define the page background (accents, or the two-tone `bold` theme) — they never anchor.
+     */
+    baseStep?: number;
+
     mix?: {
         /** If set to a hex code, this color will be additionally mixed into the generated scale according to `mix.ratio`. */
         color: string;
@@ -179,6 +203,7 @@ export function colorScale(
         darkMode = false,
         background = darkMode ? DARK_BASE : LIGHT_BASE,
         foreground = darkMode ? LIGHT_BASE : DARK_BASE,
+        baseStep,
         mix,
     }: ColorScaleOptions = {}
 ) {
@@ -188,31 +213,51 @@ export function colorScale(
     const backgroundColor = rgbToOklch(hexToRgbArray(background));
     let mapping = darkMode ? colorMixMapping.dark : colorMixMapping.light;
 
-    if (mixColor && mix?.ratio && mix.ratio > 0) {
-        // If defined, we mix in a (tiny) bit of the mix color with the base color.
+    // A near-neutral tint at the extreme end of the scale is taken as the exact page background
+    // rather than tinting pure black/white with it — letting brands set an exact background such as
+    // a warm `#F5F3EF`. Only scales that define the page background opt in (via `baseStep`). In light
+    // mode the base is pure white by default, so a near-white tint also qualifies (nothing is lighter
+    // than white); a custom, lower background is respected instead. Decided on the raw color so a
+    // neutral mix (below) can't darken a tint out of the exact base.
+    const isExtremeBase = darkMode
+        ? baseColor.L < backgroundColor.L
+        : backgroundColor.L >= LIGHT_BASE_L
+          ? baseColor.L > EXACT_BASE_LIGHT_THRESHOLD
+          : baseColor.L > backgroundColor.L;
+    const isExactBase =
+        baseStep !== undefined && isExtremeBase && baseColor.C < EXACT_BASE_NEUTRAL_CHROMA;
+    const exactBaseIndex = (baseStep ?? 1) - 1;
+
+    if (mixColor && mix?.ratio && mix.ratio > 0 && !isExactBase) {
+        // Mix a little of the mix color into the base — but not when the tint is the exact base,
+        // where it must stay true to the supplied color (and match `--header-background`).
         baseColor.L = mixColor.L * mix.ratio + baseColor.L * (1 - mix.ratio);
         baseColor.C = mixColor.C * mix.ratio + baseColor.C * (1 - mix.ratio);
         baseColor.H = mix.color === DEFAULT_TINT_COLOR ? baseColor.H : mixColor.H;
     }
 
-    if (
-        (darkMode && baseColor.L < backgroundColor.L) ||
-        (!darkMode && baseColor.L > backgroundColor.L)
-    ) {
-        // If the supplied color is outside of our lightness bounds, use the supplied color's lightness.
-        // This is mostly used to allow darker-than-dark backgrounds for brands that specifically want that look.
+    if (isExactBase) {
         const difference = (backgroundColor.L - baseColor.L) / backgroundColor.L;
-        backgroundColor.L = baseColor.L;
         // At the edges of the scale, the subtle lightness changes stop being perceptible. We need to amp up our mapping to still stand out.
         const amplifier = 1;
         mapping = mapping.map((step, index) =>
             index < 9 ? step + step * amplifier * difference : step
         );
+
+        // Anchor the supplied color to the step the theme renders as the background, solving the
+        // background lightness so neighbouring steps stay continuous with it.
+        const baseMix = mapping[exactBaseIndex]!;
+        backgroundColor.L = (baseColor.L - foregroundColor.L * baseMix) / (1 - baseMix);
     }
 
     const result = [];
 
     for (let index = 0; index < mapping.length; index++) {
+        if (isExactBase && index === exactBaseIndex) {
+            result.push(hex);
+            continue;
+        }
+
         const step = mapping[index]!;
         const targetL = foregroundColor.L * step + backgroundColor.L * (1 - step);
 
@@ -238,7 +283,10 @@ export function colorScale(
                 case 11:
                     return 0.1;
                 default:
-                    return index * 0.05;
+                    // When the tint is the exact base, hold the steps from the base toward the
+                    // accents at its chroma so the background stays tinted; steps lighter than the
+                    // base (e.g. cards in `muted`) keep desaturating toward white.
+                    return isExactBase && index >= exactBaseIndex ? 1 : index * 0.05;
             }
         })();