Add a navigate action to integration block webframes

[gregberge]

What

Lets an integration block webframe navigate the reader to another page in the site, over the client-only webframe postMessage channel (the same channel as adaptive visitor claims):

• @webframe.navigate — a webframe posts this action to navigate the reader to another page in the site, addressed by path (with an optional anchor). The path is resolved against the site base path, so a webframe can link to a page in any section or space of the site — and nowhere outside it.

Navigation is resolved entirely client-side (never through the integration render request), so the integration render cache is unchanged, and it drives the standard navigation progress bar.

Usage (from inside a webframe)

The webframe communicates with GitBook over postMessage, exactly like the existing resize/ready protocol. Post a @webframe.navigate action with a site-root-relative path:

// Navigate to another page in the site
window.parent.postMessage(
    { action: { action: '@webframe.navigate', path: 'getting-started/quickstart' } },
    '*'
);

// Optionally scroll to a heading anchor
window.parent.postMessage(
    { action: { action: '@webframe.navigate', path: 'getting-started/quickstart', anchor: 'installation' } },
    '*'
);

Why

RND-11604 — integrations (e.g. harness) need to navigate the reader to other pages within the site from a webframe. Docs: GitbookIO/integrations#1230.

How it's wired

• The ContentKit client context exposes navigate({ path, anchor? }); ElementWebframe maps the @webframe.navigate message to it.
• The path is resolved on the client through the (tested) GitBookLinker (toPathInSite), rebuilt from serializable data passed by IntegrationBlock — no duplicated join logic, no server round-trip.

Notes

• No new integration scope, and no @gitbook/api or backend change — the gitbook-x companion PR was closed.
• Scope was reduced during review: the earlier state.page current-page context and pageId-based navigation were removed; this PR now only adds @webframe.navigate by path. Pre-existing visitor claims are unchanged.

Test plan

• bun run typecheck — 27/27
• bun test on adaptive.test.ts — 3/3
• biome check on changed files — clean

🤖 Generated with Claude Code

[linear-code]

RND-11604

[changeset-bot]

🦋 Changeset detected

Latest commit: a5f3b7e

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

This PR includes changesets to release 2 packages

Name	Type
@gitbook/react-contentkit	Patch
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-a0ujmk5dq-gitbook.vercel.app	✅
Cloudflare	https://e749190f-gitbook-open-v2-preview.gitbook.workers.dev	✅

Test content

Site	2v	2c
GitBook	https://gitbook-v2-a0ujmk5dq-gitbook.vercel.app/url/gitbook.com/docs	https://e749190f-gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs
E2E	https://gitbook-v2-a0ujmk5dq-gitbook.vercel.app/url/gitbook.gitbook.io/test-gitbook-open	https://e749190f-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)	👍 Approved by Greg Bergé	181 changed, 3 ignored	Jul 10, 2026, 8:53 AM
customers-v2-vercel (Inspect)	👍 Approved by Greg Bergé	105 changed, 41 ignored	Jul 10, 2026, 8:52 AM
v2-cloudflare (Inspect)	👍 Approved by Greg Bergé	29 changed, 6 ignored	Jul 10, 2026, 8:55 AM
v2-vercel (Inspect)	👍 Approved by Greg Bergé	30 changed	Jul 10, 2026, 8:53 AM