Document page and visitor context in webframes

Add the site:page:context scope (and the previously undocumented site:visitor:claims) and document that webframes receive state.page ({ id, path, title }) and state.visitor through the postMessage state, in the interactivity guides and the ContentKit component reference.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: gregberge

docs/integrations/configurations.md

@@ -98,6 +98,8 @@ The scopes your integration has permissions for.
     - site:script:inject ## Internal scope - see note below
     - site:script:cookies ## Internal scope - see note below
     - site:visitor:auth ## Enable workflows related to authenticated access
+    - site:visitor:claims ## Expose visitor claims to webframes
+    - site:page:context ## Expose the current page (id, path, title) to webframes
     - site:adaptive:read ## Read claims available from Adaptive Content
     - site:adaptive:write ## Write claims avaiable to Adaptive Content
     # OpenAPI

docs/integrations/contentkit/interactivity.md

@@ -91,6 +91,28 @@ window.addEventListener("message", (event) => {
 });
 ```
 
+## Page and visitor context
+
+In addition to the values you bind through the `data` prop, GitBook injects contextual information about the current site into the webframe `state`, as long as your integration requests the matching [scope](../configurations.md#scopes):
+
+- `state.page` — the current page as `{ id, path, title }`, when the integration has the `site:page:context` scope.
+- `state.visitor` — the visitor claims, when the integration has the `site:visitor:claims` scope.
+
+This context is delivered client-side through the same `message` event as your bound `data`, so requesting it does not change how the integration block is cached:
+
+```js
+window.addEventListener("message", (event) => {
+    const state = event.data?.state;
+    if (!state) return;
+
+    // Current page — only present when the integration has the `site:page:context` scope.
+    if (state.page) {
+        const { id, path, title } = state.page;
+        // e.g. build a link to a sibling page from `path`
+    }
+});
+```
+
 ## Webframes and actions
 
 Webframes are powerful elements to integrate in GitBook external applications or complete UI. Passing data to the webframe can be done using the `data` prop. But the webframe also needs to be able to communicate data back to the top component. It can be achieved using the `window.postMessage`:

docs/integrations/development/contentkit/reference.md

@@ -264,6 +264,8 @@ If you need a copy button, only add it when your integration has a supported way
 | `buttons`       | `Array<Button>`          | Overlay buttons          |
 | `data`          | `Record<string, string>` | State dependencies       |
 
+The `data` values, together with GitBook-provided context, reach the frame through the `message` event as `event.data.state`. GitBook reserves two keys in `state`: `page` (`{ id, path, title }` of the current page, with the `site:page:context` scope) and `visitor` (visitor claims, with the `site:visitor:claims` scope). See [Interactivity](../../contentkit/interactivity.md#page-and-visitor-context).
+
 #### `select`
 
 ```tsx

docs/integrations/guides/interactivity.md

@@ -95,6 +95,28 @@ window.addEventListener("message", (event) => {
 });
 ```
 
+### Page and visitor context
+
+In addition to the values you bind through the `data` prop, GitBook injects contextual information about the current site into the webframe `state`, as long as your integration requests the matching [scope](../configurations.md#scopes):
+
+- `state.page` — the current page as `{ id, path, title }`, when the integration has the `site:page:context` scope.
+- `state.visitor` — the visitor claims, when the integration has the `site:visitor:claims` scope.
+
+This context is delivered client-side through the same `message` event as your bound `data`, so requesting it does not change how the integration block is cached:
+
+```js
+window.addEventListener("message", (event) => {
+    const state = event.data?.state;
+    if (!state) return;
+
+    // Current page — only present when the integration has the `site:page:context` scope.
+    if (state.page) {
+        const { id, path, title } = state.page;
+        // e.g. build a link to a sibling page from `path`
+    }
+});
+```
+
 ### Editable blocks
 
 Some blocks might be static or only generated from link unfurling, but most blocks are designed to be editable by the user. Editable means that the user can interact with the blocks to change its properties.