Only track embed view events once the frame is shown (RND-12362)

[nolannbiron]

Fixes RND-12362.

The embedded Assistant emitted ask_view from a mount-time effect, with no check
that a reader ever saw it. The frame is mounted long before it is shown:

• The standalone widget creates the iframe inside getIframe(), which configure
  calls eagerly — so the documented quickstart loads the frame into a display: none
  container on every host page load.
• ~gitbook/embed server-redirects to /assistant, so the assistant mounts on every
  frame load. configure only arrives later over the channel, so hosts whose tabs
  exclude the assistant still emitted an ask_view before being redirected away.

Result: 9,012,281 embed ask_view against 26,609 embed ask_question in July 2026
(339:1), versus 0.44:1 on the site surface, where the event is gated on chat.opened.

The same mechanism inflated search_open and embed page_view whenever the
configured tabs made one of those the landing route, so those are gated too.

Approach

A new VisibilityContext detects real visibility from inside the frame with an
IntersectionObserver: a non-rendered iframe has a zero-sized viewport, so the
observer stays non-intersecting until the host reveals it. Visibility latches once
shown — an observer inside an iframe also reports the host page scrolling it out of
view, and scrolling past an inline GitBookFrame is not a new view. Returning to the
Assistant tab still counts, because that remounts the consumer.

page_view is unaffected on the site surface: with no provider, the context defaults
to true.

No @gitbook/embed protocol change, so this takes effect for every host immediately
rather than only after they upgrade.

Verification

Verified against the real app using the ?trigger=custom demo, which loads the frame
but leaves the window closed:

• Before: window display: none, innerWidth: 0, nobody opened anything → ask_view
  fires. Bug reproduced.
• After: assistant fully renders inside the hidden frame, zero /~gitbook/__evt
  requests. Open → exactly one ask_view. Close and reopen → still one. Docs tab →
  page_view; back to Assistant → a new ask_view. Site-surface page_view still
  fires on first paint with displayContext: "site".

Covered by a new e2e case in the Docs Embed - Basic suite.

Note

A distinct frame-render event — the alternative suggested on the issue — isn't
possible from this repo: SITE_INSIGHTS_EVENT_TYPE_ENUM lives in the external
@gitbook/api package. If that's wanted too, it needs an API-side change first.

[linear-code]

RND-12362

[changeset-bot]

🦋 Changeset detected

Latest commit: 0620615

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
gitbook	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Summary of the deployments:

Version	URL	Status
Vercel	https://gitbook-v2-d80zizrya-gitbook.vercel.app	✅
Cloudflare	https://6475f3dd-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-d80zizrya-gitbook.vercel.app/url/gitbook.com/docs	https://6475f3dd-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-d80zizrya-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://6475f3dd-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.gitbook.io/test-gitbook-open

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
customers-v2-cloudflare (Inspect)	⚠️ Changes detected (Review)	1 changed, 5 ignored	Aug 19, 2026, 3:44 PM
customers-v2-vercel (Inspect)	⚠️ Changes detected (Review)	12 changed, 5 ignored	Aug 19, 2026, 3:43 PM
v2-cloudflare (Inspect)	⚠️ Changes detected (Review)	4 changed, 1 ignored	Aug 19, 2026, 3:46 PM
v2-vercel (Inspect)	⚠️ Changes detected (Review)	1 changed, 1 ignored	Aug 19, 2026, 3:45 PM