Lazy-load Loom embeds so pages with many of them don't stay blank (RND-13147) (#4652)

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

.changeset/ask-view-trigger.md

@@ -1,5 +0,0 @@
----
-"gitbook": patch
----
-
-Track which Ask AI entry point opened the chat in ask view analytics.

.changeset/brave-covers-mark.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Recolor text over a background page cover in the first frame after hydration.

.changeset/fix-cover-image-jump.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix page cover image jumping on load

.changeset/inline-ask-ai-search-state.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix inline Ask AI inputs and buttons doing nothing before search is opened.

.changeset/insights-previous-url.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Send the previous page's URL with site insights events so broken links can be traced to the page linking to them.

.changeset/lazy-load-embed-iframes.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix Loom videos staying blank on pages with many Loom embeds by lazy-loading them.

.changeset/mermaid-edge-label-contrast.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Improve dark theme contrast for Mermaid edge labels.

.changeset/site-auth-login-location.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Fix the site auth login link sometimes redirecting back to an internal URL after login.

.changeset/trademark-powered-by-url.md

@@ -0,0 +1,5 @@
+---
+"gitbook": patch
+---
+
+Point the "Powered by GitBook" trademark link to gitbook.com/powered-by.

bun.lock

@@ -129,8 +129,8 @@
         "@gitbook/react-openapi": "workspace:*",
         "@mermaid-js/mermaid-zenuml": "^0.2.2",
         "@modelcontextprotocol/sdk": "1.17.5",
-        "@opennextjs/aws": "4.1.3",
-        "@opennextjs/cloudflare": "1.20.5",
+        "@opennextjs/aws": "4.1.6",
+        "@opennextjs/cloudflare": "1.20.7",
         "@panzoom/panzoom": "^4.6.1",
         "@sindresorhus/fnv1a": "^3.1.0",
         "@tailwindcss/container-queries": "^0.1.1",
@@ -346,7 +346,6 @@
   },
   "overrides": {
     "@codemirror/state": "6.4.1",
-    "@opennextjs/aws": "4.1.5",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
     "axios": "1.8.4",
@@ -356,7 +355,7 @@
   },
   "catalog": {
     "@base-ui/react": "^1.7.0",
-    "@gitbook/api": "0.202.0",
+    "@gitbook/api": "0.203.0",
     "@scalar/api-client-react": "^1.3.46",
     "@tsconfig/node20": "^20.1.6",
     "@tsconfig/strictest": "^2.0.6",
@@ -728,7 +727,7 @@
 
     "@fortawesome/fontawesome-svg-core": ["@fortawesome/fontawesome-svg-core@7.2.0", "", { "dependencies": { "@fortawesome/fontawesome-common-types": "7.2.0" } }, "sha512-6639htZMjEkwskf3J+e6/iar+4cTNM9qhoWuRfj9F3eJD6r7iCzV1SWnQr2Mdv0QT0suuqU8BoJCZUyCtP9R4Q=="],
 
-    "@gitbook/api": ["@gitbook/api@0.202.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-qhrjEQbNNmCljR0AgP79+BsVh9yelh9TIBg9X3TyYx5a3lJwDiT3sw1ND9DFQSxGHp8hH5w+20KJHn/IDpTbaw=="],
+    "@gitbook/api": ["@gitbook/api@0.203.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-cSFUMM7cIMTHW9cdMpexGSkHHaXmc506fx+LQE2+KLqce8GlBDU/ElIP4RU0MGtN+SSYF31AUgvPD8ZerBVcMA=="],
 
     "@gitbook/browser-types": ["@gitbook/browser-types@workspace:packages/browser-types"],
 
@@ -944,9 +943,9 @@
 
     "@octokit/types": ["@octokit/types@14.1.0", "", { "dependencies": { "@octokit/openapi-types": "^25.1.0" } }, "sha512-1y6DgTy8Jomcpu33N+p5w58l6xyt55Ar2I91RPiIA0xCJBXyUAhXCcmZaDWSANiha7R9a6qJJ2CRomGPZ6f46g=="],
 
-    "@opennextjs/aws": ["@opennextjs/aws@4.1.5", "", { "dependencies": { "@ast-grep/napi": "^0.40.5", "@aws-sdk/client-cloudfront": "3.984.0", "@aws-sdk/client-dynamodb": "3.984.0", "@aws-sdk/client-lambda": "3.984.0", "@aws-sdk/client-s3": "3.984.0", "@aws-sdk/client-sqs": "3.984.0", "@node-minify/core": "^8.0.6", "@node-minify/terser": "^8.0.6", "@tsconfig/node18": "^1.0.3", "aws4fetch": "^1.0.20", "chalk": "^5.6.2", "cookie": "^1.0.2", "esbuild": "0.25.4", "express": "^5.1.0", "path-to-regexp": "^6.3.0", "urlpattern-polyfill": "^10.1.0", "yaml": "^2.8.1" }, "peerDependencies": { "next": ">=15.5.24 <16 || >=16.3.3" }, "bin": { "open-next": "dist/index.js" } }, "sha512-41LNGtS5R5SCfn9zFxHx9QKJIRnmf1uZH+jonHkUMlRKER0bSmUSGjK6GJF7e50XdLXFpTHzaqgRvGmzvr9Btw=="],
+    "@opennextjs/aws": ["@opennextjs/aws@4.1.6", "", { "dependencies": { "@ast-grep/napi": "^0.40.5", "@aws-sdk/client-cloudfront": "3.984.0", "@aws-sdk/client-dynamodb": "3.984.0", "@aws-sdk/client-lambda": "3.984.0", "@aws-sdk/client-s3": "3.984.0", "@aws-sdk/client-sqs": "3.984.0", "@node-minify/core": "^8.0.6", "@node-minify/terser": "^8.0.6", "@tsconfig/node18": "^1.0.3", "aws4fetch": "^1.0.20", "chalk": "^5.6.2", "cookie": "^1.0.2", "esbuild": "0.25.4", "express": "^5.1.0", "path-to-regexp": "^6.3.0", "urlpattern-polyfill": "^10.1.0", "yaml": "^2.8.1" }, "peerDependencies": { "next": ">=15.5.26 <16 || >=16.3.6" }, "bin": { "open-next": "dist/index.js" } }, "sha512-J5mzpWo6duetc3ZtcyBxrUqtD6Dwh8msRcMTNQdvpsgTUjEFp03AJmSOnJ/7BKkuF791YTQgjk4iJYIIYLmKqA=="],
 
-    "@opennextjs/cloudflare": ["@opennextjs/cloudflare@1.20.5", "", { "dependencies": { "@ast-grep/napi": "^0.40.5", "@dotenvx/dotenvx": "1.31.0", "@opennextjs/aws": "4.1.3", "ci-info": "^4.2.0", "cloudflare": "^4.4.1", "comment-json": "^4.5.1", "enquirer": "^2.4.1", "glob": "^12.0.0", "ts-tqdm": "^0.8.6", "yargs": "^18.0.0" }, "peerDependencies": { "next": ">=15.5.24 <16 || >=16.3.3", "rclone.js": "^0.6.6", "wrangler": "^4.125.0" }, "optionalPeers": ["rclone.js"], "bin": { "opennextjs-cloudflare": "dist/cli/index.js" } }, "sha512-Y4qCnHTYMa8waEHvf7iqDJuiresuREp0zithSZ8hT33Wn9WyvOUMBM0SWNH961Wv7ynHRdxAJ0ggmnQ3aSdzdg=="],
+    "@opennextjs/cloudflare": ["@opennextjs/cloudflare@1.20.7", "", { "dependencies": { "@ast-grep/napi": "^0.40.5", "@dotenvx/dotenvx": "1.31.0", "@opennextjs/aws": "4.1.6", "ci-info": "^4.2.0", "cloudflare": "^4.4.1", "comment-json": "^4.5.1", "enquirer": "^2.4.1", "glob": "^12.0.0", "ts-tqdm": "^0.8.6", "yargs": "^18.0.0" }, "peerDependencies": { "next": ">=15.5.26 <16 || >=16.3.6", "rclone.js": "^0.6.6", "wrangler": "^4.125.0" }, "optionalPeers": ["rclone.js"], "bin": { "opennextjs-cloudflare": "dist/cli/index.js" } }, "sha512-obZ5l96+MUmGqKd7akJlT9tv0XAvaUDDJj13MyGTVTzA+lbal8kNRoUwei08rtu1Gv+anASAwwMP3dvzcZx+Jw=="],
 
     "@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
 

package.json

@@ -19,8 +19,7 @@
         "react": "catalog:",
         "react-dom": "catalog:",
         "esbuild": "0.27.3",
-        "axios": "1.8.4",
-        "@opennextjs/aws": "4.1.5"
+        "axios": "1.8.4"
     },
     "private": true,
     "scripts": {
@@ -49,7 +48,7 @@
             "@tsconfig/strictest": "^2.0.6",
             "@tsconfig/node20": "^20.1.6",
             "@base-ui/react": "^1.7.0",
-            "@gitbook/api": "0.202.0",
+            "@gitbook/api": "0.203.0",
             "@scalar/api-client-react": "^1.3.46",
             "@types/react": "^19.0.0",
             "@types/react-dom": "^19.0.0",

packages/gitbook/package.json

@@ -20,8 +20,8 @@
         "@gitbook/react-openapi": "workspace:*",
         "@mermaid-js/mermaid-zenuml": "^0.2.2",
         "@modelcontextprotocol/sdk": "1.17.5",
-        "@opennextjs/aws": "4.1.3",
-        "@opennextjs/cloudflare": "1.20.5",
+        "@opennextjs/aws": "4.1.6",
+        "@opennextjs/cloudflare": "1.20.7",
         "@panzoom/panzoom": "^4.6.1",
         "@sindresorhus/fnv1a": "^3.1.0",
         "@tailwindcss/container-queries": "^0.1.1",

packages/gitbook/src/components/AI/useAI.tsx

@@ -7,7 +7,7 @@ import type { CustomizationAIMode } from '@gitbook/api';
 import type { GitBookAssistant } from '@gitbook/browser-types';
 import { Icon, type IconName } from '@gitbook/icons';
 
-import { type AskAITrigger, useAIChatController, useAIChatState } from '.';
+import { useAIChatController, useAIChatState } from '.';
 import { AIChatIcon, AISearchIcon, getAIChatName } from '../AIChat';
 import { useIntegrationAssistants } from '../Integrations';
 import { useSetSearchState } from '../Search/useSearch';
@@ -26,8 +26,7 @@ export type AIConfig = {
     };
 };
 
-export type Assistant = Omit<GitBookAssistant, 'icon' | 'open'> & {
-    open: (query?: string, trigger?: AskAITrigger) => void;
+export type Assistant = Omit<GitBookAssistant, 'icon'> & {
     /**
      * Unique identifier for the assistant. Generated automatically using Crypto.randomUUID().
      * @example '123e4567-e89b-12d3-a456-426614174000'
@@ -103,8 +102,8 @@ export function useAI(): AIContext {
                     className="size-text-lg"
                 />
             ),
-            open: (query?: string, trigger?: AskAITrigger) => {
-                chatController.open(trigger);
+            open: (query?: string) => {
+                chatController.open();
                 if (query) {
                     chatController.postMessage({ message: query });
                 }
@@ -120,9 +119,13 @@ export function useAI(): AIContext {
             icon: <AISearchIcon />,
             open: (query?: string) => {
                 if (query) {
-                    setSearchState((prev) =>
-                        prev ? { ...prev, query: null, ask: query, open: true } : null
-                    );
+                    setSearchState((prev) => ({
+                        ...prev,
+                        query: null,
+                        ask: query,
+                        scope: prev?.scope ?? 'default',
+                        open: true,
+                    }));
                 }
             },
             pageAction: false,

packages/gitbook/src/components/AI/useAIChat.tsx

@@ -13,7 +13,7 @@ import {
     SiteInsightsDisplayContext,
 } from '@gitbook/api';
 
-import { getInsightsSession, trackAskView, useTrackEvent } from '../Insights';
+import { getInsightsSession, useTrackEvent } from '../Insights';
 import { type UpdateSearchState, useSetSearchState } from '../Search';
 import { addRecentSearchQuery } from '../Search/recent-queries';
 import type { AnyAIControl } from './controls';
@@ -60,8 +60,6 @@ export type AIChatStatus =
     | 'error'
     | 'confirm';
 
-export type AskAITrigger = 'hover' | 'selection' | 'site' | 'page' | 'embed';
-
 export type AIChatState = {
     /**
      * If true, the chat is open.
@@ -162,7 +160,7 @@ type AIChatEventListener = (input?: Omit<AIChatEvent, 'type'>) => void;
 
 export type AIChatController = {
     /** Open the dialog */
-    open: (trigger?: AskAITrigger) => void;
+    open: () => void;
     /** Close the dialog */
     close: () => void;
     /** Post a message to the session */
@@ -304,28 +302,22 @@ export function AIChatProvider(props: {
     const eventsRef = React.useRef<Map<AIChatEvent['type'], AIChatEventListener[]>>(new Map());
 
     // Open AI chat and sync with search state
-    const onOpen = React.useCallback(
-        (trigger?: AskAITrigger) => {
-            setIntercomLauncherHidden(true);
-            if (!renderMessageOptions?.asEmbeddable) {
-                trackAskView(trackEvent, trigger);
-            }
+    const onOpen = React.useCallback(() => {
+        setIntercomLauncherHidden(true);
 
-            const { initialQuery } = globalState.getState();
-            globalState.setState((state) => ({ ...state, opened: true }));
+        const { initialQuery } = globalState.getState();
+        globalState.setState((state) => ({ ...state, opened: true }));
 
-            // Update search state to show ask mode with first message or current ask value
-            setSearchState((prev) => ({
-                ask: prev?.ask ?? initialQuery ?? '',
-                query: prev?.query ?? null,
-                scope: prev?.scope ?? 'default',
-                open: false, // Close search popover when opening chat
-            }));
+        // Update search state to show ask mode with first message or current ask value
+        setSearchState((prev) => ({
+            ask: prev?.ask ?? initialQuery ?? '',
+            query: prev?.query ?? null,
+            scope: prev?.scope ?? 'default',
+            open: false, // Close search popover when opening chat
+        }));
 
-            notify(eventsRef.current.get('open'), {});
-        },
-        [setSearchState, trackEvent, renderMessageOptions?.asEmbeddable]
-    );
+        notify(eventsRef.current.get('open'), {});
+    }, [setSearchState]);
 
     // Close AI chat and clear ask parameter
     const onClose = React.useCallback(() => {

packages/gitbook/src/components/AIChat/AIChat.tsx

@@ -24,6 +24,7 @@ import {
     EmbeddableFrameTitle,
 } from '../Embeddable/EmbeddableFrame';
 import { useIsMounted, useNow } from '../hooks';
+import { useTrackEvent } from '../Insights';
 import { Button } from '../primitives';
 import { ScrollContainer } from '../primitives/ScrollContainer';
 import { SideSheet } from '../primitives/SideSheet';
@@ -67,6 +68,16 @@ export function AIChat() {
         }
     );
 
+    // Track the view of the AI chat
+    const trackEvent = useTrackEvent();
+    React.useEffect(() => {
+        if (chat.opened) {
+            trackEvent({
+                type: 'ask_view',
+            });
+        }
+    }, [chat.opened, trackEvent]);
+
     return (
         <SideSheet
             side="right"

packages/gitbook/src/components/AIChat/AIChatButton.tsx

@@ -39,7 +39,7 @@ export function AIChatButton(props: {
                 </div>
             }
             aria-label={tString(language, 'ai_chat_ask', assistant.label)}
-            onClick={() => assistant.open(undefined, 'site')}
+            onClick={() => assistant.open()}
         >
             {showLabel ? t(language, 'ask') : null}
         </Button>

packages/gitbook/src/components/AIChat/AskAIParagraphButton/AskAIParagraphButton.tsx

@@ -33,7 +33,7 @@ export function AskAIParagraphButton(props: { content: string; className?: Class
             id: `text-${fnv1a(text, { size: 32 })}`,
             content: text,
         });
-        chatController.open('hover');
+        chatController.open();
         chatController.setDraft(tString(language, 'ai_chat_paragraph_draft'));
         chatController.focus();
     };

packages/gitbook/src/components/AIChat/AskAITextSelection/AskAITextSelection.tsx

@@ -84,7 +84,7 @@ export function AskAITextSelection() {
             id: `text-${fnv1a(content, { size: 32 })}`,
             content,
         });
-        chatController.open('selection');
+        chatController.open();
         chatController.focus();
         clear();
     };

packages/gitbook/src/components/DocumentView/CodeBlock/MermaidCodeBlock.tsx

@@ -247,11 +247,15 @@ async function renderMermaidDiagram(args: {
     const { source, id, darkMode, mermaidRuntimeURL } = args;
     const { mermaid } = await loadMermaid(mermaidRuntimeURL);
 
+    // Mermaid's default dark edge label pill only reaches 4.43:1 contrast, below WCAG AA.
+    const themeVariables = darkMode ? { edgeLabelBackground: '#3a3a3a' } : undefined;
+
     mermaid.initialize({
         startOnLoad: false,
         securityLevel: 'strict',
         darkMode,
         theme: darkMode ? 'dark' : undefined,
+        themeVariables,
     });
 
     const renderContainer = createMermaidRenderContainer();

packages/gitbook/src/components/DocumentView/Embed.tsx

@@ -37,7 +37,10 @@ export async function Embed(props: BlockProps<gitbookAPI.DocumentBlockEmbed>) {
                 <>
                     <div
                         dangerouslySetInnerHTML={{
-                            __html: embed.html,
+                            __html:
+                                context.mode !== 'print' && shouldLazyLoad(block.data.url)
+                                    ? lazyLoadIframes(embed.html)
+                                    : embed.html,
                         }}
                         data-visual-test="blackout"
                     />
@@ -73,6 +76,23 @@ export async function Embed(props: BlockProps<gitbookAPI.DocumentBlockEmbed>) {
     );
 }
 
+/**
+ * Pages with many Loom embeds exhaust the browser's request budget
+ * (ERR_INSUFFICIENT_RESOURCES) when every player loads at once, leaving some blank.
+ */
+function lazyLoadIframes(html: string): string {
+    return html.replace(/<iframe\b(?![^>]*\bloading=)/gi, '<iframe loading="lazy"');
+}
+
+function shouldLazyLoad(url: string): boolean {
+    try {
+        const { hostname } = new URL(url);
+        return hostname === 'loom.com' || hostname.endsWith('.loom.com');
+    } catch {
+        return false;
+    }
+}
+
 /**
  * Create an integration block with an unfurl action from the GitBook Embed response.
  */

packages/gitbook/src/components/Embeddable/EmbeddableAIChat.tsx

@@ -4,7 +4,7 @@ import React from 'react';
 
 import * as api from '@gitbook/api';
 
-import { trackAskView, useTrackEvent } from '../Insights';
+import { useTrackEvent } from '../Insights';
 import { LinkContext } from '../primitives';
 import { useIsVisible } from '../VisibilityContext';
 import {
@@ -60,10 +60,15 @@ export function EmbeddableAIChat(props: EmbeddableAIChatProps) {
             return;
         }
 
-        trackAskView(trackEvent, 'embed', {
-            pageId: null,
-            displayContext: api.SiteInsightsDisplayContext.Embed,
-        });
+        trackEvent(
+            {
+                type: 'ask_view',
+            },
+            {
+                pageId: null,
+                displayContext: api.SiteInsightsDisplayContext.Embed,
+            }
+        );
     }, [trackEvent, isVisible]);
 
     const tabsRef = React.useRef<HTMLDivElement>(null);

packages/gitbook/src/components/Insights/InsightsProvider.tsx

@@ -4,9 +4,9 @@ import * as React from 'react';
 import { useDebounceCallback, useEventCallback } from 'usehooks-ts';
 
 import type * as api from '@gitbook/api';
+import { SiteInsightsDisplayContext } from '@gitbook/api';
 import { OpenAPIOperationContextProvider } from '@gitbook/react-openapi';
 
-import type { AskAITrigger } from '../AI';
 import { type CurrentContentContext, useCurrentContent } from '../hooks';
 import { getSession } from './sessions';
 import { type VisitorResponse, useVisitor } from './visitorId';
@@ -43,7 +43,7 @@ export type TrackEventInput<EventName extends InsightsEventName = InsightsEventN
 /**
  * Callback to track an event.
  */
-export type TrackEventCallback = <EventName extends InsightsEventName>(
+type TrackEventCallback = <EventName extends InsightsEventName>(
     event: TrackEventInput<EventName>,
     ctx?: InsightsEventPageContext,
     options?: InsightsEventOptions
@@ -76,12 +76,15 @@ export function InsightsProvider(props: InsightsProviderProps) {
         [pathname: string]:
             | {
                   url: string;
+                  previousUrl: string | null;
                   events: TrackEventInput<InsightsEventName>[];
                   context: CurrentContentContext;
                   pageContext?: InsightsEventPageContext;
               }
             | undefined;
     }>({});
+    // Href of the last page an event was tracked on; `undefined` until the first event.
+    const lastUrlRef = React.useRef<string | null | undefined>(undefined);
 
     /**
      * Synchronously flush all the pending events.
@@ -106,6 +109,7 @@ export function InsightsProvider(props: InsightsProviderProps) {
             allEvents.push(
                 ...transformEvents({
                     url: eventsForPathname.url,
+                    previousUrl: eventsForPathname.previousUrl,
                     events: eventsForPathname.events,
                     context: currentContent,
                     pageContext: eventsForPathname.pageContext,
@@ -155,6 +159,9 @@ export function InsightsProvider(props: InsightsProviderProps) {
         ) => {
             const pathname = window.location.pathname;
             const previous = eventsRef.current[pathname];
+            const lastUrl =
+                lastUrlRef.current === undefined ? getSameOriginReferrer() : lastUrlRef.current;
+            lastUrlRef.current = window.location.href;
             eventsRef.current[pathname] = {
                 // An explicitly-provided context wins so page-scoped events (e.g. feedback) can
                 // attribute to their page even when the pathname's ambient context has none — such
@@ -162,6 +169,7 @@ export function InsightsProvider(props: InsightsProviderProps) {
                 // context keep the stored one.
                 pageContext: ctx ?? previous?.pageContext,
                 url: previous?.url ?? window.location.href,
+                previousUrl: previous ? previous.previousUrl : lastUrl,
                 events: [
                     ...(previous?.events ?? []),
                     {
@@ -215,14 +223,16 @@ export function useTrackEvent(): TrackEventCallback {
     return React.useContext(InsightsContext);
 }
 
-/** Track an ask view while the frontend uses an API type that predates its trigger field. */
-export function trackAskView(
-    trackEvent: TrackEventCallback,
-    trigger: AskAITrigger | undefined,
-    ctx?: InsightsEventPageContext
-) {
-    // TODO: remove this cast once @gitbook/api includes SiteInsightsEventAskView.trigger.
-    trackEvent({ type: 'ask_view', trigger } as unknown as TrackEventInput<'ask_view'>, ctx);
+/**
+ * The referrer when it's another page of this origin, so a full page load (e.g. an absolute link
+ * to a missing page) still records the page it came from.
+ */
+function getSameOriginReferrer(): string | null {
+    if (document.referrer === window.location.href || !URL.canParse(document.referrer)) {
+        return null;
+    }
+    const referrer = new URL(document.referrer);
+    return referrer.origin === window.location.origin ? referrer.href : null;
 }
 
 /**
@@ -251,6 +261,7 @@ function sendEvents(args: { eventUrl: string; events: api.SiteInsightsEvent[] })
  */
 function transformEvents(input: {
     url: string;
+    previousUrl: string | null;
     events: TrackEventInput<InsightsEventName>[];
     context: CurrentContentContext;
     pageContext: InsightsEventPageContext;
@@ -269,6 +280,11 @@ function transformEvents(input: {
 
     const location: api.SiteInsightsEventLocation = {
         url: input.url,
+        // The embed's navigation is between its own tabs, not pages of the site.
+        previousUrl:
+            input.pageContext.displayContext === SiteInsightsDisplayContext.Embed
+                ? null
+                : input.previousUrl,
         siteSection: input.context.siteSectionId ?? null,
         siteSpace: input.context.siteSpaceId ?? null,
         space: input.context.spaceId,

packages/gitbook/src/components/PageActions/PageActions.tsx

@@ -67,7 +67,7 @@ export function ActionOpenAssistant(props: {
                         href: page.href,
                     });
                 }
-                assistant.open(undefined, 'page');
+                assistant.open();
             }}
         />
     );

packages/gitbook/src/components/PageBody/PageCoverImage.tsx

@@ -29,18 +29,21 @@ interface PageCoverImageProps {
 
 export function PageCoverImage(props: PageCoverImageProps) {
     const { imgs, y, height, mask } = props;
-    const { containerRef, objectPositionY, isLoading } = useCoverPosition(imgs, y);
+    const { objectPositionY, isLoading } = useCoverPosition(imgs, y, {
+        height,
+        aspectRatio: PAGE_COVER_SIZE,
+    });
 
     if (isLoading) {
         return (
-            <div className="h-full w-full overflow-hidden" ref={containerRef}>
+            <div className="h-full w-full overflow-hidden">
                 <div className="h-full w-full animate-pulse bg-gradient-to-br from-gray-100 to-gray-200 dark:from-gray-800 dark:to-gray-900" />
             </div>
         );
     }
 
     return (
-        <div className="h-full w-full overflow-hidden" ref={containerRef} style={{ height }}>
+        <div className="h-full w-full overflow-hidden @container" style={{ height }}>
             <img
                 src={imgs.light.src}
                 srcSet={imgs.light.srcSet}
@@ -52,7 +55,7 @@ export function PageCoverImage(props: PageCoverImageProps) {
                     aspectRatio: height
                         ? undefined
                         : `${PAGE_COVER_SIZE.width}/${PAGE_COVER_SIZE.height}`,
-                    objectPosition: `50% ${objectPositionY}%`,
+                    objectPosition: `50% ${objectPositionY}`,
                     height, // if no height is passed, no height will be set.
                     maskComposite: 'intersect',
                     maskImage:
@@ -73,7 +76,7 @@ export function PageCoverImage(props: PageCoverImageProps) {
                         aspectRatio: height
                             ? undefined
                             : `${PAGE_COVER_SIZE.width}/${PAGE_COVER_SIZE.height}`,
-                        objectPosition: `50% ${objectPositionY}%`,
+                        objectPosition: `50% ${objectPositionY}`,
                         height, // if no height is passed, no height will be set.
                         maskComposite: 'intersect',
                         maskImage:

packages/gitbook/src/components/PageBody/useCoverPosition.ts

@@ -1,6 +1,5 @@
 'use client';
-import { useLayoutEffect, useMemo, useRef, useState } from 'react';
-import { useResizeObserver } from 'usehooks-ts';
+import { useLayoutEffect, useState } from 'react';
 
 interface ImageSize {
     width: number;
@@ -22,19 +21,18 @@ interface Images {
 }
 
 /**
- * Hook to calculate the object position Y percentage for a cover image
- * based on the y offset, image dimensions, and container dimensions.
+ * Hook to compute the CSS object position Y for a cover image, from the y offset and the image
+ * dimensions. The container must set `container-type: inline-size` and be as wide as the image,
+ * since the position is computed against its width.
  */
-export function useCoverPosition(imgs: Images, y: number) {
-    const containerRef = useRef<HTMLDivElement>(null);
+export function useCoverPosition(
+    imgs: Images,
+    y: number,
+    container: { height: number | undefined; aspectRatio: ImageSize }
+) {
     const [loadedDimensions, setLoadedDimensions] = useState<ImageSize | null>(null);
     const [isLoading, setIsLoading] = useState(!imgs.light.size && !imgs.dark?.size);
 
-    const container = useResizeObserver({
-        // @ts-expect-error wrong types
-        ref: containerRef,
-    });
-
     // Load original image dimensions if not provided in `imgs`
     useLayoutEffect(() => {
         // Check if we have dimensions from dark (if provided) or else the default light.
@@ -68,42 +66,31 @@ export function useCoverPosition(imgs: Images, y: number) {
     // Check dark first, then light, then loaded dimensions
     const imageDimensions = imgs.dark?.size ?? imgs.light.size ?? loadedDimensions;
 
-    // Calculate ratio and dimensions similar to useCoverPosition hook
-    const ratio =
-        imageDimensions && container.height && container.width
-            ? Math.max(
-                  container.width / imageDimensions.width,
-                  container.height / imageDimensions.height
-              )
-            : 1;
-    const safeRatio = ratio || 1;
-
-    const scaledHeight =
-        imageDimensions && container.height ? imageDimensions.height * safeRatio : null;
-    const maxOffset =
-        scaledHeight && container.height
-            ? Math.max(0, (scaledHeight - container.height) / 2 / safeRatio)
-            : 0;
-
-    // Parse the position between the allowed min/max
-    const objectPositionY = useMemo(() => {
-        if (!container.height || !imageDimensions) {
-            return 50;
-        }
-
-        const scaled = imageDimensions.height * safeRatio;
-        if (scaled <= container.height || maxOffset === 0) {
-            return 50;
-        }
-
-        const clampedOffset = Math.max(-maxOffset, Math.min(maxOffset, y));
-        const relative = (maxOffset - clampedOffset) / (2 * maxOffset);
-        return relative * 100;
-    }, [container.height, imageDimensions, maxOffset, safeRatio, y]);
-
     return {
-        containerRef,
-        objectPositionY,
+        objectPositionY: imageDimensions
+            ? getCoverObjectPositionY(imageDimensions, y, container)
+            : '50%',
         isLoading: !imageDimensions || isLoading,
     };
 }
+
+/**
+ * Offset the image `y` natural pixels from centered, clamped so it keeps covering the container.
+ * Expressed in CSS against the container width (`cqw`), so it renders the same on the server as
+ * after hydration, without measuring the container.
+ */
+function getCoverObjectPositionY(
+    image: ImageSize,
+    y: number,
+    container: { height: number | undefined; aspectRatio: ImageSize }
+): string {
+    const containerHeight = container.height
+        ? `${container.height}px`
+        : `${(100 * container.aspectRatio.height) / container.aspectRatio.width}cqw`;
+    // Rendered height of the image under `object-fit: cover`.
+    const scaledHeight = `max(${(100 * image.height) / image.width}cqw, ${containerHeight})`;
+    const maxOffset = `(${scaledHeight} - ${containerHeight}) / 2`;
+    const offset = `${scaledHeight} * ${y / image.height}`;
+
+    return `calc(50% + clamp(-1 * ${maxOffset}, ${offset}, ${maxOffset}))`;
+}

packages/gitbook/src/components/SiteAuth/SiteAuthLoginLink.tsx

@@ -4,6 +4,7 @@ import { usePathname, useSearchParams } from 'next/navigation';
 import { useMemo } from 'react';
 import type React from 'react';
 
+import { useIsMounted } from '../hooks/useIsMounted';
 import { Button, type ButtonProps } from '../primitives/Button';
 import { DropdownMenuItem } from '../primitives/DropdownMenu';
 import { Link, type LinkInsightsProps, type LinkProps } from '../primitives/Link';
@@ -16,9 +17,17 @@ function useSiteAuthLoginHrefWithLocation(href: string) {
     const rawPathname = usePathname();
     const searchParams = useSearchParams();
     const currentSearch = searchParams?.toString();
-    const pathname = rawPathname ?? '/';
+    // On the server, usePathname() returns the internal rewritten route (/sites/…, which includes
+    // the site API token), so the location is only added once mounted.
+    // https://nextjs.org/docs/app/api-reference/functions/use-pathname#avoid-hydration-mismatch-with-rewrites
+    const isMounted = useIsMounted();
+    const pathname = isMounted ? (rawPathname ?? '/') : null;
 
     return useMemo(() => {
+        if (pathname === null) {
+            return href;
+        }
+
         const baseURL = typeof window !== 'undefined' ? window.location.origin : 'http://localhost';
         const resolved = URL.canParse(href) ? new URL(href) : new URL(href, baseURL);
         const siteBasePath = removeTrailingSlash(

packages/gitbook/src/components/SitePage/PageClientLayout.tsx

@@ -82,7 +82,7 @@ type CoverOverlap =
  * `data-over-cover="split"` with the crossing point in `--cover-edge`.
  */
 function useMarkTextOverCover() {
-    React.useEffect(() => {
+    React.useLayoutEffect(() => {
         const root = document.documentElement;
         const pageCover = document.querySelector<HTMLElement>('[data-gb-page-cover]');
 
@@ -150,7 +150,7 @@ function useMarkTextOverCover() {
             });
         };
 
-        scheduleUpdate();
+        update();
 
         window.addEventListener('scroll', scheduleUpdate, { passive: true });
         window.addEventListener('resize', scheduleUpdate, { passive: true });

packages/gitbook/src/components/TableOfContents/Trademark.tsx

@@ -19,7 +19,7 @@ export async function Trademark(
     const { space } = context;
     const language = await getSpaceLanguage(context);
 
-    const url = new URL('https://www.gitbook.com');
+    const url = new URL('https://www.gitbook.com/powered-by');
     url.searchParams.set('utm_source', 'content');
     url.searchParams.set('utm_medium', 'trademark');
     url.searchParams.set('utm_campaign', space.id);