Merge branch 'main' into claude/tender-allen-wjt5jb

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwxstGi1QSoV6NQBdVDBye

.changeset/preview-cookie-path-scope.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix previewed customization and theme overrides being lost when navigating between pages inside the site preview. The preview cookie was scoped to the site's canonical base path instead of the preview route it is actually served under, so the browser dropped it on the next in-preview navigation.

packages/gitbook/src/lib/preview.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it } from 'bun:test';
 
-import { getPreviewRequestIdentifier, isPreviewRequest } from './preview';
+import type { PublishedSiteContent } from '@gitbook/api';
+
+import { getPreviewCookieResponse, getPreviewRequestIdentifier, isPreviewRequest } from './preview';
 
 describe('isPreviewRequest', () => {
     it('should return true for preview requests', () => {
@@ -23,3 +25,43 @@ describe('getPreviewRequestIdentifier', () => {
         expect(getPreviewRequestIdentifier(previewRequestURL)).toBe('site_foo');
     });
 });
+
+describe('getPreviewCookieResponse', () => {
+    // The site's canonical base path — deliberately different from the preview route prefix so the
+    // test fails if the cookie is scoped to it instead of the preview route.
+    const siteURLData = { siteBasePath: '/docs/' } as unknown as PublishedSiteContent;
+
+    it('scopes the cookie to the preview route prefix in url-host mode, not the site base path', () => {
+        const cookie = getPreviewCookieResponse({
+            name: 'gitbook-customization',
+            value: 'v',
+            mode: 'url-host',
+            siteRequestURL: new URL('https://sites.gitbook.com/preview/site_foo/hello/world'),
+            siteURLData,
+        });
+        expect(cookie.options?.path).toBe('/preview/site_foo');
+        expect(cookie.options?.sameSite).toBe('lax');
+    });
+
+    it('scopes the cookie to the proxied preview route prefix in url mode', () => {
+        const cookie = getPreviewCookieResponse({
+            name: 'gitbook-customization',
+            value: 'v',
+            mode: 'url',
+            siteRequestURL: new URL('https://sites.gitbook.com/preview/site_foo/hello/world'),
+            siteURLData,
+        });
+        expect(cookie.options?.path).toBe('/url/sites.gitbook.com/preview/site_foo');
+    });
+
+    it('falls back to the site base path for a non-preview url-host request', () => {
+        const cookie = getPreviewCookieResponse({
+            name: 'gitbook-customization',
+            value: 'v',
+            mode: 'url-host',
+            siteRequestURL: new URL('https://example.com/docs/hello/world'),
+            siteURLData,
+        });
+        expect(cookie.options?.path).toBe('/docs/');
+    });
+});

packages/gitbook/src/lib/preview.ts

@@ -51,8 +51,21 @@ export function getPreviewCookieResponse(args: {
                     gitbookPreviewBaseURL.host + gitbookPreviewBaseURL.pathname.replace(/\/$/, '');
                 return `/url/${gitbookPreviewHostPath}/${getPreviewRequestIdentifier(siteRequestURL)}`;
             }
-            case 'url-host':
-                return siteURLData.siteBasePath;
+            case 'url-host': {
+                // The whole site preview (all variants/sections/pages) is served under the preview
+                // route prefix `<previewBasePath>/<siteId>` (e.g. `/preview/<siteId>`). Scope the
+                // cookie to that prefix, derived from the request, so it is resent on every
+                // in-preview navigation. The resolved `siteBasePath` is the site's canonical base
+                // path and does not prefix the preview route, so relying on it makes the browser
+                // drop the cookie on the next page — the actual cause of the override being lost.
+                // Mirrors getVisitorAuthBasePath, which uses the request identifier for proxy
+                // requests. Fall back to `siteBasePath` for any preview not served under the route.
+                if (!isPreviewRequest(siteRequestURL)) {
+                    return siteURLData.siteBasePath;
+                }
+                const gitbookPreviewBaseURL = new URL(GITBOOK_PREVIEW_BASE_URL);
+                return `${gitbookPreviewBaseURL.pathname.replace(/\/$/, '')}/${getPreviewRequestIdentifier(siteRequestURL)}`;
+            }
             default:
                 assertNever(mode);
         }